libpurple/media.h

   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., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26
  27 #ifndef _PURPLE_MEDIA_H_
  28 #define _PURPLE_MEDIA_H_
  29
  30 #include "media/candidate.h"
  31 #include "media/codec.h"
  32 #include "media/enum-types.h"
  33
  34 #include <glib.h>
  35 #include <glib-object.h>
  36
  37 G_BEGIN_DECLS
  38
  39 #define PURPLE_TYPE_MEDIA            (purple_media_get_type())
  40 #define PURPLE_MEDIA(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA, PurpleMedia))
  41 #define PURPLE_MEDIA_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA, PurpleMediaClass))
  42 #define PURPLE_IS_MEDIA(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA))
  43 #define PURPLE_IS_MEDIA_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA))
  44 #define PURPLE_MEDIA_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA, PurpleMediaClass))
  45
  46 /** An opaque structure representing a media call. */
  47 typedef struct _PurpleMedia PurpleMedia;
  48
  49 #include "signals.h"
  50 #include "util.h"
  51
  52 #ifdef __cplusplus
  53 extern "C" {
  54 #endif
  55
  56 /**
  57  * Gets the media class's GType
  58  *
  59  * @return The media class's GType.
  60  *
  61  * @since 2.6.0
  62  */
  63 GType purple_media_get_type(void);
  64
  65 /**
  66  * Gets a list of session IDs.
  67  *
  68  * @param media The media session from which to retrieve session IDs.
  69  *
  70  * @return GList of session IDs. The caller must free the list.
  71  *
  72  * @since 2.6.0
  73  */
  74 GList *purple_media_get_session_ids(PurpleMedia *media);
  75
  76 /**
  77  * Gets the PurpleAccount this media session is on.
  78  *
  79  * @param media The media session to retrieve the account from.
  80  *
  81  * @return The account retrieved.
  82  *
  83  * @since 2.6.0
  84  */
  85 PurpleAccount *purple_media_get_account(PurpleMedia *media);
  86
  87 /**
  88  * Gets the prpl data from the media session.
  89  *
  90  * @param media The media session to retrieve the prpl data from.
  91  *
  92  * @return The prpl data retrieved.
  93  *
  94  * @since 2.6.0
  95  */
  96 gpointer purple_media_get_prpl_data(PurpleMedia *media);
  97
  98 /**
  99  * Sets the prpl data on the media session.
 100  *
 101  * @param media The media session to set the prpl data on.
 102  * @param prpl_data The data to set on the media session.
 103  *
 104  * @since 2.6.0
 105  */
 106 void purple_media_set_prpl_data(PurpleMedia *media, gpointer prpl_data);
 107
 108 /**
 109  * Signals an error in the media session.
 110  *
 111  * @param media The media object to set the state on.
 112  * @param error The format of the error message to send in the signal.
 113  * @param ... The arguments to plug into the format.
 114  *
 115  * @since 2.6.0
 116  */
 117 void purple_media_error(PurpleMedia *media, const gchar *error, ...);
 118
 119 /**
 120  * Ends all streams that match the given parameters
 121  *
 122  * @param media The media object with which to end streams.
 123  * @param session_id The session to end streams on.
 124  * @param participant The participant to end streams with.
 125  *
 126  * @since 2.6.0
 127  */
 128 void purple_media_end(PurpleMedia *media, const gchar *session_id,
 129                 const gchar *participant);
 130
 131 /**
 132  * Signals different information about the given stream.
 133  *
 134  * @param media The media instance to containing the stream to signal.
 135  * @param type The type of info being signaled.
 136  * @param session_id The id of the session of the stream being signaled.
 137  * @param participant The participant of the stream being signaled.
 138  * @param local TRUE if the info originated locally, FALSE if on the remote end.
 139  *
 140  * @since 2.6.0
 141  */
 142 void purple_media_stream_info(PurpleMedia *media, PurpleMediaInfoType type,
 143                 const gchar *session_id, const gchar *participant,
 144                 gboolean local);
 145
 146 /**
 147  * Sets various optional parameters of the media call.
 148  *
 149  * Currently supported are:
 150  *   - "sdes-cname"    : The CNAME for the RTP sessions
 151  *   - "sdes-name"     : Real name used to describe the source in SDES messages
 152  *   - "sdes-tool"     : The TOOL to put in SDES messages
 153  *   - "sdes-email"    : Email address to put in SDES messages
 154  *   - "sdes-location" : The LOCATION to put in SDES messages
 155  *   - "sdes-note"     : The NOTE to put in SDES messages
 156  *   - "sdes-phone"    : The PHONE to put in SDES messages
 157  *
 158  * @param media The media object to set the parameters on.
 159  * @param num_params The number of parameters to pass
 160  * @param params Array of @c GParameter to pass
 161  *
 162  * @since 2.8.0
 163  */
 164 void purple_media_set_params(PurpleMedia *media,
 165                 guint num_params, GParameter *params);
 166
 167 /**
 168  * Gets the list of optional parameters supported by the media backend.
 169  *
 170  * The list is owned by the @c PurpleMedia internals and should NOT be freed.
 171  *
 172  * @param media The media object
 173  *
 174  * @return NULL-terminated array of names of supported parameters.
 175  *
 176  * @since 2.8.0
 177  */
 178 const gchar **purple_media_get_available_params(PurpleMedia *media);
 179
 180 /**
 181  * Checks if given optional parameter is supported by the media backend.
 182  *
 183  * @param media The media object
 184  * @param param name of parameter
 185  *
 186  * @return @c TRUE if backend recognizes the parameter, @c FALSE otherwise.
 187  *
 188  * @since 2.8.0
 189  */
 190 gboolean purple_media_param_is_supported(PurpleMedia *media, const gchar *param);
 191
 192 /**
 193  * Adds a stream to a session.
 194  *
 195  * It only adds a stream to one audio session or video session as
 196  * the @c sess_id must be unique between sessions.
 197  *
 198  * @param media The media object to find the session in.
 199  * @param sess_id The session id of the session to add the stream to.
 200  * @param who The name of the remote user to add the stream for.
 201  * @param type The type of stream to create.
 202  * @param initiator Whether or not the local user initiated the stream.
 203  * @param transmitter The transmitter to use for the stream.
 204  * @param num_params The number of parameters to pass to Farsight.
 205  * @param params The parameters to pass to Farsight.
 206  *
 207  * @return @c TRUE The stream was added successfully, @c FALSE otherwise.
 208  *
 209  * @since 2.6.0
 210  */
 211 gboolean purple_media_add_stream(PurpleMedia *media, const gchar *sess_id,
 212                 const gchar *who, PurpleMediaSessionType type,
 213                 gboolean initiator, const gchar *transmitter,
 214                 guint num_params, GParameter *params);
 215
 216 /**
 217  * Gets the session type from a session
 218  *
 219  * @param media The media object to find the session in.
 220  * @param sess_id The session id of the session to get the type from.
 221  *
 222  * @return The retreived session type.
 223  *
 224  * @since 2.6.0
 225  */
 226 PurpleMediaSessionType purple_media_get_session_type(PurpleMedia *media, const gchar *sess_id);
 227
 228 /**
 229  * Gets the PurpleMediaManager this media session is a part of.
 230  *
 231  * @param media The media object to get the manager instance from.
 232  *
 233  * @return The PurpleMediaManager instance retrieved.
 234  *
 235  * @since 2.6.0
 236  */
 237 struct _PurpleMediaManager *purple_media_get_manager(PurpleMedia *media);
 238
 239 /**
 240  * Gets the codecs from a session.
 241  *
 242  * @param media The media object to find the session in.
 243  * @param sess_id The session id of the session to get the codecs from.
 244  *
 245  * @return The retreieved codecs.
 246  *
 247  * @since 2.6.0
 248  */
 249 GList *purple_media_get_codecs(PurpleMedia *media, const gchar *sess_id);
 250
 251 /**
 252  * Adds remote candidates to the stream.
 253  *
 254  * @param media The media object to find the session in.
 255  * @param sess_id The session id of the session find the stream in.
 256  * @param participant The name of the remote user to add the candidates for.
 257  * @param remote_candidates The remote candidates to add.
 258  *
 259  * @since 2.6.0
 260  */
 261 void purple_media_add_remote_candidates(PurpleMedia *media,
 262                                         const gchar *sess_id,
 263                                         const gchar *participant,
 264                                         GList *remote_candidates);
 265
 266 /**
 267  * Gets the local candidates from a stream.
 268  *
 269  * @param media The media object to find the session in.
 270  * @param sess_id The session id of the session to find the stream in.
 271  * @param participant The name of the remote user to get the candidates from.
 272  *
 273  * @since 2.6.0
 274  */
 275 GList *purple_media_get_local_candidates(PurpleMedia *media,
 276                                          const gchar *sess_id,
 277                                          const gchar *participant);
 278
 279 /**
 280  * Gets the active local candidates for the stream.
 281  *
 282  * @param media The media object to find the session in.
 283  * @param sess_id The session id of the session to find the stream in.
 284  * @param participant The name of the remote user to get the active candidate
 285  *                    from.
 286  *
 287  * @return The active candidates retrieved.
 288  *
 289  * @since 2.8.0
 290  */
 291 GList *purple_media_get_active_local_candidates(PurpleMedia *media,
 292                 const gchar *sess_id, const gchar *participant);
 293
 294 /**
 295  * Gets the active remote candidates for the stream.
 296  *
 297  * @param media The media object to find the session in.
 298  * @param sess_id The session id of the session to find the stream in.
 299  * @param participant The name of the remote user to get the remote candidate
 300  *                    from.
 301  *
 302  * @return The remote candidates retrieved.
 303  *
 304  * @since 2.8.0
 305  */
 306 GList *purple_media_get_active_remote_candidates(PurpleMedia *media,
 307                 const gchar *sess_id, const gchar *participant);
 308
 309 /**
 310  * Sets remote candidates from the stream.
 311  *
 312  * @param media The media object to find the session in.
 313  * @param sess_id The session id of the session find the stream in.
 314  * @param participant The name of the remote user to set the candidates from.
 315  * @param codecs The list of remote codecs to set.
 316  *
 317  * @return @c TRUE The codecs were set successfully, or @c FALSE otherwise.
 318  *
 319  * @since 2.6.0
 320  */
 321 gboolean purple_media_set_remote_codecs(PurpleMedia *media, const gchar *sess_id,
 322                                         const gchar *participant, GList *codecs);
 323
 324 /**
 325  * Returns whether or not the candidates for set of streams are prepared
 326  *
 327  * @param media The media object to find the remote user in.
 328  * @param session_id The session id of the session to check.
 329  * @param participant The remote user to check for.
 330  *
 331  * @return @c TRUE All streams for the given session_id/participant combination have candidates prepared, @c FALSE otherwise.
 332  *
 333  * @since 2.6.0
 334  */
 335 gboolean purple_media_candidates_prepared(PurpleMedia *media,
 336                 const gchar *session_id, const gchar *participant);
 337
 338 /**
 339  * Sets the send codec for the a session.
 340  *
 341  * @param media The media object to find the session in.
 342  * @param sess_id The session id of the session to set the codec for.
 343  * @param codec The codec to set the session to stream.
 344  *
 345  * @return @c TRUE The codec was successfully changed, or @c FALSE otherwise.
 346  *
 347  * @since 2.6.0
 348  */
 349 gboolean purple_media_set_send_codec(PurpleMedia *media, const gchar *sess_id, PurpleMediaCodec *codec);
 350
 351 /**
 352  * Gets whether a session's codecs are ready to be used.
 353  *
 354  * @param media The media object to find the session in.
 355  * @param sess_id The session id of the session to check.
 356  *
 357  * @return @c TRUE The codecs are ready, or @c FALSE otherwise.
 358  *
 359  * @since 2.6.0
 360  */
 361 gboolean purple_media_codecs_ready(PurpleMedia *media, const gchar *sess_id);
 362
 363 /**
 364  * Gets whether the local user is the conference/session/stream's initiator.
 365  *
 366  * @param media The media instance to find the session in.
 367  * @param sess_id The session id of the session to check.
 368  * @param participant The participant of the stream to check.
 369  *
 370  * @return TRUE if the local user is the stream's initator, else FALSE.
 371  *
 372  * @since 2.6.0
 373  */
 374 gboolean purple_media_is_initiator(PurpleMedia *media,
 375                 const gchar *sess_id, const gchar *participant);
 376
 377 /**
 378  * Gets whether a streams selected have been accepted.
 379  *
 380  * @param media The media object to find the session in.
 381  * @param sess_id The session id of the session to check.
 382  * @param participant The participant to check.
 383  *
 384  * @return @c TRUE The selected streams have been accepted, or @c FALSE otherwise.
 385  *
 386  * @since 2.6.0
 387  */
 388 gboolean purple_media_accepted(PurpleMedia *media, const gchar *sess_id,
 389                 const gchar *participant);
 390
 391 /**
 392  * Sets the input volume of all the selected sessions.
 393  *
 394  * @param media The media object the sessions are in.
 395  * @param session_id The session to select (if any).
 396  * @param level The level to set the volume to.
 397  *
 398  * @since 2.6.0
 399  */
 400 void purple_media_set_input_volume(PurpleMedia *media, const gchar *session_id, double level);
 401
 402 /**
 403  * Sets the output volume of all the selected streams.
 404  *
 405  * @param media The media object the streams are in.
 406  * @param session_id The session to limit the streams to (if any).
 407  * @param participant The participant to limit the streams to (if any).
 408  * @param level The level to set the volume to.
 409  *
 410  * @since 2.6.0
 411  */
 412 void purple_media_set_output_volume(PurpleMedia *media, const gchar *session_id,
 413                 const gchar *participant, double level);
 414
 415 /**
 416  * Sets a video output window for the given session/stream.
 417  *
 418  * @param media The media instance to set the output window on.
 419  * @param session_id The session to set the output window on.
 420  * @param participant Optionally, the participant to set the output window on.
 421  * @param window_id The window id use for embedding the video in.
 422  *
 423  * @return An id to reference the output window.
 424  *
 425  * @since 2.6.0
 426  */
 427 gulong purple_media_set_output_window(PurpleMedia *media,
 428                 const gchar *session_id, const gchar *participant,
 429                 gulong window_id);
 430
 431 /**
 432  * Removes all output windows from a given media session.
 433  *
 434  * @param media The instance to remove all output windows from.
 435  *
 436  * @since 2.6.0
 437  */
 438 void purple_media_remove_output_windows(PurpleMedia *media);
 439
 440 #ifdef __cplusplus
 441 }
 442 #endif
 443
 444 G_END_DECLS
 445
 446 #endif  /* _PURPLE_MEDIA_H_ */