libpurple/media/backend-iface.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_BACKEND_IFACE_H
  23 #define PURPLE_MEDIA_BACKEND_IFACE_H
  24 /**
  25  * SECTION:backend-iface
  26  * @section_id: libpurple-backend-iface
  27  * @short_description: <filename>media/backend-iface.h</filename>
  28  * @title: Interface for Media Backends
  29  */
  30
  31 #include "codec.h"
  32 #include "enum-types.h"
  33
  34 #include <glib-object.h>
  35
  36 G_BEGIN_DECLS
  37
  38 #define PURPLE_TYPE_MEDIA_BACKEND               (purple_media_backend_get_type())
  39 #define PURPLE_IS_MEDIA_BACKEND(obj)            (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA_BACKEND))
  40 #define PURPLE_MEDIA_BACKEND(obj)               (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA_BACKEND, PurpleMediaBackend))
  41 #define PURPLE_MEDIA_BACKEND_GET_INTERFACE(inst)(G_TYPE_INSTANCE_GET_INTERFACE((inst), PURPLE_TYPE_MEDIA_BACKEND, PurpleMediaBackendInterface))
  42
  43 /**
  44  * PurpleMediaBackend:
  45  *
  46  * A placeholder to represent any media backend
  47  */
  48 typedef struct _PurpleMediaBackend PurpleMediaBackend;
  49
  50 /**
  51  * PurpleMediaBackendInterface:
  52  *
  53  * A structure to derive media backends from.
  54  */
  55 typedef struct _PurpleMediaBackendInterface PurpleMediaBackendInterface;
  56
  57 struct _PurpleMediaBackendInterface
  58 {
  59         /*< private >*/
  60         GTypeInterface parent_iface; /* The parent iface class */
  61
  62         /*< public >*/
  63         /* Implementable functions called with purple_media_backend_* */
  64         gboolean (*add_stream) (PurpleMediaBackend *self,
  65                 const gchar *sess_id, const gchar *who,
  66                 PurpleMediaSessionType type, gboolean initiator,
  67                 const gchar *transmitter,
  68                 guint num_params, GParameter *params);
  69         void (*add_remote_candidates) (PurpleMediaBackend *self,
  70                 const gchar *sess_id, const gchar *participant,
  71                 GList *remote_candidates);
  72         gboolean (*codecs_ready) (PurpleMediaBackend *self,
  73                 const gchar *sess_id);
  74         GList *(*get_codecs) (PurpleMediaBackend *self,
  75                 const gchar *sess_id);
  76         GList *(*get_local_candidates) (PurpleMediaBackend *self,
  77                 const gchar *sess_id, const gchar *participant);
  78         gboolean (*set_remote_codecs) (PurpleMediaBackend *self,
  79                 const gchar *sess_id, const gchar *participant,
  80                 GList *codecs);
  81         gboolean (*set_send_codec) (PurpleMediaBackend *self,
  82                 const gchar *sess_id, PurpleMediaCodec *codec);
  83         gboolean (*set_encryption_parameters) (PurpleMediaBackend *self,
  84                 const gchar *sess_id, const gchar *cipher,
  85                 const gchar *auth, const gchar *key, gsize key_len);
  86         gboolean (*set_decryption_parameters) (PurpleMediaBackend *self,
  87                 const gchar *sess_id, const gchar *participant,
  88                 const gchar *cipher, const gchar *auth,
  89                 const gchar *key, gsize key_len);
  90         void (*set_params) (PurpleMediaBackend *self,
  91                 guint num_params, GParameter *params);
  92         const gchar **(*get_available_params) (void);
  93         gboolean (*send_dtmf) (PurpleMediaBackend *self,
  94                 const gchar *sess_id, gchar dtmf, guint8 volume,
  95                 guint16 duration);
  96         gboolean (*set_send_rtcp_mux) (PurpleMediaBackend *self,
  97                 const gchar *sess_id, const gchar *participant, gboolean send_rtcp_mux);
  98 };
  99
 100 /**
 101  * purple_media_backend_get_type:
 102  *
 103  * Gets the media backend's GType.
 104  *
 105  * Returns: The media backend's GType.
 106  */
 107 GType purple_media_backend_get_type(void);
 108
 109 /**
 110  * purple_media_backend_add_stream:
 111  * @self: The backend to add the stream to.
 112  * @sess_id: The session id of the stream to add.
 113  * @who: The remote participant of the stream to add.
 114  * @type: The media type and direction of the stream to add.
 115  * @initiator: True if the local user initiated the stream.
 116  * @transmitter: The string id of the tranmsitter to use.
 117  * @num_params: The number of parameters in the param parameter.
 118  * @params: The additional parameters to pass when creating the stream.
 119  *
 120  * Creates and adds a stream to the media backend.
 121  *
 122  * Returns: True if the stream was successfully created, othewise False.
 123  */
 124 gboolean purple_media_backend_add_stream(PurpleMediaBackend *self,
 125                 const gchar *sess_id, const gchar *who,
 126                 PurpleMediaSessionType type, gboolean initiator,
 127                 const gchar *transmitter,
 128                 guint num_params, GParameter *params);
 129
 130 /**
 131  * purple_media_backend_add_remote_candidates:
 132  * @self: The backend the stream is in.
 133  * @sess_id: The session id associated with the stream.
 134  * @participant: The participant associated with the stream.
 135  * @remote_candidates: (element-type PurpleMediaCandidate): The list of remote candidates to add.
 136  *
 137  * Add remote candidates to a stream.
 138  */
 139 void purple_media_backend_add_remote_candidates(PurpleMediaBackend *self,
 140                 const gchar *sess_id, const gchar *participant,
 141                 GList *remote_candidates);
 142
 143 /**
 144  * purple_media_backend_codecs_ready:
 145  * @self: The media backend the session is in.
 146  * @sess_id: The session id of the session to check.
 147  *
 148  * Get whether or not a session's codecs are ready.
 149  *
 150  * A codec is ready if all of the attributes and additional
 151  * parameters have been collected.
 152  *
 153  * Returns: True if the codecs are ready, otherwise False.
 154  */
 155 gboolean purple_media_backend_codecs_ready(PurpleMediaBackend *self,
 156                 const gchar *sess_id);
 157
 158 /**
 159  * purple_media_backend_get_codecs:
 160  * @self: The media backend the session is in.
 161  * @sess_id: The session id of the session to use.
 162  *
 163  * Gets the codec intersection list for a session.
 164  *
 165  * The intersection list consists of all codecs that are compatible
 166  * between the local and remote software.
 167  *
 168  * Returns: (transfer full) (element-type PurpleMediaCodec): The codec intersection list.
 169  */
 170 GList *purple_media_backend_get_codecs(PurpleMediaBackend *self,
 171                 const gchar *sess_id);
 172
 173 /**
 174  * purple_media_backend_get_local_candidates:
 175  * @self: The media backend the stream is in.
 176  * @sess_id: The session id associated with the stream.
 177  * @participant: The participant associated with the stream.
 178  *
 179  * Gets the list of local candidates for a stream.
 180  *
 181  * Return Value: (transfer full) (element-type PurpleMediaCandidate): The list of local candidates.
 182  */
 183 GList *purple_media_backend_get_local_candidates(PurpleMediaBackend *self,
 184                 const gchar *sess_id, const gchar *participant);
 185
 186 /**
 187  * purple_media_backend_set_remote_codecs:
 188  * @self: The media backend the stream is in.
 189  * @sess_id: The session id the stream is associated with.
 190  * @participant: The participant the stream is associated with.
 191  * @codecs: (element-type PurpleMediaCodec): The list of remote codecs to set.
 192  *
 193  * Sets the remote codecs on a stream.
 194  *
 195  * Returns: True if the remote codecs were set successfully, otherwise False.
 196  */
 197 gboolean purple_media_backend_set_remote_codecs(PurpleMediaBackend *self,
 198                 const gchar *sess_id, const gchar *participant,
 199                 GList *codecs);
 200
 201 /**
 202  * purple_media_backend_set_send_codec:
 203  * @self: The media backend the session is in.
 204  * @sess_id: The session id of the session to set the codec for.
 205  * @codec: The codec to set.
 206  *
 207  * Sets which codec format to send media content in for a session.
 208  *
 209  * Returns: True if set successfully, otherwise False.
 210  */
 211 gboolean purple_media_backend_set_send_codec(PurpleMediaBackend *self,
 212                 const gchar *sess_id, PurpleMediaCodec *codec);
 213
 214 /**
 215  * purple_media_backend_set_encryption_parameters:
 216  * @self: The media backend the session is in.
 217  * @sess_id: The session id of the session to set parameters of.
 218  * @cipher: The cipher to use to encrypt our media in the session.
 219  * @auth: The algorithm to use to compute authentication codes for our media
 220  *        frames.
 221  * @key: The encryption key.
 222  * @key_len: Byte length of the encryption key.
 223  *
 224  * Sets the encryption parameters of our media in the session.
 225  */
 226 gboolean purple_media_backend_set_encryption_parameters(PurpleMediaBackend *self,
 227                 const gchar *sess_id, const gchar *cipher,
 228                 const gchar *auth, const gchar *key, gsize key_len);
 229
 230 /**
 231  * purple_media_backend_set_decryption_parameters:
 232  * @self: The media backend the session is in.
 233  * @sess_id: The session id of the session to set parameters of.
 234  * @participant: The participant of the session to set parameters of.
 235  * @cipher: The cipher to use to decrypt media coming from this session's
 236  *          participant.
 237  * @auth: The algorithm to use for authentication of the media coming from
 238  *        the session's participant.
 239  * @key: The decryption key.
 240  * @key_len: Byte length of the decryption key.
 241  *
 242  * Sets the decryption parameters for a session participant's media.
 243  */
 244 gboolean purple_media_backend_set_decryption_parameters(PurpleMediaBackend *self,
 245                 const gchar *sess_id, const gchar *participant,
 246                 const gchar *cipher, const gchar *auth,
 247                 const gchar *key, gsize key_len);
 248
 249 /**
 250  * purple_media_backend_set_params:
 251  * @self: The media backend to set the parameters on.
 252  * @num_params: The number of parameters to pass to backend
 253  * @params: Array of @c GParameter to pass to backend
 254  *
 255  * Sets various optional parameters of the media backend.
 256  */
 257 void purple_media_backend_set_params(PurpleMediaBackend *self,
 258                 guint num_params, GParameter *params);
 259
 260 /**
 261  * purple_media_backend_get_available_params:
 262  * @self: The media backend
 263  *
 264  * Gets the list of optional parameters supported by the media backend.
 265  * The list should NOT be freed.
 266  *
 267  * Return Value: (transfer none): NULL-terminated array of names of supported parameters.
 268  */
 269 const gchar **purple_media_backend_get_available_params(PurpleMediaBackend *self);
 270
 271 /**
 272  * purple_media_backend_set_send_rtcp_mux:
 273  * @self: The media backend the session is in.
 274  * @sess_id: The session id of the session to set the rtcp-mux option to
 275  * @participant: The participant the stream is associated with.
 276  * @send_rtcp_mux: Whether or not to enable rtcp-mux
 277  *
 278  * Controls whether or not the RTCP should be muxed with the RTP
 279  *
 280  * Returns: True if set successfully, otherwise False.
 281  *
 282  * @since 2.11.0
 283  */
 284 gboolean purple_media_backend_set_send_rtcp_mux(PurpleMediaBackend *self,
 285                 const gchar *sess_id, const gchar *participant, gboolean send_rtcp_mux);
 286
 287
 288 G_END_DECLS
 289
 290 #endif /* PURPLE_MEDIA_BACKEND_IFACE_H */