Merge "test_res_rtp: Enable FIR and REMB nominal tests."
[asterisk/asterisk.git] / include / asterisk / res_pjsip_session.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Mark Michelson <mmichelson@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #ifndef _RES_PJSIP_SESSION_H
20 #define _RES_PJSIP_SESSION_H
21
22 /* Needed for pj_timer_entry definition */
23 #include <pjlib.h>
24 #include "asterisk/linkedlists.h"
25 /* Needed for AST_MAX_EXTENSION constant */
26 #include "asterisk/channel.h"
27 /* Needed for ast_sockaddr struct */
28 #include "asterisk/netsock2.h"
29 /* Needed for ast_sdp_srtp struct */
30 #include "asterisk/sdp_srtp.h"
31 /* Needed for ast_media_type */
32 #include "asterisk/codec.h"
33
34 /* Forward declarations */
35 struct ast_sip_endpoint;
36 struct ast_sip_transport;
37 struct pjsip_inv_session;
38 struct ast_channel;
39 struct ast_datastore;
40 struct ast_datastore_info;
41 struct ao2_container;
42 struct pjsip_tx_data;
43 struct pjsip_rx_data;
44 struct ast_party_id;
45 struct pjmedia_sdp_media;
46 struct pjmedia_sdp_session;
47 struct ast_dsp;
48 struct ast_udptl;
49
50 /*! \brief T.38 states for a session */
51 enum ast_sip_session_t38state {
52         T38_DISABLED = 0,   /*!< Not enabled */
53         T38_LOCAL_REINVITE, /*!< Offered from local - REINVITE */
54         T38_PEER_REINVITE,  /*!< Offered from peer - REINVITE */
55         T38_ENABLED,        /*!< Negotiated (enabled) */
56         T38_REJECTED,       /*!< Refused */
57         T38_MAX_ENUM,       /*!< Not an actual state; used as max value in the enum */
58 };
59
60 struct ast_sip_session_sdp_handler;
61 struct ast_sip_session;
62 struct ast_sip_session_media;
63
64 typedef struct ast_frame *(*ast_sip_session_media_read_cb)(struct ast_sip_session *session, struct ast_sip_session_media *session_media);
65 typedef int (*ast_sip_session_media_write_cb)(struct ast_sip_session *session, struct ast_sip_session_media *session_media,
66         struct ast_frame *frame);
67
68 /*!
69  * \brief A structure containing SIP session media information
70  */
71 struct ast_sip_session_media {
72         /*! \brief RTP instance itself */
73         struct ast_rtp_instance *rtp;
74         /*! \brief UDPTL instance itself */
75         struct ast_udptl *udptl;
76         /*! \brief Direct media address */
77         struct ast_sockaddr direct_media_addr;
78         /*! \brief SDP handler that setup the RTP */
79         struct ast_sip_session_sdp_handler *handler;
80         /*! \brief Holds SRTP information */
81         struct ast_sdp_srtp *srtp;
82         /*! \brief What type of encryption is in use on this stream */
83         enum ast_sip_session_media_encryption encryption;
84         /*! \brief The media transport in use for this stream */
85         pj_str_t transport;
86         /*! \brief Scheduler ID for RTP keepalive */
87         int keepalive_sched_id;
88         /*! \brief Scheduler ID for RTP timeout */
89         int timeout_sched_id;
90         /*! \brief Stream is on hold by remote side */
91         unsigned int remotely_held:1;
92         /*! \brief Stream is on hold by local side */
93         unsigned int locally_held:1;
94         /*! \brief Does remote support rtcp_mux */
95         unsigned int remote_rtcp_mux:1;
96         /*! \brief Does remote support ice */
97         unsigned int remote_ice:1;
98         /*! \brief Media type of this session media */
99         enum ast_media_type type;
100         /*! \brief The write callback when writing frames */
101         ast_sip_session_media_write_cb write_callback;
102         /*! \brief The stream number to place into any resulting frames */
103         int stream_num;
104         /*! \brief Media identifier for this stream (may be shared across multiple streams) */
105         char *mid;
106         /*! \brief The bundle group the stream belongs to */
107         int bundle_group;
108         /*! \brief Whether this stream is currently bundled or not */
109         unsigned int bundled;
110         /*! \brief Media stream label */
111         char mslabel[AST_UUID_STR_LEN];
112         /*! \brief Track label */
113         char label[AST_UUID_STR_LEN];
114         /*! \brief The underlying session has been changed in some fashion */
115         unsigned int changed;
116         /*! \brief Remote media stream label */
117         char *remote_mslabel;
118 };
119
120 /*!
121  * \brief Structure which contains read callback information
122  */
123 struct ast_sip_session_media_read_callback_state {
124         /*! \brief The file descriptor itself */
125         int fd;
126         /*! \brief The callback to invoke */
127         ast_sip_session_media_read_cb read_callback;
128         /*! \brief The media session */
129         struct ast_sip_session_media *session;
130 };
131
132 /*!
133  * \brief Structure which contains media state information (streams, sessions)
134  */
135 struct ast_sip_session_media_state {
136         /*! \brief Mapping of stream to media sessions */
137         AST_VECTOR(, struct ast_sip_session_media *) sessions;
138         /*! \brief Added read callbacks - these are whole structs and not pointers */
139         AST_VECTOR(, struct ast_sip_session_media_read_callback_state) read_callbacks;
140         /*! \brief Default media sessions for each type */
141         struct ast_sip_session_media *default_session[AST_MEDIA_TYPE_END];
142         /*! \brief The media stream topology */
143         struct ast_stream_topology *topology;
144 };
145
146 /*!
147  * \brief Opaque structure representing a request that could not be sent
148  * due to an outstanding INVITE transaction
149  */
150 struct ast_sip_session_delayed_request;
151
152 /*! \brief Opaque struct controlling the suspension of the session's serializer. */
153 struct ast_sip_session_suspender;
154
155 /*!
156  * \brief A structure describing a SIP session
157  *
158  * For the sake of brevity, a "SIP session" in Asterisk is referring to
159  * a dialog initiated by an INVITE. While "session" is typically interpreted
160  * to refer to the negotiated media within a SIP dialog, we have opted
161  * to use the term "SIP session" to refer to the INVITE dialog itself.
162  */
163 struct ast_sip_session {
164         /*! Dialplan extension where incoming call is destined */
165         char exten[AST_MAX_EXTENSION];
166         /*! The endpoint with which Asterisk is communicating */
167         struct ast_sip_endpoint *endpoint;
168         /*! The contact associated with this session */
169         struct ast_sip_contact *contact;
170         /*! The PJSIP details of the session, which includes the dialog */
171         struct pjsip_inv_session *inv_session;
172         /*! The Asterisk channel associated with the session */
173         struct ast_channel *channel;
174         /*! Registered session supplements */
175         AST_LIST_HEAD(, ast_sip_session_supplement) supplements;
176         /*! Datastores added to the session by supplements to the session */
177         struct ao2_container *datastores;
178         /*! Serializer for tasks relating to this SIP session */
179         struct ast_taskprocessor *serializer;
180         /*! Non-null if the session serializer is suspended or being suspended. */
181         struct ast_sip_session_suspender *suspended;
182         /*! Requests that could not be sent due to current inv_session state */
183         AST_LIST_HEAD_NOLOCK(, ast_sip_session_delayed_request) delayed_requests;
184         /*! When we need to reschedule a reinvite, we use this structure to do it */
185         pj_timer_entry rescheduled_reinvite;
186         /*! Format capabilities pertaining to direct media */
187         struct ast_format_cap *direct_media_cap;
188         /*! When we need to forcefully end the session */
189         pj_timer_entry scheduled_termination;
190         /*! Identity of endpoint this session deals with */
191         struct ast_party_id id;
192         /*! Active media state (sessions + streams) - contents are guaranteed not to change */
193         struct ast_sip_session_media_state *active_media_state;
194         /*! Pending media state (sessions + streams) */
195         struct ast_sip_session_media_state *pending_media_state;
196         /*! Optional DSP, used only for inband DTMF/Fax-CNG detection if configured */
197         struct ast_dsp *dsp;
198         /*! Whether the termination of the session should be deferred */
199         unsigned int defer_terminate:1;
200         /*! Termination requested while termination deferred */
201         unsigned int terminate_while_deferred:1;
202         /*! Deferred incoming re-invite */
203         pjsip_rx_data *deferred_reinvite;
204         /*! Current T.38 state */
205         enum ast_sip_session_t38state t38state;
206         /*! The AOR associated with this session */
207         struct ast_sip_aor *aor;
208         /*! From header saved at invite creation */
209         pjsip_fromto_hdr *saved_from_hdr;
210         /*! Whether the end of the session should be deferred */
211         unsigned int defer_end:1;
212         /*! Session end (remote hangup) requested while termination deferred */
213         unsigned int ended_while_deferred:1;
214         /*! Whether to pass through hold and unhold using re-invites with recvonly and sendrecv */
215         unsigned int moh_passthrough:1;
216         /*! DTMF mode to use with this session, from endpoint but can change */
217         enum ast_sip_dtmf_mode dtmf;
218         /*! Initial incoming INVITE Request-URI.  NULL otherwise. */
219         pjsip_uri *request_uri;
220         /* Media statistics for negotiated RTP streams */
221         AST_VECTOR(, struct ast_rtp_instance_stats *) media_stats;
222 };
223
224 typedef int (*ast_sip_session_request_creation_cb)(struct ast_sip_session *session, pjsip_tx_data *tdata);
225 typedef int (*ast_sip_session_response_cb)(struct ast_sip_session *session, pjsip_rx_data *rdata);
226 typedef int (*ast_sip_session_sdp_creation_cb)(struct ast_sip_session *session, pjmedia_sdp_session *sdp);
227
228 /*!
229  * \brief Describes when a supplement should be called into on incoming responses.
230  *
231  * In most cases, session supplements will not need to worry about this because in most cases,
232  * the correct value will be automatically applied. However, there are rare circumstances
233  * when a supplement will want to specify when it should be called.
234  *
235  * The values below are listed in chronological order.
236  */
237 enum ast_sip_session_response_priority {
238         /*!
239          * When processing 3XX responses, the supplement is called into before
240          * the redirecting information is processed.
241          */
242         AST_SIP_SESSION_BEFORE_REDIRECTING = (1 << 0),
243         /*!
244          * For responses to INVITE transactions, the supplement is called into
245          * before media is negotiated.
246          *
247          * This priority is applied by default to any session supplement that
248          * does not specify a response priority.
249          */
250         AST_SIP_SESSION_BEFORE_MEDIA = (1 << 1),
251         /*!
252          * For INVITE transactions, the supplement is called into after media
253          * is negotiated.
254          */
255         AST_SIP_SESSION_AFTER_MEDIA = (1 << 2),
256 };
257
258 /*!
259  * \brief A supplement to SIP message processing
260  *
261  * These can be registered by any module in order to add
262  * processing to incoming and outgoing SIP requests and responses
263  */
264 struct ast_sip_session_supplement {
265         /*! Reference module info */
266         struct ast_module *module;
267         /*! Method on which to call the callbacks. If NULL, call on all methods */
268         const char *method;
269         /*! Priority for this supplement. Lower numbers are visited before higher numbers */
270         enum ast_sip_supplement_priority priority;
271         /*!
272          * \brief Notification that the session has begun
273          * This method will always be called from a SIP servant thread.
274          */
275         void (*session_begin)(struct ast_sip_session *session);
276         /*!
277          * \brief Notification that the session has ended
278          *
279          * This method may or may not be called from a SIP servant thread. Do
280          * not make assumptions about being able to call PJSIP methods from within
281          * this method.
282          */
283         void (*session_end)(struct ast_sip_session *session);
284         /*!
285          * \brief Notification that the session is being destroyed
286          */
287         void (*session_destroy)(struct ast_sip_session *session);
288         /*!
289          * \brief Called on incoming SIP request
290          * This method can indicate a failure in processing in its return. If there
291          * is a failure, it is required that this method sends a response to the request.
292          * This method is always called from a SIP servant thread.
293          *
294          * \note
295          * The following PJSIP methods will not work properly:
296          * pjsip_rdata_get_dlg()
297          * pjsip_rdata_get_tsx()
298          * The reason is that the rdata passed into this function is a cloned rdata structure,
299          * and its module data is not copied during the cloning operation.
300          * If you need to get the dialog, you can get it via session->inv_session->dlg.
301          *
302          * \note
303          * There is no guarantee that a channel will be present on the session when this is called.
304          */
305         int (*incoming_request)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
306         /*!
307          * \brief Called on an incoming SIP response
308          * This method is always called from a SIP servant thread.
309          *
310          * \note
311          * The following PJSIP methods will not work properly:
312          * pjsip_rdata_get_dlg()
313          * pjsip_rdata_get_tsx()
314          * The reason is that the rdata passed into this function is a cloned rdata structure,
315          * and its module data is not copied during the cloning operation.
316          * If you need to get the dialog, you can get it via session->inv_session->dlg.
317          *
318          * \note
319          * There is no guarantee that a channel will be present on the session when this is called.
320          */
321         void (*incoming_response)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
322         /*!
323          * \brief Called on an outgoing SIP request
324          * This method is always called from a SIP servant thread.
325          */
326         void (*outgoing_request)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
327         /*!
328          * \brief Called on an outgoing SIP response
329          * This method is always called from a SIP servant thread.
330          */
331         void (*outgoing_response)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
332         /*! Next item in the list */
333         AST_LIST_ENTRY(ast_sip_session_supplement) next;
334         /*!
335          * Determines when the supplement is processed when handling a response.
336          * Defaults to AST_SIP_SESSION_BEFORE_MEDIA
337          */
338         enum ast_sip_session_response_priority response_priority;
339 };
340
341 enum ast_sip_session_sdp_stream_defer {
342         /*! The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called. */
343         AST_SIP_SESSION_SDP_DEFER_NOT_HANDLED,
344         /*! There was an error encountered. No further operations will take place and the current negotiation will be abandoned. */
345         AST_SIP_SESSION_SDP_DEFER_ERROR,
346         /*! Re-invite is not needed */
347         AST_SIP_SESSION_SDP_DEFER_NOT_NEEDED,
348         /*! Re-invite should be deferred and will be resumed later. No further operations will take place. */
349         AST_SIP_SESSION_SDP_DEFER_NEEDED,
350 };
351
352 /*!
353  * \brief A handler for SDPs in SIP sessions
354  *
355  * An SDP handler is registered by a module that is interested in being the
356  * responsible party for specific types of SDP streams.
357  */
358 struct ast_sip_session_sdp_handler {
359         /*! An identifier for this handler */
360         const char *id;
361         /*!
362          * \brief Determine whether a stream requires that the re-invite be deferred.
363          * If a stream can not be immediately negotiated the re-invite can be deferred and
364          * resumed at a later time. It is up to the handler which caused deferral to occur
365          * to resume it.
366          *
367          * \param session The session for which the media is being re-invited
368          * \param session_media The media being reinvited
369          * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
370          * \param stream PJSIP incoming SDP media lines to parse by handler.
371          *
372          * \return enum ast_sip_session_defer_stream
373          *
374          * \note This is optional, if not implemented the stream is assumed to not be deferred.
375          */
376         enum ast_sip_session_sdp_stream_defer (*defer_incoming_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, const struct pjmedia_sdp_session *sdp, const struct pjmedia_sdp_media *stream);
377         /*!
378          * \brief Set session details based on a stream in an incoming SDP offer or answer
379          * \param session The session for which the media is being negotiated
380          * \param session_media The media session
381          * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
382          * \param index The index for the session media, Asterisk stream, and PJMEDIA stream being negotiated
383          * \param asterisk_stream The Asterisk stream representation
384          * \retval 0 The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called.
385          * \retval <0 There was an error encountered. No further operation will take place and the current negotiation will be abandoned.
386          * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
387          */
388         int (*negotiate_incoming_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media,
389                 const struct pjmedia_sdp_session *sdp, int index, struct ast_stream *asterisk_stream);
390         /*!
391          * \brief Create an SDP media stream and add it to the outgoing SDP offer or answer
392          * \param session The session for which media is being added
393          * \param session_media The media to be setup for this session
394          * \param sdp The entire SDP as currently built
395          * \param remote Optional remote SDP if this is an answer
396          * \param stream The stream that is to be added to the outgoing SDP
397          * \retval 0 This handler has no stream to add. If there are other registered handlers for this stream type, they will be called.
398          * \retval <0 There was an error encountered. No further operation will take place and the current SDP negotiation will be abandoned.
399          * \retval >0 The handler has a stream to be added to the SDP. No further handler of this stream type will be called.
400          */
401         int (*create_outgoing_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, struct pjmedia_sdp_session *sdp,
402                 const struct pjmedia_sdp_session *remote, struct ast_stream *stream);
403         /*!
404          * \brief Update media stream with external address if applicable
405          * \param tdata The outgoing message itself
406          * \param stream The stream on which to operate
407          * \param transport The transport the SDP is going out on
408          */
409         void (*change_outgoing_sdp_stream_media_address)(struct pjsip_tx_data *tdata, struct pjmedia_sdp_media *stream, struct ast_sip_transport *transport);
410         /*!
411          * \brief Apply a negotiated SDP media stream
412          * \param session The session for which media is being applied
413          * \param session_media The media session
414          * \param local The entire local negotiated SDP
415          * \param remote The entire remote negotiated SDP
416          * \param index The index of the session media, SDP streams, and Asterisk streams
417          * \param asterisk_stream The Asterisk stream representation
418          * \retval 0 The stream was not applied by this handler. If there are other registered handlers for this stream type, they will be called.
419          * \retval <0 There was an error encountered. No further operation will take place and the current application will be abandoned.
420          * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
421          */
422         int (*apply_negotiated_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media,
423                 const struct pjmedia_sdp_session *local, const struct pjmedia_sdp_session *remote, int index,
424                 struct ast_stream *asterisk_stream);
425         /*!
426          * \brief Stop a session_media created by this handler but do not destroy resources
427          * \param session The session for which media is being stopped
428          * \param session_media The media to destroy
429          */
430         void (*stream_stop)(struct ast_sip_session_media *session_media);
431         /*!
432          * \brief Destroy a session_media created by this handler
433          * \param session The session for which media is being destroyed
434          * \param session_media The media to destroy
435          */
436         void (*stream_destroy)(struct ast_sip_session_media *session_media);
437         /*! Next item in the list. */
438         AST_LIST_ENTRY(ast_sip_session_sdp_handler) next;
439 };
440
441 /*!
442  * \brief A structure which contains a channel implementation and session
443  */
444 struct ast_sip_channel_pvt {
445         /*! \brief Pointer to channel specific implementation information, must be ao2 object */
446         void *pvt;
447         /*! \brief Pointer to session */
448         struct ast_sip_session *session;
449 };
450
451 /*!
452  * \brief Allocate a new SIP channel pvt structure
453  *
454  * \param pvt Pointer to channel specific information
455  * \param session Pointer to SIP session
456  *
457  * \retval non-NULL success
458  * \retval NULL failure
459  */
460 struct ast_sip_channel_pvt *ast_sip_channel_pvt_alloc(void *pvt, struct ast_sip_session *session);
461
462 /*!
463  * \brief Allocate a new SIP session
464  *
465  * This will take care of allocating the datastores container on the session as well
466  * as placing all registered supplements onto the session.
467  *
468  * The endpoint that is passed in will have its reference count increased by one since
469  * the session will be keeping a reference to the endpoint. The session will relinquish
470  * this reference when the session is destroyed.
471  *
472  * \param endpoint The endpoint that this session communicates with
473  * \param contact The contact associated with this session
474  * \param inv_session The PJSIP INVITE session data
475  * \param rdata INVITE request received (NULL if for outgoing allocation)
476  */
477 struct ast_sip_session *ast_sip_session_alloc(struct ast_sip_endpoint *endpoint,
478         struct ast_sip_contact *contact, pjsip_inv_session *inv, pjsip_rx_data *rdata);
479
480 /*!
481  * \brief Request and wait for the session serializer to be suspended.
482  * \since 12.7.0
483  *
484  * \param session Which session to suspend the serializer.
485  *
486  * \note No channel locks can be held while calling without risk of deadlock.
487  *
488  * \return Nothing
489  */
490 void ast_sip_session_suspend(struct ast_sip_session *session);
491
492 /*!
493  * \brief Request the session serializer be unsuspended.
494  * \since 12.7.0
495  *
496  * \param session Which session to unsuspend the serializer.
497  *
498  * \return Nothing
499  */
500 void ast_sip_session_unsuspend(struct ast_sip_session *session);
501
502 /*!
503  * \brief Create a new outgoing SIP session
504  *
505  * The endpoint that is passed in will have its reference count increased by one since
506  * the session will be keeping a reference to the endpoint. The session will relinquish
507  * this reference when the session is destroyed.
508  *
509  * \param endpoint The endpoint that this session uses for settings
510  * \param contact The contact that this session will communicate with
511  * \param location Name of the location to call, be it named location or explicit URI. Overrides contact if present.
512  * \param request_user Optional request user to place in the request URI if permitted
513  * \param req_topology The requested capabilities
514  */
515 struct ast_sip_session *ast_sip_session_create_outgoing(struct ast_sip_endpoint *endpoint,
516         struct ast_sip_contact *contact, const char *location, const char *request_user,
517         struct ast_stream_topology *req_topology);
518
519 /*!
520  * \brief Terminate a session and, if possible, send the provided response code
521  *
522  * \param session The session to terminate
523  * \param response The response code to use for termination if possible
524  *
525  * \warning Calling this function MAY cause the last session reference to be
526  * released and the session destructor to be called.  If you need to do something
527  * with session after this call, be sure to bump the ref count before calling terminate.
528  */
529 void ast_sip_session_terminate(struct ast_sip_session *session, int response);
530
531 /*!
532  * \brief Defer local termination of a session until remote side terminates, or an amount of time passes
533  *
534  * \param session The session to defer termination on
535  *
536  * \retval 0 Success
537  * \retval -1 Failure
538  */
539 int ast_sip_session_defer_termination(struct ast_sip_session *session);
540
541 /*!
542  * \brief Cancel a pending deferred termination.
543  *
544  * \param session The session to cancel a deferred termination on.
545  */
546 void ast_sip_session_defer_termination_cancel(struct ast_sip_session *session);
547
548 /*!
549  * \brief End the session if it had been previously deferred
550  *
551  * \param session The session to end if it had been deferred
552  */
553 void ast_sip_session_end_if_deferred(struct ast_sip_session *session);
554
555 /*!
556  * \brief Register an SDP handler
557  *
558  * An SDP handler is responsible for parsing incoming SDP streams and ensuring that
559  * Asterisk can cope with the contents. Similarly, the SDP handler will be
560  * responsible for constructing outgoing SDP streams.
561  *
562  * Multiple handlers for the same stream type may be registered. They will be
563  * visited in the order they were registered. Handlers will be visited for each
564  * stream type until one claims to have handled the stream.
565  *
566  * \param handler The SDP handler to register
567  * \param stream_type The type of media stream for which to call the handler
568  * \retval 0 Success
569  * \retval -1 Failure
570  */
571 int ast_sip_session_register_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
572
573 /*!
574  * \brief Unregister an SDP handler
575  *
576  * \param handler The SDP handler to unregister
577  * \param stream_type Stream type for which the SDP handler was registered
578  */
579 void ast_sip_session_unregister_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
580
581 /*!
582  * \brief Register a supplement to SIP session processing
583  *
584  * This allows for someone to insert themselves in the processing of SIP
585  * requests and responses. This, for example could allow for a module to
586  * set channel data based on headers in an incoming message. Similarly,
587  * a module could reject an incoming request if desired.
588  *
589  * \param module Referenced module(NULL safe)
590  * \param supplement The supplement to register
591  */
592 void ast_sip_session_register_supplement_with_module(struct ast_module *module, struct ast_sip_session_supplement *supplement);
593
594 #define ast_sip_session_register_supplement(supplement) \
595                 ast_sip_session_register_supplement_with_module(AST_MODULE_SELF, supplement)
596
597 /*!
598  * \brief Unregister a an supplement to SIP session processing
599  *
600  * \param supplement The supplement to unregister
601  */
602 void ast_sip_session_unregister_supplement(struct ast_sip_session_supplement *supplement);
603
604 /*!
605  * \brief Add supplements to a SIP session
606  *
607  * \param session The session to initialize
608  */
609 int ast_sip_session_add_supplements(struct ast_sip_session *session);
610
611 /*!
612  * \brief Remove supplements from a SIP session
613  *
614  * \param session The session to remove
615  */
616 void ast_sip_session_remove_supplements(struct ast_sip_session *session);
617
618 /*!
619  * \brief Alternative for ast_datastore_alloc()
620  *
621  * There are two major differences between this and ast_datastore_alloc()
622  * 1) This allocates a refcounted object
623  * 2) This will fill in a uid if one is not provided
624  *
625  * DO NOT call ast_datastore_free() on a datastore allocated in this
626  * way since that function will attempt to free the datastore rather
627  * than play nicely with its refcount.
628  *
629  * \param info Callbacks for datastore
630  * \param uid Identifier for datastore
631  * \retval NULL Failed to allocate datastore
632  * \retval non-NULL Newly allocated datastore
633  */
634 struct ast_datastore *ast_sip_session_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
635
636 /*!
637  * \brief Add a datastore to a SIP session
638  *
639  * Note that SIP uses reference counted datastores. The datastore passed into this function
640  * must have been allocated using ao2_alloc() or there will be serious problems.
641  *
642  * \param session The session to add the datastore to
643  * \param datastore The datastore to be added to the session
644  * \retval 0 Success
645  * \retval -1 Failure
646  */
647 int ast_sip_session_add_datastore(struct ast_sip_session *session, struct ast_datastore *datastore);
648
649 /*!
650  * \brief Retrieve a session datastore
651  *
652  * The datastore retrieved will have its reference count incremented. When the caller is done
653  * with the datastore, the reference counted needs to be decremented using ao2_ref().
654  *
655  * \param session The session from which to retrieve the datastore
656  * \param name The name of the datastore to retrieve
657  * \retval NULL Failed to find the specified datastore
658  * \retval non-NULL The specified datastore
659  */
660 struct ast_datastore *ast_sip_session_get_datastore(struct ast_sip_session *session, const char *name);
661
662 /*!
663  * \brief Remove a session datastore from the session
664  *
665  * This operation may cause the datastore's free() callback to be called if the reference
666  * count reaches zero.
667  *
668  * \param session The session to remove the datastore from
669  * \param name The name of the datastore to remove
670  */
671 void ast_sip_session_remove_datastore(struct ast_sip_session *session, const char *name);
672
673 /*!
674  * \brief Send a reinvite or UPDATE on a session
675  *
676  * This method will inspect the session in order to construct an appropriate
677  * session refresh request. As with any outgoing request in res_pjsip_session,
678  * this will call into registered supplements in case they wish to add anything.
679  *
680  * Note: The on_request_creation callback may or may not be called in the same
681  * thread where this function is called. Request creation may need to be delayed
682  * due to the current INVITE transaction state.
683  *
684  * \param session The session on which the reinvite will be sent
685  * \param on_request_creation Callback called when request is created
686  * \param on_sdp_creation Callback called when SDP is created
687  * \param on_response Callback called when response for request is received
688  * \param method The method that should be used when constructing the session refresh
689  * \param generate_new_sdp Boolean to indicate if a new SDP should be created
690  * \param media_state Optional requested media state for the SDP
691  *
692  * \retval 0 Successfully sent refresh
693  * \retval -1 Failure to send refresh
694  *
695  * \note If a media_state is passed in ownership will be taken in all cases
696  */
697 int ast_sip_session_refresh(struct ast_sip_session *session,
698                 ast_sip_session_request_creation_cb on_request_creation,
699                 ast_sip_session_sdp_creation_cb on_sdp_creation,
700                 ast_sip_session_response_cb on_response,
701                 enum ast_sip_session_refresh_method method,
702                 int generate_new_sdp,
703                 struct ast_sip_session_media_state *media_state);
704
705 /*!
706  * \brief Regenerate SDP Answer
707  *
708  * This method is used when an SDP offer has been received but an SDP answer
709  * has not been sent yet. It requests that a new local SDP be created and
710  * set as the SDP answer. As with any outgoing request in res_pjsip_session,
711  * this will call into registered supplements in case they wish to add anything.
712  *
713  * \param session The session on which the answer will be updated
714  * \param on_sdp_creation Callback called when SDP is created
715  * \param generate_new_sdp Boolean to indicate if a new SDP should be created
716  * \retval 0 Successfully updated the SDP answer
717  * \retval -1 Failure to updated the SDP answer
718  */
719 int ast_sip_session_regenerate_answer(struct ast_sip_session *session,
720                 ast_sip_session_sdp_creation_cb on_sdp_creation);
721
722 /*!
723  * \brief Send a SIP response
724  *
725  * This will send the SIP response specified in tdata and
726  * call into any registered supplements' outgoing_response callback.
727  *
728  * \param session The session on which to send the response.
729  * \param tdata The response to send
730  */
731 void ast_sip_session_send_response(struct ast_sip_session *session, pjsip_tx_data *tdata);
732
733 /*!
734  * \brief Send a SIP request
735  *
736  * This will send the SIP request specified in tdata and
737  * call into any registered supplements' outgoing_request callback.
738  *
739  * \param session The session to which to send the request
740  * \param tdata The request to send
741  */
742 void ast_sip_session_send_request(struct ast_sip_session *session, pjsip_tx_data *tdata);
743
744 /*!
745  * \brief Creates an INVITE request.
746  *
747  * \param session Starting session for the INVITE
748  * \param tdata The created request.
749  */
750 int ast_sip_session_create_invite(struct ast_sip_session *session, pjsip_tx_data **tdata);
751
752 /*!
753  * \brief Send a SIP request and get called back when a response is received
754  *
755  * This will send the request out exactly the same as ast_sip_send_request() does.
756  * The difference is that when a response arrives, the specified callback will be
757  * called into
758  *
759  * \param session The session on which to send the request
760  * \param tdata The request to send
761  * \param on_response Callback to be called when a response is received
762  */
763 void ast_sip_session_send_request_with_cb(struct ast_sip_session *session, pjsip_tx_data *tdata,
764                 ast_sip_session_response_cb on_response);
765
766 /*!
767  * \brief Retrieves a session from a dialog
768  *
769  * \param dlg The dialog to retrieve the session from
770  *
771  * \retval non-NULL if session exists
772  * \retval NULL if no session
773  *
774  * \note The reference count of the session is increased when returned
775  *
776  * \note This function *must* be called with the dialog locked
777  */
778 struct ast_sip_session *ast_sip_dialog_get_session(pjsip_dialog *dlg);
779
780 /*!
781  * \brief Resumes processing of a deferred incoming re-invite
782  *
783  * \param session The session which has a pending incoming re-invite
784  *
785  * \note When resuming a re-invite it is given to the pjsip stack as if it
786  *       had just been received from a transport, this means that the deferral
787  *       callback will be called again.
788  */
789 void ast_sip_session_resume_reinvite(struct ast_sip_session *session);
790
791 /*!
792  * \brief Determines if a provided pending stream will be the default stream or not
793  * \since 15.0.0
794  *
795  * \param session The session to check against
796  * \param stream The pending stream
797  *
798  * \retval 1 if stream will be default
799  * \retval 0 if stream will NOT be the default
800  */
801 int ast_sip_session_is_pending_stream_default(const struct ast_sip_session *session, const struct ast_stream *stream);
802
803 /*!
804  * \brief Allocate a session media state structure
805  * \since 15.0.0
806  *
807  * \retval non-NULL success
808  * \retval NULL failure
809  */
810 struct ast_sip_session_media_state *ast_sip_session_media_state_alloc(void);
811
812 /*!
813  * \brief Allocate an ast_session_media and add it to the media state's vector.
814  * \since 15.0.0
815  *
816  * This allocates a session media of the specified type. The position argument
817  * determines where in the vector that the new session media will be inserted.
818  *
819  * \note The returned ast_session_media is the reference held by the vector. Callers
820  * of this function must NOT decrement the refcount of the session media.
821  *
822  * \param session Session on which to query active media state for
823  * \param media_state Media state to place the session media into
824  * \param type The type of the session media
825  * \param position Position at which to insert the new session media.
826  *
827  * \note The active media state will be queried and if a media session already
828  * exists at the given position for the same type it will be reused instead of
829  * allocating a new one.
830  *
831  * \retval non-NULL success
832  * \retval NULL failure
833  */
834 struct ast_sip_session_media *ast_sip_session_media_state_add(struct ast_sip_session *session,
835         struct ast_sip_session_media_state *media_state, enum ast_media_type type, int position);
836
837 /*!
838  * \brief Save a media stats.
839  *
840  * \param media_state The media state to save
841  */
842 void ast_sip_session_media_stats_save(struct ast_sip_session *sip_session, struct ast_sip_session_media_state *media_state);
843
844 /*!
845  * \brief Reset a media state to a clean state
846  * \since 15.0.0
847  *
848  * \param media_state The media state to reset
849  */
850 void ast_sip_session_media_state_reset(struct ast_sip_session_media_state *media_state);
851
852 /*!
853  * \brief Clone a media state
854  * \since 15.0.0
855  *
856  * \param media_state The media state to clone
857  *
858  * \retval non-NULL success
859  * \retval NULL failure
860  */
861 struct ast_sip_session_media_state *ast_sip_session_media_state_clone(const struct ast_sip_session_media_state *media_state);
862
863 /*!
864  * \brief Free a session media state structure
865  * \since 15.0.0
866  */
867 void ast_sip_session_media_state_free(struct ast_sip_session_media_state *media_state);
868
869 /*!
870  * \brief Set a read callback for a media session with a specific file descriptor
871  * \since 15.0.0
872  *
873  * \param session The session
874  * \param session_media The media session
875  * \param fd The file descriptor
876  * \param callback The read callback
877  *
878  * \retval 0 the read callback was successfully added
879  * \retval -1 the read callback could not be added
880  *
881  * \note This operations on the pending media state
882  */
883 int ast_sip_session_media_add_read_callback(struct ast_sip_session *session, struct ast_sip_session_media *session_media,
884         int fd, ast_sip_session_media_read_cb callback);
885
886 /*!
887  * \brief Set a write callback for a media session
888  * \since 15.0.0
889  *
890  * \param session The session
891  * \param session_media The media session
892  * \param callback The write callback
893  *
894  * \retval 0 the write callback was successfully add
895  * \retval -1 the write callback is already set to something different
896  *
897  * \note This operates on the pending media state
898  */
899 int ast_sip_session_media_set_write_callback(struct ast_sip_session *session, struct ast_sip_session_media *session_media,
900         ast_sip_session_media_write_cb callback);
901
902 /*!
903  * \brief Retrieve the underlying media session that is acting as transport for a media session
904  * \since 15.0.0
905  *
906  * \param session The session
907  * \param session_media The media session to retrieve the transport for
908  *
909  * \note This operates on the pending media state
910  *
911  * \note This function is guaranteed to return non-NULL
912  */
913 struct ast_sip_session_media *ast_sip_session_media_get_transport(struct ast_sip_session *session, struct ast_sip_session_media *session_media);
914
915 #endif /* _RES_PJSIP_SESSION_H */