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