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