src/core/sipe-media.h

   1 /**
   2  * @file sipe-media.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2010 Jakub Adam <jakub.adam@ktknet.cz>
   7  * Copyright (C) 2016-2017 SIPE Project <http://sipe.sourceforge.net/>
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  22  */
  23
  24 /* Forward declarations */
  25 struct sdpmsg;
  26 struct sipmsg;
  27 struct sipe_core_private;
  28 struct sipe_media_call_private;
  29 struct sipe_media_stream;
  30
  31 typedef void (* sipe_media_stream_read_callback)(struct sipe_media_stream *stream,
  32                                                  guint8 *buffer, gsize len);
  33
  34 /**
  35  * Creates a new media call.
  36  *
  37  * @param sipe_private (in) SIPE core data.
  38  * @param with (in) SIP URI of the second participant.
  39  * @param msg (in) SIP INVITE message from the second participant or NULL if we
  40  *            are the call initiator.
  41  * @param ice_version (in) version of ICE protocol to use when establishing the
  42  *                    connection path.
  43  * @param flags (in) bitwise-or'd media call flags.
  44  *
  45  * @return a new @c sipe_media_call structure or @c NULL on error.
  46  */
  47 struct sipe_media_call *
  48 sipe_media_call_new(struct sipe_core_private *sipe_private, const gchar* with,
  49                     struct sipmsg *msg, SipeIceVersion ice_version,
  50                     SipeMediaCallFlags flags);
  51
  52 /**
  53  * Adds a new media stream to a call.
  54  *
  55  * @param call (in) a media call.
  56  * @param id (in) a string identifier for the media stream.
  57  * @param type (in) a type of stream's content (audio, video, data, ...).
  58  * @param ice_version (in) a version of ICE to use when negotiating the
  59  *                    connection.
  60  * @param initiator (in) @c TRUE if our client is the initiator of the stream.
  61  * @param ssrc_count (in) number of RTP Synchronization source identifiers to
  62  *                   allocate for the stream.
  63  *
  64  * @return a new @c sipe_media_stream structure or @c NULL on error.
  65  */
  66 struct sipe_media_stream *
  67 sipe_media_stream_add(struct sipe_media_call *call, const gchar *id,
  68                       SipeMediaType type, SipeIceVersion ice_version,
  69                       gboolean initiator, guint32 ssrc_count);
  70
  71 /**
  72  * Handles incoming SIP INVITE message to start a media session.
  73  *
  74  * @param sipe_private (in) SIPE core data.
  75  * @param msg (in) a SIP INVITE message
  76  * @param sdp (in) media session description string
  77  *
  78  * @return @c sipe_media_call structure created or updated by @c msg.
  79  *         The function returns @c NULL on error or if the call was rejected.
  80  */
  81 struct sipe_media_call *
  82 process_incoming_invite_call(struct sipe_core_private *sipe_private,
  83                              struct sipmsg *msg,
  84                              const gchar *sdp);
  85
  86 /**
  87  * Handles incoming SIP INVITE message to start a media session.
  88  *
  89  * @param sipe_private (in) SIPE core data.
  90  * @param msg (in) a SIP INVITE message
  91  * @param smsg (in) parsed media session description; the function takes
  92  *             ownership of the sdpmsg structure and will free it when no longer
  93  *             needed.
  94  *
  95  * @return @c sipe_media_call structure created or updated by @c msg.
  96  *         The function returns @c NULL on error or if the call was rejected.
  97  */
  98 struct sipe_media_call *
  99 process_incoming_invite_call_parsed_sdp(struct sipe_core_private *sipe_private,
 100                                         struct sipmsg *msg,
 101                                         struct sdpmsg *smsg);
 102
 103 /**
 104  * Handles incoming SIP CANCEL message.
 105  *
 106  * @param call_private (in) SIPE media call data.
 107  * @param msg (in) a SIP CANCEL message
 108  */
 109 void process_incoming_cancel_call(struct sipe_media_call_private *call_private,
 110                                   struct sipmsg *msg);
 111
 112 /**
 113  * Hangs up a media session and closes all allocated resources.
 114  *
 115  * @param sipe_private (in) media call data.
 116  */
 117 void sipe_media_hangup(struct sipe_media_call_private *call_private);
 118
 119 /**
 120  * Call before SIP account logs of the server. Function hangs up the call and
 121  * notifies remote participant according to the actual state of call
 122  * negotiation.
 123  *
 124  * @param sipe_private (in) SIPE core data.
 125  */
 126 void sipe_media_handle_going_offline(struct sipe_core_private *sipe_private);
 127
 128 /**
 129  * Checks whether the given media is a conference call.
 130  *
 131  * @return @c TRUE if call is a conference, @c FALSE when it is a PC2PC call.
 132  */
 133 gboolean sipe_media_is_conference_call(struct sipe_media_call_private *call_private);
 134
 135 /**
 136  * Retrieves the sipe core structure the given call is associated to.
 137  *
 138  * @param call (in) media call data
 139  *
 140  * @return @c sipe_core_private structure.
 141  */
 142 struct sipe_core_private *
 143 sipe_media_get_sipe_core_private(struct sipe_media_call *call);
 144
 145 /**
 146  * Retrieves a SIP dialog associated with the call.
 147  *
 148  * @param call (in) media call data
 149  *
 150  * @return a @c sip_dialog structure associated with @c call.
 151  */
 152 struct sip_dialog *
 153 sipe_media_get_sip_dialog(struct sipe_media_call *call);
 154
 155 /**
 156  * Checks whether SIP message belongs to the session of the given media call.
 157  *
 158  * Test is done on the basis of the Call-ID of the message.
 159  *
 160  * @param call_private (in) media call data
 161  * @param msg (in) a SIP message
 162  *
 163  * @return @c TRUE if the SIP message belongs to the media session.
 164  */
 165 gboolean is_media_session_msg(struct sipe_media_call_private *call_private,
 166                               struct sipmsg *msg);
 167
 168 /**
 169  * Sends a request to mras URI for the credentials to the A/V edge server.
 170  * Given @c sipe_core_private must have non-NULL mras_uri. When the valid
 171  * response is received, media_relay_username, media_relay_password and
 172  * media_relays attributes of the sipe core are filled.
 173  *
 174  * @param sipe_private (in) SIPE core data.
 175  */
 176 void sipe_media_get_av_edge_credentials(struct sipe_core_private *sipe_private);
 177
 178 /**
 179  * Turns @c call's next INVITE into a MIME multipart message with @c body as
 180  * the extra part.
 181  *
 182  * @param call (in) media call data
 183  * @param invite_content_type (in) MIME media type of the resulting message,
 184  *                            e.g. "multipart/alternative" or "multipart/mixed"
 185  * @param body (in) content to add as the second part of the INVITE message;
 186  *             @c call takes ownership of @c body and will free it after use
 187  */
 188 void
 189 sipe_media_add_extra_invite_section(struct sipe_media_call *call,
 190                                     const gchar *invite_content_type,
 191                                     gchar *body);
 192
 193 /**
 194  * Adds application-specific SDP attribute to the stream. This will be sent as
 195  * a part of our SIP INVITE alongside standard media description, formatted as:
 196  *
 197  *  a=name[:value]
 198  *
 199  * @param stream (in) media stream data
 200  * @param name (in) attribute name
 201  * @param value (in) optional value of the attribute
 202  */
 203 void
 204 sipe_media_stream_add_extra_attribute(struct sipe_media_stream *stream,
 205                                       const gchar *name, const gchar *value);
 206
 207 /**
 208  * Schedules asynchronous read of @c len bytes from @c stream into @c buffer.
 209  * When enough data becomes available in the stream, the buffer is filled and
 210  * @c callback gets invoked.
 211  *
 212  * It's possible to call sipe_media_stream_read_async() multiple times; every
 213  * request is placed into a FIFO queue. Media core does not call @c read_cb of
 214  * @c stream while there is some asynchronous read in progress.
 215  *
 216  * @param stream (in) media stream data
 217  * @param buffer (in) an empty data buffer
 218  * @param len (in) length of @c buffer
 219  * @param callback (in) a function to call when @c buffer gets filled with
 220  *                 input data
 221  */
 222 void
 223 sipe_media_stream_read_async(struct sipe_media_stream *stream,
 224                              gpointer buffer, gsize len,
 225                              sipe_media_stream_read_callback callback);
 226
 227 /**
 228  * Writes @c len bytes from @c buffer into @c stream.
 229  *
 230  * If @c stream is not in writable state, Sipe will store the data in
 231  * an internal queue which gets emptied once the stream becomes writable again.
 232  * Users should check the stream state using sipe_media_stream_is_writable()
 233  * before sending excessive data into the stream.
 234  *
 235  * @param stream (in) media stream data
 236  * @param buffer (in) data to send
 237  * @param len (in) length of @c buffer
 238  *
 239  * @return @c TRUE when @c buffer was written into the stream as a whole,
 240  *         @c FALSE when some data had to be queued for later (and thus
 241  *         the stream is now in unwritable state).
 242  */
 243 gboolean
 244 sipe_media_stream_write(struct sipe_media_stream *stream,
 245                         gpointer buffer, gsize len);
 246
 247 /**
 248  * Checks whether a @c SIPE_MEDIA_APPLICATION stream is in writable state.
 249  *
 250  * @param stream (in) media stream data
 251  *
 252  * @return @c TRUE if @c stream is writable, otherwise @c FALSE.
 253  */
 254 gboolean
 255 sipe_media_stream_is_writable(struct sipe_media_stream *stream);
 256
 257 /**
 258  * Associates user data with the media stream.
 259  *
 260  * @param stream (in) media stream data
 261  * @param data (in) user data
 262  * @param free_func (in) function to free @c data when @c stream is destroyed
 263  */
 264 void
 265 sipe_media_stream_set_data(struct sipe_media_stream *stream, gpointer data,
 266                            GDestroyNotify free_func);
 267
 268 /**
 269  * Returns user data associated with the media stream.
 270  *
 271  * @param stream (in) media stream data
 272  *
 273  * @return user data
 274  */
 275 gpointer
 276 sipe_media_stream_get_data(struct sipe_media_stream *stream);
 277
 278 /**
 279  * Deallocates the opaque list of media relay structures
 280  *
 281  * @param list (in) GSList to free
 282  */
 283 void sipe_media_relay_list_free(GSList *list);