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