5ca2c99a5295616ce31dd4d60019378396742f5f
[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
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 What type of encryption is in use on this stream */
77         enum ast_sip_session_media_encryption encryption;
78         /*! \brief The media transport in use for this stream */
79         pj_str_t transport;
80         /*! \brief Scheduler ID for RTP keepalive */
81         int keepalive_sched_id;
82         /*! \brief Scheduler ID for RTP timeout */
83         int timeout_sched_id;
84         /*! \brief Stream is on hold by remote side */
85         unsigned int remotely_held:1;
86         /*! \brief Stream is on hold by local side */
87         unsigned int locally_held:1;
88         /*! \brief Stream type this session media handles */
89         char stream_type[1];
90 };
91
92 /*!
93  * \brief Opaque structure representing a request that could not be sent
94  * due to an outstanding INVITE transaction
95  */
96 struct ast_sip_session_delayed_request;
97
98 /*! \brief Opaque struct controlling the suspension of the session's serializer. */
99 struct ast_sip_session_suspender;
100
101 /*!
102  * \brief A structure describing a SIP session
103  *
104  * For the sake of brevity, a "SIP session" in Asterisk is referring to
105  * a dialog initiated by an INVITE. While "session" is typically interpreted
106  * to refer to the negotiated media within a SIP dialog, we have opted
107  * to use the term "SIP session" to refer to the INVITE dialog itself.
108  */
109 struct ast_sip_session {
110         /*! Dialplan extension where incoming call is destined */
111         char exten[AST_MAX_EXTENSION];
112         /*! The endpoint with which Asterisk is communicating */
113         struct ast_sip_endpoint *endpoint;
114         /*! The contact associated with this session */
115         struct ast_sip_contact *contact;
116         /*! The PJSIP details of the session, which includes the dialog */
117         struct pjsip_inv_session *inv_session;
118         /*! The Asterisk channel associated with the session */
119         struct ast_channel *channel;
120         /*! Registered session supplements */
121         AST_LIST_HEAD(, ast_sip_session_supplement) supplements;
122         /*! Datastores added to the session by supplements to the session */
123         struct ao2_container *datastores;
124         /*! Media streams */
125         struct ao2_container *media;
126         /*! Serializer for tasks relating to this SIP session */
127         struct ast_taskprocessor *serializer;
128         /*! Non-null if the session serializer is suspended or being suspended. */
129         struct ast_sip_session_suspender *suspended;
130         /*! Requests that could not be sent due to current inv_session state */
131         AST_LIST_HEAD_NOLOCK(, ast_sip_session_delayed_request) delayed_requests;
132         /*! When we need to reschedule a reinvite, we use this structure to do it */
133         pj_timer_entry rescheduled_reinvite;
134         /*! Format capabilities pertaining to direct media */
135         struct ast_format_cap *direct_media_cap;
136         /*! When we need to forcefully end the session */
137         pj_timer_entry scheduled_termination;
138         /*! Identity of endpoint this session deals with */
139         struct ast_party_id id;
140         /*! Requested capabilities */
141         struct ast_format_cap *req_caps;
142         /*! Optional DSP, used only for inband DTMF detection if configured */
143         struct ast_dsp *dsp;
144         /*! Whether the termination of the session should be deferred */
145         unsigned int defer_terminate:1;
146         /*! Termination requested while termination deferred */
147         unsigned int terminate_while_deferred:1;
148         /*! Deferred incoming re-invite */
149         pjsip_rx_data *deferred_reinvite;
150         /*! Current T.38 state */
151         enum ast_sip_session_t38state t38state;
152         /*! The AOR associated with this session */
153         struct ast_sip_aor *aor;
154         /*! From header saved at invite creation */
155         pjsip_fromto_hdr *saved_from_hdr;
156 };
157
158 typedef int (*ast_sip_session_request_creation_cb)(struct ast_sip_session *session, pjsip_tx_data *tdata);
159 typedef int (*ast_sip_session_response_cb)(struct ast_sip_session *session, pjsip_rx_data *rdata);
160 typedef int (*ast_sip_session_sdp_creation_cb)(struct ast_sip_session *session, pjmedia_sdp_session *sdp);
161
162 /*!
163  * \brief Describes when a supplement should be called into on incoming responses.
164  *
165  * In most cases, session supplements will not need to worry about this because in most cases,
166  * the correct value will be automatically applied. However, there are rare circumstances
167  * when a supplement will want to specify when it should be called.
168  *
169  * The values below are listed in chronological order.
170  */
171 enum ast_sip_session_response_priority {
172         /*!
173          * When processing 3XX responses, the supplement is called into before
174          * the redirecting information is processed.
175          */
176         AST_SIP_SESSION_BEFORE_REDIRECTING = (1 << 0),
177         /*!
178          * For responses to INVITE transactions, the supplement is called into
179          * before media is negotiated.
180          *
181          * This priority is applied by default to any session supplement that
182          * does not specify a response priority.
183          */
184         AST_SIP_SESSION_BEFORE_MEDIA = (1 << 1),
185         /*!
186          * For INVITE transactions, the supplement is called into after media
187          * is negotiated.
188          */
189         AST_SIP_SESSION_AFTER_MEDIA = (1 << 2),
190 };
191
192 /*!
193  * \brief A supplement to SIP message processing
194  *
195  * These can be registered by any module in order to add
196  * processing to incoming and outgoing SIP requests and responses
197  */
198 struct ast_sip_session_supplement {
199         /*! Method on which to call the callbacks. If NULL, call on all methods */
200         const char *method;
201         /*! Priority for this supplement. Lower numbers are visited before higher numbers */
202         enum ast_sip_supplement_priority priority;
203         /*!
204          * \brief Notification that the session has begun
205          * This method will always be called from a SIP servant thread.
206          */
207         void (*session_begin)(struct ast_sip_session *session);
208         /*! 
209          * \brief Notification that the session has ended
210          *
211          * This method may or may not be called from a SIP servant thread. Do
212          * not make assumptions about being able to call PJSIP methods from within
213          * this method.
214          */
215         void (*session_end)(struct ast_sip_session *session);
216         /*!
217          * \brief Notification that the session is being destroyed
218          */
219         void (*session_destroy)(struct ast_sip_session *session);
220         /*!
221          * \brief Called on incoming SIP request
222          * This method can indicate a failure in processing in its return. If there
223          * is a failure, it is required that this method sends a response to the request.
224          * This method is always called from a SIP servant thread.
225          *
226          * \note
227          * The following PJSIP methods will not work properly:
228          * pjsip_rdata_get_dlg()
229          * pjsip_rdata_get_tsx()
230          * The reason is that the rdata passed into this function is a cloned rdata structure,
231          * and its module data is not copied during the cloning operation.
232          * If you need to get the dialog, you can get it via session->inv_session->dlg.
233          *
234          * \note
235          * There is no guarantee that a channel will be present on the session when this is called.
236          */
237         int (*incoming_request)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
238         /*! 
239          * \brief Called on an incoming SIP response
240          * This method is always called from a SIP servant thread.
241          *
242          * \note
243          * The following PJSIP methods will not work properly:
244          * pjsip_rdata_get_dlg()
245          * pjsip_rdata_get_tsx()
246          * The reason is that the rdata passed into this function is a cloned rdata structure,
247          * and its module data is not copied during the cloning operation.
248          * If you need to get the dialog, you can get it via session->inv_session->dlg.
249          *
250          * \note
251          * There is no guarantee that a channel will be present on the session when this is called.
252          */
253         void (*incoming_response)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
254         /*!
255          * \brief Called on an outgoing SIP request
256          * This method is always called from a SIP servant thread.
257          */
258         void (*outgoing_request)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
259         /*! 
260          * \brief Called on an outgoing SIP response
261          * This method is always called from a SIP servant thread.
262          */
263         void (*outgoing_response)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
264         /*! Next item in the list */
265         AST_LIST_ENTRY(ast_sip_session_supplement) next;
266         /*!
267          * Determines when the supplement is processed when handling a response.
268          * Defaults to AST_SIP_SESSION_BEFORE_MEDIA
269          */
270         enum ast_sip_session_response_priority response_priority;
271 };
272
273 enum ast_sip_session_sdp_stream_defer {
274         /*! The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called. */
275         AST_SIP_SESSION_SDP_DEFER_NOT_HANDLED,
276         /*! There was an error encountered. No further operations will take place and the current negotiation will be abandoned. */
277         AST_SIP_SESSION_SDP_DEFER_ERROR,
278         /*! Re-invite is not needed */
279         AST_SIP_SESSION_SDP_DEFER_NOT_NEEDED,
280         /*! Re-invite should be deferred and will be resumed later. No further operations will take place. */
281         AST_SIP_SESSION_SDP_DEFER_NEEDED,
282 };
283
284 /*!
285  * \brief A handler for SDPs in SIP sessions
286  *
287  * An SDP handler is registered by a module that is interested in being the
288  * responsible party for specific types of SDP streams.
289  */
290 struct ast_sip_session_sdp_handler {
291         /*! An identifier for this handler */
292         const char *id;
293         /*!
294          * \brief Determine whether a stream requires that the re-invite be deferred.
295          * If a stream can not be immediately negotiated the re-invite can be deferred and
296          * resumed at a later time. It is up to the handler which caused deferral to occur
297          * to resume it.
298          *
299          * \param session The session for which the media is being re-invited
300          * \param session_media The media being reinvited
301          * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
302          * \param stream PJSIP incoming SDP media lines to parse by handler.
303          *
304          * \return enum ast_sip_session_defer_stream
305          *
306          * \note This is optional, if not implemented the stream is assumed to not be deferred.
307          */
308         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);
309         /*!
310          * \brief Set session details based on a stream in an incoming SDP offer or answer
311          * \param session The session for which the media is being negotiated
312          * \param session_media The media to be setup for this session
313          * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
314          * \param stream The stream on which to operate
315          * \retval 0 The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called.
316          * \retval <0 There was an error encountered. No further operation will take place and the current negotiation will be abandoned.
317          * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
318          */
319         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);
320         /*!
321          * \brief Create an SDP media stream and add it to the outgoing SDP offer or answer
322          * \param session The session for which media is being added
323          * \param session_media The media to be setup for this session
324          * \param stream The stream on which to operate
325          * \retval 0 The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called.
326          * \retval <0 There was an error encountered. No further operation will take place and the current negotiation will be abandoned.
327          * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
328          */
329         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);
330         /*!
331          * \brief Create an SDP media stream and add it to the outgoing SDP offer or answer
332          * \param session The session for which media is being added
333          * \param session_media The media to be setup for this session
334          * \param sdp The entire SDP as currently built
335          * \retval 0 This handler has no stream to add. If there are other registered handlers for this stream type, they will be called.
336          * \retval <0 There was an error encountered. No further operation will take place and the current SDP negotiation will be abandoned.
337          * \retval >0 The handler has a stream to be added to the SDP. No further handler of this stream type will be called.
338          */
339         int (*create_outgoing_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, struct pjmedia_sdp_session *sdp);
340         /*!
341          * \brief Update media stream with external address if applicable
342          * \param tdata The outgoing message itself
343          * \param stream The stream on which to operate
344          * \param transport The transport the SDP is going out on
345          */
346         void (*change_outgoing_sdp_stream_media_address)(struct pjsip_tx_data *tdata, struct pjmedia_sdp_media *stream, struct ast_sip_transport *transport);
347         /*!
348          * \brief Apply a negotiated SDP media stream
349          * \param session The session for which media is being applied
350          * \param session_media The media to be setup for this session
351          * \param local The entire local negotiated SDP
352          * \param local_stream The local stream which to apply
353          * \param remote The entire remote negotiated SDP
354          * \param remote_stream The remote stream which to apply
355          * \retval 0 The stream was not applied by this handler. If there are other registered handlers for this stream type, they will be called.
356          * \retval <0 There was an error encountered. No further operation will take place and the current application will be abandoned.
357          * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
358          */
359         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,
360                 const struct pjmedia_sdp_session *remote, const struct pjmedia_sdp_media *remote_stream);
361         /*!
362          * \brief Stop a session_media created by this handler but do not destroy resources
363          * \param session The session for which media is being stopped
364          * \param session_media The media to destroy
365          */
366         void (*stream_stop)(struct ast_sip_session_media *session_media);
367         /*!
368          * \brief Destroy a session_media created by this handler
369          * \param session The session for which media is being destroyed
370          * \param session_media The media to destroy
371          */
372         void (*stream_destroy)(struct ast_sip_session_media *session_media);
373         /*! Next item in the list. */
374         AST_LIST_ENTRY(ast_sip_session_sdp_handler) next;
375 };
376
377 /*!
378  * \brief A structure which contains a channel implementation and session
379  */
380 struct ast_sip_channel_pvt {
381         /*! \brief Pointer to channel specific implementation information, must be ao2 object */
382         void *pvt;
383         /*! \brief Pointer to session */
384         struct ast_sip_session *session;
385 };
386
387 /*!
388  * \brief Allocate a new SIP channel pvt structure
389  *
390  * \param pvt Pointer to channel specific implementation
391  * \param session Pointer to SIP session
392  *
393  * \retval non-NULL success
394  * \retval NULL failure
395  */
396 struct ast_sip_channel_pvt *ast_sip_channel_pvt_alloc(void *pvt, struct ast_sip_session *session);
397
398 /*!
399  * \brief Allocate a new SIP session
400  *
401  * This will take care of allocating the datastores container on the session as well
402  * as placing all registered supplements onto the session.
403  *
404  * The endpoint that is passed in will have its reference count increased by one since
405  * the session will be keeping a reference to the endpoint. The session will relinquish
406  * this reference when the session is destroyed.
407  *
408  * \param endpoint The endpoint that this session communicates with
409  * \param contact The contact associated with this session
410  * \param inv_session The PJSIP INVITE session data
411  * \param rdata INVITE request received (NULL if for outgoing allocation)
412  */
413 struct ast_sip_session *ast_sip_session_alloc(struct ast_sip_endpoint *endpoint,
414         struct ast_sip_contact *contact, pjsip_inv_session *inv, pjsip_rx_data *rdata);
415
416 /*!
417  * \brief Request and wait for the session serializer to be suspended.
418  * \since 12.7.0
419  *
420  * \param session Which session to suspend the serializer.
421  *
422  * \note No channel locks can be held while calling without risk of deadlock.
423  *
424  * \return Nothing
425  */
426 void ast_sip_session_suspend(struct ast_sip_session *session);
427
428 /*!
429  * \brief Request the session serializer be unsuspended.
430  * \since 12.7.0
431  *
432  * \param session Which session to unsuspend the serializer.
433  *
434  * \return Nothing
435  */
436 void ast_sip_session_unsuspend(struct ast_sip_session *session);
437
438 /*!
439  * \brief Create a new outgoing SIP session
440  *
441  * The endpoint that is passed in will have its reference count increased by one since
442  * the session will be keeping a reference to the endpoint. The session will relinquish
443  * this reference when the session is destroyed.
444  *
445  * \param endpoint The endpoint that this session uses for settings
446  * \param contact The contact that this session will communicate with
447  * \param location Name of the location to call, be it named location or explicit URI. Overrides contact if present.
448  * \param request_user Optional request user to place in the request URI if permitted
449  * \param req_caps The requested capabilities
450  */
451 struct ast_sip_session *ast_sip_session_create_outgoing(struct ast_sip_endpoint *endpoint,
452         struct ast_sip_contact *contact, const char *location, const char *request_user,
453         struct ast_format_cap *req_caps);
454
455 /*!
456  * \brief Terminate a session and, if possible, send the provided response code
457  *
458  * \param session The session to terminate
459  * \param response The response code to use for termination if possible
460  */
461 void ast_sip_session_terminate(struct ast_sip_session *session, int response);
462
463 /*!
464  * \brief Defer local termination of a session until remote side terminates, or an amount of time passes
465  *
466  * \param session The session to defer termination on
467  *
468  * \retval 0 Success
469  * \retval -1 Failure
470  */
471 int ast_sip_session_defer_termination(struct ast_sip_session *session);
472
473 /*!
474  * \brief Cancel a pending deferred termination.
475  *
476  * \param session The session to cancel a deferred termination on.
477  */
478 void ast_sip_session_defer_termination_cancel(struct ast_sip_session *session);
479
480 /*!
481  * \brief Register an SDP handler
482  *
483  * An SDP handler is responsible for parsing incoming SDP streams and ensuring that
484  * Asterisk can cope with the contents. Similarly, the SDP handler will be
485  * responsible for constructing outgoing SDP streams.
486  *
487  * Multiple handlers for the same stream type may be registered. They will be
488  * visited in the order they were registered. Handlers will be visited for each
489  * stream type until one claims to have handled the stream.
490  *
491  * \param handler The SDP handler to register
492  * \param stream_type The type of media stream for which to call the handler
493  * \retval 0 Success
494  * \retval -1 Failure
495  */
496 int ast_sip_session_register_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
497
498 /*!
499  * \brief Unregister an SDP handler
500  *
501  * \param handler The SDP handler to unregister
502  * \param stream_type Stream type for which the SDP handler was registered
503  */
504 void ast_sip_session_unregister_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
505
506 /*!
507  * \brief Register a supplement to SIP session processing
508  *
509  * This allows for someone to insert themselves in the processing of SIP
510  * requests and responses. This, for example could allow for a module to
511  * set channel data based on headers in an incoming message. Similarly,
512  * a module could reject an incoming request if desired.
513  *
514  * \param supplement The supplement to register
515  * \retval 0 Success
516  * \retval -1 Failure
517  */
518 int ast_sip_session_register_supplement(struct ast_sip_session_supplement *supplement);
519
520 /*!
521  * \brief Unregister a an supplement to SIP session processing
522  *
523  * \param supplement The supplement to unregister
524  */
525 void ast_sip_session_unregister_supplement(struct ast_sip_session_supplement *supplement);
526
527 /*!
528  * \brief Alternative for ast_datastore_alloc()
529  *
530  * There are two major differences between this and ast_datastore_alloc()
531  * 1) This allocates a refcounted object
532  * 2) This will fill in a uid if one is not provided
533  *
534  * DO NOT call ast_datastore_free() on a datastore allocated in this
535  * way since that function will attempt to free the datastore rather
536  * than play nicely with its refcount.
537  *
538  * \param info Callbacks for datastore
539  * \param uid Identifier for datastore
540  * \retval NULL Failed to allocate datastore
541  * \retval non-NULL Newly allocated datastore
542  */
543 struct ast_datastore *ast_sip_session_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
544
545 /*!
546  * \brief Add a datastore to a SIP session
547  *
548  * Note that SIP uses reference counted datastores. The datastore passed into this function
549  * must have been allocated using ao2_alloc() or there will be serious problems.
550  *
551  * \param session The session to add the datastore to
552  * \param datastore The datastore to be added to the session
553  * \retval 0 Success
554  * \retval -1 Failure
555  */
556 int ast_sip_session_add_datastore(struct ast_sip_session *session, struct ast_datastore *datastore);
557
558 /*!
559  * \brief Retrieve a session datastore
560  *
561  * The datastore retrieved will have its reference count incremented. When the caller is done
562  * with the datastore, the reference counted needs to be decremented using ao2_ref().
563  *
564  * \param session The session from which to retrieve the datastore
565  * \param name The name of the datastore to retrieve
566  * \retval NULL Failed to find the specified datastore
567  * \retval non-NULL The specified datastore
568  */
569 struct ast_datastore *ast_sip_session_get_datastore(struct ast_sip_session *session, const char *name);
570
571 /*!
572  * \brief Remove a session datastore from the session
573  *
574  * This operation may cause the datastore's free() callback to be called if the reference
575  * count reaches zero.
576  *
577  * \param session The session to remove the datastore from
578  * \param name The name of the datastore to remove
579  */
580 void ast_sip_session_remove_datastore(struct ast_sip_session *session, const char *name);
581
582 /*!
583  * \brief Send a reinvite or UPDATE on a session
584  *
585  * This method will inspect the session in order to construct an appropriate
586  * session refresh request. As with any outgoing request in res_pjsip_session,
587  * this will call into registered supplements in case they wish to add anything.
588  *
589  * Note: The on_request_creation callback may or may not be called in the same
590  * thread where this function is called. Request creation may need to be delayed
591  * due to the current INVITE transaction state.
592  * 
593  * \param session The session on which the reinvite will be sent
594  * \param on_request_creation Callback called when request is created
595  * \param on_sdp_creation Callback called when SDP is created
596  * \param on_response Callback called when response for request is received
597  * \param method The method that should be used when constructing the session refresh
598  * \param generate_new_sdp Boolean to indicate if a new SDP should be created
599  * \retval 0 Successfully sent refresh
600  * \retval -1 Failure to send refresh
601  */
602 int ast_sip_session_refresh(struct ast_sip_session *session,
603                 ast_sip_session_request_creation_cb on_request_creation,
604                 ast_sip_session_sdp_creation_cb on_sdp_creation,
605                 ast_sip_session_response_cb on_response,
606                 enum ast_sip_session_refresh_method method,
607                 int generate_new_sdp);
608
609 /*!
610  * \brief Send a SIP response
611  *
612  * This will send the SIP response specified in tdata and
613  * call into any registered supplements' outgoing_response callback.
614  *
615  * \param session The session on which to send the response.
616  * \param tdata The response to send
617  */
618 void ast_sip_session_send_response(struct ast_sip_session *session, pjsip_tx_data *tdata);
619
620 /*!
621  * \brief Send a SIP request
622  *
623  * This will send the SIP request specified in tdata and
624  * call into any registered supplements' outgoing_request callback.
625  *
626  * \param session The session to which to send the request
627  * \param tdata The request to send
628  */
629 void ast_sip_session_send_request(struct ast_sip_session *session, pjsip_tx_data *tdata);
630
631 /*!
632  * \brief Creates an INVITE request.
633  *
634  * \param session Starting session for the INVITE
635  * \param tdata The created request.
636  */
637 int ast_sip_session_create_invite(struct ast_sip_session *session, pjsip_tx_data **tdata);
638
639 /*!
640  * \brief Send a SIP request and get called back when a response is received
641  *
642  * This will send the request out exactly the same as ast_sip_send_request() does.
643  * The difference is that when a response arrives, the specified callback will be
644  * called into
645  *
646  * \param session The session on which to send the request
647  * \param tdata The request to send
648  * \param on_response Callback to be called when a response is received
649  */
650 void ast_sip_session_send_request_with_cb(struct ast_sip_session *session, pjsip_tx_data *tdata,
651                 ast_sip_session_response_cb on_response);
652
653 /*!
654  * \brief Retrieves a session from a dialog
655  *
656  * \param dlg The dialog to retrieve the session from
657  *
658  * \retval non-NULL if session exists
659  * \retval NULL if no session
660  *
661  * \note The reference count of the session is increased when returned
662  *
663  * \note This function *must* be called with the dialog locked
664  */
665 struct ast_sip_session *ast_sip_dialog_get_session(pjsip_dialog *dlg);
666
667 /*!
668  * \brief Resumes processing of a deferred incoming re-invite
669  *
670  * \param session The session which has a pending incoming re-invite
671  *
672  * \note When resuming a re-invite it is given to the pjsip stack as if it
673  *       had just been received from a transport, this means that the deferral
674  *       callback will be called again.
675  */
676 void ast_sip_session_resume_reinvite(struct ast_sip_session *session);
677
678 /*! \brief Determines whether the res_pjsip_session module is loaded */
679 #define CHECK_PJSIP_SESSION_MODULE_LOADED()                             \
680         do {                                                            \
681                 CHECK_PJSIP_MODULE_LOADED();                            \
682                 if (!ast_module_check("res_pjsip_session.so")) {        \
683                         return AST_MODULE_LOAD_DECLINE;                 \
684                 }                                                       \
685         } while(0)
686
687 #endif /* _RES_PJSIP_SESSION_H */