615a6214cc460c8ff83d13d188b5ac23ba3e694b
[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/netsock.h"
29 /* Needed for ast_sdp_srtp struct */
30 #include "asterisk/sdp_srtp.h"
31
32 /* Forward declarations */
33 struct ast_sip_endpoint;
34 struct ast_sip_transport;
35 struct pjsip_inv_session;
36 struct ast_channel;
37 struct ast_datastore;
38 struct ast_datastore_info;
39 struct ao2_container;
40 struct pjsip_tx_data;
41 struct pjsip_rx_data;
42 struct ast_party_id;
43 struct pjmedia_sdp_media;
44 struct pjmedia_sdp_session;
45 struct ast_dsp;
46 struct ast_udptl;
47
48 /*! \brief T.38 states for a session */
49 enum ast_sip_session_t38state {
50         T38_DISABLED = 0,   /*!< Not enabled */
51         T38_LOCAL_REINVITE, /*!< Offered from local - REINVITE */
52         T38_PEER_REINVITE,  /*!< Offered from peer - REINVITE */
53         T38_ENABLED,        /*!< Negotiated (enabled) */
54         T38_REJECTED,       /*!< Refused */
55         T38_MAX_ENUM,       /*!< Not an actual state; used as max value in the enum */
56 };
57
58 struct ast_sip_session_sdp_handler;
59
60 /*!
61  * \brief A structure containing SIP session media information
62  */
63 struct ast_sip_session_media {
64         union {
65                 /*! \brief RTP instance itself */
66                 struct ast_rtp_instance *rtp;
67                 /*! \brief UDPTL instance itself */
68                 struct ast_udptl *udptl;
69         };
70         /*! \brief Direct media address */
71         struct ast_sockaddr direct_media_addr;
72         /*! \brief SDP handler that setup the RTP */
73         struct ast_sip_session_sdp_handler *handler;
74         /*! \brief Holds SRTP information */
75         struct ast_sdp_srtp *srtp;
76         /*! \brief Stream is on hold */
77         unsigned int held:1;
78         /*! \brief Stream type this session media handles */
79         char stream_type[1];
80 };
81
82 /*!
83  * \brief Opaque structure representing a request that could not be sent
84  * due to an outstanding INVITE transaction
85  */
86 struct ast_sip_session_delayed_request;
87
88 /*!
89  * \brief A structure describing a SIP session
90  *
91  * For the sake of brevity, a "SIP session" in Asterisk is referring to
92  * a dialog initiated by an INVITE. While "session" is typically interpreted
93  * to refer to the negotiated media within a SIP dialog, we have opted
94  * to use the term "SIP session" to refer to the INVITE dialog itself.
95  */
96 struct ast_sip_session {
97         /* Dialplan extension where incoming call is destined */
98         char exten[AST_MAX_EXTENSION];
99         /* The endpoint with which Asterisk is communicating */
100         struct ast_sip_endpoint *endpoint;
101         /* The PJSIP details of the session, which includes the dialog */
102         struct pjsip_inv_session *inv_session;
103         /* The Asterisk channel associated with the session */
104         struct ast_channel *channel;
105         /* Registered session supplements */
106         AST_LIST_HEAD(, ast_sip_session_supplement) supplements;
107         /* Datastores added to the session by supplements to the session */
108         struct ao2_container *datastores;
109         /* Media streams */
110         struct ao2_container *media;
111         /* Serializer for tasks relating to this SIP session */
112         struct ast_taskprocessor *serializer;
113         /* Requests that could not be sent due to current inv_session state */
114         AST_LIST_HEAD_NOLOCK(, ast_sip_session_delayed_request) delayed_requests;
115         /* When we need to reschedule a reinvite, we use this structure to do it */
116         pj_timer_entry rescheduled_reinvite;
117         /* Format capabilities pertaining to direct media */
118         struct ast_format_cap *direct_media_cap;
119         /* When we need to forcefully end the session */
120         pj_timer_entry scheduled_termination;
121         /* Identity of endpoint this session deals with */
122         struct ast_party_id id;
123         /* Requested capabilities */
124         struct ast_format_cap *req_caps;
125         /* Codecs overriden by dialplan on an outgoing request */
126         struct ast_codec_pref override_prefs;
127         /* Optional DSP, used only for inband DTMF detection if configured */
128         struct ast_dsp *dsp;
129         /* Whether the termination of the session should be deferred */
130         unsigned int defer_terminate:1;
131         /* Deferred incoming re-invite */
132         pjsip_rx_data *deferred_reinvite;
133         /* Current T.38 state */
134         enum ast_sip_session_t38state t38state;
135 };
136
137 typedef int (*ast_sip_session_request_creation_cb)(struct ast_sip_session *session, pjsip_tx_data *tdata);
138 typedef int (*ast_sip_session_response_cb)(struct ast_sip_session *session, pjsip_rx_data *rdata);
139 typedef int (*ast_sip_session_sdp_creation_cb)(struct ast_sip_session *session, pjmedia_sdp_session *sdp);
140
141 enum ast_sip_session_supplement_priority {
142         /*! Top priority. Supplements with this priority are those that need to run before any others */
143         AST_SIP_SESSION_SUPPLEMENT_PRIORITY_FIRST = 0,
144         /*! Channel creation priority.
145          * chan_pjsip creates a channel at this priority. If your supplement depends on being run before
146          * or after channel creation, then set your priority to be lower or higher than this value.
147          */
148         AST_SIP_SESSION_SUPPLEMENT_PRIORITY_CHANNEL = 1000000,
149         /*! Lowest priority. Supplements with this priority should be run after all other supplements */
150         AST_SIP_SESSION_SUPPLEMENT_PRIORITY_LAST = INT_MAX,
151 };
152
153 /*!
154  * \brief A supplement to SIP message processing
155  *
156  * These can be registered by any module in order to add
157  * processing to incoming and outgoing SIP requests and responses
158  */
159 struct ast_sip_session_supplement {
160     /*! Method on which to call the callbacks. If NULL, call on all methods */
161     const char *method;
162         /*! Priority for this supplement. Lower numbers are visited before higher numbers */
163         enum ast_sip_session_supplement_priority priority;
164     /*!
165          * \brief Notification that the session has begun
166          * This method will always be called from a SIP servant thread.
167          */
168     void (*session_begin)(struct ast_sip_session *session);
169     /*! 
170          * \brief Notification that the session has ended
171          *
172          * This method may or may not be called from a SIP servant thread. Do
173          * not make assumptions about being able to call PJSIP methods from within
174          * this method.
175          */
176     void (*session_end)(struct ast_sip_session *session);
177         /*!
178          * \brief Notification that the session is being destroyed
179          */
180         void (*session_destroy)(struct ast_sip_session *session);
181     /*!
182      * \brief Called on incoming SIP request
183      * This method can indicate a failure in processing in its return. If there
184      * is a failure, it is required that this method sends a response to the request.
185          * This method is always called from a SIP servant thread.
186          *
187          * \note
188          * The following PJSIP methods will not work properly:
189          * pjsip_rdata_get_dlg()
190          * pjsip_rdata_get_tsx()
191          * The reason is that the rdata passed into this function is a cloned rdata structure,
192          * and its module data is not copied during the cloning operation.
193          * If you need to get the dialog, you can get it via session->inv_session->dlg.
194          *
195          * \note
196          * There is no guarantee that a channel will be present on the session when this is called.
197      */
198     int (*incoming_request)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
199     /*! 
200          * \brief Called on an incoming SIP response
201          * This method is always called from a SIP servant thread.
202          *
203          * \note
204          * The following PJSIP methods will not work properly:
205          * pjsip_rdata_get_dlg()
206          * pjsip_rdata_get_tsx()
207          * The reason is that the rdata passed into this function is a cloned rdata structure,
208          * and its module data is not copied during the cloning operation.
209          * If you need to get the dialog, you can get it via session->inv_session->dlg.
210          *
211          * \note
212          * There is no guarantee that a channel will be present on the session when this is called.
213          */
214     void (*incoming_response)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
215     /*!
216          * \brief Called on an outgoing SIP request
217          * This method is always called from a SIP servant thread.
218          */
219     void (*outgoing_request)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
220     /*! 
221          * \brief Called on an outgoing SIP response
222          * This method is always called from a SIP servant thread.
223          */
224     void (*outgoing_response)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
225         /*! Next item in the list */
226         AST_LIST_ENTRY(ast_sip_session_supplement) next;
227 };
228
229 /*!
230  * \brief A handler for SDPs in SIP sessions
231  *
232  * An SDP handler is registered by a module that is interested in being the
233  * responsible party for specific types of SDP streams.
234  */
235 struct ast_sip_session_sdp_handler {
236         /*! An identifier for this handler */
237         const char *id;
238         /*!
239          * \brief Determine whether a stream requires that the re-invite be deferred.
240          * If a stream can not be immediately negotiated the re-invite can be deferred and
241          * resumed at a later time. It is up to the handler which caused deferral to occur
242          * to resume it.
243          * \param session The session for which the media is being re-invited
244          * \param session_media The media being reinvited
245          * \param sdp The entire SDP.
246          * \retval 0 The stream was unhandled or does not need the re-invite to be deferred.
247          * \retval 1 Re-invite should be deferred and will be resumed later. No further operations will take place.
248          * \note This is optional, if not implemented the stream is assumed to not be deferred.
249          */
250         int (*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);
251         /*!
252          * \brief Set session details based on a stream in an incoming SDP offer or answer
253          * \param session The session for which the media is being negotiated
254          * \param session_media The media to be setup for this session
255          * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
256          * \param stream The stream on which to operate
257          * \retval 0 The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called.
258          * \retval <0 There was an error encountered. No further operation will take place and the current negotiation will be abandoned.
259          * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
260          */
261         int (*negotiate_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);
262         /*!
263          * \brief Create an SDP media stream and add it to the outgoing SDP offer or answer
264          * \param session The session for which media is being added
265          * \param session_media The media to be setup for this session
266          * \param stream The stream on which to operate
267          * \retval 0 The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called.
268          * \retval <0 There was an error encountered. No further operation will take place and the current negotiation will be abandoned.
269          * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
270          */
271         int (*handle_incoming_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, const struct pjmedia_sdp_session *sdp, struct pjmedia_sdp_media *stream);
272         /*!
273          * \brief Create an SDP media stream and add it to the outgoing SDP offer or answer
274          * \param session The session for which media is being added
275          * \param session_media The media to be setup for this session
276          * \param sdp The entire SDP as currently built
277          * \retval 0 This handler has no stream to add. If there are other registered handlers for this stream type, they will be called.
278          * \retval <0 There was an error encountered. No further operation will take place and the current SDP negotiation will be abandoned.
279          * \retval >0 The handler has a stream to be added to the SDP. No further handler of this stream type will be called.
280          */
281         int (*create_outgoing_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, struct pjmedia_sdp_session *sdp);
282         /*!
283          * \brief Update media stream with external address if applicable
284          * \param tdata The outgoing message itself
285          * \param stream The stream on which to operate
286          * \param transport The transport the SDP is going out on
287          */
288         void (*change_outgoing_sdp_stream_media_address)(struct pjsip_tx_data *tdata, struct pjmedia_sdp_media *stream, struct ast_sip_transport *transport);
289         /*!
290          * \brief Apply a negotiated SDP media stream
291          * \param session The session for which media is being applied
292          * \param session_media The media to be setup for this session
293          * \param local The entire local negotiated SDP
294          * \param local_stream The local stream which to apply
295          * \param remote The entire remote negotiated SDP
296          * \param remote_stream The remote stream which to apply
297          * \retval 0 The stream was not applied by this handler. If there are other registered handlers for this stream type, they will be called.
298          * \retval <0 There was an error encountered. No further operation will take place and the current application will be abandoned.
299          * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
300          */
301         int (*apply_negotiated_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, const struct pjmedia_sdp_session *local, const struct pjmedia_sdp_media *local_stream,
302                 const struct pjmedia_sdp_session *remote, const struct pjmedia_sdp_media *remote_stream);
303         /*!
304          * \brief Destroy a session_media created by this handler
305          * \param session The session for which media is being destroyed
306          * \param session_media The media to destroy
307          */
308         void (*stream_destroy)(struct ast_sip_session_media *session_media);
309         /*! Next item in the list. */
310         AST_LIST_ENTRY(ast_sip_session_sdp_handler) next;
311 };
312
313 /*!
314  * \brief A structure which contains a channel implementation and session
315  */
316 struct ast_sip_channel_pvt {
317         /*! \brief Pointer to channel specific implementation information, must be ao2 object */
318         void *pvt;
319         /*! \brief Pointer to session */
320         struct ast_sip_session *session;
321 };
322
323 /*!
324  * \brief Allocate a new SIP channel pvt structure
325  *
326  * \param pvt Pointer to channel specific implementation
327  * \param session Pointer to SIP session
328  *
329  * \retval non-NULL success
330  * \retval NULL failure
331  */
332 struct ast_sip_channel_pvt *ast_sip_channel_pvt_alloc(void *pvt, struct ast_sip_session *session);
333
334 /*!
335  * \brief Allocate a new SIP session
336  *
337  * This will take care of allocating the datastores container on the session as well
338  * as placing all registered supplements onto the session.
339  *
340  * The endpoint that is passed in will have its reference count increased by one since
341  * the session will be keeping a reference to the endpoint. The session will relinquish
342  * this reference when the session is destroyed.
343  *
344  * \param endpoint The endpoint that this session communicates with
345  * \param inv_session The PJSIP INVITE session data
346  */
347 struct ast_sip_session *ast_sip_session_alloc(struct ast_sip_endpoint *endpoint, pjsip_inv_session *inv);
348
349 /*!
350  * \brief Create a new outgoing SIP session
351  *
352  * The endpoint that is passed in will have its reference count increased by one since
353  * the session will be keeping a reference to the endpoint. The session will relinquish
354  * this reference when the session is destroyed.
355  *
356  * \param endpoint The endpoint that this session uses for settings
357  * \param location Optional name of the location to call, be it named location or explicit URI
358  * \param request_user Optional request user to place in the request URI if permitted
359  * \param req_caps The requested capabilities
360  */
361 struct ast_sip_session *ast_sip_session_create_outgoing(struct ast_sip_endpoint *endpoint, const char *location, const char *request_user, struct ast_format_cap *req_caps);
362
363 /*!
364  * \brief Defer local termination of a session until remote side terminates, or an amount of time passes
365  *
366  * \param session The session to defer termination on
367  */
368 void ast_sip_session_defer_termination(struct ast_sip_session *session);
369
370 /*!
371  * \brief Register an SDP handler
372  *
373  * An SDP handler is responsible for parsing incoming SDP streams and ensuring that
374  * Asterisk can cope with the contents. Similarly, the SDP handler will be
375  * responsible for constructing outgoing SDP streams.
376  *
377  * Multiple handlers for the same stream type may be registered. They will be
378  * visited in the order they were registered. Handlers will be visited for each
379  * stream type until one claims to have handled the stream.
380  *
381  * \param handler The SDP handler to register
382  * \param stream_type The type of media stream for which to call the handler
383  * \retval 0 Success
384  * \retval -1 Failure
385  */
386 int ast_sip_session_register_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
387
388 /*!
389  * \brief Unregister an SDP handler
390  *
391  * \param handler The SDP handler to unregister
392  * \param stream_type Stream type for which the SDP handler was registered
393  */
394 void ast_sip_session_unregister_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
395
396 /*!
397  * \brief Register a supplement to SIP session processing
398  *
399  * This allows for someone to insert themselves in the processing of SIP
400  * requests and responses. This, for example could allow for a module to
401  * set channel data based on headers in an incoming message. Similarly,
402  * a module could reject an incoming request if desired.
403  *
404  * \param supplement The supplement to register
405  * \retval 0 Success
406  * \retval -1 Failure
407  */
408 int ast_sip_session_register_supplement(struct ast_sip_session_supplement *supplement);
409
410 /*!
411  * \brief Unregister a an supplement to SIP session processing
412  *
413  * \param supplement The supplement to unregister
414  */
415 void ast_sip_session_unregister_supplement(struct ast_sip_session_supplement *supplement);
416
417 /*!
418  * \brief Alternative for ast_datastore_alloc()
419  *
420  * There are two major differences between this and ast_datastore_alloc()
421  * 1) This allocates a refcounted object
422  * 2) This will fill in a uid if one is not provided
423  *
424  * DO NOT call ast_datastore_free() on a datastore allocated in this
425  * way since that function will attempt to free the datastore rather
426  * than play nicely with its refcount.
427  *
428  * \param info Callbacks for datastore
429  * \param uid Identifier for datastore
430  * \retval NULL Failed to allocate datastore
431  * \retval non-NULL Newly allocated datastore
432  */
433 struct ast_datastore *ast_sip_session_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
434
435 /*!
436  * \brief Add a datastore to a SIP session
437  *
438  * Note that SIP uses reference counted datastores. The datastore passed into this function
439  * must have been allocated using ao2_alloc() or there will be serious problems.
440  *
441  * \param session The session to add the datastore to
442  * \param datastore The datastore to be added to the session
443  * \retval 0 Success
444  * \retval -1 Failure
445  */
446 int ast_sip_session_add_datastore(struct ast_sip_session *session, struct ast_datastore *datastore);
447
448 /*!
449  * \brief Retrieve a session datastore
450  *
451  * The datastore retrieved will have its reference count incremented. When the caller is done
452  * with the datastore, the reference counted needs to be decremented using ao2_ref().
453  *
454  * \param session The session from which to retrieve the datastore
455  * \param name The name of the datastore to retrieve
456  * \retval NULL Failed to find the specified datastore
457  * \retval non-NULL The specified datastore
458  */
459 struct ast_datastore *ast_sip_session_get_datastore(struct ast_sip_session *session, const char *name);
460
461 /*!
462  * \brief Remove a session datastore from the session
463  *
464  * This operation may cause the datastore's free() callback to be called if the reference
465  * count reaches zero.
466  *
467  * \param session The session to remove the datastore from
468  * \param name The name of the datastore to remove
469  */
470 void ast_sip_session_remove_datastore(struct ast_sip_session *session, const char *name);
471
472 /*!
473  * \brief Send a reinvite or UPDATE on a session
474  *
475  * This method will inspect the session in order to construct an appropriate
476  * session refresh request. As with any outgoing request in res_pjsip_session,
477  * this will call into registered supplements in case they wish to add anything.
478  *
479  * Note: The on_request_creation callback may or may not be called in the same
480  * thread where this function is called. Request creation may need to be delayed
481  * due to the current INVITE transaction state.
482  * 
483  * \param session The session on which the reinvite will be sent
484  * \param on_request_creation Callback called when request is created
485  * \param on_sdp_creation Callback called when SDP is created
486  * \param on_response Callback called when response for request is received
487  * \param method The method that should be used when constructing the session refresh
488  * \param generate_new_sdp Boolean to indicate if a new SDP should be created
489  * \retval 0 Successfully sent refresh
490  * \retval -1 Failure to send refresh
491  */
492 int ast_sip_session_refresh(struct ast_sip_session *session,
493                 ast_sip_session_request_creation_cb on_request_creation,
494                 ast_sip_session_sdp_creation_cb on_sdp_creation,
495                 ast_sip_session_response_cb on_response,
496                 enum ast_sip_session_refresh_method method,
497                 int generate_new_sdp);
498
499 /*!
500  * \brief Send a SIP response
501  *
502  * This will send the SIP response specified in tdata and
503  * call into any registered supplements' outgoing_response callback.
504  *
505  * \param session The session on which to send the response.
506  * \param tdata The response to send
507  */
508 void ast_sip_session_send_response(struct ast_sip_session *session, pjsip_tx_data *tdata);
509
510 /*!
511  * \brief Send a SIP request
512  *
513  * This will send the SIP request specified in tdata and
514  * call into any registered supplements' outgoing_request callback.
515  *
516  * \param session The session to which to send the request
517  * \param tdata The request to send
518  */
519 void ast_sip_session_send_request(struct ast_sip_session *session, pjsip_tx_data *tdata);
520
521 /*!
522  * \brief Creates an INVITE request.
523  *
524  * \param session Starting session for the INVITE
525  * \param tdata The created request.
526  */
527 int ast_sip_session_create_invite(struct ast_sip_session *session, pjsip_tx_data **tdata);
528
529 /*!
530  * \brief Send a SIP request and get called back when a response is received
531  *
532  * This will send the request out exactly the same as ast_sip_send_request() does.
533  * The difference is that when a response arrives, the specified callback will be
534  * called into
535  *
536  * \param session The session on which to send the request
537  * \param tdata The request to send
538  * \param on_response Callback to be called when a response is received
539  */
540 void ast_sip_session_send_request_with_cb(struct ast_sip_session *session, pjsip_tx_data *tdata,
541                 ast_sip_session_response_cb on_response);
542
543 /*!
544  * \brief Retrieves a session from a dialog
545  *
546  * \param dlg The dialog to retrieve the session from
547  *
548  * \retval non-NULL if session exists
549  * \retval NULL if no session
550  *
551  * \note The reference count of the session is increased when returned
552  *
553  * \note This function *must* be called with the dialog locked
554  */
555 struct ast_sip_session *ast_sip_dialog_get_session(pjsip_dialog *dlg);
556
557 /*!
558  * \brief Resumes processing of a deferred incoming re-invite
559  *
560  * \param session The session which has a pending incoming re-invite
561  *
562  * \note When resuming a re-invite it is given to the pjsip stack as if it
563  *       had just been received from a transport, this means that the deferral
564  *       callback will be called again.
565  */
566 void ast_sip_session_resume_reinvite(struct ast_sip_session *session);
567
568 #endif /* _RES_PJSIP_SESSION_H */