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 void purple_media_set_params(PurpleMedia *media,
 189                 guint num_params, GParameter *params);
 190
 191 /**
 192  * purple_media_get_available_params:
 193  * @media: The media object
 194  *
 195  * Gets the list of optional parameters supported by the media backend.
 196  *
 197  * The list is owned by the #PurpleMedia internals and should NOT be freed.
 198  *
 199  * Returns: (array zero-terminated=1) (transfer none): Names of supported
 200  *          parameters.
 201  */
 202 const gchar **purple_media_get_available_params(PurpleMedia *media);
 203
 204 /**
 205  * purple_media_param_is_supported:
 206  * @media: The media object
 207  * @param: name of parameter
 208  *
 209  * Checks if given optional parameter is supported by the media backend.
 210  *
 211  * Returns: %TRUE if backend recognizes the parameter, %FALSE otherwise.
 212  */
 213 gboolean purple_media_param_is_supported(PurpleMedia *media, const gchar *param);
 214
 215 /**
 216  * purple_media_add_stream:
 217  * @media: The media object to find the session in.
 218  * @sess_id: The session id of the session to add the stream to.
 219  * @who: The name of the remote user to add the stream for.
 220  * @type: The type of stream to create.
 221  * @initiator: Whether or not the local user initiated the stream.
 222  * @transmitter: The transmitter to use for the stream.
 223  * @num_params: The number of parameters to pass to Farstream.
 224  * @params: The parameters to pass to Farstream.
 225  *
 226  * Adds a stream to a session.
 227  *
 228  * It only adds a stream to one audio session or video session as
 229  * the @sess_id must be unique between sessions.
 230  *
 231  * Returns: %TRUE The stream was added successfully, %FALSE otherwise.
 232  */
 233 gboolean purple_media_add_stream(PurpleMedia *media, const gchar *sess_id,
 234                 const gchar *who, PurpleMediaSessionType type,
 235                 gboolean initiator, const gchar *transmitter,
 236                 guint num_params, GParameter *params);
 237
 238 /**
 239  * purple_media_get_session_type:
 240  * @media: The media object to find the session in.
 241  * @sess_id: The session id of the session to get the type from.
 242  *
 243  * Gets the session type from a session
 244  *
 245  * Returns: The retreived session type.
 246  */
 247 PurpleMediaSessionType purple_media_get_session_type(PurpleMedia *media, const gchar *sess_id);
 248
 249 /**
 250  * purple_media_get_manager:
 251  * @media: The media object to get the manager instance from.
 252  *
 253  * Gets the PurpleMediaManager this media session is a part of.
 254  *
 255  * Returns: The PurpleMediaManager instance retrieved.
 256  */
 257 struct _PurpleMediaManager *purple_media_get_manager(PurpleMedia *media);
 258
 259 /**
 260  * purple_media_get_codecs:
 261  * @media: The media object to find the session in.
 262  * @sess_id: The session id of the session to get the codecs from.
 263  *
 264  * Gets the codecs from a session.
 265  *
 266  * Returns: (element-type PurpleMediaCodec) (transfer full): The retrieved
 267  *          codecs.
 268  */
 269 GList *purple_media_get_codecs(PurpleMedia *media, const gchar *sess_id);
 270
 271 /**
 272  * purple_media_add_remote_candidates:
 273  * @media: The media object to find the session in.
 274  * @sess_id: The session id of the session find the stream in.
 275  * @participant: The name of the remote user to add the candidates for.
 276  * @remote_candidates: (element-type PurpleMediaCandidate) (transfer none): The
 277  *                     remote candidates to add.
 278  *
 279  * Adds remote candidates to the stream.
 280  */
 281 void purple_media_add_remote_candidates(PurpleMedia *media,
 282                                         const gchar *sess_id,
 283                                         const gchar *participant,
 284                                         GList *remote_candidates);
 285
 286 /**
 287  * purple_media_get_local_candidates:
 288  * @media: The media object to find the session in.
 289  * @sess_id: The session id of the session to find the stream in.
 290  * @participant: The name of the remote user to get the candidates from.
 291  *
 292  * Gets the local candidates from a stream.
 293  *
 294  * Returns: (element-type PurpleMediaCandidate) (transfer full): The local
 295  *          candidates.
 296  */
 297 GList *purple_media_get_local_candidates(PurpleMedia *media,
 298                                          const gchar *sess_id,
 299                                          const gchar *participant);
 300
 301 /**
 302  * purple_media_get_active_local_candidates:
 303  * @media: The media object to find the session in.
 304  * @sess_id: The session id of the session to find the stream in.
 305  * @participant: The name of the remote user to get the active candidate
 306  *                    from.
 307  *
 308  * Gets the active local candidates for the stream.
 309  *
 310  * Returns: (element-type PurpleMediaCandidate) (transfer full): The active
 311  *          candidates retrieved.
 312  */
 313 GList *purple_media_get_active_local_candidates(PurpleMedia *media,
 314                 const gchar *sess_id, const gchar *participant);
 315
 316 /**
 317  * purple_media_get_active_remote_candidates:
 318  * @media: The media object to find the session in.
 319  * @sess_id: The session id of the session to find the stream in.
 320  * @participant: The name of the remote user to get the remote candidate
 321  *                    from.
 322  *
 323  * Gets the active remote candidates for the stream.
 324  *
 325  * Returns: (element-type PurpleMediaCandidate) (transfer full): The remote
 326  *          candidates retrieved.
 327  */
 328 GList *purple_media_get_active_remote_candidates(PurpleMedia *media,
 329                 const gchar *sess_id, const gchar *participant);
 330
 331 /**
 332  * purple_media_set_remote_codecs:
 333  * @media: The media object to find the session in.
 334  * @sess_id: The session id of the session find the stream in.
 335  * @participant: The name of the remote user to set the codecs for.
 336  * @codecs: (element-type PurpleMediaCodec) (transfer none): The list of remote
 337  *          codecs to set.
 338  *
 339  * Sets remote codecs from the stream.
 340  *
 341  * Returns: %TRUE The codecs were set successfully, or %FALSE otherwise.
 342  */
 343 gboolean purple_media_set_remote_codecs(PurpleMedia *media, const gchar *sess_id,
 344                                         const gchar *participant, GList *codecs);
 345
 346 /**
 347  * purple_media_candidates_prepared:
 348  * @media: The media object to find the remote user in.
 349  * @session_id: The session id of the session to check.
 350  * @participant: The remote user to check for.
 351  *
 352  * Returns whether or not the candidates for set of streams are prepared
 353  *
 354  * Returns: %TRUE All streams for the given session_id/participant combination have candidates prepared, %FALSE otherwise.
 355  */
 356 gboolean purple_media_candidates_prepared(PurpleMedia *media,
 357                 const gchar *session_id, const gchar *participant);
 358
 359 /**
 360  * purple_media_set_send_codec:
 361  * @media: The media object to find the session in.
 362  * @sess_id: The session id of the session to set the codec for.
 363  * @codec: The codec to set the session to stream.
 364  *
 365  * Sets the send codec for the a session.
 366  *
 367  * Returns: %TRUE The codec was successfully changed, or %FALSE otherwise.
 368  */
 369 gboolean purple_media_set_send_codec(PurpleMedia *media, const gchar *sess_id, PurpleMediaCodec *codec);
 370
 371 /**
 372  * purple_media_set_encryption_parameters:
 373  * @media: The media object to find the session in.
 374  * @sess_id: The session id of the session to set parameters of.
 375  * @cipher: The cipher to use to encrypt our media in the session.
 376  * @auth: The algorithm to use to compute authentication codes for our media
 377  *        frames.
 378  * @key: The encryption key.
 379  * @key_len: Byte length of the encryption key.
 380  *
 381  * Sets the encryption parameters of our media in the session.
 382  */
 383 gboolean purple_media_set_encryption_parameters(PurpleMedia *media,
 384                 const gchar *sess_id, const gchar *cipher,
 385                 const gchar *auth, const gchar *key, gsize key_len);
 386
 387 /**
 388  * purple_media_set_decryption_parameters:
 389  * @media: The media object to find the session in.
 390  * @sess_id: The session id of the session to set parameters of.
 391  * @participant: The participant of the session to set parameters of.
 392  * @cipher: The cipher to use to decrypt media coming from this session's
 393  *          participant.
 394  * @auth: The algorithm to use for authentication of the media coming from
 395  *        the session's participant.
 396  * @key: The decryption key.
 397  * @key_len: Byte length of the decryption key.
 398  *
 399  * Sets the decryption parameters for a session participant's media.
 400  */
 401 gboolean purple_media_set_decryption_parameters(PurpleMedia *media,
 402                 const gchar *sess_id, const gchar *participant,
 403                 const gchar *cipher, const gchar *auth,
 404                 const gchar *key, gsize key_len);
 405
 406 /**
 407  * purple_media_codecs_ready:
 408  * @media: The media object to find the session in.
 409  * @sess_id: The session id of the session to check.
 410  *
 411  * Gets whether a session's codecs are ready to be used.
 412  *
 413  * Returns: %TRUE The codecs are ready, or %FALSE otherwise.
 414  */
 415 gboolean purple_media_codecs_ready(PurpleMedia *media, const gchar *sess_id);
 416
 417 /**
 418  * purple_media_set_send_rtcp_mux:
 419  * @media: The media object to find the session in.
 420  * @sess_id: The session id of the session find the stream in.
 421  * @participant: The name of the remote user to set the rtcp-mux for.
 422  * @send_rtcp_mux: Whether to enable the rtcp-mux option
 423  *
 424  * Sets the rtcp-mux option for the stream.
 425  *
 426  * Returns: %TRUE RTCP-Mux was set successfully, or %FALSE otherwise.
 427  *
 428  * @since 2.11.0
 429  */
 430 gboolean purple_media_set_send_rtcp_mux(PurpleMedia *media,
 431                 const gchar *sess_id, const gchar *participant, gboolean send_rtcp_mux);
 432 /**
 433  * purple_media_is_initiator:
 434  * @media: The media instance to find the session in.
 435  * @sess_id: The session id of the session to check.
 436  * @participant: The participant of the stream to check.
 437  *
 438  * Gets whether the local user is the conference/session/stream's initiator.
 439  *
 440  * Returns: TRUE if the local user is the stream's initator, else FALSE.
 441  */
 442 gboolean purple_media_is_initiator(PurpleMedia *media,
 443                 const gchar *sess_id, const gchar *participant);
 444
 445 /**
 446  * purple_media_accepted:
 447  * @media: The media object to find the session in.
 448  * @sess_id: The session id of the session to check.
 449  * @participant: The participant to check.
 450  *
 451  * Gets whether a streams selected have been accepted.
 452  *
 453  * Returns: %TRUE The selected streams have been accepted, or %FALSE otherwise.
 454  */
 455 gboolean purple_media_accepted(PurpleMedia *media, const gchar *sess_id,
 456                 const gchar *participant);
 457
 458 /**
 459  * purple_media_set_input_volume:
 460  * @media: The media object the sessions are in.
 461  * @session_id: The session to select (if any).
 462  * @level: The level to set the volume to.
 463  *
 464  * Sets the input volume of all the selected sessions.
 465  */
 466 void purple_media_set_input_volume(PurpleMedia *media, const gchar *session_id, double level);
 467
 468 /**
 469  * purple_media_set_output_volume:
 470  * @media: The media object the streams are in.
 471  * @session_id: The session to limit the streams to (if any).
 472  * @participant: The participant to limit the streams to (if any).
 473  * @level: The level to set the volume to.
 474  *
 475  * Sets the output volume of all the selected streams.
 476  */
 477 void purple_media_set_output_volume(PurpleMedia *media, const gchar *session_id,
 478                 const gchar *participant, double level);
 479
 480 /**
 481  * purple_media_set_output_window:
 482  * @media: The media instance to set the output window on.
 483  * @session_id: The session to set the output window on.
 484  * @participant: Optionally, the participant to set the output window on.
 485  * @window_id: The window id use for embedding the video in.
 486  *
 487  * Sets a video output window for the given session/stream.
 488  *
 489  * Returns: An id to reference the output window.
 490  */
 491 gulong purple_media_set_output_window(PurpleMedia *media,
 492                 const gchar *session_id, const gchar *participant,
 493                 gulong window_id);
 494
 495 /**
 496  * purple_media_remove_output_windows:
 497  * @media: The instance to remove all output windows from.
 498  *
 499  * Removes all output windows from a given media session.
 500  */
 501 void purple_media_remove_output_windows(PurpleMedia *media);
 502
 503 /**
 504  * purple_media_send_dtmf:
 505  * @media: The media instance to send a DTMF signal to.
 506  * @session_id: The session id of the session to send the DTMF signal on.
 507  * @dtmf: The character representing the DTMF in the range [0-9#*A-D].
 508  * @volume: The power level expressed in dBm0 after dropping the sign in the
 509  *          range of 0 to 63.  A larger value represents a lower volume.
 510  * @duration: The duration of the tone in milliseconds.
 511  *
 512  * Sends a DTMF signal out-of-band.
 513  *
 514  * Returns: %TRUE DTMF sent successfully, or %FALSE otherwise.
 515  */
 516 gboolean purple_media_send_dtmf(PurpleMedia *media, const gchar *session_id,
 517                 gchar dtmf, guint8 volume, guint16 duration);
 518
 519 G_END_DECLS
 520
 521 #endif /* PURPLE_MEDIA_H */