libpurple/media.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_MEDIA_H
  23 #define PURPLE_MEDIA_H
  24 /**
  25  * SECTION:media
  26  * @section_id: libpurple-media
  27  * @short_description: <filename>media.h</filename>
  28  * @title: Media Object API
  29  */
  30
  31 #include <glib.h>
  32 #include <glib-object.h>
  33
  34 typedef struct _PurpleMedia PurpleMedia;
  35
  36 #include "media/candidate.h"
  37 #include "media/codec.h"
  38 #include "media/enum-types.h"
  39
  40 #define PURPLE_TYPE_MEDIA            (purple_media_get_type())
  41 #define PURPLE_MEDIA(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA, PurpleMedia))
  42 #define PURPLE_MEDIA_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA, PurpleMediaClass))
  43 #define PURPLE_IS_MEDIA(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA))
  44 #define PURPLE_IS_MEDIA_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA))
  45 #define PURPLE_MEDIA_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA, PurpleMediaClass))
  46
  47 #include "signals.h"
  48 #include "util.h"
  49
  50 #ifdef USE_VV
  51
  52 typedef struct _PurpleMediaClass    PurpleMediaClass;
  53 typedef struct _PurpleMediaPrivate  PurpleMediaPrivate;
  54
  55 /**
  56  * PurpleMedia:
  57  *
  58  * The media instance
  59  */
  60 struct _PurpleMedia
  61 {
  62         GObject parent;
  63
  64         /*< private >*/
  65         PurpleMediaPrivate *priv;
  66 };
  67
  68 /**
  69  * PurpleMediaClass:
  70  *
  71  * The media class
  72  */
  73 struct _PurpleMediaClass
  74 {
  75         GObjectClass parent_class;
  76
  77         /*< private >*/
  78         void (*purple_reserved1)(void);
  79         void (*purple_reserved2)(void);
  80         void (*purple_reserved3)(void);
  81         void (*purple_reserved4)(void);
  82 };
  83
  84 #endif
  85
  86 G_BEGIN_DECLS
  87
  88 /**
  89  * purple_media_get_type:
  90  *
  91  * Gets the media class's GType
  92  *
  93  * Returns: The media class's GType.
  94  */
  95 GType purple_media_get_type(void);
  96
  97 /**
  98  * purple_media_get_session_ids:
  99  * @media: The media session from which to retrieve session IDs.
 100  *
 101  * Gets a list of session IDs.
 102  *
 103  * Returns: (element-type utf8) (transfer container): List of session IDs.
 104  */
 105 GList *purple_media_get_session_ids(PurpleMedia *media);
 106
 107 /**
 108  * purple_media_get_account:
 109  * @media: The media session to retrieve the account from.
 110  *
 111  * Gets the PurpleAccount this media session is on.
 112  *
 113  * Returns: (transfer none): The account retrieved.
 114  */
 115 PurpleAccount *purple_media_get_account(PurpleMedia *media);
 116
 117 /**
 118  * purple_media_get_protocol_data:
 119  * @media: The media session to retrieve the protocol data from.
 120  *
 121  * Gets the protocol data from the media session.
 122  *
 123  * Returns: The protocol data retrieved.
 124  */
 125 gpointer purple_media_get_protocol_data(PurpleMedia *media);
 126
 127 /**
 128  * purple_media_set_protocol_data:
 129  * @media: The media session to set the protocol data on.
 130  * @protocol_data: The data to set on the media session.
 131  *
 132  * Sets the protocol data on the media session.
 133  */
 134 void purple_media_set_protocol_data(PurpleMedia *media, gpointer protocol_data);
 135
 136 /**
 137  * purple_media_error:
 138  * @media: The media object to set the state on.
 139  * @error: The format of the error message to send in the signal.
 140  * @...: The arguments to plug into the format.
 141  *
 142  * Signals an error in the media session.
 143  */
 144 void purple_media_error(PurpleMedia *media, const gchar *error, ...);
 145
 146 /**
 147  * purple_media_end:
 148  * @media: The media object with which to end streams.
 149  * @session_id: The session to end streams on.
 150  * @participant: The participant to end streams with.
 151  *
 152  * Ends all streams that match the given parameters
 153  */
 154 void purple_media_end(PurpleMedia *media, const gchar *session_id,
 155                 const gchar *participant);
 156
 157 /**
 158  * purple_media_stream_info:
 159  * @media: The media instance to containing the stream to signal.
 160  * @type: The type of info being signaled.
 161  * @session_id: The id of the session of the stream being signaled.
 162  * @participant: The participant of the stream being signaled.
 163  * @local: TRUE if the info originated locally, FALSE if on the remote end.
 164  *
 165  * Signals different information about the given stream.
 166  */
 167 void purple_media_stream_info(PurpleMedia *media, PurpleMediaInfoType type,
 168                 const gchar *session_id, const gchar *participant,
 169                 gboolean local);
 170
 171 /**
 172  * purple_media_set_params:
 173  * @media: The media object to set the parameters on.
 174  * @num_params: The number of parameters to pass
 175  * @params: Array of @c GParameter to pass
 176  *
 177  * Sets various optional parameters of the media call.
 178  *
 179  * Currently supported are:
 180  *   - "sdes-cname"    : The CNAME for the RTP sessions
 181  *   - "sdes-name"     : Real name used to describe the source in SDES messages
 182  *   - "sdes-tool"     : The TOOL to put in SDES messages
 183  *   - "sdes-email"    : Email address to put in SDES messages
 184  *   - "sdes-location" : The LOCATION to put in SDES messages
 185  *   - "sdes-note"     : The NOTE to put in SDES messages
 186  *   - "sdes-phone"    : The PHONE to put in SDES messages
 187  */
 188 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 189 void purple_media_set_params(PurpleMedia *media,
 190                 guint num_params, GParameter *params);
 191 G_GNUC_END_IGNORE_DEPRECATIONS
 192
 193 /**
 194  * purple_media_get_available_params:
 195  * @media: The media object
 196  *
 197  * Gets the list of optional parameters supported by the media backend.
 198  *
 199  * The list is owned by the #PurpleMedia internals and should NOT be freed.
 200  *
 201  * Returns: (array zero-terminated=1) (transfer none): Names of supported
 202  *          parameters.
 203  */
 204 const gchar **purple_media_get_available_params(PurpleMedia *media);
 205
 206 /**
 207  * purple_media_param_is_supported:
 208  * @media: The media object
 209  * @param: name of parameter
 210  *
 211  * Checks if given optional parameter is supported by the media backend.
 212  *
 213  * Returns: %TRUE if backend recognizes the parameter, %FALSE otherwise.
 214  */
 215 gboolean purple_media_param_is_supported(PurpleMedia *media, const gchar *param);
 216
 217 /**
 218  * purple_media_add_stream:
 219  * @media: The media object to find the session in.
 220  * @sess_id: The session id of the session to add the stream to.
 221  * @who: The name of the remote user to add the stream for.
 222  * @type: The type of stream to create.
 223  * @initiator: Whether or not the local user initiated the stream.
 224  * @transmitter: The transmitter to use for the stream.
 225  * @num_params: The number of parameters to pass to Farstream.
 226  * @params: The parameters to pass to Farstream.
 227  *
 228  * Adds a stream to a session.
 229  *
 230  * It only adds a stream to one audio session or video session as
 231  * the @sess_id must be unique between sessions.
 232  *
 233  * Returns: %TRUE The stream was added successfully, %FALSE otherwise.
 234  */
 235 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 236 gboolean purple_media_add_stream(PurpleMedia *media, const gchar *sess_id,
 237                 const gchar *who, PurpleMediaSessionType type,
 238                 gboolean initiator, const gchar *transmitter,
 239                 guint num_params, GParameter *params);
 240 G_GNUC_END_IGNORE_DEPRECATIONS
 241
 242 /**
 243  * purple_media_get_session_type:
 244  * @media: The media object to find the session in.
 245  * @sess_id: The session id of the session to get the type from.
 246  *
 247  * Gets the session type from a session
 248  *
 249  * Returns: The retreived session type.
 250  */
 251 PurpleMediaSessionType purple_media_get_session_type(PurpleMedia *media, const gchar *sess_id);
 252
 253 /**
 254  * purple_media_get_manager:
 255  * @media: The media object to get the manager instance from.
 256  *
 257  * Gets the PurpleMediaManager this media session is a part of.
 258  *
 259  * Returns: The PurpleMediaManager instance retrieved.
 260  */
 261 struct _PurpleMediaManager *purple_media_get_manager(PurpleMedia *media);
 262
 263 /**
 264  * purple_media_get_codecs:
 265  * @media: The media object to find the session in.
 266  * @sess_id: The session id of the session to get the codecs from.
 267  *
 268  * Gets the codecs from a session.
 269  *
 270  * Returns: (element-type PurpleMediaCodec) (transfer full): The retrieved
 271  *          codecs.
 272  */
 273 GList *purple_media_get_codecs(PurpleMedia *media, const gchar *sess_id);
 274
 275 /**
 276  * purple_media_add_remote_candidates:
 277  * @media: The media object to find the session in.
 278  * @sess_id: The session id of the session find the stream in.
 279  * @participant: The name of the remote user to add the candidates for.
 280  * @remote_candidates: (element-type PurpleMediaCandidate) (transfer none): The
 281  *                     remote candidates to add.
 282  *
 283  * Adds remote candidates to the stream.
 284  */
 285 void purple_media_add_remote_candidates(PurpleMedia *media,
 286                                         const gchar *sess_id,
 287                                         const gchar *participant,
 288                                         GList *remote_candidates);
 289
 290 /**
 291  * purple_media_get_local_candidates:
 292  * @media: The media object to find the session in.
 293  * @sess_id: The session id of the session to find the stream in.
 294  * @participant: The name of the remote user to get the candidates from.
 295  *
 296  * Gets the local candidates from a stream.
 297  *
 298  * Returns: (element-type PurpleMediaCandidate) (transfer full): The local
 299  *          candidates.
 300  */
 301 GList *purple_media_get_local_candidates(PurpleMedia *media,
 302                                          const gchar *sess_id,
 303                                          const gchar *participant);
 304
 305 /**
 306  * purple_media_get_active_local_candidates:
 307  * @media: The media object to find the session in.
 308  * @sess_id: The session id of the session to find the stream in.
 309  * @participant: The name of the remote user to get the active candidate
 310  *                    from.
 311  *
 312  * Gets the active local candidates for the stream.
 313  *
 314  * Returns: (element-type PurpleMediaCandidate) (transfer full): The active
 315  *          candidates retrieved.
 316  */
 317 GList *purple_media_get_active_local_candidates(PurpleMedia *media,
 318                 const gchar *sess_id, const gchar *participant);
 319
 320 /**
 321  * purple_media_get_active_remote_candidates:
 322  * @media: The media object to find the session in.
 323  * @sess_id: The session id of the session to find the stream in.
 324  * @participant: The name of the remote user to get the remote candidate
 325  *                    from.
 326  *
 327  * Gets the active remote candidates for the stream.
 328  *
 329  * Returns: (element-type PurpleMediaCandidate) (transfer full): The remote
 330  *          candidates retrieved.
 331  */
 332 GList *purple_media_get_active_remote_candidates(PurpleMedia *media,
 333                 const gchar *sess_id, const gchar *participant);
 334
 335 /**
 336  * purple_media_set_remote_codecs:
 337  * @media: The media object to find the session in.
 338  * @sess_id: The session id of the session find the stream in.
 339  * @participant: The name of the remote user to set the codecs for.
 340  * @codecs: (element-type PurpleMediaCodec) (transfer none): The list of remote
 341  *          codecs to set.
 342  *
 343  * Sets remote codecs from the stream.
 344  *
 345  * Returns: %TRUE The codecs were set successfully, or %FALSE otherwise.
 346  */
 347 gboolean purple_media_set_remote_codecs(PurpleMedia *media, const gchar *sess_id,
 348                                         const gchar *participant, GList *codecs);
 349
 350 /**
 351  * purple_media_candidates_prepared:
 352  * @media: The media object to find the remote user in.
 353  * @session_id: The session id of the session to check.
 354  * @participant: The remote user to check for.
 355  *
 356  * Returns whether or not the candidates for set of streams are prepared
 357  *
 358  * Returns: %TRUE All streams for the given session_id/participant combination have candidates prepared, %FALSE otherwise.
 359  */
 360 gboolean purple_media_candidates_prepared(PurpleMedia *media,
 361                 const gchar *session_id, const gchar *participant);
 362
 363 /**
 364  * purple_media_set_send_codec:
 365  * @media: The media object to find the session in.
 366  * @sess_id: The session id of the session to set the codec for.
 367  * @codec: The codec to set the session to stream.
 368  *
 369  * Sets the send codec for the a session.
 370  *
 371  * Returns: %TRUE The codec was successfully changed, or %FALSE otherwise.
 372  */
 373 gboolean purple_media_set_send_codec(PurpleMedia *media, const gchar *sess_id, PurpleMediaCodec *codec);
 374
 375 /**
 376  * purple_media_set_encryption_parameters:
 377  * @media: The media object to find the session in.
 378  * @sess_id: The session id of the session to set parameters of.
 379  * @cipher: The cipher to use to encrypt our media in the session.
 380  * @auth: The algorithm to use to compute authentication codes for our media
 381  *        frames.
 382  * @key: The encryption key.
 383  * @key_len: Byte length of the encryption key.
 384  *
 385  * Sets the encryption parameters of our media in the session.
 386  */
 387 gboolean purple_media_set_encryption_parameters(PurpleMedia *media,
 388                 const gchar *sess_id, const gchar *cipher,
 389                 const gchar *auth, const gchar *key, gsize key_len);
 390
 391 /**
 392  * purple_media_set_decryption_parameters:
 393  * @media: The media object to find the session in.
 394  * @sess_id: The session id of the session to set parameters of.
 395  * @participant: The participant of the session to set parameters of.
 396  * @cipher: The cipher to use to decrypt media coming from this session's
 397  *          participant.
 398  * @auth: The algorithm to use for authentication of the media coming from
 399  *        the session's participant.
 400  * @key: The decryption key.
 401  * @key_len: Byte length of the decryption key.
 402  *
 403  * Sets the decryption parameters for a session participant's media.
 404  */
 405 gboolean purple_media_set_decryption_parameters(PurpleMedia *media,
 406                 const gchar *sess_id, const gchar *participant,
 407                 const gchar *cipher, const gchar *auth,
 408                 const gchar *key, gsize key_len);
 409
 410 /**
 411  * purple_media_codecs_ready:
 412  * @media: The media object to find the session in.
 413  * @sess_id: The session id of the session to check.
 414  *
 415  * Gets whether a session's codecs are ready to be used.
 416  *
 417  * Returns: %TRUE The codecs are ready, or %FALSE otherwise.
 418  */
 419 gboolean purple_media_codecs_ready(PurpleMedia *media, const gchar *sess_id);
 420
 421 /**
 422  * purple_media_set_send_rtcp_mux:
 423  * @media: The media object to find the session in.
 424  * @sess_id: The session id of the session find the stream in.
 425  * @participant: The name of the remote user to set the rtcp-mux for.
 426  * @send_rtcp_mux: Whether to enable the rtcp-mux option
 427  *
 428  * Sets the rtcp-mux option for the stream.
 429  *
 430  * Returns: %TRUE RTCP-Mux was set successfully, or %FALSE otherwise.
 431  *
 432  * @since 2.11.0
 433  */
 434 gboolean purple_media_set_send_rtcp_mux(PurpleMedia *media,
 435                 const gchar *sess_id, const gchar *participant, gboolean send_rtcp_mux);
 436 /**
 437  * purple_media_is_initiator:
 438  * @media: The media instance to find the session in.
 439  * @sess_id: The session id of the session to check.
 440  * @participant: The participant of the stream to check.
 441  *
 442  * Gets whether the local user is the conference/session/stream's initiator.
 443  *
 444  * Returns: TRUE if the local user is the stream's initator, else FALSE.
 445  */
 446 gboolean purple_media_is_initiator(PurpleMedia *media,
 447                 const gchar *sess_id, const gchar *participant);
 448
 449 /**
 450  * purple_media_accepted:
 451  * @media: The media object to find the session in.
 452  * @sess_id: The session id of the session to check.
 453  * @participant: The participant to check.
 454  *
 455  * Gets whether a streams selected have been accepted.
 456  *
 457  * Returns: %TRUE The selected streams have been accepted, or %FALSE otherwise.
 458  */
 459 gboolean purple_media_accepted(PurpleMedia *media, const gchar *sess_id,
 460                 const gchar *participant);
 461
 462 /**
 463  * purple_media_set_input_volume:
 464  * @media: The media object the sessions are in.
 465  * @session_id: The session to select (if any).
 466  * @level: The level to set the volume to.
 467  *
 468  * Sets the input volume of all the selected sessions.
 469  */
 470 void purple_media_set_input_volume(PurpleMedia *media, const gchar *session_id, double level);
 471
 472 /**
 473  * purple_media_set_output_volume:
 474  * @media: The media object the streams are in.
 475  * @session_id: The session to limit the streams to (if any).
 476  * @participant: The participant to limit the streams to (if any).
 477  * @level: The level to set the volume to.
 478  *
 479  * Sets the output volume of all the selected streams.
 480  */
 481 void purple_media_set_output_volume(PurpleMedia *media, const gchar *session_id,
 482                 const gchar *participant, double level);
 483
 484 /**
 485  * purple_media_set_output_window:
 486  * @media: The media instance to set the output window on.
 487  * @session_id: The session to set the output window on.
 488  * @participant: Optionally, the participant to set the output window on.
 489  * @window_id: The window id use for embedding the video in.
 490  *
 491  * Sets a video output window for the given session/stream.
 492  *
 493  * Returns: An id to reference the output window.
 494  */
 495 gulong purple_media_set_output_window(PurpleMedia *media,
 496                 const gchar *session_id, const gchar *participant,
 497                 gulong window_id);
 498
 499 /**
 500  * purple_media_remove_output_windows:
 501  * @media: The instance to remove all output windows from.
 502  *
 503  * Removes all output windows from a given media session.
 504  */
 505 void purple_media_remove_output_windows(PurpleMedia *media);
 506
 507 /**
 508  * purple_media_send_dtmf:
 509  * @media: The media instance to send a DTMF signal to.
 510  * @session_id: The session id of the session to send the DTMF signal on.
 511  * @dtmf: The character representing the DTMF in the range [0-9#*A-D].
 512  * @volume: The power level expressed in dBm0 after dropping the sign in the
 513  *          range of 0 to 63.  A larger value represents a lower volume.
 514  * @duration: The duration of the tone in milliseconds.
 515  *
 516  * Sends a DTMF signal out-of-band.
 517  *
 518  * Returns: %TRUE DTMF sent successfully, or %FALSE otherwise.
 519  */
 520 gboolean purple_media_send_dtmf(PurpleMedia *media, const gchar *session_id,
 521                 gchar dtmf, guint8 volume, guint16 duration);
 522
 523 G_END_DECLS
 524
 525 #endif /* PURPLE_MEDIA_H */