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