media.h File Reference
libpurple

Media API. More...

`#include "media/candidate.h"`
`#include "media/codec.h"`
`#include "media/enum-types.h"`
`#include <glib.h>`
`#include <glib-object.h>`
`#include "signals.h"`
`#include "util.h"`

Go to the source code of this file.

## Macros

#define | PURPLE_TYPE_MEDIA (purple_media_get_type())
#define | PURPLE_MEDIA(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA, PurpleMedia))
#define | PURPLE_MEDIA_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA, PurpleMediaClass))
#define | PURPLE_IS_MEDIA(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA))
#define | PURPLE_IS_MEDIA_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA))
#define | PURPLE_MEDIA_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA, PurpleMediaClass))

## Typedefs

typedef struct _PurpleMedia | PurpleMedia
| An opaque structure representing a media call. More...

## Functions

GType | purple_media_get_type (void)
| Gets the media class's GType. More...
GList * | purple_media_get_session_ids (PurpleMedia *media)
| Gets a list of session IDs. More...
PurpleAccount * | purple_media_get_account (PurpleMedia *media)
| Gets the PurpleAccount this media session is on. More...
gpointer | purple_media_get_prpl_data (PurpleMedia *media)
| Gets the prpl data from the media session. More...
void | purple_media_set_prpl_data (PurpleMedia *media, gpointer prpl_data)
| Sets the prpl data on the media session. More...
void | purple_media_error (PurpleMedia *media, const gchar *error,...)
| Signals an error in the media session. More...
void | purple_media_end (PurpleMedia *media, const gchar *session_id, const gchar *participant)
| Ends all streams that match the given parameters. More...
void | purple_media_stream_info (PurpleMedia *media, PurpleMediaInfoType type, const gchar *session_id, const gchar *participant, gboolean local)
| Signals different information about the given stream. More...
void | purple_media_set_params (PurpleMedia *media, guint num_params, GParameter *params)
| Sets various optional parameters of the media call. More...
const gchar ** | purple_media_get_available_params (PurpleMedia *media)
| Gets the list of optional parameters supported by the media backend. More...
gboolean | purple_media_param_is_supported (PurpleMedia *media, const gchar *param)
| Checks if given optional parameter is supported by the media backend. More...
gboolean | purple_media_add_stream (PurpleMedia *media, const gchar *sess_id, const gchar *who, PurpleMediaSessionType type, gboolean initiator, const gchar *transmitter, guint num_params, GParameter *params)
| Adds a stream to a session. More...
PurpleMediaSessionType | purple_media_get_session_type (PurpleMedia *media, const gchar *sess_id)
| Gets the session type from a session. More...
struct _PurpleMediaManager * | purple_media_get_manager (PurpleMedia *media)
| Gets the PurpleMediaManager this media session is a part of. More...
GList * | purple_media_get_codecs (PurpleMedia *media, const gchar *sess_id)
| Gets the codecs from a session. More...
void | purple_media_add_remote_candidates (PurpleMedia *media, const gchar *sess_id, const gchar *participant, GList *remote_candidates)
| Adds remote candidates to the stream. More...
GList * | purple_media_get_local_candidates (PurpleMedia *media, const gchar *sess_id, const gchar *participant)
| Gets the local candidates from a stream. More...
GList * | purple_media_get_active_local_candidates (PurpleMedia *media, const gchar *sess_id, const gchar *participant)
| Gets the active local candidates for the stream. More...
GList * | purple_media_get_active_remote_candidates (PurpleMedia *media, const gchar *sess_id, const gchar *participant)
| Gets the active remote candidates for the stream. More...
gboolean | purple_media_set_remote_codecs (PurpleMedia *media, const gchar *sess_id, const gchar *participant, GList *codecs)
| Sets remote candidates from the stream. More...
gboolean | purple_media_candidates_prepared (PurpleMedia *media, const gchar *session_id, const gchar *participant)
| Returns whether or not the candidates for set of streams are prepared. More...
gboolean | purple_media_set_send_codec (PurpleMedia *media, const gchar *sess_id, PurpleMediaCodec *codec)
| Sets the send codec for the a session. More...
gboolean | purple_media_set_encryption_parameters (PurpleMedia *media, const gchar *sess_id, const gchar *cipher, const gchar *auth, const gchar *key, gsize key_len)
| Sets the encryption parameters of our media in the session. More...
gboolean | purple_media_set_decryption_parameters (PurpleMedia *media, const gchar *sess_id, const gchar *participant, const gchar *cipher, const gchar *auth, const gchar *key, gsize key_len)
| Sets the decryption parameters for a session participant's media. More...
gboolean | purple_media_codecs_ready (PurpleMedia *media, const gchar *sess_id)
| Gets whether a session's codecs are ready to be used. More...
gboolean | purple_media_set_send_rtcp_mux (PurpleMedia *media, const gchar *sess_id, const gchar *participant, gboolean send_rtcp_mux)
| Sets the rtcp-mux option for the stream. More...
gboolean | purple_media_is_initiator (PurpleMedia *media, const gchar *sess_id, const gchar *participant)
| Gets whether the local user is the conference/session/stream's initiator. More...
gboolean | purple_media_accepted (PurpleMedia *media, const gchar *sess_id, const gchar *participant)
| Gets whether a streams selected have been accepted. More...
void | purple_media_set_input_volume (PurpleMedia *media, const gchar *session_id, double level)
| Sets the input volume of all the selected sessions. More...
void | purple_media_set_output_volume (PurpleMedia *media, const gchar *session_id, const gchar *participant, double level)
| Sets the output volume of all the selected streams. More...
gulong | purple_media_set_output_window (PurpleMedia *media, const gchar *session_id, const gchar *participant, gulong window_id)
| Sets a video output window for the given session/stream. More...
void | purple_media_remove_output_windows (PurpleMedia *media)
| Removes all output windows from a given media session. More...
gboolean | purple_media_send_dtmf (PurpleMedia *media, const gchar *session_id, gchar dtmf, guint8 volume, guint16 duration)
| Sends a DTMF signal out-of-band. More...

