13. Appendix: Generating This Documentation

Requirements

This documentation is created with Sphinx and Breathe. Here are the required tools:

  1. Doxygen is required. Install it for your platform.

  2. The easiest way to install all the tools is with Python Package Index (PyPI). Just run this and it will install Sphinx, Breathe, and all the required tools if they are not installed:

    $ sudo pip install breathe

  3. Otherwise if PyPI is not available, consult Sphinx and Breathe sites for installation instructions and you may need to install these manually:

Rendering The Documentation

The main source of the documentation is currently the ‘’’Trac’’’ pages at https://trac.pjsip.org/repos/wiki/pjsip-doc/index. The copies in SVN are just copies for backup.

To render the documentation as HTML in _build/html directory:

$ cd $PJDIR/doc/pjsip-book
$ python fetch_trac.py
$ make

To build PDF, run:

$ make latexpdf

How to Use Integrate Book with Doxygen

Quick sample:

will be rendered like this:
+++++++++++++++++++++++++++

This is how to quote a code with syntax coloring:

.. code-block:: c++

     pj::AudioMediaPlayer *player = new AudioMediaPlayer;
     player->createPlayer("announcement.wav");

There are many ways to refer a symbol:

* A method: :cpp:func:`pj::AudioMediaPlayer::createPlayer()`
* A method with alternate display: :cpp:func:`a method <pj::AudioMediaPlayer::createPlayer()>`
* A class :cpp:class:`pj::AudioMediaPlayer`
* A class with alternate display: :cpp:class:`a class <pj::AudioMediaPlayer>`

For that links to work, we need to display the link target declaration (a class or method)
somewhere in the doc, like this:

.. doxygenclass:: pj::AudioMediaPlayer
      :path: xml
      :members:

Alternatively we can display a single method declaration like this:

.. doxygenfunction:: pj::AudioMediaPlayer::createPlayer()
      :path: xml
      :no-link:

We can also display class declaration with specific members.

For more info see `Breathe documentation <http://michaeljones.github.io/breathe/domains.html>`_

will be rendered like this:

This is how to quote a code with syntax coloring:

pj::AudioMediaPlayer *player = new AudioMediaPlayer;
player->createPlayer("announcement.wav");

There are many ways to refer a symbol:

For that links to work, we need to display the link target declaration (a class or method) somewhere in the doc, like this:

class AudioMediaPlayer : public pj::AudioMedia

Audio Media Player.

Public Functions

AudioMediaPlayer()

Constructor.

void createPlayer(const string &file_name, unsigned options = 0)

Create a file player, and automatically add this player to the conference bridge.

Parameters

  • file_name: The filename to be played. Currently only WAV files are supported, and the WAV file MUST be formatted as 16bit PCM mono/single channel (any clock rate is supported).

  • options: Optional option flag. Application may specify PJMEDIA_FILE_NO_LOOP to prevent playback loop.

void createPlaylist(const StringVector &file_names, const string &label = "", unsigned options = 0)

Create a file playlist media port, and automatically add the port to the conference bridge.

Parameters

  • file_names: Array of file names to be added to the play list. Note that the files must have the same clock rate, number of channels, and number of bits per sample.

  • label: Optional label to be set for the media port.

  • options: Optional option flag. Application may specify PJMEDIA_FILE_NO_LOOP to prevent looping.

AudioMediaPlayerInfo getInfo() const

Get additional info about the player.

This operation is only valid for player. For playlist, Error will be thrown.

Return

the info.

pj_uint32_t getPos() const

Get current playback position in samples.

This operation is not valid for playlist.

Return

Current playback position, in samples.

void setPos(pj_uint32_t samples)

Set playback position in samples.

This operation is not valid for playlist.

Parameters

  • samples: The desired playback position, in samples.

virtual ~AudioMediaPlayer()

Destructor.

This will unregister the player port from the conference bridge.

virtual void onEof2()

Register a callback to be called when the file player reading has reached the end of file, or when the file reading has reached the end of file of the last file for a playlist.

If the file or playlist is set to play repeatedly, then the callback will be called multiple times.

If application wishes to stop the playback, it can stop the media transmission in the callback, and only after all transmissions have been stopped, could the application safely destroy the player.

Public Static Functions

static AudioMediaPlayer *typecastFromAudioMedia(AudioMedia *media)

Warning: deprecated and will be removed in future release.

Typecast from base class AudioMedia. This is useful for application written in language that does not support downcasting such as Python.

Return

The object as AudioMediaPlayer instance

Parameters

  • media: The object to be downcasted

Alternatively we can display a single method declaration like this:

void pj::AudioMediaPlayer::createPlayer(const string &file_name, unsigned options = 0)

Create a file player, and automatically add this player to the conference bridge.

Parameters

  • file_name: The filename to be played. Currently only WAV files are supported, and the WAV file MUST be formatted as 16bit PCM mono/single channel (any clock rate is supported).

  • options: Optional option flag. Application may specify PJMEDIA_FILE_NO_LOOP to prevent playback loop.

We can also display class declaration with specific members.

For more info see Breathe documentation