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