Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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 */
105  enum ast_media_type type;
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 */
150  /*! \brief Default media sessions for each type */
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 */
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 */
242  /*! Originating Line Info (ANI II digits) */
243  int ani2;
244 };
245 
246 typedef int (*ast_sip_session_request_creation_cb)(struct ast_sip_session *session, pjsip_tx_data *tdata);
247 typedef int (*ast_sip_session_response_cb)(struct ast_sip_session *session, pjsip_rx_data *rdata);
248 typedef int (*ast_sip_session_sdp_creation_cb)(struct ast_sip_session *session, pjmedia_sdp_session *sdp);
249 
250 /*!
251  * \brief Describes when a supplement should be called into on incoming responses.
252  *
253  * In most cases, session supplements will not need to worry about this because in most cases,
254  * the correct value will be automatically applied. However, there are rare circumstances
255  * when a supplement will want to specify when it should be called.
256  *
257  * The values below are listed in chronological order.
258  */
260  /*!
261  * When processing 3XX responses, the supplement is called into before
262  * the redirecting information is processed.
263  */
265  /*!
266  * For responses to INVITE transactions, the supplement is called into
267  * before media is negotiated.
268  *
269  * This priority is applied by default to any session supplement that
270  * does not specify a response priority.
271  */
273  /*!
274  * For INVITE transactions, the supplement is called into after media
275  * is negotiated.
276  */
278 };
279 
280 /*!
281  * \brief A supplement to SIP message processing
282  *
283  * These can be registered by any module in order to add
284  * processing to incoming and outgoing SIP requests and responses
285  */
287  /*! Reference module info */
289  /*! Method on which to call the callbacks. If NULL, call on all methods */
290  const char *method;
291  /*! Priority for this supplement. Lower numbers are visited before higher numbers */
293  /*!
294  * \brief Notification that the session has begun
295  * This method will always be called from a SIP servant thread.
296  */
298  /*!
299  * \brief Notification that the session has ended
300  *
301  * This method may or may not be called from a SIP servant thread. Do
302  * not make assumptions about being able to call PJSIP methods from within
303  * this method.
304  */
306  /*!
307  * \brief Notification that the session is being destroyed
308  */
310  /*!
311  * \brief Called on incoming SIP request
312  * This method can indicate a failure in processing in its return. If there
313  * is a failure, it is required that this method sends a response to the request.
314  * This method is always called from a SIP servant thread.
315  *
316  * \note
317  * The following PJSIP methods will not work properly:
318  * pjsip_rdata_get_dlg()
319  * pjsip_rdata_get_tsx()
320  * The reason is that the rdata passed into this function is a cloned rdata structure,
321  * and its module data is not copied during the cloning operation.
322  * If you need to get the dialog, you can get it via session->inv_session->dlg.
323  *
324  * \note
325  * There is no guarantee that a channel will be present on the session when this is called.
326  */
327  int (*incoming_request)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
328  /*!
329  * \brief Called on an incoming SIP response
330  * This method is always called from a SIP servant thread.
331  *
332  * \note
333  * The following PJSIP methods will not work properly:
334  * pjsip_rdata_get_dlg()
335  * pjsip_rdata_get_tsx()
336  * The reason is that the rdata passed into this function is a cloned rdata structure,
337  * and its module data is not copied during the cloning operation.
338  * If you need to get the dialog, you can get it via session->inv_session->dlg.
339  *
340  * \note
341  * There is no guarantee that a channel will be present on the session when this is called.
342  */
343  void (*incoming_response)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
344  /*!
345  * \brief Called on an outgoing SIP request
346  * This method is always called from a SIP servant thread.
347  */
348  void (*outgoing_request)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
349  /*!
350  * \brief Called on an outgoing SIP response
351  * This method is always called from a SIP servant thread.
352  */
353  void (*outgoing_response)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
354  /*! Next item in the list */
356  /*!
357  * Determines when the supplement is processed when handling a response.
358  * Defaults to AST_SIP_SESSION_BEFORE_MEDIA
359  */
361 };
362 
364  /*! The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called. */
366  /*! There was an error encountered. No further operations will take place and the current negotiation will be abandoned. */
368  /*! Re-invite is not needed */
370  /*! Re-invite should be deferred and will be resumed later. No further operations will take place. */
372 };
373 
374 /*!
375  * \brief A handler for SDPs in SIP sessions
376  *
377  * An SDP handler is registered by a module that is interested in being the
378  * responsible party for specific types of SDP streams.
379  */
381  /*! An identifier for this handler */
382  const char *id;
383  /*!
384  * \brief Determine whether a stream requires that the re-invite be deferred.
385  * If a stream can not be immediately negotiated the re-invite can be deferred and
386  * resumed at a later time. It is up to the handler which caused deferral to occur
387  * to resume it.
388  *
389  * \param session The session for which the media is being re-invited
390  * \param session_media The media being reinvited
391  * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
392  * \param stream PJSIP incoming SDP media lines to parse by handler.
393  *
394  * \return enum ast_sip_session_defer_stream
395  *
396  * \note This is optional, if not implemented the stream is assumed to not be deferred.
397  */
398  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);
399  /*!
400  * \brief Set session details based on a stream in an incoming SDP offer or answer
401  * \param session The session for which the media is being negotiated
402  * \param session_media The media session
403  * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
404  * \param index The index for the session media, Asterisk stream, and PJMEDIA stream being negotiated
405  * \param asterisk_stream The Asterisk stream representation
406  * \retval 0 The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called.
407  * \retval <0 There was an error encountered. No further operation will take place and the current negotiation will be abandoned.
408  * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
409  */
411  const struct pjmedia_sdp_session *sdp, int index, struct ast_stream *asterisk_stream);
412  /*!
413  * \brief Create an SDP media stream and add it to the outgoing SDP offer or answer
414  * \param session The session for which media is being added
415  * \param session_media The media to be setup for this session
416  * \param sdp The entire SDP as currently built
417  * \param remote Optional remote SDP if this is an answer
418  * \param stream The stream that is to be added to the outgoing SDP
419  * \retval 0 This handler has no stream to add. If there are other registered handlers for this stream type, they will be called.
420  * \retval <0 There was an error encountered. No further operation will take place and the current SDP negotiation will be abandoned.
421  * \retval >0 The handler has a stream to be added to the SDP. No further handler of this stream type will be called.
422  */
423  int (*create_outgoing_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, struct pjmedia_sdp_session *sdp,
424  const struct pjmedia_sdp_session *remote, struct ast_stream *stream);
425  /*!
426  * \brief Update media stream with external address if applicable
427  * \param tdata The outgoing message itself
428  * \param stream The stream on which to operate
429  * \param transport The transport the SDP is going out on
430  */
431  void (*change_outgoing_sdp_stream_media_address)(struct pjsip_tx_data *tdata, struct pjmedia_sdp_media *stream, struct ast_sip_transport *transport);
432  /*!
433  * \brief Apply a negotiated SDP media stream
434  * \param session The session for which media is being applied
435  * \param session_media The media session
436  * \param local The entire local negotiated SDP
437  * \param remote The entire remote negotiated SDP
438  * \param index The index of the session media, SDP streams, and Asterisk streams
439  * \param asterisk_stream The Asterisk stream representation
440  * \retval 0 The stream was not applied by this handler. If there are other registered handlers for this stream type, they will be called.
441  * \retval <0 There was an error encountered. No further operation will take place and the current application will be abandoned.
442  * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
443  */
445  const struct pjmedia_sdp_session *local, const struct pjmedia_sdp_session *remote, int index,
446  struct ast_stream *asterisk_stream);
447  /*!
448  * \brief Stop a session_media created by this handler but do not destroy resources
449  * \param session The session for which media is being stopped
450  * \param session_media The media to destroy
451  */
452  void (*stream_stop)(struct ast_sip_session_media *session_media);
453  /*!
454  * \brief Destroy a session_media created by this handler
455  * \param session The session for which media is being destroyed
456  * \param session_media The media to destroy
457  */
458  void (*stream_destroy)(struct ast_sip_session_media *session_media);
459  /*! Next item in the list. */
461 };
462 
463 /*!
464  * \brief A structure which contains a channel implementation and session
465  */
467  /*! \brief Pointer to channel specific implementation information, must be ao2 object */
468  void *pvt;
469  /*! \brief Pointer to session */
471 };
472 
473 /*!
474  * \brief Allocate a new SIP channel pvt structure
475  *
476  * \param pvt Pointer to channel specific information
477  * \param session Pointer to SIP session
478  *
479  * \retval non-NULL success
480  * \retval NULL failure
481  */
483 
484 /*!
485  * \brief Allocate a new SIP session
486  *
487  * This will take care of allocating the datastores container on the session as well
488  * as placing all registered supplements onto the session.
489  *
490  * The endpoint that is passed in will have its reference count increased by one since
491  * the session will be keeping a reference to the endpoint. The session will relinquish
492  * this reference when the session is destroyed.
493  *
494  * \param endpoint The endpoint that this session communicates with
495  * \param contact The contact associated with this session
496  * \param inv The PJSIP INVITE session data
497  * \param rdata INVITE request received (NULL if for outgoing allocation)
498  */
500  struct ast_sip_contact *contact, pjsip_inv_session *inv, pjsip_rx_data *rdata);
501 
502 /*!
503  * \brief Request and wait for the session serializer to be suspended.
504  * \since 12.7.0
505  *
506  * \param session Which session to suspend the serializer.
507  *
508  * \note No channel locks can be held while calling without risk of deadlock.
509  */
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  */
519 
520 /*!
521  * \brief Create a new outgoing SIP session
522  *
523  * The endpoint that is passed in will have its reference count increased by one since
524  * the session will be keeping a reference to the endpoint. The session will relinquish
525  * this reference when the session is destroyed.
526  *
527  * \param endpoint The endpoint that this session uses for settings
528  * \param contact The contact that this session will communicate with
529  * \param location Name of the location to call, be it named location or explicit URI. Overrides contact if present.
530  * \param request_user Optional request user to place in the request URI if permitted
531  * \param req_topology The requested capabilities
532  */
534  struct ast_sip_contact *contact, const char *location, const char *request_user,
535  struct ast_stream_topology *req_topology);
536 
537 /*!
538  * \brief Terminate a session and, if possible, send the provided response code
539  *
540  * \param session The session to terminate
541  * \param response The response code to use for termination if possible
542  *
543  * \warning Calling this function MAY cause the last session reference to be
544  * released and the session destructor to be called. If you need to do something
545  * with session after this call, be sure to bump the ref count before calling terminate.
546  */
547 void ast_sip_session_terminate(struct ast_sip_session *session, int response);
548 
549 /*!
550  * \brief Defer local termination of a session until remote side terminates, or an amount of time passes
551  *
552  * \param session The session to defer termination on
553  *
554  * \retval 0 Success
555  * \retval -1 Failure
556  */
558 
559 /*!
560  * \brief Cancel a pending deferred termination.
561  *
562  * \param session The session to cancel a deferred termination on.
563  */
565 
566 /*!
567  * \brief End the session if it had been previously deferred
568  *
569  * \param session The session to end if it had been deferred
570  */
572 
573 /*!
574  * \brief Register an SDP handler
575  *
576  * An SDP handler is responsible for parsing incoming SDP streams and ensuring that
577  * Asterisk can cope with the contents. Similarly, the SDP handler will be
578  * responsible for constructing outgoing SDP streams.
579  *
580  * Multiple handlers for the same stream type may be registered. They will be
581  * visited in the order they were registered. Handlers will be visited for each
582  * stream type until one claims to have handled the stream.
583  *
584  * \param handler The SDP handler to register
585  * \param stream_type The type of media stream for which to call the handler
586  * \retval 0 Success
587  * \retval -1 Failure
588  */
589 int ast_sip_session_register_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
590 
591 /*!
592  * \brief Unregister an SDP handler
593  *
594  * \param handler The SDP handler to unregister
595  * \param stream_type Stream type for which the SDP handler was registered
596  */
597 void ast_sip_session_unregister_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
598 
599 /*!
600  * \brief Register a supplement to SIP session processing
601  *
602  * This allows for someone to insert themselves in the processing of SIP
603  * requests and responses. This, for example could allow for a module to
604  * set channel data based on headers in an incoming message. Similarly,
605  * a module could reject an incoming request if desired.
606  *
607  * \param module Referenced module(NULL safe)
608  * \param supplement The supplement to register
609  */
611 
612 #define ast_sip_session_register_supplement(supplement) \
613  ast_sip_session_register_supplement_with_module(AST_MODULE_SELF, supplement)
614 
615 /*!
616  * \brief Unregister a an supplement to SIP session processing
617  *
618  * \param supplement The supplement to unregister
619  */
621 
622 /*!
623  * \brief Add supplements to a SIP session
624  *
625  * \param session The session to initialize
626  */
628 
629 /*!
630  * \brief Remove supplements from a SIP session
631  *
632  * \param session The session to remove
633  */
635 
636 /*!
637  * \brief Alternative for ast_datastore_alloc()
638  *
639  * There are two major differences between this and ast_datastore_alloc()
640  * 1) This allocates a refcounted object
641  * 2) This will fill in a uid if one is not provided
642  *
643  * DO NOT call ast_datastore_free() on a datastore allocated in this
644  * way since that function will attempt to free the datastore rather
645  * than play nicely with its refcount.
646  *
647  * \param info Callbacks for datastore
648  * \param uid Identifier for datastore
649  * \retval NULL Failed to allocate datastore
650  * \retval non-NULL Newly allocated datastore
651  */
652 struct ast_datastore *ast_sip_session_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
653 
654 /*!
655  * \brief Add a datastore to a SIP session
656  *
657  * Note that SIP uses reference counted datastores. The datastore passed into this function
658  * must have been allocated using ao2_alloc() or there will be serious problems.
659  *
660  * \param session The session to add the datastore to
661  * \param datastore The datastore to be added to the session
662  * \retval 0 Success
663  * \retval -1 Failure
664  */
666 
667 /*!
668  * \brief Retrieve a session datastore
669  *
670  * The datastore retrieved will have its reference count incremented. When the caller is done
671  * with the datastore, the reference counted needs to be decremented using ao2_ref().
672  *
673  * \param session The session from which to retrieve the datastore
674  * \param name The name of the datastore to retrieve
675  * \retval NULL Failed to find the specified datastore
676  * \retval non-NULL The specified datastore
677  */
679 
680 /*!
681  * \brief Remove a session datastore from the session
682  *
683  * This operation may cause the datastore's free() callback to be called if the reference
684  * count reaches zero.
685  *
686  * \param session The session to remove the datastore from
687  * \param name The name of the datastore to remove
688  */
690 
691 /*!
692  * \brief Send a reinvite or UPDATE on a session
693  *
694  * This method will inspect the session in order to construct an appropriate
695  * session refresh request. As with any outgoing request in res_pjsip_session,
696  * this will call into registered supplements in case they wish to add anything.
697  *
698  * Note: The on_request_creation callback may or may not be called in the same
699  * thread where this function is called. Request creation may need to be delayed
700  * due to the current INVITE transaction state.
701  *
702  * \param session The session on which the reinvite will be sent
703  * \param on_request_creation Callback called when request is created
704  * \param on_sdp_creation Callback called when SDP is created
705  * \param on_response Callback called when response for request is received
706  * \param method The method that should be used when constructing the session refresh
707  * \param generate_new_sdp Boolean to indicate if a new SDP should be created
708  * \param media_state Optional requested media state for the SDP
709  *
710  * \retval 0 Successfully sent refresh
711  * \retval -1 Failure to send refresh
712  *
713  * \note If a media_state is passed in ownership will be taken in all cases
714  */
716  ast_sip_session_request_creation_cb on_request_creation,
717  ast_sip_session_sdp_creation_cb on_sdp_creation,
718  ast_sip_session_response_cb on_response,
720  int generate_new_sdp,
721  struct ast_sip_session_media_state *media_state);
722 
723 /*!
724  * \brief Regenerate SDP Answer
725  *
726  * This method is used when an SDP offer has been received but an SDP answer
727  * has not been sent yet. It requests that a new local SDP be created and
728  * set as the SDP answer. As with any outgoing request in res_pjsip_session,
729  * this will call into registered supplements in case they wish to add anything.
730  *
731  * \param session The session on which the answer will be updated
732  * \param on_sdp_creation Callback called when SDP is created
733  * \retval 0 Successfully updated the SDP answer
734  * \retval -1 Failure to updated the SDP answer
735  */
737  ast_sip_session_sdp_creation_cb on_sdp_creation);
738 
739 /*!
740  * \brief Send a SIP response
741  *
742  * This will send the SIP response specified in tdata and
743  * call into any registered supplements' outgoing_response callback.
744  *
745  * \param session The session on which to send the response.
746  * \param tdata The response to send
747  */
748 void ast_sip_session_send_response(struct ast_sip_session *session, pjsip_tx_data *tdata);
749 
750 /*!
751  * \brief Send a SIP request
752  *
753  * This will send the SIP request specified in tdata and
754  * call into any registered supplements' outgoing_request callback.
755  *
756  * \param session The session to which to send the request
757  * \param tdata The request to send
758  */
759 void ast_sip_session_send_request(struct ast_sip_session *session, pjsip_tx_data *tdata);
760 
761 /*!
762  * \brief Creates an INVITE request.
763  *
764  * \param session Starting session for the INVITE
765  * \param tdata The created request.
766  */
767 int ast_sip_session_create_invite(struct ast_sip_session *session, pjsip_tx_data **tdata);
768 
769 /*!
770  * \brief Send a SIP request and get called back when a response is received
771  *
772  * This will send the request out exactly the same as ast_sip_send_request() does.
773  * The difference is that when a response arrives, the specified callback will be
774  * called into
775  *
776  * \param session The session on which to send the request
777  * \param tdata The request to send
778  * \param on_response Callback to be called when a response is received
779  */
780 void ast_sip_session_send_request_with_cb(struct ast_sip_session *session, pjsip_tx_data *tdata,
781  ast_sip_session_response_cb on_response);
782 
783 /*!
784  * \brief Retrieves a session from a dialog
785  *
786  * \param dlg The dialog to retrieve the session from
787  *
788  * \retval non-NULL if session exists
789  * \retval NULL if no session
790  *
791  * \note The reference count of the session is increased when returned
792  *
793  * \note This function *must* be called with the dialog locked
794  */
795 struct ast_sip_session *ast_sip_dialog_get_session(pjsip_dialog *dlg);
796 
797 /*!
798  * \brief Resumes processing of a deferred incoming re-invite
799  *
800  * \param session The session which has a pending incoming re-invite
801  *
802  * \note When resuming a re-invite it is given to the pjsip stack as if it
803  * had just been received from a transport, this means that the deferral
804  * callback will be called again.
805  */
807 
808 /*!
809  * \brief Determines if a provided pending stream will be the default stream or not
810  * \since 15.0.0
811  *
812  * \param session The session to check against
813  * \param stream The pending stream
814  *
815  * \retval 1 if stream will be default
816  * \retval 0 if stream will NOT be the default
817  */
818 int ast_sip_session_is_pending_stream_default(const struct ast_sip_session *session, const struct ast_stream *stream);
819 
820 /*!
821  * \brief Allocate a session media state structure
822  * \since 15.0.0
823  *
824  * \retval non-NULL success
825  * \retval NULL failure
826  */
828 
829 /*!
830  * \brief Allocate an ast_session_media and add it to the media state's vector.
831  * \since 15.0.0
832  *
833  * This allocates a session media of the specified type. The position argument
834  * determines where in the vector that the new session media will be inserted.
835  *
836  * \note The returned ast_session_media is the reference held by the vector. Callers
837  * of this function must NOT decrement the refcount of the session media.
838  *
839  * \param session Session on which to query active media state for
840  * \param media_state Media state to place the session media into
841  * \param type The type of the session media
842  * \param position Position at which to insert the new session media.
843  *
844  * \note The active media state will be queried and if a media session already
845  * exists at the given position for the same type it will be reused instead of
846  * allocating a new one.
847  *
848  * \retval non-NULL success
849  * \retval NULL failure
850  */
852  struct ast_sip_session_media_state *media_state, enum ast_media_type type, int position);
853 
854 /*!
855  * \brief Save a media stats.
856  *
857  * \param sip_session Session on which to save active media state for
858  * \param media_state The media state to save
859  */
860 void ast_sip_session_media_stats_save(struct ast_sip_session *sip_session, struct ast_sip_session_media_state *media_state);
861 
862 /*!
863  * \brief Reset a media state to a clean state
864  * \since 15.0.0
865  *
866  * \param media_state The media state to reset
867  */
869 
870 /*!
871  * \brief Clone a media state
872  * \since 15.0.0
873  *
874  * \param media_state The media state to clone
875  *
876  * \retval non-NULL success
877  * \retval NULL failure
878  */
880 
881 /*!
882  * \brief Free a session media state structure
883  * \since 15.0.0
884  */
886 
887 /*!
888  * \brief Set a read callback for a media session with a specific file descriptor
889  * \since 15.0.0
890  *
891  * \param session The session
892  * \param session_media The media session
893  * \param fd The file descriptor
894  * \param callback The read callback
895  *
896  * \retval 0 the read callback was successfully added
897  * \retval -1 the read callback could not be added
898  *
899  * \note This operations on the pending media state
900  */
902  int fd, ast_sip_session_media_read_cb callback);
903 
904 /*!
905  * \brief Set a write callback for a media session
906  * \since 15.0.0
907  *
908  * \param session The session
909  * \param session_media The media session
910  * \param callback The write callback
911  *
912  * \retval 0 the write callback was successfully add
913  * \retval -1 the write callback is already set to something different
914  *
915  * \note This operates on the pending media state
916  */
919 
920 /*!
921  * \brief Retrieve the underlying media session that is acting as transport for a media session
922  * \since 15.0.0
923  *
924  * \param session The session
925  * \param session_media The media session to retrieve the transport for
926  *
927  * \note This operates on the pending media state
928  *
929  * \note This function is guaranteed to return non-NULL
930  */
932 
933 /*!
934  * \brief Get the channel or endpoint name associated with the session
935  * \since 18.0.0
936  *
937  * \param session
938  * \retval Channel name or endpoint name or "unknown"
939  */
940 const char *ast_sip_session_get_name(const struct ast_sip_session *session);
941 
942 #endif /* _RES_PJSIP_SESSION_H */
static struct ast_mansession session
static const char type[]
Definition: chan_ooh323.c:109
General Asterisk PBX channel definitions.
#define AST_MAX_EXTENSION
Definition: channel.h:134
Codec API.
ast_media_type
Types of media.
Definition: codec.h:30
@ AST_MEDIA_TYPE_END
Definition: codec.h:36
static const char name[]
Definition: format_mp3.c:68
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
#define AST_LIST_HEAD(name, type)
Defines a structure to be used to hold a list of specified type.
Definition: linkedlists.h:173
def info(msg)
Network socket handling.
AST_LIST_HEAD_NOLOCK(contactliststruct, contact)
const char * method
Definition: res_pjsip.c:1130
ast_sip_session_media_encryption
Definition: res_pjsip.h:525
ast_sip_supplement_priority
Definition: res_pjsip.h:2951
ast_sip_dtmf_mode
DTMF modes for SIP endpoints.
Definition: res_pjsip.h:427
ast_sip_session_refresh_method
Definition: res_pjsip.h:505
struct ast_sip_session_media_state * ast_sip_session_media_state_alloc(void)
Allocate a session media state structure.
struct ast_datastore * ast_sip_session_get_datastore(struct ast_sip_session *session, const char *name)
Retrieve a session datastore.
int(* ast_sip_session_request_creation_cb)(struct ast_sip_session *session, pjsip_tx_data *tdata)
int ast_sip_session_regenerate_answer(struct ast_sip_session *session, ast_sip_session_sdp_creation_cb on_sdp_creation)
Regenerate SDP Answer.
int(* ast_sip_session_sdp_creation_cb)(struct ast_sip_session *session, pjmedia_sdp_session *sdp)
void ast_sip_session_unregister_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type)
Unregister an SDP handler.
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_register_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type)
Register an SDP handler.
void ast_sip_session_send_request(struct ast_sip_session *session, pjsip_tx_data *tdata)
Send a SIP request.
void ast_sip_session_remove_supplements(struct ast_sip_session *session)
Remove supplements from a SIP session.
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.
void ast_sip_session_defer_termination_cancel(struct ast_sip_session *session)
Cancel a pending deferred termination.
ast_sip_session_t38state
T.38 states for a session.
@ T38_PEER_REINVITE
@ T38_LOCAL_REINVITE
@ T38_MAX_ENUM
@ T38_ENABLED
@ T38_REJECTED
@ T38_DISABLED
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.
int ast_sip_session_add_supplements(struct ast_sip_session *session)
Add supplements to a SIP session.
Definition: pjsip_session.c:90
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.
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.
ast_sip_session_response_priority
Describes when a supplement should be called into on incoming responses.
@ AST_SIP_SESSION_BEFORE_REDIRECTING
@ AST_SIP_SESSION_AFTER_MEDIA
@ AST_SIP_SESSION_BEFORE_MEDIA
void ast_sip_session_remove_datastore(struct ast_sip_session *session, const char *name)
Remove a session datastore from the session.
int(* ast_sip_session_response_cb)(struct ast_sip_session *session, pjsip_rx_data *rdata)
void ast_sip_session_media_state_free(struct ast_sip_session_media_state *media_state)
Free a session media state structure.
struct ast_sip_session * ast_sip_dialog_get_session(pjsip_dialog *dlg)
Retrieves a session from a dialog.
const char * ast_sip_session_get_name(const struct ast_sip_session *session)
Get the channel or endpoint name associated with the 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.
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.
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
void ast_sip_session_end_if_deferred(struct ast_sip_session *session)
End the session if it had been previously deferred.
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.
int ast_sip_session_create_invite(struct ast_sip_session *session, pjsip_tx_data **tdata)
Creates an INVITE request.
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
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(* ast_sip_session_media_write_cb)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, struct ast_frame *frame)
ast_sip_session_call_direction
Indicates the call direction respective to Asterisk.
@ AST_SIP_SESSION_OUTGOING_CALL
@ AST_SIP_SESSION_INCOMING_CALL
void ast_sip_session_unsuspend(struct ast_sip_session *session)
Request the session serializer be unsuspended.
void ast_sip_session_terminate(struct ast_sip_session *session, int response)
Terminate a session and, if possible, send the provided response code.
ast_sip_session_sdp_stream_defer
@ AST_SIP_SESSION_SDP_DEFER_NEEDED
@ AST_SIP_SESSION_SDP_DEFER_NOT_HANDLED
@ AST_SIP_SESSION_SDP_DEFER_NOT_NEEDED
@ AST_SIP_SESSION_SDP_DEFER_ERROR
void ast_sip_session_resume_reinvite(struct ast_sip_session *session)
Resumes processing of a deferred incoming re-invite.
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's vector.
void ast_sip_session_media_state_reset(struct ast_sip_session_media_state *media_state)
Reset a media state to a clean state.
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.
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.
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.
void ast_sip_session_send_response(struct ast_sip_session *session, pjsip_tx_data *tdata)
Send a SIP response.
void ast_sip_session_suspend(struct ast_sip_session *session)
Request and wait for the session serializer to be suspended.
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.
struct ast_frame *(* ast_sip_session_media_read_cb)(struct ast_sip_session *session, struct ast_sip_session_media *session_media)
SRTP and SDP Security descriptions.
Generic container type.
Main Channel structure associated with a channel.
Structure for a data store type.
Definition: datastore.h:31
Structure for a data store object.
Definition: datastore.h:64
const char * uid
Definition: datastore.h:65
Definition: dsp.c:407
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
Data structure associated with a single frame of data.
Information needed to identify an endpoint in a call.
Definition: channel.h:338
structure for secure RTP audio
Definition: sdp_srtp.h:38
A SIP address of record.
Definition: res_pjsip.h:376
A structure which contains a channel implementation and session.
struct ast_sip_session * session
Pointer to session.
void * pvt
Pointer to channel specific implementation information, must be ao2 object.
Contact associated with an address of record.
Definition: res_pjsip.h:297
An entity with which Asterisk communicates.
Definition: res_pjsip.h:854
Structure used for sending delayed requests.
Structure which contains read callback information.
ast_sip_session_media_read_cb read_callback
The callback to invoke.
struct ast_sip_session_media * session
The media session.
Structure which contains media state information (streams, sessions)
struct ast_stream_topology * topology
The media stream topology.
struct ast_sip_session_media_state::@293 sessions
Mapping of stream to media sessions.
struct ast_sip_session_media * default_session[AST_MEDIA_TYPE_END]
Default media sessions for each type.
struct ast_sip_session_media_state::@294 read_callbacks
Added read callbacks - these are whole structs and not pointers.
A structure containing SIP session media information.
ast_sip_session_media_write_cb write_callback
The write callback when writing frames.
struct ast_sdp_srtp * srtp
Holds SRTP information.
unsigned int remotely_held_changed
Stream is held by remote side changed during this negotiation.
char * stream_name
Stream name.
struct ast_sip_session_sdp_handler * handler
SDP handler that setup the RTP.
char label[AST_UUID_STR_LEN]
Track label.
unsigned int remote_ice
Does remote support ice.
enum ast_media_type type
Media type of this session media.
unsigned int locally_held
Stream is on hold by local side.
unsigned int remote_rtcp_mux
Does remote support rtcp_mux.
char * remote_label
Remote stream label.
int timeout_sched_id
Scheduler ID for RTP timeout.
int stream_num
The stream number to place into any resulting frames.
int bundle_group
The bundle group the stream belongs to.
unsigned int remotely_held
Stream is on hold by remote side.
struct ast_rtp_instance * rtp
RTP instance itself.
enum ast_sip_session_media_encryption encryption
What type of encryption is in use on this stream.
struct ast_udptl * udptl
UDPTL instance itself.
char * remote_mslabel
Remote media stream label.
struct ast_sockaddr direct_media_addr
Direct media address.
char mslabel[AST_UUID_STR_LEN]
Media stream label.
pj_str_t transport
The media transport in use for this stream.
unsigned int bundled
Whether this stream is currently bundled or not.
unsigned int changed
The underlying session has been changed in some fashion.
int keepalive_sched_id
Scheduler ID for RTP keepalive.
char * mid
Media identifier for this stream (may be shared across multiple streams)
A handler for SDPs in SIP sessions.
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)
Apply a negotiated SDP media stream.
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)
Create an SDP media stream and add it to the outgoing SDP offer or answer.
void(* stream_destroy)(struct ast_sip_session_media *session_media)
Destroy a session_media created by this handler.
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)
Determine whether a stream requires that the re-invite be deferred. If a stream can not be immediatel...
struct ast_sip_session_sdp_handler * next
int(* negotiate_incoming_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, const struct pjmedia_sdp_session *sdp, int index, struct ast_stream *asterisk_stream)
Set session details based on a stream in an incoming SDP offer or answer.
void(* change_outgoing_sdp_stream_media_address)(struct pjsip_tx_data *tdata, struct pjmedia_sdp_media *stream, struct ast_sip_transport *transport)
Update media stream with external address if applicable.
void(* stream_stop)(struct ast_sip_session_media *session_media)
Stop a session_media created by this handler but do not destroy resources.
A supplement to SIP message processing.
void(* session_begin)(struct ast_sip_session *session)
Notification that the session has begun This method will always be called from a SIP servant thread.
void(* incoming_response)(struct ast_sip_session *session, struct pjsip_rx_data *rdata)
Called on an incoming SIP response This method is always called from a SIP servant thread.
void(* session_destroy)(struct ast_sip_session *session)
Notification that the session is being destroyed.
void(* session_end)(struct ast_sip_session *session)
Notification that the session has ended.
int(* incoming_request)(struct ast_sip_session *session, struct pjsip_rx_data *rdata)
Called on incoming SIP request This method can indicate a failure in processing in its return....
struct ast_sip_session_supplement * next
enum ast_sip_session_response_priority response_priority
struct ast_module * module
void(* outgoing_response)(struct ast_sip_session *session, struct pjsip_tx_data *tdata)
Called on an outgoing SIP response This method is always called from a SIP servant thread.
enum ast_sip_supplement_priority priority
void(* outgoing_request)(struct ast_sip_session *session, struct pjsip_tx_data *tdata)
Called on an outgoing SIP request This method is always called from a SIP servant thread.
struct controlling the suspension of the session's serializer.
A structure describing a SIP session.
struct ast_sip_contact * contact
enum ast_sip_session_call_direction call_direction
pjsip_uri * request_uri
pj_timer_entry rescheduled_reinvite
unsigned int authentication_challenge_count
struct ast_sip_endpoint * endpoint
struct ast_sip_session::@297 media_stats
enum ast_sip_session_t38state t38state
struct ast_channel * channel
unsigned int defer_terminate
unsigned int moh_passthrough
pj_timer_entry scheduled_termination
char exten[AST_MAX_EXTENSION]
pjsip_rx_data * deferred_reinvite
struct ast_sip_session::@295 supplements
struct ast_party_id id
struct ast_sip_session_media_state * active_media_state
pjsip_fromto_hdr * saved_from_hdr
struct ast_sip_session::@296 delayed_requests
struct ast_sip_session_suspender * suspended
struct ast_sip_session_media_state * pending_media_state
struct ast_dsp * dsp
struct pjsip_inv_session * inv_session
enum ast_sip_dtmf_mode dtmf
struct ao2_container * datastores
struct ast_sip_aor * aor
struct ast_taskprocessor * serializer
unsigned int defer_end
unsigned int terminate_while_deferred
struct ast_format_cap * direct_media_cap
unsigned int ended_while_deferred
Transport to bind to.
Definition: res_pjsip.h:187
Socket address structure.
Definition: netsock2.h:97
A ast_taskprocessor structure is a singleton by name.
Definition: taskprocessor.c:69
Structure for an UDPTL session.
Definition: udptl.c:156
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59
#define AST_UUID_STR_LEN
Definition: uuid.h:27
#define AST_VECTOR(name, type)
Define a vector structure.
Definition: vector.h:44