## Detailed Description

Media API.

Definition in file media.h.

## Typedef Documentation

## PurpleMedia

typedef struct _PurpleMedia PurpleMedia

An opaque structure representing a media call.

Definition at line 47 of file media.h.

## Function Documentation

## purple_media_accepted()

gboolean purple_media_accepted | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | participant
| ) |  |

Gets whether a streams selected have been accepted.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to check.
  participant | The participant to check.

Returns
  `TRUE` The selected streams have been accepted, or `FALSE` otherwise.

Since
  2.6.0

## purple_media_add_remote_candidates()

void purple_media_add_remote_candidates | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | participant,
|  | GList * | remote_candidates
| ) |  |

Adds remote candidates to the stream.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session find the stream in.
  participant | The name of the remote user to add the candidates for.
  remote_candidates | The remote candidates to add.

Since
  2.6.0

## purple_media_add_stream()

gboolean purple_media_add_stream | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | who,
|  | PurpleMediaSessionType | type,
|  | gboolean | initiator,
|  | const gchar * | transmitter,
|  | guint | num_params,
|  | GParameter * | params
| ) |  |

Adds a stream to a session.

It only adds a stream to one audio session or video session as the `sess_id` must be unique between sessions.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to add the stream to.
  who | The name of the remote user to add the stream for.
  type | The type of stream to create.
  initiator | Whether or not the local user initiated the stream.
  transmitter | The transmitter to use for the stream.
  num_params | The number of parameters to pass to Farsight.
  params | The parameters to pass to Farsight.

Returns
  `TRUE` The stream was added successfully, `FALSE` otherwise.

Since
  2.6.0

## purple_media_candidates_prepared()

