Asterisk - The Open Source Telephony Project GIT-master-754dea3
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Modules Pages
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>
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 */
40struct ast_sip_endpoint;
42struct pjsip_inv_session;
43struct ast_channel;
44struct ast_datastore;
46struct ao2_container;
47struct pjsip_tx_data;
48struct pjsip_rx_data;
49struct ast_party_id;
50struct pjmedia_sdp_media;
51struct pjmedia_sdp_session;
52struct ast_dsp;
53struct ast_udptl;
54
55/*! \brief T.38 states for a session */
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
66struct ast_sip_session;
67struct ast_sip_session_caps;
69
70typedef struct ast_frame *(*ast_sip_session_media_read_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 */
82 /*! \brief Direct media address */
84 /*! \brief SDP handler that setup the RTP */
86 /*! \brief Holds SRTP information */
88 /*! \brief What type of encryption is in use on this stream */
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 */
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 */
120 /*! \brief Track label */
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 */
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 */
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 */
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 */
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 */
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 */
220 /*! Transferhandling ari */
221 unsigned int transferhandling_ari:1;
222 /*! Deferred incoming re-invite */
223 pjsip_rx_data *deferred_reinvite;
224 /*! Current T.38 state */
226 /*! The AOR associated with this session */
228 /*! From header saved at invite creation */
229 pjsip_fromto_hdr *saved_from_hdr;
230 /*! Whether the end of the session should be deferred */
231 unsigned int defer_end:1;
232 /*! Session end (remote hangup) requested while termination deferred */
233 unsigned int ended_while_deferred:1;
234 /*! Whether to pass through hold and unhold using re-invites with recvonly and sendrecv */
235 unsigned int moh_passthrough:1;
236 /*! Whether early media state has been confirmed through PRACK */
237 unsigned int early_confirmed:1;
238 /*! DTMF mode to use with this session, from endpoint but can change */
240 /*! Initial incoming INVITE Request-URI. NULL otherwise. */
241 pjsip_uri *request_uri;
242 /*! Media statistics for negotiated RTP streams */
244 /*! Number of challenges received during outgoing requests to determine if we are in a loop */
246 /*! The direction of the call respective to Asterisk */
248 /*! Originating Line Info (ANI II digits) */
249 int ani2;
250};
251
252typedef int (*ast_sip_session_request_creation_cb)(struct ast_sip_session *session, pjsip_tx_data *tdata);
253typedef int (*ast_sip_session_response_cb)(struct ast_sip_session *session, pjsip_rx_data *rdata);
254typedef int (*ast_sip_session_sdp_creation_cb)(struct ast_sip_session *session, pjmedia_sdp_session *sdp);
255
256/*!
257 * \brief Describes when a supplement should be called into on incoming responses.
258 *
259 * In most cases, session supplements will not need to worry about this because in most cases,
260 * the correct value will be automatically applied. However, there are rare circumstances
261 * when a supplement will want to specify when it should be called.
262 *
263 * The values below are listed in chronological order.
264 */
266 /*!
267 * When processing 3XX responses, the supplement is called into before
268 * the redirecting information is processed.
269 */
271 /*!
272 * For responses to INVITE transactions, the supplement is called into
273 * before media is negotiated.
274 *
275 * This priority is applied by default to any session supplement that
276 * does not specify a response priority.
277 */
279 /*!
280 * For INVITE transactions, the supplement is called into after media
281 * is negotiated.
282 */
284};
285
286/*!
287 * \brief A supplement to SIP message processing
288 *
289 * These can be registered by any module in order to add
290 * processing to incoming and outgoing SIP requests and responses
291 */
293 /*! Reference module info */
295 /*! Method on which to call the callbacks. If NULL, call on all methods */
296 const char *method;
297 /*! Priority for this supplement. Lower numbers are visited before higher numbers */
299 /*!
300 * \brief Notification that the session has begun
301 * This method will always be called from a SIP servant thread.
302 */
304 /*!
305 * \brief Notification that the session has ended
306 *
307 * This method may or may not be called from a SIP servant thread. Do
308 * not make assumptions about being able to call PJSIP methods from within
309 * this method.
310 */
312 /*!
313 * \brief Notification that the session is being destroyed
314 */
316 /*!
317 * \brief Called on incoming SIP request
318 * This method can indicate a failure in processing in its return. If there
319 * is a failure, it is required that this method sends a response to the request.
320 * This method is always called from a SIP servant thread.
321 *
322 * \note
323 * The following PJSIP methods will not work properly:
324 * pjsip_rdata_get_dlg()
325 * pjsip_rdata_get_tsx()
326 * The reason is that the rdata passed into this function is a cloned rdata structure,
327 * and its module data is not copied during the cloning operation.
328 * If you need to get the dialog, you can get it via session->inv_session->dlg.
329 *
330 * \note
331 * There is no guarantee that a channel will be present on the session when this is called.
332 */
333 int (*incoming_request)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
334 /*!
335 * \brief Called on an incoming SIP response
336 * This method is always called from a SIP servant thread.
337 *
338 * \note
339 * The following PJSIP methods will not work properly:
340 * pjsip_rdata_get_dlg()
341 * pjsip_rdata_get_tsx()
342 * The reason is that the rdata passed into this function is a cloned rdata structure,
343 * and its module data is not copied during the cloning operation.
344 * If you need to get the dialog, you can get it via session->inv_session->dlg.
345 *
346 * \note
347 * There is no guarantee that a channel will be present on the session when this is called.
348 */
349 void (*incoming_response)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
350 /*!
351 * \brief Called on an outgoing SIP request
352 * This method is always called from a SIP servant thread.
353 */
354 void (*outgoing_request)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
355 /*!
356 * \brief Called on an outgoing SIP response
357 * This method is always called from a SIP servant thread.
358 */
359 void (*outgoing_response)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
360 /*! Next item in the list */
362 /*!
363 * Determines when the supplement is processed when handling a response.
364 * Defaults to AST_SIP_SESSION_BEFORE_MEDIA
365 */
367};
368
370 /*! The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called. */
372 /*! There was an error encountered. No further operations will take place and the current negotiation will be abandoned. */
374 /*! Re-invite is not needed */
376 /*! Re-invite should be deferred and will be resumed later. No further operations will take place. */
378};
379
380/*!
381 * \brief A handler for SDPs in SIP sessions
382 *
383 * An SDP handler is registered by a module that is interested in being the
384 * responsible party for specific types of SDP streams.
385 */
387 /*! An identifier for this handler */
388 const char *id;
389 /*!
390 * \brief Determine whether a stream requires that the re-invite be deferred.
391 * If a stream can not be immediately negotiated the re-invite can be deferred and
392 * resumed at a later time. It is up to the handler which caused deferral to occur
393 * to resume it.
394 *
395 * \param session The session for which the media is being re-invited
396 * \param session_media The media being reinvited
397 * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
398 * \param stream PJSIP incoming SDP media lines to parse by handler.
399 *
400 * \return enum ast_sip_session_defer_stream
401 *
402 * \note This is optional, if not implemented the stream is assumed to not be deferred.
403 */
404 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);
405 /*!
406 * \brief Set session details based on a stream in an incoming SDP offer or answer
407 * \param session The session for which the media is being negotiated
408 * \param session_media The media session
409 * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
410 * \param index The index for the session media, Asterisk stream, and PJMEDIA stream being negotiated
411 * \param asterisk_stream The Asterisk stream representation
412 * \retval 0 The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called.
413 * \retval <0 There was an error encountered. No further operation will take place and the current negotiation will be abandoned.
414 * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
415 */
417 const struct pjmedia_sdp_session *sdp, int index, struct ast_stream *asterisk_stream);
418 /*!
419 * \brief Create an SDP media stream and add it to the outgoing SDP offer or answer
420 * \param session The session for which media is being added
421 * \param session_media The media to be setup for this session
422 * \param sdp The entire SDP as currently built
423 * \param remote Optional remote SDP if this is an answer
424 * \param stream The stream that is to be added to the outgoing SDP
425 * \retval 0 This handler has no stream to add. If there are other registered handlers for this stream type, they will be called.
426 * \retval <0 There was an error encountered. No further operation will take place and the current SDP negotiation will be abandoned.
427 * \retval >0 The handler has a stream to be added to the SDP. No further handler of this stream type will be called.
428 */
429 int (*create_outgoing_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, struct pjmedia_sdp_session *sdp,
430 const struct pjmedia_sdp_session *remote, struct ast_stream *stream);
431 /*!
432 * \brief Update media stream with external address if applicable
433 * \param tdata The outgoing message itself
434 * \param stream The stream on which to operate
435 * \param transport The transport the SDP is going out on
436 */
437 void (*change_outgoing_sdp_stream_media_address)(struct pjsip_tx_data *tdata, struct pjmedia_sdp_media *stream, struct ast_sip_transport *transport);
438 /*!
439 * \brief Apply a negotiated SDP media stream
440 * \param session The session for which media is being applied
441 * \param session_media The media session
442 * \param local The entire local negotiated SDP
443 * \param remote The entire remote negotiated SDP
444 * \param index The index of the session media, SDP streams, and Asterisk streams
445 * \param asterisk_stream The Asterisk stream representation
446 * \retval 0 The stream was not applied by this handler. If there are other registered handlers for this stream type, they will be called.
447 * \retval <0 There was an error encountered. No further operation will take place and the current application will be abandoned.
448 * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
449 */
451 const struct pjmedia_sdp_session *local, const struct pjmedia_sdp_session *remote, int index,
452 struct ast_stream *asterisk_stream);
453 /*!
454 * \brief Stop a session_media created by this handler but do not destroy resources
455 * \param session The session for which media is being stopped
456 * \param session_media The media to destroy
457 */
458 void (*stream_stop)(struct ast_sip_session_media *session_media);
459 /*!
460 * \brief Destroy a session_media created by this handler
461 * \param session The session for which media is being destroyed
462 * \param session_media The media to destroy
463 */
464 void (*stream_destroy)(struct ast_sip_session_media *session_media);
465 /*! Next item in the list. */
467};
468
469/*!
470 * \brief A structure which contains a channel implementation and session
471 */
473 /*! \brief Pointer to channel specific implementation information, must be ao2 object */
474 void *pvt;
475 /*! \brief Pointer to session */
477};
478
479/*!
480 * \brief Allocate a new SIP channel pvt structure
481 *
482 * \param pvt Pointer to channel specific information
483 * \param session Pointer to SIP session
484 *
485 * \retval non-NULL success
486 * \retval NULL failure
487 */
489
490/*!
491 * \brief Allocate a new SIP session
492 *
493 * This will take care of allocating the datastores container on the session as well
494 * as placing all registered supplements onto the session.
495 *
496 * The endpoint that is passed in will have its reference count increased by one since
497 * the session will be keeping a reference to the endpoint. The session will relinquish
498 * this reference when the session is destroyed.
499 *
500 * \param endpoint The endpoint that this session communicates with
501 * \param contact The contact associated with this session
502 * \param inv The PJSIP INVITE session data
503 * \param rdata INVITE request received (NULL if for outgoing allocation)
504 */
506 struct ast_sip_contact *contact, pjsip_inv_session *inv, pjsip_rx_data *rdata);
507
508/*!
509 * \brief Request and wait for the session serializer to be suspended.
510 * \since 12.7.0
511 *
512 * \param session Which session to suspend the serializer.
513 *
514 * \note No channel locks can be held while calling without risk of deadlock.
515 */
517
518/*!
519 * \brief Request the session serializer be unsuspended.
520 * \since 12.7.0
521 *
522 * \param session Which session to unsuspend the serializer.
523 */
525
526/*!
527 * \brief Create a new outgoing SIP session
528 *
529 * The endpoint that is passed in will have its reference count increased by one since
530 * the session will be keeping a reference to the endpoint. The session will relinquish
531 * this reference when the session is destroyed.
532 *
533 * \param endpoint The endpoint that this session uses for settings
534 * \param contact The contact that this session will communicate with
535 * \param location Name of the location to call, be it named location or explicit URI. Overrides contact if present.
536 * \param request_user Optional request user to place in the request URI if permitted
537 * \param req_topology The requested capabilities
538 */
540 struct ast_sip_contact *contact, const char *location, const char *request_user,
541 struct ast_stream_topology *req_topology);
542
543/*!
544 * \brief Terminate a session and, if possible, send the provided response code
545 *
546 * \param session The session to terminate
547 * \param response The response code to use for termination if possible
548 *
549 * \warning Calling this function MAY cause the last session reference to be
550 * released and the session destructor to be called. If you need to do something
551 * with session after this call, be sure to bump the ref count before calling terminate.
552 */
553void ast_sip_session_terminate(struct ast_sip_session *session, int response);
554
555/*!
556 * \brief Defer local termination of a session until remote side terminates, or an amount of time passes
557 *
558 * \param session The session to defer termination on
559 *
560 * \retval 0 Success
561 * \retval -1 Failure
562 */
564
565/*!
566 * \brief Cancel a pending deferred termination.
567 *
568 * \param session The session to cancel a deferred termination on.
569 */
571
572/*!
573 * \brief End the session if it had been previously deferred
574 *
575 * \param session The session to end if it had been deferred
576 */
578
579/*!
580 * \brief Register an SDP handler
581 *
582 * An SDP handler is responsible for parsing incoming SDP streams and ensuring that
583 * Asterisk can cope with the contents. Similarly, the SDP handler will be
584 * responsible for constructing outgoing SDP streams.
585 *
586 * Multiple handlers for the same stream type may be registered. They will be
587 * visited in the order they were registered. Handlers will be visited for each
588 * stream type until one claims to have handled the stream.
589 *
590 * \param handler The SDP handler to register
591 * \param stream_type The type of media stream for which to call the handler
592 * \retval 0 Success
593 * \retval -1 Failure
594 */
596
597/*!
598 * \brief Unregister an SDP handler
599 *
600 * \param handler The SDP handler to unregister
601 * \param stream_type Stream type for which the SDP handler was registered
602 */
604
605/*!
606 * \brief Register a supplement to SIP session processing
607 *
608 * This allows for someone to insert themselves in the processing of SIP
609 * requests and responses. This, for example could allow for a module to
610 * set channel data based on headers in an incoming message. Similarly,
611 * a module could reject an incoming request if desired.
612 *
613 * \param module Referenced module(NULL safe)
614 * \param supplement The supplement to register
615 */
617
618#define ast_sip_session_register_supplement(supplement) \
619 ast_sip_session_register_supplement_with_module(AST_MODULE_SELF, supplement)
620
621/*!
622 * \brief Unregister a an supplement to SIP session processing
623 *
624 * \param supplement The supplement to unregister
625 */
627
628/*!
629 * \brief Add supplements to a SIP session
630 *
631 * \param session The session to initialize
632 */
634
635/*!
636 * \brief Remove supplements from a SIP session
637 *
638 * \param session The session to remove
639 */
641
642/*!
643 * \brief Alternative for ast_datastore_alloc()
644 *
645 * There are two major differences between this and ast_datastore_alloc()
646 * 1) This allocates a refcounted object
647 * 2) This will fill in a uid if one is not provided
648 *
649 * DO NOT call ast_datastore_free() on a datastore allocated in this
650 * way since that function will attempt to free the datastore rather
651 * than play nicely with its refcount.
652 *
653 * \param info Callbacks for datastore
654 * \param uid Identifier for datastore
655 * \retval NULL Failed to allocate datastore
656 * \retval non-NULL Newly allocated datastore
657 */
659
660/*!
661 * \brief Add a datastore to a SIP session
662 *
663 * Note that SIP uses reference counted datastores. The datastore passed into this function
664 * must have been allocated using ao2_alloc() or there will be serious problems.
665 *
666 * \param session The session to add the datastore to
667 * \param datastore The datastore to be added to the session
668 * \retval 0 Success
669 * \retval -1 Failure
670 */
672
673/*!
674 * \brief Retrieve a session datastore
675 *
676 * The datastore retrieved will have its reference count incremented. When the caller is done
677 * with the datastore, the reference counted needs to be decremented using ao2_ref().
678 *
679 * \param session The session from which to retrieve the datastore
680 * \param name The name of the datastore to retrieve
681 * \retval NULL Failed to find the specified datastore
682 * \retval non-NULL The specified datastore
683 */
685
686/*!
687 * \brief Remove a session datastore from the session
688 *
689 * This operation may cause the datastore's free() callback to be called if the reference
690 * count reaches zero.
691 *
692 * \param session The session to remove the datastore from
693 * \param name The name of the datastore to remove
694 */
696
697/*!
698 * \brief Send a reinvite or UPDATE on a session
699 *
700 * This method will inspect the session in order to construct an appropriate
701 * session refresh request. As with any outgoing request in res_pjsip_session,
702 * this will call into registered supplements in case they wish to add anything.
703 *
704 * Note: The on_request_creation callback may or may not be called in the same
705 * thread where this function is called. Request creation may need to be delayed
706 * due to the current INVITE transaction state.
707 *
708 * \param session The session on which the reinvite will be sent
709 * \param on_request_creation Callback called when request is created
710 * \param on_sdp_creation Callback called when SDP is created
711 * \param on_response Callback called when response for request is received
712 * \param method The method that should be used when constructing the session refresh
713 * \param generate_new_sdp Boolean to indicate if a new SDP should be created
714 * \param media_state Optional requested media state for the SDP
715 *
716 * \retval 0 Successfully sent refresh
717 * \retval -1 Failure to send refresh
718 *
719 * \note If a media_state is passed in ownership will be taken in all cases
720 */
722 ast_sip_session_request_creation_cb on_request_creation,
723 ast_sip_session_sdp_creation_cb on_sdp_creation,
724 ast_sip_session_response_cb on_response,
726 int generate_new_sdp,
727 struct ast_sip_session_media_state *media_state);
728
729/*!
730 * \brief Regenerate SDP Answer
731 *
732 * This method is used when an SDP offer has been received but an SDP answer
733 * has not been sent yet. It requests that a new local SDP be created and
734 * set as the SDP answer. As with any outgoing request in res_pjsip_session,
735 * this will call into registered supplements in case they wish to add anything.
736 *
737 * \param session The session on which the answer will be updated
738 * \param on_sdp_creation Callback called when SDP is created
739 * \retval 0 Successfully updated the SDP answer
740 * \retval -1 Failure to updated the SDP answer
741 */
743 ast_sip_session_sdp_creation_cb on_sdp_creation);
744
745/*!
746 * \brief Send a SIP response
747 *
748 * This will send the SIP response specified in tdata and
749 * call into any registered supplements' outgoing_response callback.
750 *
751 * \param session The session on which to send the response.
752 * \param tdata The response to send
753 */
754void ast_sip_session_send_response(struct ast_sip_session *session, pjsip_tx_data *tdata);
755
756/*!
757 * \brief Send a SIP request
758 *
759 * This will send the SIP request specified in tdata and
760 * call into any registered supplements' outgoing_request callback.
761 *
762 * \param session The session to which to send the request
763 * \param tdata The request to send
764 */
765void ast_sip_session_send_request(struct ast_sip_session *session, pjsip_tx_data *tdata);
766
767/*!
768 * \brief Creates an INVITE request.
769 *
770 * \param session Starting session for the INVITE
771 * \param tdata The created request.
772 */
773int ast_sip_session_create_invite(struct ast_sip_session *session, pjsip_tx_data **tdata);
774
775/*!
776 * \brief Send a SIP request and get called back when a response is received
777 *
778 * This will send the request out exactly the same as ast_sip_send_request() does.
779 * The difference is that when a response arrives, the specified callback will be
780 * called into
781 *
782 * \param session The session on which to send the request
783 * \param tdata The request to send
784 * \param on_response Callback to be called when a response is received
785 */
786void ast_sip_session_send_request_with_cb(struct ast_sip_session *session, pjsip_tx_data *tdata,
787 ast_sip_session_response_cb on_response);
788
789/*!
790 * \brief Retrieves a session from a dialog
791 *
792 * \param dlg The dialog to retrieve the session from
793 *
794 * \retval non-NULL if session exists
795 * \retval NULL if no session
796 *
797 * \note The reference count of the session is increased when returned
798 *
799 * \note This function *must* be called with the dialog locked
800 */
801struct ast_sip_session *ast_sip_dialog_get_session(pjsip_dialog *dlg);
802
803/*!
804 * \brief Retrieves a dialog from a session
805 *
806 * \param session The session to retrieve the dialog from
807 *
808 * \retval non-NULL if dialog exists
809 * \retval NULL if no dialog
810 */
811pjsip_dialog *ast_sip_session_get_dialog(const struct ast_sip_session *session);
812
813/*!
814 * \brief Retrieves the pjsip_inv_state from a session
815 *
816 * \param session The session to retrieve the state from
817 *
818 * \retval state if inv_session exists
819 * \retval PJSIP_INV_STATE_NULL if inv_session is NULL
820 */
821pjsip_inv_state ast_sip_session_get_pjsip_inv_state(const struct ast_sip_session *session);
822
823/*!
824 * \brief Resumes processing of a deferred incoming re-invite
825 *
826 * \param session The session which has a pending incoming re-invite
827 *
828 * \note When resuming a re-invite it is given to the pjsip stack as if it
829 * had just been received from a transport, this means that the deferral
830 * callback will be called again.
831 */
833
834/*!
835 * \brief Determines if a provided pending stream will be the default stream or not
836 * \since 15.0.0
837 *
838 * \param session The session to check against
839 * \param stream The pending stream
840 *
841 * \retval 1 if stream will be default
842 * \retval 0 if stream will NOT be the default
843 */
844int ast_sip_session_is_pending_stream_default(const struct ast_sip_session *session, const struct ast_stream *stream);
845
846/*!
847 * \brief Allocate a session media state structure
848 * \since 15.0.0
849 *
850 * \retval non-NULL success
851 * \retval NULL failure
852 */
854
855/*!
856 * \brief Allocate an ast_session_media and add it to the media state's vector.
857 * \since 15.0.0
858 *
859 * This allocates a session media of the specified type. The position argument
860 * determines where in the vector that the new session media will be inserted.
861 *
862 * \note The returned ast_session_media is the reference held by the vector. Callers
863 * of this function must NOT decrement the refcount of the session media.
864 *
865 * \param session Session on which to query active media state for
866 * \param media_state Media state to place the session media into
867 * \param type The type of the session media
868 * \param position Position at which to insert the new session media.
869 *
870 * \note The active media state will be queried and if a media session already
871 * exists at the given position for the same type it will be reused instead of
872 * allocating a new one.
873 *
874 * \retval non-NULL success
875 * \retval NULL failure
876 */
878 struct ast_sip_session_media_state *media_state, enum ast_media_type type, int position);
879
880/*!
881 * \brief Save a media stats.
882 *
883 * \param sip_session Session on which to save active media state for
884 * \param media_state The media state to save
885 */
886void ast_sip_session_media_stats_save(struct ast_sip_session *sip_session, struct ast_sip_session_media_state *media_state);
887
888/*!
889 * \brief Reset a media state to a clean state
890 * \since 15.0.0
891 *
892 * \param media_state The media state to reset
893 */
895
896/*!
897 * \brief Clone a media state
898 * \since 15.0.0
899 *
900 * \param media_state The media state to clone
901 *
902 * \retval non-NULL success
903 * \retval NULL failure
904 */
906
907/*!
908 * \brief Free a session media state structure
909 * \since 15.0.0
910 */
912
913/*!
914 * \brief Set a read callback for a media session with a specific file descriptor
915 * \since 15.0.0
916 *
917 * \param session The session
918 * \param session_media The media session
919 * \param fd The file descriptor
920 * \param callback The read callback
921 *
922 * \retval 0 the read callback was successfully added
923 * \retval -1 the read callback could not be added
924 *
925 * \note This operations on the pending media state
926 */
928 int fd, ast_sip_session_media_read_cb callback);
929
930/*!
931 * \brief Set a write callback for a media session
932 * \since 15.0.0
933 *
934 * \param session The session
935 * \param session_media The media session
936 * \param callback The write callback
937 *
938 * \retval 0 the write callback was successfully add
939 * \retval -1 the write callback is already set to something different
940 *
941 * \note This operates on the pending media state
942 */
945
946/*!
947 * \brief Retrieve the underlying media session that is acting as transport for a media session
948 * \since 15.0.0
949 *
950 * \param session The session
951 * \param session_media The media session to retrieve the transport for
952 *
953 * \note This operates on the pending media state
954 *
955 * \note This function is guaranteed to return non-NULL
956 */
958
959/*!
960 * \brief Get the channel or endpoint name associated with the session
961 * \since 18.0.0
962 *
963 * \param session
964 * \retval Channel name or endpoint name or "unknown"
965 */
966const char *ast_sip_session_get_name(const struct ast_sip_session *session);
967
968/*!
969 * \brief Determines if the Connected Line info can be presented for this session
970 *
971 * \param session The session
972 * \param id The Connected Line info to evaluate
973 *
974 * \retval 1 The Connected Line info can be presented
975 * \retval 0 The Connected Line info cannot be presented
976 */
977int ast_sip_can_present_connected_id(const struct ast_sip_session *session, const struct ast_party_id *id);
978
979/*!
980 * \brief Adds a Reason header in the next reponse to an incoming INVITE
981 *
982 * \param session The session
983 * \param protocol Usually "SIP" but may be "STIR" for stir-shaken
984 * \param code SIP response code
985 * \param text Reason string
986 *
987 * \retval 0 the header is accepted
988 * \retval -1 the header is rejected
989 */
991 const char *protocol, int code, const char *text);
992
993#endif /* _RES_PJSIP_SESSION_H */
char * text
Definition: app_queue.c:1809
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_HEAD_NOLOCK(name, type)
Defines a structure to be used to hold a list of specified type (with no lock).
Definition: linkedlists.h:225
#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.
const char * method
Definition: res_pjsip.c:1279
ast_sip_session_media_encryption
Definition: res_pjsip.h:733
ast_sip_supplement_priority
Definition: res_pjsip.h:3332
ast_sip_dtmf_mode
DTMF modes for SIP endpoints.
Definition: res_pjsip.h:545
ast_sip_session_refresh_method
Definition: res_pjsip.h:713
int(* ast_sip_session_request_creation_cb)(struct ast_sip_session *session, pjsip_tx_data *tdata)
struct ast_sip_session * ast_sip_dialog_get_session(pjsip_dialog *dlg)
Retrieves a session from a dialog.
int ast_sip_session_regenerate_answer(struct ast_sip_session *session, ast_sip_session_sdp_creation_cb on_sdp_creation)
Regenerate SDP Answer.
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_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.
int ast_sip_can_present_connected_id(const struct ast_sip_session *session, const struct ast_party_id *id)
Determines if the Connected Line info can be presented for this session.
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.
pjsip_inv_state ast_sip_session_get_pjsip_inv_state(const struct ast_sip_session *session)
Retrieves the pjsip_inv_state from a session.
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.
struct ast_datastore * ast_sip_session_get_datastore(struct ast_sip_session *session, const char *name)
Retrieve a session datastore.
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_t38state
T.38 states for a session.
@ T38_PEER_REINVITE
@ T38_LOCAL_REINVITE
@ T38_MAX_ENUM
@ T38_ENABLED
@ T38_REJECTED
@ T38_DISABLED
struct ast_sip_session_media_state * ast_sip_session_media_state_alloc(void)
Allocate a session media state structure.
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.
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.
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.
int(* ast_sip_session_response_cb)(struct ast_sip_session *session, pjsip_rx_data *rdata)
pjsip_dialog * ast_sip_session_get_dialog(const struct ast_sip_session *session)
Retrieves a dialog from a session.
struct ast_frame *(* ast_sip_session_media_read_cb)(struct ast_sip_session *session, struct ast_sip_session_media *session_media)
void ast_sip_session_media_state_free(struct ast_sip_session_media_state *media_state)
Free a session media state structure.
struct ast_datastore * ast_sip_session_alloc_datastore(const struct ast_datastore_info *info, const char *uid)
Alternative for ast_datastore_alloc()
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.
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)
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.
struct ast_sip_channel_pvt * ast_sip_channel_pvt_alloc(void *pvt, struct ast_sip_session *session)
Allocate a new SIP channel pvt structure.
ast_sip_session_call_direction
Indicates the call direction respective to Asterisk.
@ AST_SIP_SESSION_OUTGOING_CALL
@ AST_SIP_SESSION_INCOMING_CALL
int ast_sip_session_add_reason_header(struct ast_sip_session *session, const char *protocol, int code, const char *text)
Adds a Reason header in the next reponse to an incoming INVITE.
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.
void ast_sip_session_media_state_reset(struct ast_sip_session_media_state *media_state)
Reset a media state to a clean state.
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.
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_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.
const char * ast_sip_session_get_name(const struct ast_sip_session *session)
Get the channel or endpoint name associated with the 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.
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:340
structure for secure RTP audio
Definition: sdp_srtp.h:38
A SIP address of record.
Definition: res_pjsip.h:478
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:390
An entity with which Asterisk communicates.
Definition: res_pjsip.h:1051
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::@265 sessions
Mapping of stream to media sessions.
struct ast_sip_session_media_state::@266 read_callbacks
Added read callbacks - these are whole structs and not pointers.
struct ast_sip_session_media * default_session[AST_MEDIA_TYPE_END]
Default media sessions for each type.
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
unsigned int early_confirmed
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
unsigned int transferhandling_ari
enum ast_sip_session_t38state t38state
struct ast_channel * channel
struct ast_sip_session::@268 delayed_requests
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_party_id id
struct ast_sip_session_media_state * active_media_state
pjsip_fromto_hdr * saved_from_hdr
struct ast_sip_session_suspender * suspended
struct ast_sip_session_media_state * pending_media_state
struct ast_sip_session::@269 media_stats
struct ast_dsp * dsp
struct pjsip_inv_session * inv_session
struct ast_sip_session::@267 supplements
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:219
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:181
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