Frameworks/libpurple.framework/Versions/0.6.2/Headers/media.h
author Zachary West <zacw@adium.im>
Fri Aug 21 13:25:11 2009 -0700 (2009-08-21)
changeset 2592 e8d15275025e
parent 2069 Frameworks/libpurple.framework/Versions/0.6.0/Headers/media.h@1346acdb9a2b
permissions -rw-r--r--
im.pidgin.adium.1-4 at 267c6165e02e34318a1823960bd04c0639952f73
     1 /**
     2  * @file media.h Media API
     3  * @ingroup core
     4  */
     5 
     6 /* purple
     7  *
     8  * Purple is the legal property of its developers, whose names are too numerous
     9  * to list here.  Please refer to the COPYRIGHT file distributed with this
    10  * source distribution.
    11  *
    12  * This program is free software; you can redistribute it and/or modify
    13  * it under the terms of the GNU General Public License as published by
    14  * the Free Software Foundation; either version 2 of the License, or
    15  * (at your option) any later version.
    16  *
    17  * This program is distributed in the hope that it will be useful,
    18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    20  * GNU General Public License for more details.
    21  *
    22  * You should have received a copy of the GNU General Public License
    23  * along with this program; if not, write to the Free Software
    24  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    25  */
    26 
    27 #ifndef _PURPLE_MEDIA_H_
    28 #define _PURPLE_MEDIA_H_
    29 
    30 #include <glib.h>
    31 #include <glib-object.h>
    32 
    33 G_BEGIN_DECLS
    34 
    35 #define PURPLE_TYPE_MEDIA_CANDIDATE           (purple_media_candidate_get_type())
    36 #define PURPLE_MEDIA_CANDIDATE(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA_CANDIDATE, PurpleMediaCandidate))
    37 #define PURPLE_MEDIA_CANDIDATE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA_CANDIDATE, PurpleMediaCandidate))
    38 #define PURPLE_IS_MEDIA_CANDIDATE(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA_CANDIDATE))
    39 #define PURPLE_IS_MEDIA_CANDIDATE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA_CANDIDATE))
    40 #define PURPLE_MEDIA_CANDIDATE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA_CANDIDATE, PurpleMediaCandidate))
    41 
    42 #define PURPLE_TYPE_MEDIA_CODEC           (purple_media_codec_get_type())
    43 #define PURPLE_MEDIA_CODEC(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA_CODEC, PurpleMediaCodec))
    44 #define PURPLE_MEDIA_CODEC_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA_CODEC, PurpleMediaCodec))
    45 #define PURPLE_IS_MEDIA_CODEC(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA_CODEC))
    46 #define PURPLE_IS_MEDIA_CODEC_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA_CODEC))
    47 #define PURPLE_MEDIA_CODEC_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA_CODEC, PurpleMediaCodec))
    48 
    49 #define PURPLE_TYPE_MEDIA_SESSION_TYPE (purple_media_session_type_get_type())
    50 #define PURPLE_TYPE_MEDIA            (purple_media_get_type())
    51 #define PURPLE_MEDIA(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA, PurpleMedia))
    52 #define PURPLE_MEDIA_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA, PurpleMediaClass))
    53 #define PURPLE_IS_MEDIA(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA))
    54 #define PURPLE_IS_MEDIA_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA))
    55 #define PURPLE_MEDIA_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA, PurpleMediaClass))
    56 
    57 #define PURPLE_TYPE_MEDIA_CANDIDATE_TYPE (purple_media_candidate_type_get_type())
    58 #define PURPLE_TYPE_MEDIA_NETWORK_PROTOCOL (purple_media_network_protocol_get_type())
    59 #define PURPLE_MEDIA_TYPE_STATE      (purple_media_state_changed_get_type())
    60 #define PURPLE_MEDIA_TYPE_INFO_TYPE	(purple_media_info_type_get_type())
    61 
    62 /** @copydoc _PurpleMedia */
    63 typedef struct _PurpleMedia PurpleMedia;
    64 /** @copydoc _PurpleMediaCandidate */
    65 typedef struct _PurpleMediaCandidate PurpleMediaCandidate;
    66 /** @copydoc _PurpleMediaCodec */
    67 typedef struct _PurpleMediaCodec PurpleMediaCodec;
    68 
    69 /** Media caps */
    70 typedef enum {
    71 	PURPLE_MEDIA_CAPS_NONE = 0,
    72 	PURPLE_MEDIA_CAPS_AUDIO = 1,
    73 	PURPLE_MEDIA_CAPS_AUDIO_SINGLE_DIRECTION = 1 << 1,
    74 	PURPLE_MEDIA_CAPS_VIDEO = 1 << 2,
    75 	PURPLE_MEDIA_CAPS_VIDEO_SINGLE_DIRECTION = 1 << 3,
    76 	PURPLE_MEDIA_CAPS_AUDIO_VIDEO = 1 << 4,
    77 	PURPLE_MEDIA_CAPS_MODIFY_SESSION = 1 << 5,
    78 	PURPLE_MEDIA_CAPS_CHANGE_DIRECTION = 1 << 6,
    79 } PurpleMediaCaps;
    80 
    81 /** Media session types */
    82 typedef enum {
    83 	PURPLE_MEDIA_NONE	= 0,
    84 	PURPLE_MEDIA_RECV_AUDIO = 1 << 0,
    85 	PURPLE_MEDIA_SEND_AUDIO = 1 << 1,
    86 	PURPLE_MEDIA_RECV_VIDEO = 1 << 2,
    87 	PURPLE_MEDIA_SEND_VIDEO = 1 << 3,
    88 	PURPLE_MEDIA_AUDIO = PURPLE_MEDIA_RECV_AUDIO | PURPLE_MEDIA_SEND_AUDIO,
    89 	PURPLE_MEDIA_VIDEO = PURPLE_MEDIA_RECV_VIDEO | PURPLE_MEDIA_SEND_VIDEO
    90 } PurpleMediaSessionType;
    91 
    92 /** Media state-changed types */
    93 typedef enum {
    94 	PURPLE_MEDIA_STATE_NEW = 0,
    95 	PURPLE_MEDIA_STATE_CONNECTED,
    96 	PURPLE_MEDIA_STATE_END,
    97 } PurpleMediaState;
    98 
    99 /** Media info types */
   100 typedef enum {
   101 	PURPLE_MEDIA_INFO_HANGUP = 0,
   102 	PURPLE_MEDIA_INFO_ACCEPT,
   103 	PURPLE_MEDIA_INFO_REJECT,
   104 	PURPLE_MEDIA_INFO_MUTE,
   105 	PURPLE_MEDIA_INFO_UNMUTE,
   106 	PURPLE_MEDIA_INFO_PAUSE,
   107 	PURPLE_MEDIA_INFO_UNPAUSE,
   108 	PURPLE_MEDIA_INFO_HOLD,
   109 	PURPLE_MEDIA_INFO_UNHOLD,
   110 } PurpleMediaInfoType;
   111 
   112 typedef enum {
   113 	PURPLE_MEDIA_CANDIDATE_TYPE_HOST,
   114 	PURPLE_MEDIA_CANDIDATE_TYPE_SRFLX,
   115 	PURPLE_MEDIA_CANDIDATE_TYPE_PRFLX,
   116 	PURPLE_MEDIA_CANDIDATE_TYPE_RELAY,
   117 	PURPLE_MEDIA_CANDIDATE_TYPE_MULTICAST,
   118 } PurpleMediaCandidateType;
   119 
   120 typedef enum {
   121 	PURPLE_MEDIA_COMPONENT_NONE = 0,
   122 	PURPLE_MEDIA_COMPONENT_RTP = 1,
   123 	PURPLE_MEDIA_COMPONENT_RTCP = 2,
   124 } PurpleMediaComponentType;
   125 
   126 typedef enum {
   127 	PURPLE_MEDIA_NETWORK_PROTOCOL_UDP,
   128 	PURPLE_MEDIA_NETWORK_PROTOCOL_TCP,
   129 } PurpleMediaNetworkProtocol;
   130 
   131 #include "signals.h"
   132 #include "util.h"
   133 
   134 #ifdef __cplusplus
   135 extern "C" {
   136 #endif
   137 
   138 /**
   139  * Gets the media session type's GType
   140  *
   141  * @return The media session type's GType.
   142  *
   143  * @since 2.6.0
   144  */
   145 GType purple_media_session_type_get_type(void);
   146 
   147 /**
   148  * Gets the media candidate type's GType
   149  *
   150  * @return The media candidate type's GType.
   151  *
   152  * @since 2.6.0
   153  */
   154 GType purple_media_candidate_type_get_type(void);
   155 
   156 /**
   157  * Gets the media network protocol's GType
   158  *
   159  * @return The media network protocol's GType.
   160  *
   161  * @since 2.6.0
   162  */
   163 GType purple_media_network_protocol_get_type(void);
   164 
   165 /**
   166  * Gets the media class's GType
   167  *
   168  * @return The media class's GType.
   169  *
   170  * @since 2.6.0
   171  */
   172 GType purple_media_get_type(void);
   173 
   174 /**
   175  * Gets the type of the state-changed enum
   176  *
   177  * @return The state-changed enum's GType
   178  *
   179  * @since 2.6.0
   180  */
   181 GType purple_media_state_changed_get_type(void);
   182 
   183 /**
   184  * Gets the type of the info type enum
   185  *
   186  * @return The info type enum's GType
   187  *
   188  * @since 2.6.0
   189  */
   190 GType purple_media_info_type_get_type(void);
   191 
   192 /**
   193  * Gets the type of the media candidate structure.
   194  *
   195  * @return The media canditate's GType
   196  *
   197  * @since 2.6.0
   198  */
   199 GType purple_media_candidate_get_type(void);
   200 
   201 /**
   202  * Creates a PurpleMediaCandidate instance.
   203  *
   204  * @param foundation The foundation of the candidate.
   205  * @param component_id The component this candidate is for.
   206  * @param type The type of candidate.
   207  * @param proto The protocol this component is for.
   208  * @param ip The IP address of this component.
   209  * @param port The network port.
   210  *
   211  * @return The newly created PurpleMediaCandidate instance.
   212  *
   213  * @since 2.6.0
   214  */
   215 PurpleMediaCandidate *purple_media_candidate_new(
   216 		const gchar *foundation, guint component_id,
   217 		PurpleMediaCandidateType type,
   218 		PurpleMediaNetworkProtocol proto,
   219 		const gchar *ip, guint port);
   220 
   221 /**
   222  * Copies a GList of PurpleMediaCandidate and its contents.
   223  *
   224  * @param candidates The list of candidates to be copied.
   225  *
   226  * @return The copy of the GList.
   227  *
   228  * @since 2.6.0
   229  */
   230 GList *purple_media_candidate_list_copy(GList *candidates);
   231 
   232 /**
   233  * Frees a GList of PurpleMediaCandidate and its contents.
   234  *
   235  * @param candidates The list of candidates to be freed.
   236  *
   237  * @since 2.6.0
   238  */
   239 void purple_media_candidate_list_free(GList *candidates);
   240 
   241 gchar *purple_media_candidate_get_foundation(PurpleMediaCandidate *candidate);
   242 guint purple_media_candidate_get_component_id(PurpleMediaCandidate *candidate);
   243 gchar *purple_media_candidate_get_ip(PurpleMediaCandidate *candidate);
   244 guint16 purple_media_candidate_get_port(PurpleMediaCandidate *candidate);
   245 gchar *purple_media_candidate_get_base_ip(PurpleMediaCandidate *candidate);
   246 guint16 purple_media_candidate_get_base_port(PurpleMediaCandidate *candidate);
   247 PurpleMediaNetworkProtocol purple_media_candidate_get_protocol(
   248 		PurpleMediaCandidate *candidate);
   249 guint32 purple_media_candidate_get_priority(PurpleMediaCandidate *candidate);
   250 PurpleMediaCandidateType purple_media_candidate_get_candidate_type(
   251 		PurpleMediaCandidate *candidate);
   252 gchar *purple_media_candidate_get_username(PurpleMediaCandidate *candidate);
   253 gchar *purple_media_candidate_get_password(PurpleMediaCandidate *candidate);
   254 guint purple_media_candidate_get_ttl(PurpleMediaCandidate *candidate);
   255 
   256 /**
   257  * Gets the type of the media codec structure.
   258  *
   259  * @return The media codec's GType
   260  *
   261  * @since 2.6.0
   262  */
   263 GType purple_media_codec_get_type(void);
   264 
   265 /**
   266  * Creates a new PurpleMediaCodec instance.
   267  *
   268  * @param id Codec identifier.
   269  * @param encoding_name Name of the media type this encodes.
   270  * @param media_type PurpleMediaSessionType of this codec.
   271  * @param clock_rate The clock rate this codec encodes at, if applicable.
   272  *
   273  * @return The newly created PurpleMediaCodec.
   274  *
   275  * @since 2.6.0
   276  */
   277 PurpleMediaCodec *purple_media_codec_new(int id, const char *encoding_name,
   278 		PurpleMediaSessionType media_type, guint clock_rate);
   279 
   280 guint purple_media_codec_get_id(PurpleMediaCodec *codec);
   281 gchar *purple_media_codec_get_encoding_name(PurpleMediaCodec *codec);
   282 guint purple_media_codec_get_clock_rate(PurpleMediaCodec *codec);
   283 guint purple_media_codec_get_channels(PurpleMediaCodec *codec);
   284 GList *purple_media_codec_get_optional_parameters(PurpleMediaCodec *codec);
   285 
   286 /**
   287  * Creates a string representation of the codec.
   288  *
   289  * @param codec The codec to create the string of.
   290  *
   291  * @return The new string representation.
   292  *
   293  * @since 2.6.0
   294  */
   295 gchar *purple_media_codec_to_string(const PurpleMediaCodec *codec);
   296 
   297 /**
   298  * Adds an optional parameter to the codec.
   299  *
   300  * @param codec The codec to add the parameter to.
   301  * @param name The name of the parameter to add.
   302  * @param value The value of the parameter to add.
   303  *
   304  * @since 2.6.0
   305  */
   306 void purple_media_codec_add_optional_parameter(PurpleMediaCodec *codec,
   307 		const gchar *name, const gchar *value);
   308 
   309 /**
   310  * Removes an optional parameter from the codec.
   311  *
   312  * @param codec The codec to remove the parameter from.
   313  * @param param A pointer to the parameter to remove.
   314  *
   315  * @since 2.6.0
   316  */
   317 void purple_media_codec_remove_optional_parameter(PurpleMediaCodec *codec,
   318 		PurpleKeyValuePair *param);
   319 
   320 /**
   321  * Gets an optional parameter based on the values given.
   322  *
   323  * @param codec The codec to find the parameter in.
   324  * @param name The name of the parameter to search for.
   325  * @param value The value to search for or NULL.
   326  *
   327  * @return The value found or NULL.
   328  *
   329  * @since 2.6.0
   330  */
   331 PurpleKeyValuePair *purple_media_codec_get_optional_parameter(
   332 		PurpleMediaCodec *codec, const gchar *name,
   333 		const gchar *value);
   334 
   335 /**
   336  * Copies a GList of PurpleMediaCodec and its contents.
   337  *
   338  * @param codecs The list of codecs to be copied.
   339  *
   340  * @return The copy of the GList.
   341  *
   342  * @since 2.6.0
   343  */
   344 GList *purple_media_codec_list_copy(GList *codecs);
   345 
   346 /**
   347  * Frees a GList of PurpleMediaCodec and its contents.
   348  *
   349  * @param codecs The list of codecs to be freed.
   350  *
   351  * @since 2.6.0
   352  */
   353 void purple_media_codec_list_free(GList *codecs);
   354 
   355 /**
   356  * Gets a list of session IDs.
   357  *
   358  * @param media The media session from which to retrieve session IDs.
   359  *
   360  * @return GList of session IDs. The caller must free the list.
   361  *
   362  * @since 2.6.0
   363  */
   364 GList *purple_media_get_session_ids(PurpleMedia *media);
   365 
   366 /**
   367  * Gets the PurpleAccount this media session is on.
   368  *
   369  * @param media The media session to retrieve the account from.
   370  *
   371  * @return The account retrieved.
   372  *
   373  * @since 2.6.0
   374  */
   375 PurpleAccount *purple_media_get_account(PurpleMedia *media);
   376 
   377 /**
   378  * Gets the prpl data from the media session.
   379  *
   380  * @param media The media session to retrieve the prpl data from.
   381  *
   382  * @return The prpl data retrieved.
   383  *
   384  * @since 2.6.0
   385  */
   386 gpointer purple_media_get_prpl_data(PurpleMedia *media);
   387 
   388 /**
   389  * Sets the prpl data on the media session.
   390  *
   391  * @param media The media session to set the prpl data on.
   392  * @param prpl_data The data to set on the media session.
   393  *
   394  * @since 2.6.0
   395  */
   396 void purple_media_set_prpl_data(PurpleMedia *media, gpointer prpl_data);
   397 
   398 /**
   399  * Signals an error in the media session.
   400  *
   401  * @param media The media object to set the state on.
   402  * @param error The format of the error message to send in the signal.
   403  * @param ... The arguments to plug into the format.
   404  *
   405  * @since 2.6.0
   406  */
   407 void purple_media_error(PurpleMedia *media, const gchar *error, ...);
   408 
   409 /**
   410  * Ends all streams that match the given parameters
   411  *
   412  * @param media The media object with which to end streams.
   413  * @param session_id The session to end streams on.
   414  * @param participant The participant to end streams with.
   415  *
   416  * @since 2.6.0
   417  */
   418 void purple_media_end(PurpleMedia *media, const gchar *session_id,
   419 		const gchar *participant);
   420 
   421 /**
   422  * Signals different information about the given stream.
   423  *
   424  * @param media The media instance to containing the stream to signal.
   425  * @param type The type of info being signaled.
   426  * @param session_id The id of the session of the stream being signaled.
   427  * @param participant The participant of the stream being signaled.
   428  * @param local TRUE if the info originated locally, FALSE if on the remote end.
   429  *
   430  * @since 2.6.0
   431  */
   432 void purple_media_stream_info(PurpleMedia *media, PurpleMediaInfoType type,
   433 		const gchar *session_id, const gchar *participant,
   434 		gboolean local);
   435 
   436 /**
   437  * Adds a stream to a session.
   438  *
   439  * It only adds a stream to one audio session or video session as
   440  * the @c sess_id must be unique between sessions.
   441  *
   442  * @param media The media object to find the session in.
   443  * @param sess_id The session id of the session to add the stream to.
   444  * @param who The name of the remote user to add the stream for.
   445  * @param type The type of stream to create.
   446  * @param initiator Whether or not the local user initiated the stream.
   447  * @param transmitter The transmitter to use for the stream.
   448  * @param num_params The number of parameters to pass to Farsight.
   449  * @param params The parameters to pass to Farsight.
   450  *
   451  * @return @c TRUE The stream was added successfully, @c FALSE otherwise.
   452  *
   453  * @since 2.6.0
   454  */
   455 gboolean purple_media_add_stream(PurpleMedia *media, const gchar *sess_id,
   456 		const gchar *who, PurpleMediaSessionType type,
   457 		gboolean initiator, const gchar *transmitter,
   458 		guint num_params, GParameter *params);
   459 
   460 /**
   461  * Gets the session type from a session
   462  *
   463  * @param media The media object to find the session in.
   464  * @param sess_id The session id of the session to get the type from.
   465  *
   466  * @return The retreived session type.
   467  *
   468  * @since 2.6.0
   469  */
   470 PurpleMediaSessionType purple_media_get_session_type(PurpleMedia *media, const gchar *sess_id);
   471 
   472 /**
   473  * Gets the PurpleMediaManager this media session is a part of.
   474  *
   475  * @param media The media object to get the manager instance from.
   476  *
   477  * @return The PurpleMediaManager instance retrieved.
   478  *
   479  * @since 2.6.0
   480  */
   481 struct _PurpleMediaManager *purple_media_get_manager(PurpleMedia *media);
   482 
   483 /**
   484  * Gets the codecs from a session.
   485  *
   486  * @param media The media object to find the session in.
   487  * @param sess_id The session id of the session to get the codecs from.
   488  *
   489  * @return The retreieved codecs.
   490  *
   491  * @since 2.6.0
   492  */
   493 GList *purple_media_get_codecs(PurpleMedia *media, const gchar *sess_id);
   494 
   495 /**
   496  * Adds remote candidates to the stream.
   497  *
   498  * @param media The media object to find the session in.
   499  * @param sess_id The session id of the session find the stream in.
   500  * @param participant The name of the remote user to add the candidates for.
   501  * @param remote_candidates The remote candidates to add.
   502  *
   503  * @since 2.6.0
   504  */
   505 void purple_media_add_remote_candidates(PurpleMedia *media,
   506 					const gchar *sess_id,
   507 					const gchar *participant,
   508 					GList *remote_candidates);
   509 
   510 /**
   511  * Gets the local candidates from a stream.
   512  *
   513  * @param media The media object to find the session in.
   514  * @param sess_id The session id of the session to find the stream in.
   515  * @param participant The name of the remote user to get the candidates from.
   516  *
   517  * @since 2.6.0
   518  */
   519 GList *purple_media_get_local_candidates(PurpleMedia *media,
   520 					 const gchar *sess_id,
   521 					 const gchar *participant);
   522 
   523 #if 0
   524 /*
   525  * These two functions aren't being used and I'd rather not lock in the API
   526  * until they are needed. If they ever are.
   527  */
   528 
   529 /**
   530  * Gets the active local candidates for the stream.
   531  *
   532  * @param media The media object to find the session in.
   533  * @param sess_id The session id of the session to find the stream in.
   534  * @param participant The name of the remote user to get the active candidate
   535  *                    from.
   536  *
   537  * @return The active candidates retrieved.
   538  */
   539 GList *purple_media_get_active_local_candidates(PurpleMedia *media,
   540 		const gchar *sess_id, const gchar *participant);
   541 
   542 /**
   543  * Gets the active remote candidates for the stream.
   544  *
   545  * @param media The media object to find the session in.
   546  * @param sess_id The session id of the session to find the stream in.
   547  * @param participant The name of the remote user to get the remote candidate
   548  *                    from.
   549  *
   550  * @return The remote candidates retrieved.
   551  */
   552 GList *purple_media_get_active_remote_candidates(PurpleMedia *media,
   553 		const gchar *sess_id, const gchar *participant);
   554 #endif
   555 
   556 /**
   557  * Sets remote candidates from the stream.
   558  *
   559  * @param media The media object to find the session in.
   560  * @param sess_id The session id of the session find the stream in.
   561  * @param participant The name of the remote user to set the candidates from.
   562  *
   563  * @return @c TRUE The codecs were set successfully, or @c FALSE otherwise.
   564  *
   565  * @since 2.6.0
   566  */
   567 gboolean purple_media_set_remote_codecs(PurpleMedia *media, const gchar *sess_id,
   568 					const gchar *participant, GList *codecs);
   569 
   570 /**
   571  * Returns whether or not the candidates for set of streams are prepared
   572  *
   573  * @param media The media object to find the remote user in.
   574  * @param session_id The session id of the session to check.
   575  * @param participant The remote user to check for.
   576  *
   577  * @return @c TRUE All streams for the given session_id/participant combination have candidates prepared, @c FALSE otherwise.
   578  *
   579  * @since 2.6.0
   580  */
   581 gboolean purple_media_candidates_prepared(PurpleMedia *media,
   582 		const gchar *session_id, const gchar *participant);
   583 
   584 /**
   585  * Sets the send codec for the a session.
   586  *
   587  * @param media The media object to find the session in.
   588  * @param sess_id The session id of the session to set the codec for.
   589  * @param codec The codec to set the session to stream.
   590  *
   591  * @return @c TRUE The codec was successfully changed, or @c FALSE otherwise.
   592  *
   593  * @since 2.6.0
   594  */
   595 gboolean purple_media_set_send_codec(PurpleMedia *media, const gchar *sess_id, PurpleMediaCodec *codec);
   596 
   597 /**
   598  * Gets whether a session's codecs are ready to be used.
   599  *
   600  * @param media The media object to find the session in.
   601  * @param sess_id The session id of the session to check.
   602  *
   603  * @return @c TRUE The codecs are ready, or @c FALSE otherwise.
   604  *
   605  * @since 2.6.0
   606  */
   607 gboolean purple_media_codecs_ready(PurpleMedia *media, const gchar *sess_id);
   608 
   609 /**
   610  * Gets whether the local user is the conference/session/stream's initiator.
   611  *
   612  * @param media The media instance to find the session in.
   613  * @param sess_id The session id of the session to check.
   614  * @param participant The participant of the stream to check.
   615  *
   616  * @return TRUE if the local user is the stream's initator, else FALSE.
   617  *
   618  * @since 2.6.0
   619  */
   620 gboolean purple_media_is_initiator(PurpleMedia *media,
   621 		const gchar *sess_id, const gchar *participant);
   622 
   623 /**
   624  * Gets whether a streams selected have been accepted.
   625  *
   626  * @param media The media object to find the session in.
   627  * @param sess_id The session id of the session to check.
   628  * @param participant The participant to check.
   629  *
   630  * @return @c TRUE The selected streams have been accepted, or @c FALSE otherwise.
   631  *
   632  * @since 2.6.0
   633  */
   634 gboolean purple_media_accepted(PurpleMedia *media, const gchar *sess_id,
   635 		const gchar *participant);
   636 
   637 /**
   638  * Sets the input volume of all the selected sessions.
   639  *
   640  * @param media The media object the sessions are in.
   641  * @param session_id The session to select (if any).
   642  * @param level The level to set the volume to.
   643  *
   644  * @since 2.6.0
   645  */
   646 void purple_media_set_input_volume(PurpleMedia *media, const gchar *session_id, double level);
   647 
   648 /**
   649  * Sets the output volume of all the selected streams.
   650  *
   651  * @param media The media object the streams are in.
   652  * @param session_id The session to limit the streams to (if any).
   653  * @param participant The participant to limit the streams to (if any).
   654  * @param level The level to set the volume to.
   655  *
   656  * @since 2.6.0
   657  */
   658 void purple_media_set_output_volume(PurpleMedia *media, const gchar *session_id,
   659 		const gchar *participant, double level);
   660 
   661 /**
   662  * Sets a video output window for the given session/stream.
   663  *
   664  * @param media The media instance to set the output window on.
   665  * @param session_id The session to set the output window on.
   666  * @param participant Optionally, the participant to set the output window on.
   667  * @param window_id The window id use for embedding the video in.
   668  *
   669  * @return An id to reference the output window.
   670  *
   671  * @since 2.6.0
   672  */
   673 gulong purple_media_set_output_window(PurpleMedia *media,
   674 		const gchar *session_id, const gchar *participant,
   675 		gulong window_id);
   676 
   677 /**
   678  * Removes all output windows from a given media session.
   679  *
   680  * @param media The instance to remove all output windows from.
   681  *
   682  * @since 2.6.0
   683  */
   684 void purple_media_remove_output_windows(PurpleMedia *media);
   685 
   686 #ifdef __cplusplus
   687 }
   688 #endif
   689 
   690 G_END_DECLS
   691 
   692 #endif  /* _PURPLE_MEDIA_H_ */