gboolean purple_media_candidates_prepared | ( | PurpleMedia * | media,
|  | const gchar * | session_id,
|  | const gchar * | participant
| ) |  |

Returns whether or not the candidates for set of streams are prepared.

Parameters

  media | The media object to find the remote user in.
  session_id | The session id of the session to check.
  participant | The remote user to check for.

Returns
  `TRUE` All streams for the given session_id/participant combination have candidates prepared, `FALSE` otherwise.

Since
  2.6.0

## purple_media_codecs_ready()

gboolean purple_media_codecs_ready | ( | PurpleMedia * | media,
|  | const gchar * | sess_id
| ) |  |

Gets whether a session's codecs are ready to be used.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to check.

Returns
  `TRUE` The codecs are ready, or `FALSE` otherwise.

Since
  2.6.0

## purple_media_end()

void purple_media_end | ( | PurpleMedia * | media,
|  | const gchar * | session_id,
|  | const gchar * | participant
| ) |  |

Ends all streams that match the given parameters.

Parameters

  media | The media object with which to end streams.
  session_id | The session to end streams on.
  participant | The participant to end streams with.

Since
  2.6.0

## purple_media_error()

void purple_media_error | ( | PurpleMedia * | media,
|  | const gchar * | error,
|  |  | ...
| ) |  |

Signals an error in the media session.

Parameters

  media | The media object to set the state on.
  error | The format of the error message to send in the signal.
  ... | The arguments to plug into the format.

Since
  2.6.0

## purple_media_get_account()

PurpleAccount* purple_media_get_account | ( | PurpleMedia * | media | ) |

Gets the PurpleAccount this media session is on.

Parameters

  media | The media session to retrieve the account from.

Returns
  The account retrieved.

Since
  2.6.0

## purple_media_get_active_local_candidates()

GList* purple_media_get_active_local_candidates | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | participant
| ) |  |

Gets the active local candidates for the stream.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to find the stream in.
  participant | The name of the remote user to get the active candidate from.

Returns
  The active candidates retrieved.

Since
  2.8.0

## purple_media_get_active_remote_candidates()

GList* purple_media_get_active_remote_candidates | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | participant
| ) |  |

Gets the active remote candidates for the stream.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to find the stream in.
  participant | The name of the remote user to get the remote candidate from.

Returns
  The remote candidates retrieved.

Since
  2.8.0

## purple_media_get_available_params()

const gchar** purple_media_get_available_params | ( | PurpleMedia * | media | ) |

Gets the list of optional parameters supported by the media backend.

The list is owned by the `PurpleMedia` internals and should NOT be freed.

Parameters

  media | The media object

Returns
  NULL-terminated array of names of supported parameters.

Since
  2.8.0

## purple_media_get_codecs()

GList* purple_media_get_codecs | ( | PurpleMedia * | media,
|  | const gchar * | sess_id
| ) |  |

Gets the codecs from a session.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to get the codecs from.

Returns
  The retreieved codecs.

Since
  2.6.0

## purple_media_get_local_candidates()

GList* purple_media_get_local_candidates | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | participant
| ) |  |

Gets the local candidates from a stream.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to find the stream in.
  participant | The name of the remote user to get the candidates from.

Since
  2.6.0

## purple_media_get_manager()

struct _PurpleMediaManager* purple_media_get_manager | ( | PurpleMedia * | media | ) |

Gets the PurpleMediaManager this media session is a part of.

Parameters

  media | The media object to get the manager instance from.

Returns
  The PurpleMediaManager instance retrieved.

Since
  2.6.0

## purple_media_get_prpl_data()

gpointer purple_media_get_prpl_data | ( | PurpleMedia * | media | ) |

Gets the prpl data from the media session.

Parameters

  media | The media session to retrieve the prpl data from.

Returns
  The prpl data retrieved.

Since
  2.6.0

## purple_media_get_session_ids()

GList* purple_media_get_session_ids | ( | PurpleMedia * | media | ) |

