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