pidgin 2.14.14dev
media.h File Reference

Media API. More...

#include "media/candidate.h"
#include "media/codec.h"
#include "media/enum-types.h"
#include "glibcompat.h"
#include <glib.h>
#include <glib-object.h>
#include "signals.h"
#include "util.h"
Include dependency graph for media.h:
This graph shows which files directly or indirectly include this file:

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...
 
PurpleAccountpurple_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...
 
G_GNUC_BEGIN_IGNORE_DEPRECATIONS void purple_media_set_params (PurpleMedia *media, guint num_params, GParameter *params)
 Sets various optional parameters of the media call. More...
 
G_GNUC_END_IGNORE_DEPRECATIONS 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...
 
G_GNUC_BEGIN_IGNORE_DEPRECATIONS 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...
 
G_GNUC_END_IGNORE_DEPRECATIONS 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_set_require_encryption (PurpleMedia *media, const gchar *sess_id, const gchar *participant, gboolean require_encryption)
 Sets whether a session participant's media requires encryption. 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.

Macro Definition Documentation

◆ PURPLE_IS_MEDIA

#define PURPLE_IS_MEDIA (   obj)    (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA))

Definition at line 43 of file media.h.

◆ PURPLE_IS_MEDIA_CLASS

#define PURPLE_IS_MEDIA_CLASS (   klass)    (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA))

Definition at line 44 of file media.h.

◆ PURPLE_MEDIA

#define PURPLE_MEDIA (   obj)    (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA, PurpleMedia))

Definition at line 41 of file media.h.

◆ PURPLE_MEDIA_CLASS

#define PURPLE_MEDIA_CLASS (   klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA, PurpleMediaClass))

Definition at line 42 of file media.h.

◆ PURPLE_MEDIA_GET_CLASS

#define PURPLE_MEDIA_GET_CLASS (   obj)    (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA, PurpleMediaClass))

Definition at line 45 of file media.h.

◆ PURPLE_TYPE_MEDIA

#define PURPLE_TYPE_MEDIA   (purple_media_get_type())

Definition at line 40 of file media.h.

Typedef Documentation

◆ PurpleMedia

typedef struct _PurpleMedia PurpleMedia

An opaque structure representing a media call.

Definition at line 48 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
mediaThe media object to find the session in.
sess_idThe session id of the session to check.
participantThe 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
mediaThe media object to find the session in.
sess_idThe session id of the session find the stream in.
participantThe name of the remote user to add the candidates for.
remote_candidatesThe remote candidates to add.
Since
2.6.0

◆ purple_media_add_stream()

G_GNUC_BEGIN_IGNORE_DEPRECATIONS 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
mediaThe media object to find the session in.
sess_idThe session id of the session to add the stream to.
whoThe name of the remote user to add the stream for.
typeThe type of stream to create.
initiatorWhether or not the local user initiated the stream.
transmitterThe transmitter to use for the stream.
num_paramsThe number of parameters to pass to Farsight.
paramsThe 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
mediaThe media object to find the remote user in.
session_idThe session id of the session to check.
participantThe 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
mediaThe media object to find the session in.
sess_idThe 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
mediaThe media object with which to end streams.
session_idThe session to end streams on.
participantThe 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
mediaThe media object to set the state on.
errorThe 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
mediaThe 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
mediaThe media object to find the session in.
sess_idThe session id of the session to find the stream in.
participantThe 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
mediaThe media object to find the session in.
sess_idThe session id of the session to find the stream in.
participantThe 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()

G_GNUC_END_IGNORE_DEPRECATIONS 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
mediaThe 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
mediaThe media object to find the session in.
sess_idThe 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
mediaThe media object to find the session in.
sess_idThe session id of the session to find the stream in.
participantThe 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
mediaThe 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
mediaThe 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
mediaThe 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()

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

Gets the session type from a session.

Parameters
mediaThe media object to find the session in.
sess_idThe 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
mediaThe media instance to find the session in.
sess_idThe session id of the session to check.
participantThe 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
mediaThe media object
paramname 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
mediaThe 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
mediaThe media instance to send a DTMF signal to.
sess_idThe session id of the session to send the DTMF signal on.
dtmfThe character representing the DTMF in the range [0-9#*A-D].
volumeThe power level expressed in dBm0 after dropping the sign in the range of 0 to 63. A larger value represents a lower volume.
durationThe 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
mediaThe media object to find the session in.
sess_idThe session id of the session to set parameters of.
participantThe participant of the session to set parameters of.
cipherThe cipher to use to decrypt media coming from this session's participant.
authThe algorithm to use for authentication of the media coming from the session's participant.
keyThe decryption key.
key_lenByte 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
mediaThe media object to find the session in.
sess_idThe session id of the session to set parameters of.
cipherThe cipher to use to encrypt our media in the session.
authThe algorithm to use to compute authentication codes for our media frames.
keyThe encryption key.
key_lenByte 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
mediaThe media object the sessions are in.
session_idThe session to select (if any).
levelThe 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
mediaThe media object the streams are in.
session_idThe session to limit the streams to (if any).
participantThe participant to limit the streams to (if any).
levelThe 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
mediaThe media instance to set the output window on.
session_idThe session to set the output window on.
participantOptionally, the participant to set the output window on.
window_idThe window id use for embedding the video in.
Returns
An id to reference the output window.
Since
2.6.0

◆ purple_media_set_params()

G_GNUC_BEGIN_IGNORE_DEPRECATIONS 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
mediaThe media object to set the parameters on.
num_paramsThe number of parameters to pass
paramsArray 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
mediaThe media session to set the prpl data on.
prpl_dataThe 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
mediaThe media object to find the session in.
sess_idThe session id of the session find the stream in.
participantThe name of the remote user to set the candidates from.
codecsThe list of remote codecs to set.
Returns
TRUE The codecs were set successfully, or FALSE otherwise.
Since
2.6.0

◆ purple_media_set_require_encryption()

gboolean purple_media_set_require_encryption ( PurpleMedia media,
const gchar *  sess_id,
const gchar *  participant,
gboolean  require_encryption 
)

Sets whether a session participant's media requires encryption.

Parameters
mediaThe media object to find the session in.
sess_idThe id of the session to set parameters of.
participantThe participant of the session to set parameters of.
require_encryptionTRUE if the media requires encryption.
Since
2.14.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
mediaThe media object to find the session in.
sess_idThe session id of the session to set the codec for.
codecThe 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
mediaThe media object to find the session in.
sess_idThe session id of the session find the stream in.
participantThe name of the remote user to set the rtcp-mux for. @paran 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
mediaThe media instance to containing the stream to signal.
typeThe type of info being signaled.
session_idThe id of the session of the stream being signaled.
participantThe participant of the stream being signaled.
localTRUE if the info originated locally, FALSE if on the remote end.
Since
2.6.0