Gets a list of session IDs.

Parameters

  media | The media session from which to retrieve session IDs.

Returns
  GList of session IDs. The caller must free the list.

Since
  2.6.0

## purple_media_get_session_type()

PurpleMediaSessionType purple_media_get_session_type | ( | PurpleMedia * | media,
|  | const gchar * | sess_id
| ) |  |

Gets the session type from a session.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to get the type from.

Returns
  The retreived session type.

Since
  2.6.0

## purple_media_get_type()

GType purple_media_get_type | ( | void |  | ) |

Gets the media class's GType.

Returns
  The media class's GType.

Since
  2.6.0

## purple_media_is_initiator()

gboolean purple_media_is_initiator | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | participant
| ) |  |

Gets whether the local user is the conference/session/stream's initiator.

Parameters

  media | The media instance to find the session in.
  sess_id | The session id of the session to check.
  participant | The participant of the stream to check.

Returns
  TRUE if the local user is the stream's initator, else FALSE.

Since
  2.6.0

## purple_media_param_is_supported()

gboolean purple_media_param_is_supported | ( | PurpleMedia * | media,
|  | const gchar * | param
| ) |  |

Checks if given optional parameter is supported by the media backend.

Parameters

  media | The media object
  param | name of parameter

Returns
  `TRUE` if backend recognizes the parameter, `FALSE` otherwise.

Since
  2.8.0

## purple_media_remove_output_windows()

void purple_media_remove_output_windows | ( | PurpleMedia * | media | ) |

Removes all output windows from a given media session.

Parameters

  media | The instance to remove all output windows from.

Since
  2.6.0

## purple_media_send_dtmf()

gboolean purple_media_send_dtmf | ( | PurpleMedia * | media,
|  | const gchar * | session_id,
|  | gchar | dtmf,
|  | guint8 | volume,
|  | guint16 | duration
| ) |  |

Sends a DTMF signal out-of-band.

Parameters

  media | The media instance to send a DTMF signal to.
  sess_id | The session id of the session to send the DTMF signal on.
  dtmf | The character representing the DTMF in the range [0-9#*A-D].
  volume | The power level expressed in dBm0 after dropping the sign in the range of 0 to 63. A larger value represents a lower volume.
  duration | The duration of the tone in milliseconds.

Since
  2.11

## purple_media_set_decryption_parameters()

gboolean purple_media_set_decryption_parameters | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | participant,
|  | const gchar * | cipher,
|  | const gchar * | auth,
|  | const gchar * | key,
|  | gsize | key_len
| ) |  |

Sets the decryption parameters for a session participant's media.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to set parameters of.
  participant | The participant of the session to set parameters of.
  cipher | The cipher to use to decrypt media coming from this session's participant.
  auth | The algorithm to use for authentication of the media coming from the session's participant.
  key | The decryption key.
  key_len | Byte length of the decryption key.

Since
  2.11.0

## purple_media_set_encryption_parameters()

gboolean purple_media_set_encryption_parameters | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | cipher,
|  | const gchar * | auth,
|  | const gchar * | key,
|  | gsize | key_len
| ) |  |

Sets the encryption parameters of our media in the session.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to set parameters of.
  cipher | The cipher to use to encrypt our media in the session.
  auth | The algorithm to use to compute authentication codes for our media frames.
  key | The encryption key.
  key_len | Byte length of the encryption key.

Since
  2.11.0

## purple_media_set_input_volume()

void purple_media_set_input_volume | ( | PurpleMedia * | media,
|  | const gchar * | session_id,
|  | double | level
| ) |  |

Sets the input volume of all the selected sessions.

Parameters

  media | The media object the sessions are in.
  session_id | The session to select (if any).
  level | The level to set the volume to.

Since
  2.6.0

## purple_media_set_output_volume()

void purple_media_set_output_volume | ( | PurpleMedia * | media,
|  | const gchar * | session_id,
|  | const gchar * | participant,
|  | double | level
| ) |  |

