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 pj::AudioMediaPlayer

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.

virtual bool onEof()

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.

Return
If the callback returns false, the playback will stop. Note that if application destroys the player in the callback, it must return false here.

Public Static Functions
AudioMediaPlayer * typecastFromAudioMedia(AudioMedia * media)

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 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