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-2018 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  * Retrieves the @c sipe_media_call structure representing the ongoing call with
  54  * the given participant.
  55  *
  56  * @param sipe_private (in) SIPE core data.
  57  * @param with (in) SIP URI of the call participant.
  58  *
  59  * @return a @c sipe_media_call structure or @c NULL if there isn't a call going
  60  * on with @c with.
  61  */
  62 struct sipe_media_call *
  63 sipe_media_call_find(struct sipe_core_private *sipe_private, const gchar *with);
  64
  65 /**
  66  * Adds a new media stream to a call.
  67  *
  68  * @param call (in) a media call.
  69  * @param id (in) a string identifier for the media stream.
  70  * @param type (in) a type of stream's content (audio, video, data, ...).
  71  * @param ice_version (in) a version of ICE to use when negotiating the
  72  *                    connection.
  73  * @param initiator (in) @c TRUE if our client is the initiator of the stream.
  74  * @param ssrc_count (in) number of RTP Synchronization source identifiers to
  75  *                   allocate for the stream.
  76  *
  77  * @return a new @c sipe_media_stream structure or @c NULL on error.
  78  */
  79 struct sipe_media_stream *
  80 sipe_media_stream_add(struct sipe_media_call *call, const gchar *id,
  81                       SipeMediaType type, SipeIceVersion ice_version,
  82                       gboolean initiator, guint32 ssrc_count);
  83
  84 /**
  85  * Handles incoming SIP INVITE message to start a media session.
  86  *
  87  * @param sipe_private (in) SIPE core data.
  88  * @param msg (in) a SIP INVITE message
  89  * @param sdp (in) media session description string
  90  *
  91  * @return @c sipe_media_call structure created or updated by @c msg.
  92  *         The function returns @c NULL on error or if the call was rejected.
  93  */
  94 struct sipe_media_call *
  95 process_incoming_invite_call(struct sipe_core_private *sipe_private,
  96                              struct sipmsg *msg,
  97                              const gchar *sdp);
  98
  99 /**
 100  * Handles incoming SIP INVITE message to start a media session.
 101  *
 102  * @param sipe_private (in) SIPE core data.
 103  * @param msg (in) a SIP INVITE message
 104  * @param smsg (in) parsed media session description; the function takes
 105  *             ownership of the sdpmsg structure and will free it when no longer
 106  *             needed.
 107  *
 108  * @return @c sipe_media_call structure created or updated by @c msg.
 109  *         The function returns @c NULL on error or if the call was rejected.
 110  */
 111 struct sipe_media_call *
 112 process_incoming_invite_call_parsed_sdp(struct sipe_core_private *sipe_private,
 113                                         struct sipmsg *msg,
 114                                         struct sdpmsg *smsg);
 115
 116 /**
 117  * Handles incoming SIP CANCEL message.
 118  *
 119  * @param call_private (in) SIPE media call data.
 120  * @param msg (in) a SIP CANCEL message
 121  */
 122 void process_incoming_cancel_call(struct sipe_media_call_private *call_private,
 123                                   struct sipmsg *msg);
 124
 125 /**
 126  * Hangs up a media session and closes all allocated resources.
 127  *
 128  * @param sipe_private (in) media call data.
 129  */
 130 void sipe_media_hangup(struct sipe_media_call_private *call_private);
 131
 132 /**
 133  * Call before SIP account logs of the server. Function hangs up the call and
 134  * notifies remote participant according to the actual state of call
 135  * negotiation.
 136  *
 137  * @param sipe_private (in) SIPE core data.
 138  */
 139 void sipe_media_handle_going_offline(struct sipe_core_private *sipe_private);
 140
 141 /**
 142  * Checks whether the given media is a conference call.
 143  *
 144  * @return @c TRUE if call is a conference, @c FALSE when it is a PC2PC call.
 145  */
 146 gboolean sipe_media_is_conference_call(struct sipe_media_call_private *call_private);
 147
 148 /**
 149  * Retrieves the sipe core structure the given call is associated to.
 150  *
 151  * @param call (in) media call data
 152  *
 153  * @return @c sipe_core_private structure.
 154  */
 155 struct sipe_core_private *
 156 sipe_media_get_sipe_core_private(struct sipe_media_call *call);
 157
 158 /**
 159  * Retrieves a SIP dialog associated with the call.
 160  *
 161  * @param call (in) media call data
 162  *
 163  * @return a @c sip_dialog structure associated with @c call.
 164  */
 165 struct sip_dialog *
 166 sipe_media_get_sip_dialog(struct sipe_media_call *call);
 167
 168 /**
 169  * Checks whether SIP message belongs to the session of the given media call.
 170  *
 171  * Test is done on the basis of the Call-ID of the message.
 172  *
 173  * @param call_private (in) media call data
 174  * @param msg (in) a SIP message
 175  *
 176  * @return @c TRUE if the SIP message belongs to the media session.
 177  */
 178 gboolean is_media_session_msg(struct sipe_media_call_private *call_private,
 179                               struct sipmsg *msg);
 180
 181 /**
 182  * Sends a request to mras URI for the credentials to the A/V edge server.
 183  * Given @c sipe_core_private must have non-NULL mras_uri. When the valid
 184  * response is received, media_relay_username, media_relay_password and
 185  * media_relays attributes of the sipe core are filled.
 186  *
 187  * @param sipe_private (in) SIPE core data.
 188  */
 189 void sipe_media_get_av_edge_credentials(struct sipe_core_private *sipe_private);
 190
 191 /**
 192  * Turns @c call's next INVITE into a MIME multipart message with @c body as
 193  * the extra part.
 194  *
 195  * @param call (in) media call data
 196  * @param invite_content_type (in) MIME media type of the resulting message,
 197  *                            e.g. "multipart/alternative" or "multipart/mixed"
 198  * @param body (in) content to add as the second part of the INVITE message;
 199  *             @c call takes ownership of @c body and will free it after use
 200  */
 201 void
 202 sipe_media_add_extra_invite_section(struct sipe_media_call *call,
 203                                     const gchar *invite_content_type,
 204                                     gchar *body);
 205
 206 /**
 207  * Adds application-specific SDP attribute to the stream. This will be sent as
 208  * a part of our SIP INVITE alongside standard media description, formatted as:
 209  *
 210  *  a=name[:value]
 211  *
 212  * @param stream (in) media stream data
 213  * @param name (in) attribute name
 214  * @param value (in) optional value of the attribute
 215  */
 216 void
 217 sipe_media_stream_add_extra_attribute(struct sipe_media_stream *stream,
 218                                       const gchar *name, const gchar *value);
 219
 220 /**
 221  * Schedules asynchronous read of @c len bytes from @c stream into @c buffer.
 222  * When enough data becomes available in the stream, the buffer is filled and
 223  * @c callback gets invoked.
 224  *
 225  * It's possible to call sipe_media_stream_read_async() multiple times; every
 226  * request is placed into a FIFO queue. Media core does not call @c read_cb of
 227  * @c stream while there is some asynchronous read in progress.
 228  *
 229  * @param stream (in) media stream data
 230  * @param buffer (in) an empty data buffer
 231  * @param len (in) length of @c buffer
 232  * @param callback (in) a function to call when @c buffer gets filled with
 233  *                 input data
 234  */
 235 void
 236 sipe_media_stream_read_async(struct sipe_media_stream *stream,
 237                              gpointer buffer, gsize len,
 238                              sipe_media_stream_read_callback callback);
 239
 240 /**
 241  * Writes @c len bytes from @c buffer into @c stream.
 242  *
 243  * If @c stream is not in writable state, Sipe will store the data in
 244  * an internal queue which gets emptied once the stream becomes writable again.
 245  * Users should check the stream state using sipe_media_stream_is_writable()
 246  * before sending excessive data into the stream.
 247  *
 248  * @param stream (in) media stream data
 249  * @param buffer (in) data to send
 250  * @param len (in) length of @c buffer
 251  *
 252  * @return @c TRUE when @c buffer was written into the stream as a whole,
 253  *         @c FALSE when some data had to be queued for later (and thus
 254  *         the stream is now in unwritable state).
 255  */
 256 gboolean
 257 sipe_media_stream_write(struct sipe_media_stream *stream,
 258                         gpointer buffer, gsize len);
 259
 260 /**
 261  * Checks whether a @c SIPE_MEDIA_APPLICATION stream is in writable state.
 262  *
 263  * @param stream (in) media stream data
 264  *
 265  * @return @c TRUE if @c stream is writable, otherwise @c FALSE.
 266  */
 267 gboolean
 268 sipe_media_stream_is_writable(struct sipe_media_stream *stream);
 269
 270 /**
 271  * Associates user data with the media stream.
 272  *
 273  * @param stream (in) media stream data
 274  * @param data (in) user data
 275  * @param free_func (in) function to free @c data when @c stream is destroyed
 276  */
 277 void
 278 sipe_media_stream_set_data(struct sipe_media_stream *stream, gpointer data,
 279                            GDestroyNotify free_func);
 280
 281 /**
 282  * Returns user data associated with the media stream.
 283  *
 284  * @param stream (in) media stream data
 285  *
 286  * @return user data
 287  */
 288 gpointer
 289 sipe_media_stream_get_data(struct sipe_media_stream *stream);
 290
 291 /**
 292  * Deallocates the opaque list of media relay structures
 293  *
 294  * @param list (in) GSList to free
 295  */
 296 void sipe_media_relay_list_free(GSList *list);