Sets the output volume of all the selected streams.

Parameters

  media | The media object the streams are in.
  session_id | The session to limit the streams to (if any).
  participant | The participant to limit the streams to (if any).
  level | The level to set the volume to.

Since
  2.6.0

## purple_media_set_output_window()

gulong purple_media_set_output_window | ( | PurpleMedia * | media,
|  | const gchar * | session_id,
|  | const gchar * | participant,
|  | gulong | window_id
| ) |  |

Sets a video output window for the given session/stream.

Parameters

  media | The media instance to set the output window on.
  session_id | The session to set the output window on.
  participant | Optionally, the participant to set the output window on.
  window_id | The window id use for embedding the video in.

Returns
  An id to reference the output window.

Since
  2.6.0

## purple_media_set_params()

void purple_media_set_params | ( | PurpleMedia * | media,
|  | guint | num_params,
|  | GParameter * | params
| ) |  |

Sets various optional parameters of the media call.

Currently supported are:

- "sdes-cname" : The CNAME for the RTP sessions
- "sdes-name" : Real name used to describe the source in SDES messages
- "sdes-tool" : The TOOL to put in SDES messages
- "sdes-email" : Email address to put in SDES messages
- "sdes-location" : The LOCATION to put in SDES messages
- "sdes-note" : The NOTE to put in SDES messages
- "sdes-phone" : The PHONE to put in SDES messages

Parameters

  media | The media object to set the parameters on.
  num_params | The number of parameters to pass
  params | Array of `GParameter` to pass

Since
  2.8.0

## purple_media_set_prpl_data()

void purple_media_set_prpl_data | ( | PurpleMedia * | media,
|  | gpointer | prpl_data
| ) |  |

Sets the prpl data on the media session.

Parameters

  media | The media session to set the prpl data on.
  prpl_data | The data to set on the media session.

Since
  2.6.0

## purple_media_set_remote_codecs()

gboolean purple_media_set_remote_codecs | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | participant,
|  | GList * | codecs
| ) |  |

Sets remote candidates from the stream.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session find the stream in.
  participant | The name of the remote user to set the candidates from.
  codecs | The list of remote codecs to set.

Returns
  `TRUE` The codecs were set successfully, or `FALSE` otherwise.

Since
  2.6.0

## purple_media_set_send_codec()

gboolean purple_media_set_send_codec | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | PurpleMediaCodec * | codec
| ) |  |

Sets the send codec for the a session.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session to set the codec for.
  codec | The codec to set the session to stream.

Returns
  `TRUE` The codec was successfully changed, or `FALSE` otherwise.

Since
  2.6.0

## purple_media_set_send_rtcp_mux()

gboolean purple_media_set_send_rtcp_mux | ( | PurpleMedia * | media,
|  | const gchar * | sess_id,
|  | const gchar * | participant,
|  | gboolean | send_rtcp_mux
| ) |  |

Sets the rtcp-mux option for the stream.

Parameters

  media | The media object to find the session in.
  sess_id | The session id of the session find the stream in.
  participant | The name of the remote user to set the rtcp-mux for. send_rtcp_mux Whether to enable the rtcp-mux option

Returns
  `TRUE` RTCP-Mux was set successfully, or `FALSE` otherwise.

Since
  2.11.0

## purple_media_stream_info()

void purple_media_stream_info | ( | PurpleMedia * | media,
|  | PurpleMediaInfoType | type,
|  | const gchar * | session_id,
|  | const gchar * | participant,
|  | gboolean | local
| ) |  |

Signals different information about the given stream.

Parameters

  media | The media instance to containing the stream to signal.
  type | The type of info being signaled.
  session_id | The id of the session of the stream being signaled.
  participant | The participant of the stream being signaled.
  local | TRUE if the info originated locally, FALSE if on the remote end.

Since
  2.6.0