Asterisk - The Open Source Telephony Project GIT-master-85241bd
res_pjsip.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_H
20#define _RES_PJSIP_H
21
22#include <pjsip.h>
23/* Needed for SUBSCRIBE, NOTIFY, and PUBLISH method definitions */
24#include <pjsip_simple.h>
25#include <pjsip/sip_transaction.h>
26#include <pj/timer.h>
27/* Needed for pj_sockaddr */
28#include <pjlib.h>
29
31/* Needed for struct ast_sockaddr */
32#include "asterisk/netsock2.h"
33/* Needed for linked list macros */
35/* Needed for ast_party_id */
36#include "asterisk/channel.h"
37/* Needed for ast_sorcery */
38#include "asterisk/sorcery.h"
39/* Needed for ast_dnsmgr */
40#include "asterisk/dnsmgr.h"
41/* Needed for ast_endpoint */
42#include "asterisk/endpoints.h"
43/* Needed for ast_t38_ec_modes */
44#include "asterisk/udptl.h"
45/* Needed for ast_rtp_dtls_cfg struct */
46#include "asterisk/rtp_engine.h"
47/* Needed for AST_VECTOR macro */
48#include "asterisk/vector.h"
49/* Needed for ast_sip_for_each_channel_snapshot struct */
52#include "asterisk/stream.h"
53
54#ifdef HAVE_PJSIP_TLS_TRANSPORT_RESTART
55/* Needed for knowing if the cert or priv key files changed */
56#include <sys/stat.h>
57#endif
58
59#define PJSIP_MINVERSION(m,n,p) (((m << 24) | (n << 16) | (p << 8)) >= PJ_VERSION_NUM)
60
61#ifndef PJSIP_EXPIRES_NOT_SPECIFIED
62/*
63 * Added in pjproject 2.10.0. However define here if someone compiles against a
64 * version of pjproject < 2.10.0.
65 *
66 * Usually defined in pjsip/include/pjsip/sip_msg.h (included as part of <pjsip.h>)
67 */
68#define PJSIP_EXPIRES_NOT_SPECIFIED ((pj_uint32_t)-1)
69#endif
70
71#define PJSTR_PRINTF_SPEC "%.*s"
72#define PJSTR_PRINTF_VAR(_v) ((int)(_v).slen), ((_v).ptr)
73
74#define AST_SIP_AUTH_MAX_REALM_LENGTH 255 /* From the auth/realm realtime column size */
75
76/* ":12345" */
77#define COLON_PORT_STRLEN 6
78/*
79 * "<ipaddr>:<port>"
80 * PJ_INET6_ADDRSTRLEN includes the NULL terminator
81 */
82#define IP6ADDR_COLON_PORT_BUFLEN (PJ_INET6_ADDRSTRLEN + COLON_PORT_STRLEN)
83
84/*!
85 * \brief Fill a buffer with a pjsip transport's remote ip address and port
86 *
87 * \param _transport The pjsip_transport to use
88 * \param _dest The destination buffer of at least IP6ADDR_COLON_PORT_BUFLEN bytes
89 */
90#define AST_SIP_MAKE_REMOTE_IPADDR_PORT_STR(_transport, _dest) \
91 snprintf(_dest, IP6ADDR_COLON_PORT_BUFLEN, \
92 PJSTR_PRINTF_SPEC ":%d", \
93 PJSTR_PRINTF_VAR(_transport->remote_name.host), \
94 _transport->remote_name.port);
95
96/* Forward declarations of PJSIP stuff */
97struct pjsip_rx_data;
98struct pjsip_module;
99struct pjsip_tx_data;
100struct pjsip_dialog;
101struct pjsip_transport;
102struct pjsip_tpfactory;
103struct pjsip_tls_setting;
104struct pjsip_tpselector;
105
106/*! \brief Maximum number of ciphers supported for a TLS transport */
107#define SIP_TLS_MAX_CIPHERS 64
108
109/*! Maximum number of challenges before assuming that we are in a loop */
110#define MAX_RX_CHALLENGES 10
111
113
114static const pj_str_t AST_PJ_STR_EMPTY = { "", 0 };
115
116/*!
117 * \brief Structure for SIP transport information
118 */
120 /*! \brief Transport itself */
121 struct pjsip_transport *transport;
122 /*! \brief Transport factory */
123 struct pjsip_tpfactory *factory;
124 /*!
125 * Transport id
126 * \since 13.8.0
127 */
128 char *id;
129 /*!
130 * Transport type
131 * \since 13.8.0
132 */
134 /*!
135 * Address and port to bind to
136 * \since 13.8.0
137 */
138 pj_sockaddr host;
139 /*!
140 * TLS settings
141 * \since 13.8.0
142 */
143 pjsip_tls_setting tls;
144 /*!
145 * Configured TLS ciphers
146 * \since 13.8.0
147 */
149 /*!
150 * Optional local network information, used for NAT purposes.
151 * "deny" (set) means that it's in the local network. Use the
152 * ast_sip_transport_is_nonlocal and ast_sip_transport_is_local
153 * macro's.
154 * \since 13.8.0
155 */
157 /*!
158 * DNS manager for refreshing the external signaling address
159 * \since 13.8.0
160 */
162 /*!
163 * Optional external signaling address information
164 * \since 13.8.0
165 */
167 /*!
168 * DNS manager for refreshing the external media address
169 * \since 13.18.0
170 */
172 /*!
173 * Optional external signaling address information
174 * \since 13.18.0
175 */
177 /*!
178 * Set when this transport is a flow of signaling to a target
179 * \since 17.0.0
180 */
181 int flow;
182 /*!
183 * The P-Preferred-Identity to use on traffic using this transport
184 * \since 17.0.0
185 */
187 /*!
188 * The Service Routes to use on traffic using this transport
189 * \since 17.0.0
190 */
192 /*!
193 * Disregard RFC5922 7.2, and allow wildcard certs (TLS only)
194 */
196 /*!
197 * If true, fail if server certificate cannot verify (TLS only)
198 */
200#ifdef HAVE_PJSIP_TLS_TRANSPORT_RESTART
201 /*!
202 * The stats information for the certificate file, if configured
203 */
204 struct stat cert_file_stat;
205 /*!
206 * The stats information for the private key file, if configured
207 */
208 struct stat privkey_file_stat;
209#endif
210};
211
212#define ast_sip_transport_is_nonlocal(transport_state, addr) \
213 (!transport_state->localnet || ast_apply_ha(transport_state->localnet, addr) == AST_SENSE_ALLOW)
214
215#define ast_sip_transport_is_local(transport_state, addr) \
216 (transport_state->localnet && ast_apply_ha(transport_state->localnet, addr) != AST_SENSE_ALLOW)
217
218/*!
219 * \brief Transport to bind to
220 */
222 /*! Sorcery object details */
225 /*! Certificate of authority list file */
227 /*! Certificate of authority list path */
229 /*! Public certificate file */
231 /*! Optional private key of the certificate file */
233 /*! Password to open the private key */
235 /*! External signaling address */
237 /*! External media address */
239 /*! Optional domain to use for messages if provided could not be found */
241 );
242 /*! Type of transport */
244 /*!
245 * \deprecated Moved to ast_sip_transport_state
246 * \version 13.8.0 deprecated
247 * Address and port to bind to
248 */
249 pj_sockaddr host;
250 /*! Number of simultaneous asynchronous operations */
251 unsigned int async_operations;
252 /*! Optional external port for signaling */
254 /*!
255 * \deprecated Moved to ast_sip_transport_state
256 * \version 13.7.1 deprecated
257 * TLS settings
258 */
259 pjsip_tls_setting tls;
260 /*!
261 * \deprecated Moved to ast_sip_transport_state
262 * \version 13.7.1 deprecated
263 * Configured TLS ciphers
264 */
266 /*!
267 * \deprecated Moved to ast_sip_transport_state
268 * \version 13.7.1 deprecated
269 * Optional local network information, used for NAT purposes
270 */
272 /*!
273 * \deprecated Moved to ast_sip_transport_state
274 * \version 13.7.1 deprecated
275 * DNS manager for refreshing the external address
276 */
278 /*!
279 * \deprecated Moved to ast_sip_transport_state
280 * \version 13.7.1 deprecated
281 * Optional external address information
282 */
284 /*!
285 * \deprecated
286 * \version 13.7.1 deprecated
287 * Transport state information
288 */
290 /*! QOS DSCP TOS bits */
291 unsigned int tos;
292 /*! QOS COS value */
293 unsigned int cos;
294 /*! Write timeout */
296 /*! Allow reload */
298 /*! Automatically send requests out the same transport requests have come in on */
300 /*! This is a flow to another target */
301 int flow;
302 /*! Enable TCP keepalive */
304 /*! Time in seconds the connection needs to remain idle before TCP starts sending keepalive probes */
306 /*! The time in seconds between individual keepalive probes */
308 /*! The maximum number of keepalive probes TCP should send before dropping the connection */
310};
311
312#define SIP_SORCERY_DOMAIN_ALIAS_TYPE "domain_alias"
313
314/*!
315 * Details about a SIP domain alias
316 */
318 /*! Sorcery object details */
321 /*! Domain to be aliased to */
323 );
324};
325
326/*!
327 * \brief Structure for SIP nat hook information
328 */
330 /*! Sorcery object details */
332 /*! Callback for when a message is going outside of our local network */
333 void (*outgoing_external_message)(struct pjsip_tx_data *tdata, struct ast_sip_transport *transport);
334};
335
336/*! \brief Structure which contains information about a transport */
338 /*! \brief Type of transport */
340 /*! \brief Potential pointer to the transport itself, if UDP */
341 pjsip_transport *transport;
342 /*! \brief Potential pointer to the transport factory itself, if TCP/TLS */
343 pjsip_tpfactory *factory;
344 /*! \brief Local address for transport */
346 /*! \brief Local port for transport */
348};
349
350/*!
351 * \brief The kind of security negotiation
352 */
354 /*! No security mechanism negotiation */
356 /*! Use mediasec security mechanism negotiation */
358 /* Add RFC 3329 (sec-agree) mechanism negotiation in the future */
359};
360
361/*!
362 * \brief The security mechanism type
363 */
366 /* Use msrp-tls as security mechanism */
368 /* Use sdes-srtp as security mechanism */
370 /* Use dtls-srtp as security mechanism */
372 /* Add RFC 3329 (sec-agree) mechanisms like tle, digest, ipsec-ike in the future */
373};
374
375/*!
376 * \brief Structure representing a security mechanism as defined in RFC 3329
377 */
379 /* Used to determine which security mechanism to use. */
381 /* The preference of this security mechanism. The higher the value, the more preferred. */
382 float qvalue;
383 /* Optional mechanism parameters. */
385};
386
388
389/*!
390 * \brief Contact associated with an address of record
391 */
393 /*! Sorcery object details, the id is the aor name plus a random string */
396 /*! Full URI of the contact */
398 /*! Outbound proxy to use for qualify */
400 /*! Path information to place in Route headers */
402 /*! Content of the User-Agent header in REGISTER request */
404 /*! The name of the aor this contact belongs to */
406 /*! Asterisk Server name */
408 /*! IP-address of the Via header in REGISTER request */
410 /*! Content of the Call-ID header in REGISTER request */
412 /*! The name of the endpoint that added the contact */
414 );
415 /*! Absolute time that this contact is no longer valid after */
416 struct timeval expiration_time;
417 /*! Frequency to send OPTIONS requests to contact. 0 is disabled. */
418 unsigned int qualify_frequency;
419 /*! If true authenticate the qualify challenge response if needed */
421 /*! Qualify timeout. 0 is diabled. */
423 /*! Endpoint that added the contact, only available in observers */
425 /*! Port of the Via header in REGISTER request */
427 /*! If true delete the contact on Asterisk restart/boot */
429};
430
431/*!
432 * \brief Status type for a contact.
433 */
435 /*! Frequency > 0, but no response from remote uri */
437 /*! Frequency > 0, and got response from remote uri */
439 /*! Default last status, and when a contact status object is not found */
441 /*! Frequency == 0, has a contact, but don't know status (non-qualified) */
444};
445
446/*!
447 * \brief A contact's status.
448 *
449 * Maintains a contact's current status and round trip time if available.
450 */
453 /*! The original contact's URI */
455 /*! The name of the aor this contact_status belongs to */
457 );
458 /*! The round trip time in microseconds */
459 int64_t rtt;
460 /*!
461 * The security mechanism list of the contact (RFC 3329).
462 * Stores the values of Security-Server headers in 401/421/494 responses to an
463 * in-dialog request or successful outbound registration which will be used to
464 * set the Security-Verify headers of all subsequent requests to the contact.
465 */
467 /*! Current status for a contact (default - unavailable) */
469 /*! Last status for a contact (default - unavailable) */
471 /*! Name of the contact */
472 char name[0];
473};
474
475/*!
476 * \brief A SIP address of record
477 */
479 /*! Sorcery object details, the id is the AOR name */
482 /*! Voicemail boxes for this AOR */
484 /*! Outbound proxy for OPTIONS requests */
486 );
487 /*! Minimum expiration time */
488 unsigned int minimum_expiration;
489 /*! Maximum expiration time */
490 unsigned int maximum_expiration;
491 /*! Default contact expiration if one is not provided in the contact */
492 unsigned int default_expiration;
493 /*! Frequency to send OPTIONS requests to AOR contacts. 0 is disabled. */
494 unsigned int qualify_frequency;
495 /*! If true authenticate the qualify challenge response if needed */
497 /*! Maximum number of external contacts, 0 to disable */
498 unsigned int max_contacts;
499 /*! Whether to remove any existing contacts not related to an incoming REGISTER when it comes in */
500 unsigned int remove_existing;
501 /*! Any permanent configured contacts */
503 /*! Determines whether SIP Path headers are supported */
504 unsigned int support_path;
505 /*! Qualify timeout. 0 is diabled. */
507 /*! Voicemail extension to set in Message-Account */
509 /*! Whether to remove unavailable contacts over max_contacts at all or first if remove_existing is enabled */
510 unsigned int remove_unavailable;
511};
512
513/*!
514 * \brief A wrapper for contact that adds the aor_id and
515 * a consistent contact id. Used by ast_sip_for_each_contact.
516 */
518 /*! The id of the parent aor. */
519 char *aor_id;
520 /*! The id of contact in form of aor_id/contact_uri. */
522 /*! Pointer to the actual contact. */
524};
525
526/*!
527 * \brief 100rel modes for SIP endpoints
528 */
530 /*! Do not support 100rel. (no) */
532 /*! As UAC, indicate 100rel support in Supported header. (yes) */
534 /*! As UAS, send 1xx responses reliably, if the UAC indicated its support. Otherwise same as AST_SIP_100REL_SUPPORTED. (peer_supported) */
536 /*! Require the use of 100rel. (required) */
538};
539
540/*!
541 * \brief DTMF modes for SIP endpoints
542 */
544 /*! No DTMF to be used */
546 /* XXX Should this be 2833 instead? */
547 /*! Use RFC 4733 events for DTMF */
549 /*! Use DTMF in the audio stream */
551 /*! Use SIP INFO DTMF (blech) */
553 /*! Use SIP 4733 if supported by the other side or INBAND if not */
555 /*! Use SIP 4733 if supported by the other side or INFO DTMF (blech) if not */
557};
558
559/*!
560 * \brief Methods of storing SIP digest authentication credentials.
561 *
562 * Note that both methods result in MD5 digest authentication being
563 * used. The two methods simply alter how Asterisk determines the
564 * credentials for a SIP authentication
565 */
567 /*! Credentials stored as a username and password combination */
569 /*! Credentials stored as an MD5 sum */
571 /*! Google Oauth */
573 /*! Credentials not stored this is a fake auth */
576
577#define SIP_SORCERY_AUTH_TYPE "auth"
578
580 /*! Sorcery ID of the auth is its name */
583 /*! Identification for these credentials */
585 /*! Authentication username */
587 /*! Authentication password */
589 /*! Authentication credentials in MD5 format (hash of user:realm:pass) */
591 /*! Refresh token to use for OAuth authentication */
593 /*! Client ID to use for OAuth authentication */
595 /*! Secret to use for OAuth authentication */
597 );
598 /*! The time period (in seconds) that a nonce may be reused */
599 unsigned int nonce_lifetime;
600 /*! Used to determine what to use when authenticating */
602};
603
605
606/*!
607 * \brief Different methods by which incoming requests can be matched to endpoints
608 */
610 /*! Identify based on user name in From header */
612 /*! Identify based on user name in Auth header first, then From header */
614 /*! Identify based on source IP address */
616 /*! Identify based on arbitrary headers */
618 /*! Identify based on request uri */
620};
622
624 /*! Use reinvite to negotiate direct media */
626 /*! Use UPDATE to negotiate direct media */
628};
629
631 /*! Take no special action to mitigate reinvite glare */
633 /*! Do not send an initial direct media session refresh on outgoing call legs
634 * Subsequent session refreshes will be sent no matter the session direction
635 */
637 /*! Do not send an initial direct media session refresh on incoming call legs
638 * Subsequent session refreshes will be sent no matter the session direction
639 */
641};
642
644 /*! Invalid media encryption configuration */
646 /*! Do not allow any encryption of session media */
648 /*! Offer SDES-encrypted session media */
650 /*! Offer encrypted session media with datagram TLS key exchange */
652};
653
655 /*! User portion of the target URI should be used as the target in the dialplan */
657 /*! Target URI should be used as the target in the dialplan */
659 /*! Target URI should be used as the target within chan_pjsip itself */
661};
662
663/*!
664 * \brief Incoming/Outgoing call offer/answer joint codec preference.
665 *
666 * The default is INTERSECT ALL LOCAL.
667 */
669 /*! Two bits for merge */
670 /*! Intersection of local and remote */
672 /*! Union of local and remote */
674
675 /*! Two bits for filter */
676 /*! No filter */
678 /*! Only the first */
680
681 /*! Two bits for preference and sort */
682 /*! Prefer, and order by local values */
684 /*! Prefer, and order by remote values */
686};
687
688/*!
689 * \brief Returns true if the preference is set in the parameter
690 * \since 18.0.0
691 *
692 * \param __param A ast_flags struct with one or more of enum ast_sip_call_codec_pref set
693 * \param __codec_pref The last component of one of the enum values
694 * \retval 1 if the enum value is set
695 * \retval 0 if not
696 */
697#define ast_sip_call_codec_pref_test(__param, __codec_pref) (!!(ast_test_flag( &__param, AST_SIP_CALL_CODEC_PREF_ ## __codec_pref )))
698
699/*!
700 * \brief Session timers options
701 */
703 /*! Minimum session expiration period, in seconds */
704 unsigned int min_se;
705 /*! Session expiration period, in seconds */
706 unsigned int sess_expires;
707};
708
709/*!
710 * \brief Endpoint configuration for SIP extensions.
711 *
712 * SIP extensions, in this case refers to features
713 * indicated in Supported or Required headers.
714 */
716 /*! Enabled SIP extensions */
717 unsigned int flags;
718 /*! Timer options */
720};
721
722/*!
723 * \brief Endpoint configuration for unsolicited MWI
724 */
727 /*! Configured voicemail boxes for this endpoint. Used for MWI */
729 /*! Username to use when sending MWI NOTIFYs to this endpoint */
731 );
732 /*! Should mailbox states be combined into a single notification? */
733 unsigned int aggregate;
734 /*! Should a subscribe replace unsolicited notifies? */
736 /*! Voicemail extension to set in Message-Account */
738};
739
740/*!
741 * \brief Endpoint subscription configuration
742 */
744 /*! Indicates if endpoint is allowed to initiate subscriptions */
745 unsigned int allow;
746 /*! The minimum allowed expiration for subscriptions from endpoint */
747 unsigned int minexpiry;
748 /*! Message waiting configuration */
750 /*! Context for SUBSCRIBE requests */
752};
753
754/*!
755 * \brief NAT configuration options for endpoints
756 */
758 /*! Whether to force using the source IP address/port for sending responses */
759 unsigned int force_rport;
760 /*! Whether to rewrite the Contact header with the source IP address/port or not */
761 unsigned int rewrite_contact;
762};
763
764/*!
765 * \brief Party identification options for endpoints
766 *
767 * This includes caller ID, connected line, and redirecting-related options
768 */
771 /*! Do we accept identification information from this endpoint */
772 unsigned int trust_inbound;
773 /*! Do we send private identification information to this endpoint? */
774 unsigned int trust_outbound;
775 /*! Do we send P-Asserted-Identity headers to this endpoint? */
776 unsigned int send_pai;
777 /*! Do we send Remote-Party-ID headers to this endpoint? */
778 unsigned int send_rpid;
779 /*! Do we send messages for connected line updates for unanswered incoming calls immediately to this endpoint? */
780 unsigned int rpid_immediate;
781 /*! Do we add Diversion headers to applicable outgoing requests/responses? */
782 unsigned int send_diversion;
783 /*! Do we accept connected line updates from this endpoint? */
785 /*! Do we send connected line updates to this endpoint? */
787 /*! When performing connected line update, which method should be used */
789 /*! Do we add History-Info headers to applicable outgoing requests/responses? */
790 unsigned int send_history_info;
791};
792
793/*!
794 * \brief Call pickup configuration options for endpoints
795 */
797 /*! Call group */
799 /*! Pickup group */
801 /*! Named call group */
802 struct ast_namedgroups *named_callgroups;
803 /*! Named pickup group */
804 struct ast_namedgroups *named_pickupgroups;
805};
806
807/*!
808 * \brief Configuration for one-touch INFO recording
809 */
812 /*! Feature to enact when one-touch recording INFO with Record: On is received */
814 /*! Feature to enact when one-touch recording INFO with Record: Off is received */
816 );
817 /*! Is one-touch recording permitted? */
818 unsigned int enabled;
819};
820
821/*!
822 * \brief Endpoint configuration options for INFO packages
823 */
825 /*! Configuration for one-touch recording */
827};
828
829/*!
830 * \brief RTP configuration for SIP endpoints
831 */
834 /*! Configured RTP engine for this endpoint. */
836 );
837 /*! Whether IPv6 RTP is enabled or not */
838 unsigned int ipv6;
839 /*! Whether symmetric RTP is enabled or not */
840 unsigned int symmetric;
841 /*! Whether ICE support is enabled or not */
842 unsigned int ice_support;
843 /*! Whether to use the "ptime" attribute received from the endpoint or not */
844 unsigned int use_ptime;
845 /*! Do we use AVPF exclusively for this endpoint? */
846 unsigned int use_avpf;
847 /*! Do we force AVP, AVPF, SAVP, or SAVPF even for DTLS media streams? */
848 unsigned int force_avp;
849 /*! Do we use the received media transport in our answer SDP */
851 /*! \brief DTLS-SRTP configuration information */
853 /*! Should SRTP use a 32 byte tag instead of an 80 byte tag? */
854 unsigned int srtp_tag_32;
855 /*! Do we use media encryption? what type? */
857 /*! Do we want to optimistically support encryption if possible? */
859 /*! Number of seconds between RTP keepalive packets */
860 unsigned int keepalive;
861 /*! Number of seconds before terminating channel due to lack of RTP (when not on hold) */
862 unsigned int timeout;
863 /*! Number of seconds before terminating channel due to lack of RTP (when on hold) */
864 unsigned int timeout_hold;
865 /*! Follow forked media with a different To tag */
867 /*! Accept updated SDPs on non-100rel 18X and 2XX responses with the same To tag */
869};
870
871/*!
872 * \brief Direct media options for SIP endpoints
873 */
875 /*! Boolean indicating if direct_media is permissible */
876 unsigned int enabled;
877 /*! When using direct media, which method should be used */
879 /*! Take steps to mitigate glare for direct media */
881 /*! Do not attempt direct media session refreshes if a media NAT is detected */
882 unsigned int disable_on_nat;
883};
884
886 /*! Whether T.38 UDPTL support is enabled or not */
887 unsigned int enabled;
888 /*! Error correction setting for T.38 UDPTL */
890 /*! Explicit T.38 max datagram value, may be 0 to indicate the remote side can be trusted */
891 unsigned int maxdatagram;
892 /*! Whether NAT Support is enabled for T.38 UDPTL sessions or not */
893 unsigned int nat;
894 /*! Whether to use IPv6 for UDPTL or not */
895 unsigned int ipv6;
896 /*! Bind the UDPTL instance to the media_address */
898};
899
900/*!
901 * \brief Media configuration for SIP endpoints
902 */
905 /*! Optional media address to use in SDP */
907 /*! SDP origin username */
909 /*! SDP session name */
911 );
912 /*! RTP media configuration */
914 /*! Direct media options */
916 /*! T.38 (FoIP) options */
918 /*! Configured codecs */
920 /*! Capabilities in topology form */
922 /*! DSCP TOS bits for audio streams */
923 unsigned int tos_audio;
924 /*! Priority for audio streams */
925 unsigned int cos_audio;
926 /*! DSCP TOS bits for video streams */
927 unsigned int tos_video;
928 /*! Priority for video streams */
929 unsigned int cos_video;
930 /*! Is g.726 packed in a non standard way */
931 unsigned int g726_non_standard;
932 /*! Bind the RTP instance to the media_address */
934 /*! Use RTCP-MUX */
935 unsigned int rtcp_mux;
936 /*! Maximum number of audio streams to offer/accept */
937 unsigned int max_audio_streams;
938 /*! Maximum number of video streams to offer/accept */
939 unsigned int max_video_streams;
940 /*! Use BUNDLE */
941 unsigned int bundle;
942 /*! Enable webrtc settings and defaults */
943 unsigned int webrtc;
944 /*! Codec preference for an incoming offer */
946 /*! Codec preference for an outgoing offer */
948 /*! Codec negotiation prefs for incoming offers */
950 /*! Codec negotiation prefs for outgoing offers */
952 /*! Codec negotiation prefs for incoming answers */
954 /*! Codec negotiation prefs for outgoing answers */
956};
957
958/*!
959 * \brief An entity with which Asterisk communicates
960 */
964 /*! Context to send incoming calls to */
966 /*! Name of an explicit transport to use */
968 /*! Outbound proxy to use */
970 /*! Explicit AORs to dial if none are specified */
972 /*! Musiconhold class to suggest that the other side use when placing on hold */
974 /*! Configured tone zone for this endpoint. */
976 /*! Configured language for this endpoint. */
978 /*! Default username to place in From header */
980 /*! Domain to place in From header */
982 /*! Context to route incoming MESSAGE requests to */
984 /*! Accountcode to auto-set on channels */
986 /*! If set, we'll push incoming MWI NOTIFYs to stasis using this mailbox */
988 /*! STIR/SHAKEN profile to use */
990 );
991 /*! Configuration for extensions */
993 /*! Configuration relating to media */
995 /*! SUBSCRIBE/NOTIFY configuration options */
997 /*! NAT configuration */
999 /*! Party identification options */
1001 /*! Configuration options for INFO packages */
1003 /*! Call pickup configuration */
1005 /*! Inbound authentication credentials */
1007 /*! Outbound authentication credentials */
1009 /*! DTMF mode to use with this endpoint */
1011 /*! Method(s) by which the endpoint should be identified. */
1013 /*! Order of the method(s) by which the endpoint should be identified. */
1015 /*! Boolean indicating if ringing should be sent as inband progress */
1016 unsigned int inband_progress;
1017 /*! Pointer to the persistent Asterisk endpoint */
1019 /*! The number of channels at which busy device state is returned */
1021 /*! Whether fax detection is enabled or not (CNG tone detection) */
1022 unsigned int faxdetect;
1023 /*! Determines if transfers (using REFER) are allowed by this endpoint */
1024 unsigned int allowtransfer;
1025 /*! Method used when handling redirects */
1027 /*! Variables set on channel creation */
1029 /*! Whether to place a 'user=phone' parameter into the request URI if user is a number */
1030 unsigned int usereqphone;
1031 /*! Whether to pass through hold and unhold using re-invites with recvonly and sendrecv */
1032 unsigned int moh_passthrough;
1033 /*! Access control list */
1035 /*! Restrict what IPs are allowed in the Contact header (for registration) */
1037 /*! The number of seconds into call to disable fax detection. (0 = disabled) */
1038 unsigned int faxdetect_timeout;
1039 /*! Override the user on the outgoing Contact header with this value. */
1041 /*! Whether to response SDP offer with single most preferred codec. */
1043 /*! Do we allow an asymmetric RTP codec? */
1045 /*! Do we allow overlap dialling? */
1046 unsigned int allow_overlap;
1047 /*! Whether to notifies all the progress details on blind transfer */
1049 /*! Whether to notifies dialog-info 'early' on INUSE && RINGING state */
1051 /*! Suppress Q.850 Reason headers on this endpoint */
1053 /*! Ignore 183 if no SDP is present */
1055 /*! Type of security negotiation to use (RFC 3329). */
1057 /*! Client security mechanisms (RFC 3329). */
1059 /*! Set which STIR/SHAKEN behaviors we want on this endpoint */
1060 unsigned int stir_shaken;
1061 /*! Should we authenticate OPTIONS requests per RFC 3261? */
1063 /*! The name of the geoloc profile to apply when Asterisk receives a call from this endpoint */
1064 AST_STRING_FIELD_EXTENDED(geoloc_incoming_call_profile);
1065 /*! The name of the geoloc profile to apply when Asterisk sends a call to this endpoint */
1066 AST_STRING_FIELD_EXTENDED(geoloc_outgoing_call_profile);
1067 /*! The context to use for overlap dialing, if different from the endpoint's context */
1069 /*! 100rel mode to use with this endpoint */
1071 /*! Send Advice-of-Charge messages */
1072 unsigned int send_aoc;
1073};
1074
1075/*! URI parameter for symmetric transport */
1076#define AST_SIP_X_AST_TXP "x-ast-txp"
1077#define AST_SIP_X_AST_TXP_LEN 9
1078
1079/*! Common media types used throughout res_pjsip and pjproject */
1080extern pjsip_media_type pjsip_media_type_application_json;
1082extern pjsip_media_type pjsip_media_type_application_pidf_xml;
1083extern pjsip_media_type pjsip_media_type_application_xpidf_xml;
1084extern pjsip_media_type pjsip_media_type_application_cpim_xpidf_xml;
1085extern pjsip_media_type pjsip_media_type_application_rlmi_xml;
1087extern pjsip_media_type pjsip_media_type_application_sdp;
1088extern pjsip_media_type pjsip_media_type_multipart_alternative;
1089extern pjsip_media_type pjsip_media_type_multipart_mixed;
1090extern pjsip_media_type pjsip_media_type_multipart_related;
1091extern pjsip_media_type pjsip_media_type_text_plain;
1092
1093/*!
1094 * \brief Compare pjsip media types
1095 *
1096 * \param a the first media type
1097 * \param b the second media type
1098 * \retval 1 Media types are equal
1099 * \retval 0 Media types are not equal
1100 */
1101int ast_sip_are_media_types_equal(pjsip_media_type *a, pjsip_media_type *b);
1102
1103/*!
1104 * \brief Check if a media type is in a list of others
1105 *
1106 * \param a pjsip_media_type to search for
1107 * \param ... one or more pointers to pjsip_media_types the last of which must be "SENTINEL"
1108 * \retval 1 Media types are equal
1109 * \retval 0 Media types are not equal
1110 */
1111int ast_sip_is_media_type_in(pjsip_media_type *a, ...) attribute_sentinel;
1112
1113/*!
1114 * \brief Add security headers to transmission data
1115 *
1116 * \param security_mechanisms Vector of security mechanisms.
1117 * \param header_name The header name under which to add the security mechanisms.
1118 * One of Security-Client, Security-Server, Security-Verify.
1119 * \param add_qval If zero, don't add the q-value to the header.
1120 * \param tdata The transmission data.
1121 * \retval 0 Success
1122 * \retval non-zero Failure
1123 */
1125 const char *header_name, int add_qval, pjsip_tx_data *tdata);
1126
1127/*!
1128 * \brief Append to security mechanism vector from SIP header
1129 *
1130 * \param hdr The header of the security mechanisms.
1131 * \param security_mechanisms Vector of security mechanisms to append to.
1132 * Header name must be one of Security-Client, Security-Server, Security-Verify.
1133 */
1134void ast_sip_header_to_security_mechanism(const pjsip_generic_string_hdr *hdr,
1135 struct ast_sip_security_mechanism_vector *security_mechanisms);
1136
1137/*!
1138 * \brief Initialize security mechanism vector from string of security mechanisms.
1139 *
1140 * \param security_mechanism Pointer to vector of security mechanisms to initialize.
1141 * \param value String of security mechanisms as defined in RFC 3329.
1142 * \retval 0 Success
1143 * \retval non-zero Failure
1144 */
1145int ast_sip_security_mechanism_vector_init(struct ast_sip_security_mechanism_vector *security_mechanism, const char *value);
1146
1147/*!
1148 * \brief Removes all headers of a specific name and value from a pjsip_msg.
1149 *
1150 * \param msg PJSIP message from which to remove headers.
1151 * \param hdr_name Name of the header to remove.
1152 * \param value Optional string value of the header to remove.
1153 * If NULL, remove all headers of given hdr_name.
1154 */
1155void ast_sip_remove_headers_by_name_and_value(pjsip_msg *msg, const pj_str_t *hdr_name, const char* value);
1156
1157/*!
1158 * \brief Duplicate a security mechanism.
1159 *
1160 * \param dst Security mechanism to duplicate to.
1161 * \param src Security mechanism to duplicate.
1162 */
1164 const struct ast_sip_security_mechanism_vector *src);
1165
1166/*!
1167 * \brief Free contents of a security mechanism vector.
1168 *
1169 * \param security_mechanisms Vector whose contents are to be freed
1170 */
1172
1173/*!
1174 * \brief Allocate a security mechanism from a string.
1175 *
1176 * \param security_mechanism Pointer-pointer to the security mechanism to allocate.
1177 * \param value The security mechanism string as defined in RFC 3329 (section 2.2)
1178 * in the form <mechanism_name>;q=<q_value>;<mechanism_parameters>
1179 * \retval 0 Success
1180 * \retval non-zero Failure
1181 */
1182int ast_sip_str_to_security_mechanism(struct ast_sip_security_mechanism **security_mechanism, const char *value);
1183
1184/*!
1185 * \brief Writes the security mechanisms of an endpoint into a buffer as a string and returns the buffer.
1186 *
1187 * \note The buffer must be freed by the caller.
1188 *
1189 * \param endpoint Pointer to endpoint.
1190 * \param add_qvalue If non-zero, the q-value is printed as well
1191 * \param buf The buffer to write the string into
1192 * \retval 0 Success
1193 * \retval non-zero Failure
1194 */
1195int ast_sip_security_mechanisms_to_str(const struct ast_sip_security_mechanism_vector *security_mechanisms, int add_qvalue, char **buf);
1196
1197/*!
1198 * \brief Set the security negotiation based on a given string.
1199 *
1200 * \param security_negotiation Security negotiation enum to set.
1201 * \param val String that represents a security_negotiation value.
1202 * \retval 0 Success
1203 * \retval non-zero Failure
1204 */
1205int ast_sip_set_security_negotiation(enum ast_sip_security_negotiation *security_negotiation, const char *val);
1206
1207/*!
1208 * \brief Initialize an auth vector with the configured values.
1209 *
1210 * \param vector Vector to initialize
1211 * \param auth_names Comma-separated list of names to set in the array
1212 * \retval 0 Success
1213 * \retval non-zero Failure
1214 */
1215int ast_sip_auth_vector_init(struct ast_sip_auth_vector *vector, const char *auth_names);
1216
1217/*!
1218 * \brief Free contents of an auth vector.
1219 *
1220 * \param vector Vector whose contents are to be freed
1221 */
1223
1224/*!
1225 * \brief Possible returns from ast_sip_check_authentication
1226 */
1228 /*! Authentication needs to be challenged */
1230 /*! Authentication succeeded */
1232 /*! Authentication failed */
1234 /*! Authentication encountered some internal error */
1236};
1237
1238/*!
1239 * \brief An interchangeable way of handling digest authentication for SIP.
1240 *
1241 * An authenticator is responsible for filling in the callbacks provided below. Each is called from a publicly available
1242 * function in res_sip. The authenticator can use configuration or other local policy to determine whether authentication
1243 * should take place and what credentials should be used when challenging and authenticating a request.
1244 */
1246 /*!
1247 * \brief Check if a request requires authentication
1248 * See ast_sip_requires_authentication for more details
1249 */
1250 int (*requires_authentication)(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
1251 /*!
1252 * \brief Check that an incoming request passes authentication.
1253 *
1254 * The tdata parameter is useful for adding information such as digest challenges.
1255 *
1256 * \param endpoint The endpoint sending the incoming request
1257 * \param rdata The incoming request
1258 * \param tdata Tentative outgoing request.
1259 */
1261 pjsip_rx_data *rdata, pjsip_tx_data *tdata);
1262};
1263
1264/*!
1265 * \brief an interchangeable way of responding to authentication challenges
1266 *
1267 * An outbound authenticator takes incoming challenges and formulates a new SIP request with
1268 * credentials.
1269 */
1271 /*!
1272 * \brief Create a new request with authentication credentials
1273 *
1274 * \param auths A vector of IDs of auth sorcery objects
1275 * \param challenge The SIP response with authentication challenge(s)
1276 * \param old_request The request that received the auth challenge(s)
1277 * \param new_request The new SIP request with challenge response(s)
1278 * \retval 0 Successfully created new request
1279 * \retval -1 Failed to create a new request
1280 */
1281 int (*create_request_with_auth)(const struct ast_sip_auth_vector *auths, struct pjsip_rx_data *challenge,
1282 struct pjsip_tx_data *old_request, struct pjsip_tx_data **new_request);
1283};
1284
1285/*!
1286 * \brief An entity responsible for identifying the source of a SIP message
1287 */
1289 /*!
1290 * \brief Callback used to identify the source of a message.
1291 * See ast_sip_identify_endpoint for more details
1292 */
1293 struct ast_sip_endpoint *(*identify_endpoint)(pjsip_rx_data *rdata);
1294};
1295
1296/*!
1297 * \brief Contact retrieval filtering flags
1298 */
1300 /*! \brief Default filter flags */
1302
1303 /*! \brief Return only reachable or unknown contacts */
1305};
1306
1307/*!
1308 * \brief Adds a Date header to the tdata, formatted like:
1309 * Date: Wed, 01 Jan 2021 14:53:01 GMT
1310 * \since 16.19.0
1311 *
1312 * \note There is no checking done to see if the header already exists
1313 * before adding it. It's up to the caller of this function to determine
1314 * if that needs to be done or not.
1315 */
1316void ast_sip_add_date_header(pjsip_tx_data *tdata);
1317
1318/*!
1319 * \brief Register a SIP service in Asterisk.
1320 *
1321 * This is more-or-less a wrapper around pjsip_endpt_register_module().
1322 * Registering a service makes it so that PJSIP will call into the
1323 * service at appropriate times. For more information about PJSIP module
1324 * callbacks, see the PJSIP documentation. Asterisk modules that call
1325 * this function will likely do so at module load time.
1326 *
1327 * \param module The module that is to be registered with PJSIP
1328 * \retval 0 Success
1329 * \retval -1 Failure
1330 */
1331int ast_sip_register_service(pjsip_module *module);
1332
1333/*!
1334 * This is the opposite of ast_sip_register_service(). Unregistering a
1335 * service means that PJSIP will no longer call into the module any more.
1336 * This will likely occur when an Asterisk module is unloaded.
1337 *
1338 * \param module The PJSIP module to unregister
1339 */
1340void ast_sip_unregister_service(pjsip_module *module);
1341
1342/*!
1343 * \brief Register a SIP authenticator
1344 *
1345 * An authenticator has three main purposes:
1346 * 1) Determining if authentication should be performed on an incoming request
1347 * 2) Gathering credentials necessary for issuing an authentication challenge
1348 * 3) Authenticating a request that has credentials
1349 *
1350 * Asterisk provides a default authenticator, but it may be replaced by a
1351 * custom one if desired.
1352 *
1353 * \param auth The authenticator to register
1354 * \retval 0 Success
1355 * \retval -1 Failure
1356 */
1358
1359/*!
1360 * \brief Unregister a SIP authenticator
1361 *
1362 * When there is no authenticator registered, requests cannot be challenged
1363 * or authenticated.
1364 *
1365 * \param auth The authenticator to unregister
1366 */
1368
1369 /*!
1370 * \brief Register an outbound SIP authenticator
1371 *
1372 * An outbound authenticator is responsible for creating responses to
1373 * authentication challenges by remote endpoints.
1374 *
1375 * \param outbound_auth The authenticator to register
1376 * \retval 0 Success
1377 * \retval -1 Failure
1378 */
1380
1381/*!
1382 * \brief Unregister an outbound SIP authenticator
1383 *
1384 * When there is no outbound authenticator registered, authentication challenges
1385 * will be handled as any other final response would be.
1386 *
1387 * \param auth The authenticator to unregister
1388 */
1390
1391/*!
1392 * \brief Register a SIP endpoint identifier with a name.
1393 *
1394 * An endpoint identifier's purpose is to determine which endpoint a given SIP
1395 * message has come from.
1396 *
1397 * Multiple endpoint identifiers may be registered so that if an endpoint
1398 * cannot be identified by one identifier, it may be identified by another.
1399 *
1400 * \param identifier The SIP endpoint identifier to register
1401 * \param name The name of the endpoint identifier
1402 * \retval 0 Success
1403 * \retval -1 Failure
1404 */
1406 const char *name);
1407
1408/*!
1409 * \brief Register a SIP endpoint identifier
1410 *
1411 * An endpoint identifier's purpose is to determine which endpoint a given SIP
1412 * message has come from.
1413 *
1414 * Multiple endpoint identifiers may be registered so that if an endpoint
1415 * cannot be identified by one identifier, it may be identified by another.
1416 *
1417 * Asterisk provides two endpoint identifiers. One identifies endpoints based
1418 * on the user part of the From header URI. The other identifies endpoints based
1419 * on the source IP address.
1420 *
1421 * If the order in which endpoint identifiers is run is important to you, then
1422 * be sure to load individual endpoint identifier modules in the order you wish
1423 * for them to be run in modules.conf
1424 *
1425 * \note endpoint identifiers registered using this method (no name specified)
1426 * are placed at the front of the endpoint identifiers list ahead of any
1427 * named identifiers.
1428 *
1429 * \param identifier The SIP endpoint identifier to register
1430 * \retval 0 Success
1431 * \retval -1 Failure
1432 */
1434
1435/*!
1436 * \brief Unregister a SIP endpoint identifier
1437 *
1438 * This stops an endpoint identifier from being used.
1439 *
1440 * \param identifier The SIP endoint identifier to unregister
1441 */
1443
1444/*!
1445 * \brief Allocate a new SIP endpoint
1446 *
1447 * This will return an endpoint with its refcount increased by one. This reference
1448 * can be released using ao2_ref().
1449 *
1450 * \param name The name of the endpoint.
1451 * \retval NULL Endpoint allocation failed
1452 * \retval non-NULL The newly allocated endpoint
1453 */
1454void *ast_sip_endpoint_alloc(const char *name);
1455
1456/*!
1457 * \brief Change state of a persistent endpoint.
1458 *
1459 * \param endpoint_name The SIP endpoint name to change state.
1460 * \param state The new state
1461 * \retval 0 Success
1462 * \retval -1 Endpoint not found
1463 */
1464int ast_sip_persistent_endpoint_update_state(const char *endpoint_name, enum ast_endpoint_state state);
1465
1466/*!
1467 * \brief Publish the change of state for a contact.
1468 *
1469 * \param endpoint_name The SIP endpoint name.
1470 * \param contact_status The contact status.
1471 */
1472void ast_sip_persistent_endpoint_publish_contact_state(const char *endpoint_name, const struct ast_sip_contact_status *contact_status);
1473
1474/*!
1475 * \brief Retrieve the current status for a contact.
1476 *
1477 * \param contact The contact.
1478 *
1479 * \retval non-NULL Success
1480 * \retval NULL Status information not found
1481 *
1482 * \note The returned contact status object is immutable.
1483 */
1485
1486/*!
1487 * \brief Get a pointer to the PJSIP endpoint.
1488 *
1489 * This is useful when modules have specific information they need
1490 * to register with the PJSIP core.
1491 * \retval NULL endpoint has not been created yet.
1492 * \retval non-NULL PJSIP endpoint.
1493 */
1494pjsip_endpoint *ast_sip_get_pjsip_endpoint(void);
1495
1496/*!
1497 * \brief Get a pointer to the SIP sorcery structure.
1498 *
1499 * \retval NULL sorcery has not been initialized
1500 * \retval non-NULL sorcery structure
1501 */
1502struct ast_sorcery *ast_sip_get_sorcery(void);
1503
1504/*!
1505 * \brief Retrieve a named AOR
1506 *
1507 * \param aor_name Name of the AOR
1508 *
1509 * \retval NULL if not found
1510 * \retval non-NULL if found
1511 */
1512struct ast_sip_aor *ast_sip_location_retrieve_aor(const char *aor_name);
1513
1514/*!
1515 * \brief Retrieve the first bound contact for an AOR
1516 *
1517 * \param aor Pointer to the AOR
1518 * \retval NULL if no contacts available
1519 * \retval non-NULL if contacts available
1520 */
1522
1523/*!
1524 * \brief Retrieve the first bound contact for an AOR and filter based on flags
1525 * \since 13.16.0
1526 *
1527 * \param aor Pointer to the AOR
1528 * \param flags Filtering flags
1529 * \retval NULL if no contacts available
1530 * \retval non-NULL if contacts available
1531 */
1533 unsigned int flags);
1534
1535/*!
1536 * \brief Retrieve all contacts currently available for an AOR
1537 *
1538 * \param aor Pointer to the AOR
1539 *
1540 * \retval NULL if no contacts available
1541 * \retval non-NULL if contacts available
1542 *
1543 * \warning
1544 * Since this function prunes expired contacts before returning, it holds a named write
1545 * lock on the aor. If you already hold the lock, call ast_sip_location_retrieve_aor_contacts_nolock instead.
1546 */
1548
1549/*!
1550 * \brief Retrieve all contacts currently available for an AOR and filter based on flags
1551 * \since 13.16.0
1552 *
1553 * \param aor Pointer to the AOR
1554 * \param flags Filtering flags
1555 *
1556 * \retval NULL if no contacts available
1557 * \retval non-NULL if contacts available
1558 *
1559 * \warning
1560 * Since this function prunes expired contacts before returning, it holds a named write
1561 * lock on the aor. If you already hold the lock, call ast_sip_location_retrieve_aor_contacts_nolock instead.
1562 */
1564 unsigned int flags);
1565
1566/*!
1567 * \brief Retrieve all contacts currently available for an AOR without locking the AOR
1568 * \since 13.9.0
1569 *
1570 * \param aor Pointer to the AOR
1571 *
1572 * \retval NULL if no contacts available
1573 * \retval non-NULL if contacts available
1574 *
1575 * \warning
1576 * This function should only be called if you already hold a named write lock on the aor.
1577 */
1579
1580/*!
1581 * \brief Retrieve all contacts currently available for an AOR without locking the AOR and filter based on flags
1582 * \since 13.16.0
1583 *
1584 * \param aor Pointer to the AOR
1585 * \param flags Filtering flags
1586 *
1587 * \retval NULL if no contacts available
1588 * \retval non-NULL if contacts available
1589 *
1590 * \warning
1591 * This function should only be called if you already hold a named write lock on the aor.
1592 */
1594 unsigned int flags);
1595
1596/*!
1597 * \brief Retrieve the first bound contact from a list of AORs
1598 *
1599 * \param aor_list A comma-separated list of AOR names
1600 * \retval NULL if no contacts available
1601 * \retval non-NULL if contacts available
1602 */
1604
1605/*!
1606 * \brief Retrieve all contacts from a list of AORs
1607 *
1608 * \param aor_list A comma-separated list of AOR names
1609 * \retval NULL if no contacts available
1610 * \retval non-NULL container (which must be freed) if contacts available
1611 */
1613
1614/*!
1615 * \brief Retrieve the first bound contact AND the AOR chosen from a list of AORs
1616 *
1617 * \param aor_list A comma-separated list of AOR names
1618 * \param aor The chosen AOR
1619 * \param contact The chosen contact
1620 */
1621 void ast_sip_location_retrieve_contact_and_aor_from_list(const char *aor_list, struct ast_sip_aor **aor,
1622 struct ast_sip_contact **contact);
1623
1624/*!
1625 * \brief Retrieve the first bound contact AND the AOR chosen from a list of AORs and filter based on flags
1626 * \since 13.16.0
1627 *
1628 * \param aor_list A comma-separated list of AOR names
1629 * \param flags Filtering flags
1630 * \param aor The chosen AOR
1631 * \param contact The chosen contact
1632 */
1633void ast_sip_location_retrieve_contact_and_aor_from_list_filtered(const char *aor_list, unsigned int flags,
1634 struct ast_sip_aor **aor, struct ast_sip_contact **contact);
1635
1636/*!
1637 * \brief Retrieve a named contact
1638 *
1639 * \param contact_name Name of the contact
1640 *
1641 * \retval NULL if not found
1642 * \retval non-NULL if found
1643 */
1644struct ast_sip_contact *ast_sip_location_retrieve_contact(const char *contact_name);
1645
1646/*!
1647 * \brief Add a new contact to an AOR
1648 *
1649 * \param aor Pointer to the AOR
1650 * \param uri Full contact URI
1651 * \param expiration_time Optional expiration time of the contact
1652 * \param path_info Path information
1653 * \param user_agent User-Agent header from REGISTER request
1654 * \param via_addr
1655 * \param via_port
1656 * \param call_id
1657 * \param endpoint The endpoint that resulted in the contact being added
1658 *
1659 * \retval -1 failure
1660 * \retval 0 success
1661 *
1662 * \warning
1663 * This function holds a named write lock on the aor. If you already hold the lock
1664 * you should call ast_sip_location_add_contact_nolock instead.
1665 */
1666int ast_sip_location_add_contact(struct ast_sip_aor *aor, const char *uri,
1667 struct timeval expiration_time, const char *path_info, const char *user_agent,
1668 const char *via_addr, int via_port, const char *call_id,
1669 struct ast_sip_endpoint *endpoint);
1670
1671/*!
1672 * \brief Add a new contact to an AOR without locking the AOR
1673 * \since 13.9.0
1674 *
1675 * \param aor Pointer to the AOR
1676 * \param uri Full contact URI
1677 * \param expiration_time Optional expiration time of the contact
1678 * \param path_info Path information
1679 * \param user_agent User-Agent header from REGISTER request
1680 * \param via_addr
1681 * \param via_port
1682 * \param call_id
1683 * \param endpoint The endpoint that resulted in the contact being added
1684 *
1685 * \retval -1 failure
1686 * \retval 0 success
1687 *
1688 * \warning
1689 * This function should only be called if you already hold a named write lock on the aor.
1690 */
1692 struct timeval expiration_time, const char *path_info, const char *user_agent,
1693 const char *via_addr, int via_port, const char *call_id,
1694 struct ast_sip_endpoint *endpoint);
1695
1696/*!
1697 * \brief Create a new contact for an AOR without locking the AOR
1698 * \since 13.18.0
1699 *
1700 * \param aor Pointer to the AOR
1701 * \param uri Full contact URI
1702 * \param expiration_time Optional expiration time of the contact
1703 * \param path_info Path information
1704 * \param user_agent User-Agent header from REGISTER request
1705 * \param via_addr
1706 * \param via_port
1707 * \param call_id
1708 * \param prune_on_boot Non-zero if the contact cannot survive a restart/boot.
1709 * \param endpoint The endpoint that resulted in the contact being added
1710 *
1711 * \return The created contact or NULL on failure.
1712 *
1713 * \warning
1714 * This function should only be called if you already hold a named write lock on the aor.
1715 */
1717 const char *uri, struct timeval expiration_time, const char *path_info,
1718 const char *user_agent, const char *via_addr, int via_port, const char *call_id,
1720
1721/*!
1722 * \brief Update a contact
1723 *
1724 * \param contact New contact object with details
1725 *
1726 * \retval -1 failure
1727 * \retval 0 success
1728 */
1730
1731/*!
1732* \brief Delete a contact
1733*
1734* \param contact Contact object to delete
1735*
1736* \retval -1 failure
1737* \retval 0 success
1738*/
1740
1741/*!
1742 * \brief Prune the prune_on_boot contacts
1743 * \since 13.18.0
1744 */
1746
1747/*!
1748 * \brief Callback called when an outbound request with authentication credentials is to be sent in dialog
1749 *
1750 * This callback will have the created request on it. The callback's purpose is to do any extra
1751 * housekeeping that needs to be done as well as to send the request out.
1752 *
1753 * This callback is only necessary if working with a PJSIP API that sits between the application
1754 * and the dialog layer.
1755 *
1756 * \param dlg The dialog to which the request belongs
1757 * \param tdata The created request to be sent out
1758 * \param user_data Data supplied with the callback
1759 *
1760 * \retval 0 Success
1761 * \retval -1 Failure
1762 */
1763typedef int (*ast_sip_dialog_outbound_auth_cb)(pjsip_dialog *dlg, pjsip_tx_data *tdata, void *user_data);
1764
1765/*!
1766 * \brief Set up outbound authentication on a SIP dialog
1767 *
1768 * This sets up the infrastructure so that all requests associated with a created dialog
1769 * can be re-sent with authentication credentials if the original request is challenged.
1770 *
1771 * \param dlg The dialog on which requests will be authenticated
1772 * \param endpoint The endpoint whom this dialog pertains to
1773 * \param cb Callback to call to send requests with authentication
1774 * \param user_data Data to be provided to the callback when it is called
1775 *
1776 * \retval 0 Success
1777 * \retval -1 Failure
1778 */
1780 ast_sip_dialog_outbound_auth_cb cb, void *user_data);
1781
1782/*!
1783 * \brief Retrieves a reference to the artificial auth.
1784 *
1785 * \retval The artificial auth
1786 */
1788
1789/*!
1790 * \brief Retrieves a reference to the artificial endpoint.
1791 *
1792 * \retval The artificial endpoint
1793 */
1795
1796/*! \defgroup pjsip_threading PJSIP Threading Model
1797 * @{
1798 * \page PJSIP PJSIP Threading Model
1799 *
1800 * There are three major types of threads that SIP will have to deal with:
1801 * \li Asterisk threads
1802 * \li PJSIP threads
1803 * \li SIP threadpool threads (a.k.a. "servants")
1804 *
1805 * \par Asterisk Threads
1806 *
1807 * Asterisk threads are those that originate from outside of SIP but within
1808 * Asterisk. The most common of these threads are PBX (channel) threads and
1809 * the autoservice thread. Most interaction with these threads will be through
1810 * channel technology callbacks. Within these threads, it is fine to handle
1811 * Asterisk data from outside of SIP, but any handling of SIP data should be
1812 * left to servants, \b especially if you wish to call into PJSIP for anything.
1813 * Asterisk threads are not registered with PJLIB, so attempting to call into
1814 * PJSIP will cause an assertion to be triggered, thus causing the program to
1815 * crash.
1816 *
1817 * \par PJSIP Threads
1818 *
1819 * PJSIP threads are those that originate from handling of PJSIP events, such
1820 * as an incoming SIP request or response, or a transaction timeout. The role
1821 * of these threads is to process information as quickly as possible so that
1822 * the next item on the SIP socket(s) can be serviced. On incoming messages,
1823 * Asterisk automatically will push the request to a servant thread. When your
1824 * module callback is called, processing will already be in a servant. However,
1825 * for other PJSIP events, such as transaction state changes due to timer
1826 * expirations, your module will be called into from a PJSIP thread. If you
1827 * are called into from a PJSIP thread, then you should push whatever processing
1828 * is needed to a servant as soon as possible. You can discern if you are currently
1829 * in a SIP servant thread using the \ref ast_sip_thread_is_servant function.
1830 *
1831 * \par Servants
1832 *
1833 * Servants are where the bulk of SIP work should be performed. These threads
1834 * exist in order to do the work that Asterisk threads and PJSIP threads hand
1835 * off to them. Servant threads register themselves with PJLIB, meaning that
1836 * they are capable of calling PJSIP and PJLIB functions if they wish.
1837 *
1838 * \par Serializer
1839 *
1840 * Tasks are handed off to servant threads using the API call \ref ast_sip_push_task.
1841 * The first parameter of this call is a serializer. If this pointer
1842 * is NULL, then the work will be handed off to whatever servant can currently handle
1843 * the task. If this pointer is non-NULL, then the task will not be executed until
1844 * previous tasks pushed with the same serializer have completed. For more information
1845 * on serializers and the benefits they provide, see \ref ast_threadpool_serializer
1846 *
1847 * \par Scheduler
1848 *
1849 * Some situations require that a task run periodically or at a future time. Normally
1850 * the ast_sched functionality would be used but ast_sched only uses 1 thread for all
1851 * tasks and that thread isn't registered with PJLIB and therefore can't do any PJSIP
1852 * related work.
1853 *
1854 * ast_sip_sched uses ast_sched only as a scheduled queue. When a task is ready to run,
1855 * it's pushed to a Serializer to be invoked asynchronously by a Servant. This ensures
1856 * that the task is executed in a PJLIB registered thread and allows the ast_sched thread
1857 * to immediately continue processing the queue. The Serializer used by ast_sip_sched
1858 * is one of your choosing or a random one from the res_pjsip pool if you don't choose one.
1859 *
1860 * \note
1861 *
1862 * Do not make assumptions about individual threads based on a corresponding serializer.
1863 * In other words, just because several tasks use the same serializer when being pushed
1864 * to servants, it does not mean that the same thread is necessarily going to execute those
1865 * tasks, even though they are all guaranteed to be executed in sequence.
1866 */
1867
1868typedef int (*ast_sip_task)(void *user_data);
1869
1870/*!
1871 * \brief Create a new serializer for SIP tasks
1872 * \since 13.8.0
1873 *
1874 * See \ref ast_threadpool_serializer for more information on serializers.
1875 * SIP creates serializers so that tasks operating on similar data will run
1876 * in sequence.
1877 *
1878 * \param name Name of the serializer. (must be unique)
1879 *
1880 * \retval NULL Failure
1881 * \retval non-NULL Newly-created serializer
1882 */
1884
1886
1887/*!
1888 * \brief Create a new serializer for SIP tasks
1889 * \since 13.8.0
1890 *
1891 * See \ref ast_threadpool_serializer for more information on serializers.
1892 * SIP creates serializers so that tasks operating on similar data will run
1893 * in sequence.
1894 *
1895 * \param name Name of the serializer. (must be unique)
1896 * \param shutdown_group Group shutdown controller. (NULL if no group association)
1897 *
1898 * \retval NULL Failure
1899 * \retval non-NULL Newly-created serializer
1900 */
1902
1903/*!
1904 * \brief Determine the distributor serializer for the SIP message.
1905 * \since 13.10.0
1906 *
1907 * \param rdata The incoming message.
1908 *
1909 * \retval Calculated distributor serializer on success.
1910 * \retval NULL on error.
1911 */
1912struct ast_taskprocessor *ast_sip_get_distributor_serializer(pjsip_rx_data *rdata);
1913
1914/*!
1915 * \brief Set a serializer on a SIP dialog so requests and responses are automatically serialized
1916 *
1917 * Passing a NULL serializer is a way to remove a serializer from a dialog.
1918 *
1919 * \param dlg The SIP dialog itself
1920 * \param serializer The serializer to use
1921 */
1922void ast_sip_dialog_set_serializer(pjsip_dialog *dlg, struct ast_taskprocessor *serializer);
1923
1924/*!
1925 * \brief Set an endpoint on a SIP dialog so in-dialog requests do not undergo endpoint lookup.
1926 *
1927 * \param dlg The SIP dialog itself
1928 * \param endpoint The endpoint that this dialog is communicating with
1929 */
1930void ast_sip_dialog_set_endpoint(pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint);
1931
1932/*!
1933 * \brief Get the endpoint associated with this dialog
1934 *
1935 * This function increases the refcount of the endpoint by one. Release
1936 * the reference once you are finished with the endpoint.
1937 *
1938 * \param dlg The SIP dialog from which to retrieve the endpoint
1939 * \retval NULL No endpoint associated with this dialog
1940 * \retval non-NULL The endpoint.
1941 */
1942struct ast_sip_endpoint *ast_sip_dialog_get_endpoint(pjsip_dialog *dlg);
1943
1944/*!
1945 * \brief Pushes a task to SIP servants
1946 *
1947 * This uses the serializer provided to determine how to push the task.
1948 * If the serializer is NULL, then the task will be pushed to the
1949 * servants directly. If the serializer is non-NULL, then the task will be
1950 * queued behind other tasks associated with the same serializer.
1951 *
1952 * \param serializer The serializer to which the task belongs. Can be NULL
1953 * \param sip_task The task to execute
1954 * \param task_data The parameter to pass to the task when it executes
1955 * \retval 0 Success
1956 * \retval -1 Failure
1957 */
1958int ast_sip_push_task(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1959
1960/*!
1961 * \brief Push a task to SIP servants and wait for it to complete.
1962 *
1963 * Like \ref ast_sip_push_task except that it blocks until the task
1964 * completes. If the current thread is a SIP servant thread then the
1965 * task executes immediately. Otherwise, the specified serializer
1966 * executes the task and the current thread waits for it to complete.
1967 *
1968 * \note PJPROJECT callbacks tend to have locks already held when
1969 * called.
1970 *
1971 * \warning \b Never hold locks that may be acquired by a SIP servant
1972 * thread when calling this function. Doing so may cause a deadlock
1973 * if all SIP servant threads are blocked waiting to acquire the lock
1974 * while the thread holding the lock is waiting for a free SIP servant
1975 * thread.
1976 *
1977 * \warning \b Use of this function in an ao2 destructor callback is a
1978 * bad idea. You don't have control over which thread executes the
1979 * destructor. Attempting to shift execution to another thread with
1980 * this function is likely to cause deadlock.
1981 *
1982 * \param serializer The SIP serializer to execute the task if the
1983 * current thread is not a SIP servant. NULL if any of the default
1984 * serializers can be used.
1985 * \param sip_task The task to execute
1986 * \param task_data The parameter to pass to the task when it executes
1987 *
1988 * \note The sip_task() return value may need to be distinguished from
1989 * the failure to push the task.
1990 *
1991 * \return sip_task() return value on success.
1992 * \retval -1 Failure to push the task.
1993 */
1994int ast_sip_push_task_wait_servant(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1995
1996/*!
1997 * \brief Push a task to SIP servants and wait for it to complete.
1998 * \deprecated Replaced with ast_sip_push_task_wait_servant().
1999 */
2000int ast_sip_push_task_synchronous(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
2001
2002/*!
2003 * \brief Push a task to the serializer and wait for it to complete.
2004 *
2005 * Like \ref ast_sip_push_task except that it blocks until the task is
2006 * completed by the specified serializer. If the specified serializer
2007 * is the current thread then the task executes immediately.
2008 *
2009 * \note PJPROJECT callbacks tend to have locks already held when
2010 * called.
2011 *
2012 * \warning \b Never hold locks that may be acquired by a SIP servant
2013 * thread when calling this function. Doing so may cause a deadlock
2014 * if all SIP servant threads are blocked waiting to acquire the lock
2015 * while the thread holding the lock is waiting for a free SIP servant
2016 * thread for the serializer to execute in.
2017 *
2018 * \warning \b Never hold locks that may be acquired by the serializer
2019 * when calling this function. Doing so will cause a deadlock.
2020 *
2021 * \warning \b Never use this function in the pjsip monitor thread (It
2022 * is a SIP servant thread). This is likely to cause a deadlock.
2023 *
2024 * \warning \b Use of this function in an ao2 destructor callback is a
2025 * bad idea. You don't have control over which thread executes the
2026 * destructor. Attempting to shift execution to another thread with
2027 * this function is likely to cause deadlock.
2028 *
2029 * \param serializer The SIP serializer to execute the task. NULL if
2030 * any of the default serializers can be used.
2031 * \param sip_task The task to execute
2032 * \param task_data The parameter to pass to the task when it executes
2033 *
2034 * \note It is generally better to call
2035 * ast_sip_push_task_wait_servant() if you pass NULL for the
2036 * serializer parameter.
2037 *
2038 * \note The sip_task() return value may need to be distinguished from
2039 * the failure to push the task.
2040 *
2041 * \return sip_task() return value on success.
2042 * \retval -1 Failure to push the task.
2043 */
2044int ast_sip_push_task_wait_serializer(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
2045
2046/*!
2047 * \brief Determine if the current thread is a SIP servant thread
2048 *
2049 * \retval 0 This is not a SIP servant thread
2050 * \retval 1 This is a SIP servant thread
2051 */
2053
2054/*!
2055 * \brief Task flags for the res_pjsip scheduler
2056 *
2057 * The default is AST_SIP_SCHED_TASK_FIXED
2058 * | AST_SIP_SCHED_TASK_DATA_NOT_AO2
2059 * | AST_SIP_SCHED_TASK_DATA_NO_CLEANUP
2060 * | AST_SIP_SCHED_TASK_PERIODIC
2061 */
2063 /*!
2064 * The defaults
2065 */
2067
2068 /*!
2069 * Run at a fixed interval.
2070 * Stop scheduling if the callback returns <= 0.
2071 * Any other value is ignored.
2072 */
2074 /*!
2075 * Run at a variable interval.
2076 * Stop scheduling if the callback returns <= 0.
2077 * Any other return value is used as the new interval.
2078 */
2080
2081 /*!
2082 * Run just once.
2083 * Return values are ignored.
2084 */
2086
2087 /*!
2088 * The task data is not an AO2 object.
2089 */
2091 /*!
2092 * The task data is an AO2 object.
2093 * A reference count will be held by the scheduler until
2094 * after the task has run for the final time (if ever).
2095 */
2097
2098 /*!
2099 * Don't take any cleanup action on the data
2100 */
2102 /*!
2103 * If AST_SIP_SCHED_TASK_DATA_AO2 is set, decrement the reference count
2104 * otherwise call ast_free on it.
2105 */
2107
2108 /*!
2109 * \brief The task is scheduled at multiples of interval
2110 * \see Interval
2111 */
2113 /*!
2114 * \brief The next invocation of the task is at last finish + interval
2115 * \see Interval
2116 */
2118 /*!
2119 * \brief The scheduled task's events are tracked in the debug log.
2120 * \details
2121 * Schedule events such as scheduling, running, rescheduling, canceling,
2122 * and destroying are logged about the task.
2123 */
2125};
2126
2127/*!
2128 * \brief Scheduler task data structure
2129 */
2130struct ast_sip_sched_task;
2131
2132/*!
2133 * \brief Schedule a task to run in the res_pjsip thread pool
2134 * \since 13.9.0
2135 *
2136 * \param serializer The serializer to use. If NULL, don't use a serializer (see note below)
2137 * \param interval The invocation interval in milliseconds (see note below)
2138 * \param sip_task The task to invoke
2139 * \param name An optional name to associate with the task
2140 * \param task_data Optional data to pass to the task
2141 * \param flags One of enum ast_sip_scheduler_task_type
2142 *
2143 * \returns Pointer to \ref ast_sip_sched_task ao2 object which must be dereferenced when done.
2144 *
2145 * \par Serialization
2146 *
2147 * Specifying a serializer guarantees serialized execution but NOT specifying a serializer
2148 * may still result in tasks being effectively serialized if the thread pool is busy.
2149 * The point of the serializer BTW is not to prevent parallel executions of the SAME task.
2150 * That happens automatically (see below). It's to prevent the task from running at the same
2151 * time as other work using the same serializer, whether or not it's being run by the scheduler.
2152 *
2153 * \par Interval
2154 *
2155 * The interval is used to calculate the next time the task should run. There are two models.
2156 *
2157 * \ref AST_SIP_SCHED_TASK_PERIODIC specifies that the invocations of the task occur at the
2158 * specific interval. That is, every \p interval milliseconds, regardless of how long the task
2159 * takes. If the task takes longer than \p interval, it will be scheduled at the next available
2160 * multiple of \p interval. For example: If the task has an interval of 60 seconds and the task
2161 * takes 70 seconds, the next invocation will happen at 120 seconds.
2162 *
2163 * \ref AST_SIP_SCHED_TASK_DELAY specifies that the next invocation of the task should start
2164 * at \p interval milliseconds after the current invocation has finished.
2165 *
2166 */
2168 int interval, ast_sip_task sip_task, const char *name, void *task_data,
2170
2171/*!
2172 * \brief Cancels the next invocation of a task
2173 * \since 13.9.0
2174 *
2175 * \param schtd The task structure pointer
2176 * \retval 0 Success
2177 * \retval -1 Failure
2178 * \note Only cancels future invocations not the currently running invocation.
2179 */
2181
2182/*!
2183 * \brief Cancels the next invocation of a task by name
2184 * \since 13.9.0
2185 *
2186 * \param name The task name
2187 * \retval 0 Success
2188 * \retval -1 Failure
2189 * \note Only cancels future invocations not the currently running invocation.
2190 */
2192
2193/*!
2194 * \brief Gets the last start and end times of the task
2195 * \since 13.9.0
2196 *
2197 * \param schtd The task structure pointer
2198 * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
2199 * \param[out] last_start Pointer to a timeval structure to contain the time when last started
2200 * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
2201 * \retval 0 Success
2202 * \retval -1 Failure
2203 * \note Any of the pointers can be NULL if you don't need them.
2204 */
2206 struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end);
2207
2208/*!
2209 * \brief Gets the queued, last start, last_end, time left, interval, next run
2210 * \since 16.15.0
2211 * \since 18.1.0
2212 *
2213 * \param schtd The task structure pointer
2214 * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
2215 * \param[out] last_start Pointer to a timeval structure to contain the time when last started
2216 * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
2217 * \param[out] interval Pointer to an int to contain the interval in ms
2218 * \param[out] time_left Pointer to an int to contain the ms left to the next run
2219 * \param[out] next_start Pointer to a timeval structure to contain the next run time
2220 * \retval 0 Success
2221 * \retval -1 Failure
2222 * \note Any of the pointers can be NULL if you don't need them.
2223 */
2225 struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end,
2226 int *interval, int *time_left, struct timeval *next_start);
2227
2228/*!
2229 * \brief Gets the last start and end times of the task by name
2230 * \since 13.9.0
2231 *
2232 * \param name The task name
2233 * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
2234 * \param[out] last_start Pointer to a timeval structure to contain the time when last started
2235 * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
2236 * \retval 0 Success
2237 * \retval -1 Failure
2238 * \note Any of the pointers can be NULL if you don't need them.
2239 */
2241 struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end);
2242
2243/*!
2244 * \brief Gets the queued, last start, last_end, time left, interval, next run by task name
2245 * \since 16.15.0
2246 * \since 18.1.0
2247 *
2248 * \param name The task name
2249 * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
2250 * \param[out] last_start Pointer to a timeval structure to contain the time when last started
2251 * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
2252 * \param[out] interval Pointer to an int to contain the interval in ms
2253 * \param[out] time_left Pointer to an int to contain the ms left to the next run
2254 * \param[out] next_start Pointer to a timeval structure to contain the next run time
2255 * \retval 0 Success
2256 * \retval -1 Failure
2257 * \note Any of the pointers can be NULL if you don't need them.
2258 */
2260 struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end,
2261 int *interval, int *time_left, struct timeval *next_start);
2262
2263/*!
2264 * \brief Gets the number of milliseconds until the next invocation
2265 * \since 13.9.0
2266 *
2267 * \param schtd The task structure pointer
2268 * \return The number of milliseconds until the next invocation or -1 if the task isn't scheduled
2269 */
2271
2272/*!
2273 * \brief Gets the number of milliseconds until the next invocation
2274 * \since 13.9.0
2275 *
2276 * \param name The task name
2277 * \return The number of milliseconds until the next invocation or -1 if the task isn't scheduled
2278 */
2280
2281/*!
2282 * \brief Checks if the task is currently running
2283 * \since 13.9.0
2284 *
2285 * \param schtd The task structure pointer
2286 * \retval 0 not running
2287 * \retval 1 running
2288 */
2290
2291/*!
2292 * \brief Checks if the task is currently running
2293 * \since 13.9.0
2294 *
2295 * \param name The task name
2296 * \retval 0 not running or not found
2297 * \retval 1 running
2298 */
2300
2301/*!
2302 * \brief Gets the task name
2303 * \since 13.9.0
2304 *
2305 * \param schtd The task structure pointer
2306 * \param name, maxlen
2307 * \retval 0 success
2308 * \retval 1 failure
2309 */
2310int ast_sip_sched_task_get_name(struct ast_sip_sched_task *schtd, char *name, size_t maxlen);
2311
2312/*!
2313 * @}
2314 */
2315
2316/*!
2317 * \brief SIP body description
2318 *
2319 * This contains a type and subtype that will be added as
2320 * the "Content-Type" for the message as well as the body
2321 * text.
2322 */
2324 /*! Type of the body, such as "application" */
2325 const char *type;
2326 /*! Subtype of the body, such as "sdp" */
2327 const char *subtype;
2328 /*! The text to go in the body */
2329 const char *body_text;
2330};
2331
2332/*!
2333 * \brief General purpose method for creating a UAC dialog with an endpoint
2334 *
2335 * \param endpoint A pointer to the endpoint
2336 * \param aor_name Optional name of the AOR to target, may even be an explicit SIP URI
2337 * \param request_user Optional user to place into the target URI
2338 *
2339 * \retval non-NULL success
2340 * \retval NULL failure
2341 */
2342pjsip_dialog *ast_sip_create_dialog_uac(const struct ast_sip_endpoint *endpoint, const char *aor_name, const char *request_user);
2343
2344/*!
2345 * \brief General purpose method for creating a UAS dialog with an endpoint
2346 *
2347 * \deprecated This function is unsafe (due to the returned object not being locked nor
2348 * having its reference incremented) and should no longer be used. Instead
2349 * use ast_sip_create_dialog_uas_locked so a properly locked and referenced
2350 * object is returned.
2351 *
2352 * \param endpoint A pointer to the endpoint
2353 * \param rdata The request that is starting the dialog
2354 * \param[out] status On failure, the reason for failure in creating the dialog
2355 */
2356pjsip_dialog *ast_sip_create_dialog_uas(const struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pj_status_t *status);
2357
2358/*!
2359 * \brief General purpose method for creating a UAS dialog with an endpoint
2360 *
2361 * This function creates and returns a locked, and referenced counted pjsip
2362 * dialog object. The caller is thus responsible for freeing the allocated
2363 * memory, decrementing the reference, and releasing the lock when done with
2364 * the returned object.
2365 *
2366 * \note The safest way to unlock the object, and decrement its reference is by
2367 * calling pjsip_dlg_dec_lock. Alternatively, pjsip_dlg_dec_session can be
2368 * used to decrement the reference only.
2369 *
2370 * The dialog is returned locked and with a reference in order to ensure that the
2371 * dialog object, and any of its associated objects (e.g. transaction) are not
2372 * untimely destroyed. For instance, that could happen when a transport error
2373 * occurs.
2374 *
2375 * As long as the caller maintains a reference to the dialog there should be no
2376 * worry that it might unknowingly be destroyed. However, once the caller unlocks
2377 * the dialog there is a danger that some of the dialog's internal objects could
2378 * be lost and/or compromised. For example, when the aforementioned transport error
2379 * occurs the dialog's associated transaction gets destroyed (see pjsip_dlg_on_tsx_state
2380 * in sip_dialog.c, and mod_inv_on_tsx_state in sip_inv.c).
2381 *
2382 * In this case and before using the dialog again the caller should re-lock the
2383 * dialog, check to make sure the dialog is still established, and the transaction
2384 * still exists and has not been destroyed.
2385 *
2386 * \param endpoint A pointer to the endpoint
2387 * \param rdata The request that is starting the dialog
2388 * \param[out] status On failure, the reason for failure in creating the dialog
2389 *
2390 * \retval A locked, and reference counted pjsip_dialog object.
2391 * \retval NULL on failure
2392 */
2393pjsip_dialog *ast_sip_create_dialog_uas_locked(const struct ast_sip_endpoint *endpoint,
2394 pjsip_rx_data *rdata, pj_status_t *status);
2395
2396/*!
2397 * \brief General purpose method for creating an rdata structure using specific information
2398 * \since 13.15.0
2399 *
2400 * \param[out] rdata The rdata structure that will be populated
2401 * \param packet A SIP message
2402 * \param src_name The source IP address of the message
2403 * \param src_port The source port of the message
2404 * \param transport_type The type of transport the message was received on
2405 * \param local_name The local IP address the message was received on
2406 * \param local_port The local port the message was received on
2407 * \param contact_uri The contact URI of the message
2408 *
2409 * \retval 0 success
2410 * \retval -1 failure
2411 */
2412int ast_sip_create_rdata_with_contact(pjsip_rx_data *rdata, char *packet,
2413 const char *src_name, int src_port, char *transport_type, const char *local_name,
2414 int local_port, const char *contact_uri);
2415
2416/*!
2417 * \brief General purpose method for creating an rdata structure using specific information
2418 *
2419 * \param[out] rdata The rdata structure that will be populated
2420 * \param packet A SIP message
2421 * \param src_name The source IP address of the message
2422 * \param src_port The source port of the message
2423 * \param transport_type The type of transport the message was received on
2424 * \param local_name The local IP address the message was received on
2425 * \param local_port The local port the message was received on
2426 *
2427 * \retval 0 success
2428 * \retval -1 failure
2429 */
2430int ast_sip_create_rdata(pjsip_rx_data *rdata, char *packet, const char *src_name,
2431 int src_port, char *transport_type, const char *local_name, int local_port);
2432
2433/*!
2434 * \brief General purpose method for creating a SIP request
2435 *
2436 * Its typical use would be to create one-off requests such as an out of dialog
2437 * SIP MESSAGE.
2438 *
2439 * The request can either be in- or out-of-dialog. If in-dialog, the
2440 * dlg parameter MUST be present. If out-of-dialog the endpoint parameter
2441 * MUST be present. If both are present, then we will assume that the message
2442 * is to be sent in-dialog.
2443 *
2444 * The uri parameter can be specified if the request should be sent to an explicit
2445 * URI rather than one configured on the endpoint.
2446 *
2447 * \param method The method of the SIP request to send
2448 * \param dlg Optional. If specified, the dialog on which to request the message.
2449 * \param endpoint Optional. If specified, the request will be created out-of-dialog to the endpoint.
2450 * \param uri Optional. If specified, the request will be sent to this URI rather
2451 * than one configured for the endpoint.
2452 * \param contact The contact with which this request is associated for out-of-dialog requests.
2453 * \param[out] tdata The newly-created request
2454 *
2455 * The provided contact is attached to tdata with its reference bumped, but will
2456 * not survive for the entire lifetime of tdata since the contact is cleaned up
2457 * when all supplements have completed execution.
2458 *
2459 * \retval 0 Success
2460 * \retval -1 Failure
2461 */
2462int ast_sip_create_request(const char *method, struct pjsip_dialog *dlg,
2463 struct ast_sip_endpoint *endpoint, const char *uri,
2464 struct ast_sip_contact *contact, pjsip_tx_data **tdata);
2465
2466/*!
2467 * \brief General purpose method for sending a SIP request
2468 *
2469 * This is a companion function for \ref ast_sip_create_request. The request
2470 * created there can be passed to this function, though any request may be
2471 * passed in.
2472 *
2473 * This will automatically set up handling outbound authentication challenges if
2474 * they arrive.
2475 *
2476 * \param tdata The request to send
2477 * \param dlg Optional. The dialog in which the request is sent. Otherwise it is out-of-dialog.
2478 * \param endpoint Optional. If specified, the out-of-dialog request is sent to the endpoint.
2479 * \param token Data to be passed to the callback upon receipt of out-of-dialog response.
2480 * \param callback Callback to be called upon receipt of out-of-dialog response.
2481 *
2482 * \retval 0 Success
2483 * \retval -1 Failure (out-of-dialog callback will not be called.)
2484 */
2485int ast_sip_send_request(pjsip_tx_data *tdata, struct pjsip_dialog *dlg,
2486 struct ast_sip_endpoint *endpoint, void *token,
2487 void (*callback)(void *token, pjsip_event *e));
2488
2489/*!
2490 * \brief General purpose method for sending an Out-Of-Dialog SIP request
2491 *
2492 * This is a companion function for \ref ast_sip_create_request. The request
2493 * created there can be passed to this function, though any request may be
2494 * passed in.
2495 *
2496 * This will automatically set up handling outbound authentication challenges if
2497 * they arrive.
2498 *
2499 * \param tdata The request to send
2500 * \param endpoint Optional. If specified, the out-of-dialog request is sent to the endpoint.
2501 * \param timeout If non-zero, after the timeout the transaction will be terminated
2502 * and the callback will be called with the PJSIP_EVENT_TIMER type.
2503 * \param token Data to be passed to the callback upon receipt of out-of-dialog response.
2504 * \param callback Callback to be called upon receipt of out-of-dialog response.
2505 *
2506 * \retval 0 Success
2507 * \retval -1 Failure (out-of-dialog callback will not be called.)
2508 *
2509 * \note Timeout processing:
2510 * There are 2 timers associated with this request, PJSIP timer_b which is
2511 * set globally in the "system" section of pjsip.conf, and the timeout specified
2512 * on this call. The timer that expires first (before normal completion) will
2513 * cause the callback to be run with e->body.tsx_state.type = PJSIP_EVENT_TIMER.
2514 * The timer that expires second is simply ignored and the callback is not run again.
2515 */
2516int ast_sip_send_out_of_dialog_request(pjsip_tx_data *tdata,
2517 struct ast_sip_endpoint *endpoint, int timeout, void *token,
2518 void (*callback)(void *token, pjsip_event *e));
2519
2520/*!
2521 * \brief General purpose method for creating a SIP response
2522 *
2523 * Its typical use would be to create responses for out of dialog
2524 * requests.
2525 *
2526 * \param rdata The rdata from the incoming request.
2527 * \param st_code The response code to transmit.
2528 * \param contact The contact with which this request is associated.
2529 * \param[out] p_tdata The newly-created response
2530 *
2531 * The provided contact is attached to tdata with its reference bumped, but will
2532 * not survive for the entire lifetime of tdata since the contact is cleaned up
2533 * when all supplements have completed execution.
2534 *
2535 * \retval 0 Success
2536 * \retval -1 Failure
2537 */
2538int ast_sip_create_response(const pjsip_rx_data *rdata, int st_code,
2539 struct ast_sip_contact *contact, pjsip_tx_data **p_tdata);
2540
2541/*!
2542 * \brief Send a response to an out of dialog request
2543 *
2544 * Use this function sparingly, since this does not create a transaction
2545 * within PJSIP. This means that if the request is retransmitted, it is
2546 * your responsibility to detect this and not process the same request
2547 * twice, and to send the same response for each retransmission.
2548 *
2549 * \param res_addr The response address for this response
2550 * \param tdata The response to send
2551 * \param sip_endpoint The ast_sip_endpoint associated with this response
2552 *
2553 * \retval 0 Success
2554 * \retval -1 Failure
2555 */
2556int ast_sip_send_response(pjsip_response_addr *res_addr, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint);
2557
2558/*!
2559 * \brief Send a stateful response to an out of dialog request
2560 *
2561 * This creates a transaction within PJSIP, meaning that if the request
2562 * that we are responding to is retransmitted, we will not attempt to
2563 * re-handle the request.
2564 *
2565 * \param rdata The request that is being responded to
2566 * \param tdata The response to send
2567 * \param sip_endpoint The ast_sip_endpoint associated with this response
2568 *
2569 * \since 13.4.0
2570 *
2571 * \retval 0 Success
2572 * \retval -1 Failure
2573 */
2574int ast_sip_send_stateful_response(pjsip_rx_data *rdata, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint);
2575
2576/*!
2577 * \brief Determine if an incoming request requires authentication
2578 *
2579 * This calls into the registered authenticator's requires_authentication callback
2580 * in order to determine if the request requires authentication.
2581 *
2582 * If there is no registered authenticator, then authentication will be assumed
2583 * not to be required.
2584 *
2585 * \param endpoint The endpoint from which the request originates
2586 * \param rdata The incoming SIP request
2587 * \retval non-zero The request requires authentication
2588 * \retval 0 The request does not require authentication
2589 */
2590int ast_sip_requires_authentication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2591
2592/*!
2593 * \brief Method to determine authentication status of an incoming request
2594 *
2595 * This will call into a registered authenticator. The registered authenticator will
2596 * do what is necessary to determine whether the incoming request passes authentication.
2597 * A tentative response is passed into this function so that if, say, a digest authentication
2598 * challenge should be sent in the ensuing response, it can be added to the response.
2599 *
2600 * \param endpoint The endpoint from the request was sent
2601 * \param rdata The request to potentially authenticate
2602 * \param tdata Tentative response to the request
2603 * \return The result of checking authentication.
2604 */
2606 pjsip_rx_data *rdata, pjsip_tx_data *tdata);
2607
2608/*!
2609 * \brief Create a response to an authentication challenge
2610 *
2611 * This will call into an outbound authenticator's create_request_with_auth callback
2612 * to create a new request with authentication credentials. See the create_request_with_auth
2613 * callback in the \ref ast_sip_outbound_authenticator structure for details about
2614 * the parameters and return values.
2615 */
2616int ast_sip_create_request_with_auth(const struct ast_sip_auth_vector *auths, pjsip_rx_data *challenge,
2617 pjsip_tx_data *tdata, pjsip_tx_data **new_request);
2618
2619/*!
2620 * \brief Determine the endpoint that has sent a SIP message
2621 *
2622 * This will call into each of the registered endpoint identifiers'
2623 * identify_endpoint() callbacks until one returns a non-NULL endpoint.
2624 * This will return an ao2 object. Its reference count will need to be
2625 * decremented when completed using the endpoint.
2626 *
2627 * \param rdata The inbound SIP message to use when identifying the endpoint.
2628 * \retval NULL No matching endpoint
2629 * \retval non-NULL The matching endpoint
2630 */
2631struct ast_sip_endpoint *ast_sip_identify_endpoint(pjsip_rx_data *rdata);
2632
2633/*!
2634 * \brief Get a specific header value from rdata
2635 *
2636 * \note The returned value does not need to be freed since it's from the rdata pool
2637 *
2638 * \param rdata The rdata
2639 * \param str The header to find
2640 *
2641 * \retval NULL on failure
2642 * \retval The header value on success
2643 */
2644char *ast_sip_rdata_get_header_value(pjsip_rx_data *rdata, const pj_str_t str);
2645
2646/*!
2647 * \brief Set the outbound proxy for an outbound SIP message
2648 *
2649 * \param tdata The message to set the outbound proxy on
2650 * \param proxy SIP uri of the proxy
2651 * \retval 0 Success
2652 * \retval -1 Failure
2653 */
2654int ast_sip_set_outbound_proxy(pjsip_tx_data *tdata, const char *proxy);
2655
2656/*!
2657 * \brief Add a header to an outbound SIP message
2658 *
2659 * \param tdata The message to add the header to
2660 * \param name The header name
2661 * \param value The header value
2662 * \retval 0 Success
2663 * \retval -1 Failure
2664 */
2665int ast_sip_add_header(pjsip_tx_data *tdata, const char *name, const char *value);
2666
2667/*!
2668 * \brief Add a header to an outbound SIP message, returning a pointer to the header
2669 *
2670 * \param tdata The message to add the header to
2671 * \param name The header name
2672 * \param value The header value
2673 * \return The pjsip_generic_string_hdr * added.
2674 */
2675pjsip_generic_string_hdr *ast_sip_add_header2(pjsip_tx_data *tdata,
2676 const char *name, const char *value);
2677
2678/*!
2679 * \brief Add a body to an outbound SIP message
2680 *
2681 * If this is called multiple times, the latest body will replace the current
2682 * body.
2683 *
2684 * \param tdata The message to add the body to
2685 * \param body The message body to add
2686 * \retval 0 Success
2687 * \retval -1 Failure
2688 */
2689int ast_sip_add_body(pjsip_tx_data *tdata, const struct ast_sip_body *body);
2690
2691/*!
2692 * \brief Add a multipart body to an outbound SIP message
2693 *
2694 * This will treat each part of the input vector as part of a multipart body and
2695 * add each part to the SIP message.
2696 *
2697 * \param tdata The message to add the body to
2698 * \param bodies The message bodies to add
2699 * \param num_bodies The parts of the body to add
2700 * \retval 0 Success
2701 * \retval -1 Failure
2702 */
2703int ast_sip_add_body_multipart(pjsip_tx_data *tdata, const struct ast_sip_body *bodies[], int num_bodies);
2704
2705/*!
2706 * \brief Append body data to a SIP message
2707 *
2708 * This acts mostly the same as ast_sip_add_body, except that rather than replacing
2709 * a body if it currently exists, it appends data to an existing body.
2710 *
2711 * \param tdata The message to append the body to
2712 * \param body_text The string to append to the end of the current body
2713 * \retval 0 Success
2714 * \retval -1 Failure
2715 */
2716int ast_sip_append_body(pjsip_tx_data *tdata, const char *body_text);
2717
2718/*!
2719 * \brief Copy a pj_str_t into a standard character buffer.
2720 *
2721 * pj_str_t is not NULL-terminated. Any place that expects a NULL-
2722 * terminated string needs to have the pj_str_t copied into a separate
2723 * buffer.
2724 *
2725 * This method copies the pj_str_t contents into the destination buffer
2726 * and NULL-terminates the buffer.
2727 *
2728 * \param dest The destination buffer
2729 * \param src The pj_str_t to copy
2730 * \param size The size of the destination buffer.
2731 */
2732void ast_copy_pj_str(char *dest, const pj_str_t *src, size_t size);
2733
2734/*!
2735 * \brief Create and copy a pj_str_t into a standard character buffer.
2736 *
2737 * pj_str_t is not NULL-terminated. Any place that expects a NULL-
2738 * terminated string needs to have the pj_str_t copied into a separate
2739 * buffer.
2740 *
2741 * Copies the pj_str_t contents into a newly allocated buffer pointed to
2742 * by dest. NULL-terminates the buffer.
2743 *
2744 * \note Caller is responsible for freeing the allocated memory.
2745 *
2746 * \param[out] dest The destination buffer
2747 * \param src The pj_str_t to copy
2748 * \return Number of characters copied or negative value on error
2749 */
2750int ast_copy_pj_str2(char **dest, const pj_str_t *src);
2751
2752/*!
2753 * \brief Get the looked-up endpoint on an out-of dialog request or response
2754 *
2755 * The function may ONLY be called on out-of-dialog requests or responses. For
2756 * in-dialog requests and responses, it is required that the user of the dialog
2757 * has the looked-up endpoint stored locally.
2758 *
2759 * This function should never return NULL if the message is out-of-dialog. It will
2760 * always return NULL if the message is in-dialog.
2761 *
2762 * This function will increase the reference count of the returned endpoint by one.
2763 * Release your reference using the ao2_ref function when finished.
2764 *
2765 * \param rdata Out-of-dialog request or response
2766 * \return The looked up endpoint
2767 */
2768struct ast_sip_endpoint *ast_pjsip_rdata_get_endpoint(pjsip_rx_data *rdata);
2769
2770/*!
2771 * \brief Add 'user=phone' parameter to URI if enabled and user is a phone number.
2772 *
2773 * \param endpoint The endpoint to use for configuration
2774 * \param pool The memory pool to allocate the parameter from
2775 * \param uri The URI to check for user and to add parameter to
2776 */
2777void ast_sip_add_usereqphone(const struct ast_sip_endpoint *endpoint, pj_pool_t *pool, pjsip_uri *uri);
2778
2779/*!
2780 * \brief Retrieve any endpoints available to sorcery.
2781 *
2782 * \retval Endpoints available to sorcery, NULL if no endpoints found.
2783 */
2785
2786/*!
2787 * \brief Retrieve the default outbound endpoint.
2788 *
2789 * \retval The default outbound endpoint, NULL if not found.
2790 */
2792
2793/*!
2794 * \brief Retrieve relevant SIP auth structures from sorcery
2795 *
2796 * \param auths Vector of sorcery IDs of auth credentials to retrieve
2797 * \param[out] out The retrieved auths are stored here
2798 */
2799int ast_sip_retrieve_auths(const struct ast_sip_auth_vector *auths, struct ast_sip_auth **out);
2800
2801/*!
2802 * \brief Clean up retrieved auth structures from memory
2803 *
2804 * Call this function once you have completed operating on auths
2805 * retrieved from \ref ast_sip_retrieve_auths
2806 *
2807 * \param auths An array of auth object pointers to clean up
2808 * \param num_auths The number of auths in the array
2809 */
2810void ast_sip_cleanup_auths(struct ast_sip_auth *auths[], size_t num_auths);
2811
2813/*!
2814 * \brief Retrieve relevant SIP auth structures from sorcery as a vector
2815 *
2816 * \param auth_ids Vector of sorcery IDs of auth credentials to retrieve
2817 * \param[out] auth_objects A pointer ast_sip_auth_objects_vector to hold the objects
2818 *
2819 * \retval 0 Success
2820 * \retval -1 Number of auth objects found is less than the number of names supplied.
2821 *
2822 * \warning The number of auth objects retrieved may be less than the
2823 * number of auth ids supplied if auth objects couldn't be found for
2824 * some of them.
2825 *
2826 * \note Since the ref count on all auth objects returned has been
2827 * bumped, you must call ast_sip_cleanup_auth_objects_vector() to decrement
2828 * the ref count on all of the auth objects in the vector,
2829 * then call AST_VECTOR_FREE() on the vector itself.
2830 *
2831 */
2832int ast_sip_retrieve_auths_vector(const struct ast_sip_auth_vector *auth_ids,
2833 struct ast_sip_auth_objects_vector *auth_objects);
2834
2835/*!
2836 * \brief Clean up retrieved auth objects in vector
2837 *
2838 * Call this function once you have completed operating on auths
2839 * retrieved from \ref ast_sip_retrieve_auths_vector. All
2840 * auth objects will have their reference counts decremented and
2841 * the vector size will be reset to 0. You must still call
2842 * AST_VECTOR_FREE() on the vector itself.
2843 *
2844 * \param auth_objects A vector of auth structures to clean up
2845 */
2846#define ast_sip_cleanup_auth_objects_vector(auth_objects) AST_VECTOR_RESET(auth_objects, ao2_cleanup)
2847
2848/*!
2849 * \brief Checks if the given content type matches type/subtype.
2850 *
2851 * Compares the pjsip_media_type with the passed type and subtype and
2852 * returns the result of that comparison. The media type parameters are
2853 * ignored.
2854 *
2855 * \param content_type The pjsip_media_type structure to compare
2856 * \param type The media type to compare
2857 * \param subtype The media subtype to compare
2858 * \retval 0 No match
2859 * \retval -1 Match
2860 */
2861int ast_sip_is_content_type(pjsip_media_type *content_type, char *type, char *subtype);
2862
2863/*!
2864 * \brief Send a security event notification for when an invalid endpoint is requested
2865 *
2866 * \param name Name of the endpoint requested
2867 * \param rdata Received message
2868 */
2869void ast_sip_report_invalid_endpoint(const char *name, pjsip_rx_data *rdata);
2870
2871/*!
2872 * \brief Send a security event notification for when an ACL check fails
2873 *
2874 * \param endpoint Pointer to the endpoint in use
2875 * \param rdata Received message
2876 * \param name Name of the ACL
2877 */
2878void ast_sip_report_failed_acl(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, const char *name);
2879
2880/*!
2881 * \brief Send a security event notification for when a challenge response has failed
2882 *
2883 * \param endpoint Pointer to the endpoint in use
2884 * \param rdata Received message
2885 */
2886void ast_sip_report_auth_failed_challenge_response(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2887
2888/*!
2889 * \brief Send a security event notification for when authentication succeeds
2890 *
2891 * \param endpoint Pointer to the endpoint in use
2892 * \param rdata Received message
2893 */
2894void ast_sip_report_auth_success(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2895
2896/*!
2897 * \brief Send a security event notification for when an authentication challenge is sent
2898 *
2899 * \param endpoint Pointer to the endpoint in use
2900 * \param rdata Received message
2901 * \param tdata Sent message
2902 */
2903void ast_sip_report_auth_challenge_sent(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pjsip_tx_data *tdata);
2904
2905/*!
2906 * \brief Send a security event notification for when a request is not supported
2907 *
2908 * \param endpoint Pointer to the endpoint in use
2909 * \param rdata Received message
2910 * \param req_type the type of request
2911 */
2912void ast_sip_report_req_no_support(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata,
2913 const char* req_type);
2914
2915/*!
2916 * \brief Send a security event notification for when a memory limit is hit.
2917 *
2918 * \param endpoint Pointer to the endpoint in use
2919 * \param rdata Received message
2920 */
2921void ast_sip_report_mem_limit(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2922
2923int ast_sip_add_global_request_header(const char *name, const char *value, int replace);
2924int ast_sip_add_global_response_header(const char *name, const char *value, int replace);
2925
2926/*!
2927 * \brief Retrieves the value associated with the given key.
2928 *
2929 * \param ht the hash table/dictionary to search
2930 * \param key the key to find
2931 *
2932 * \retval the value associated with the key, NULL otherwise.
2933 */
2934void *ast_sip_dict_get(void *ht, const char *key);
2935
2936/*!
2937 * \brief Using the dictionary stored in mod_data array at a given id,
2938 * retrieve the value associated with the given key.
2939 *
2940 * \param mod_data a module data array
2941 * \param id the mod_data array index
2942 * \param key the key to find
2943 *
2944 * \retval the value associated with the key, NULL otherwise.
2945 */
2946#define ast_sip_mod_data_get(mod_data, id, key) \
2947 ast_sip_dict_get(mod_data[id], key)
2948
2949/*!
2950 * \brief Set the value for the given key.
2951 *
2952 * Note - if the hash table does not exist one is created first, the key/value
2953 * pair is set, and the hash table returned.
2954 *
2955 * \param pool the pool to allocate memory in
2956 * \param ht the hash table/dictionary in which to store the key/value pair
2957 * \param key the key to associate a value with
2958 * \param val the value to associate with a key
2959 *
2960 * \retval the given, or newly created, hash table.
2961 */
2962void *ast_sip_dict_set(pj_pool_t* pool, void *ht,
2963 const char *key, void *val);
2964
2965/*!
2966 * \brief Utilizing a mod_data array for a given id, set the value
2967 * associated with the given key.
2968 *
2969 * For a given structure's mod_data array set the element indexed by id to
2970 * be a dictionary containing the key/val pair.
2971 *
2972 * \param pool a memory allocation pool
2973 * \param mod_data a module data array
2974 * \param id the mod_data array index
2975 * \param key the key to find
2976 * \param val the value to associate with a key
2977 */
2978#define ast_sip_mod_data_set(pool, mod_data, id, key, val) \
2979 mod_data[id] = ast_sip_dict_set(pool, mod_data[id], key, val)
2980
2981/*!
2982 * \brief For every contact on an AOR call the given 'on_contact' handler.
2983 *
2984 * \param aor the aor containing a list of contacts to iterate
2985 * \param on_contact callback on each contact on an AOR. The object
2986 * received by the callback will be a ast_sip_contact_wrapper structure.
2987 * \param arg user data passed to handler
2988 * \retval 0 Success, non-zero on failure
2989 */
2990int ast_sip_for_each_contact(const struct ast_sip_aor *aor,
2991 ao2_callback_fn on_contact, void *arg);
2992
2993/*!
2994 * \brief Handler used to convert a contact to a string.
2995 *
2996 * \param object the ast_sip_aor_contact_pair containing a list of contacts to iterate and the contact
2997 * \param arg user data passed to handler
2998 * \param flags
2999 * \retval 0 Success, non-zero on failure
3000 */
3001int ast_sip_contact_to_str(void *object, void *arg, int flags);
3002
3003/*!
3004 * \brief For every aor in the comma separated aors string call the
3005 * given 'on_aor' handler.
3006 *
3007 * \param aors a comma separated list of aors
3008 * \param on_aor callback for each aor
3009 * \param arg user data passed to handler
3010 * \retval 0 Success, non-zero on failure
3011 */
3012int ast_sip_for_each_aor(const char *aors, ao2_callback_fn on_aor, void *arg);
3013
3014/*!
3015 * \brief For every auth in the array call the given 'on_auth' handler.
3016 *
3017 * \param array an array of auths
3018 * \param on_auth callback for each auth
3019 * \param arg user data passed to handler
3020 * \retval 0 Success, non-zero on failure
3021 */
3023 ao2_callback_fn on_auth, void *arg);
3024
3025/*!
3026 * \brief Converts the given auth type to a string
3027 *
3028 * \param type the auth type to convert
3029 * \retval a string representative of the auth type
3030 */
3032
3033/*!
3034 * \brief Converts an auths array to a string of comma separated values
3035 *
3036 * \param auths an auth array
3037 * \param buf the string buffer to write the object data
3038 * \retval 0 Success, non-zero on failure
3039 */
3040int ast_sip_auths_to_str(const struct ast_sip_auth_vector *auths, char **buf);
3041
3042/*!
3043 * \brief AMI variable container
3044 */
3046 /*! Manager session */
3047 struct mansession *s;
3048 /*! Manager message */
3049 const struct message *m;
3050 /*! Manager Action ID */
3051 const char *action_id;
3052 /*! user specified argument data */
3053 void *arg;
3054 /*! count of objects */
3056};
3057
3058/*!
3059 * \brief Creates a string to store AMI event data in.
3060 *
3061 * \param event the event to set
3062 * \param ami AMI session and message container
3063 * \retval an initialized ast_str or NULL on error.
3064 */
3065struct ast_str *ast_sip_create_ami_event(const char *event,
3066 struct ast_sip_ami *ami);
3067
3068/*!
3069 * \brief An entity responsible formatting endpoint information.
3070 */
3072 /*!
3073 * \brief Callback used to format endpoint information over AMI.
3074 */
3075 int (*format_ami)(const struct ast_sip_endpoint *endpoint,
3076 struct ast_sip_ami *ami);
3078};
3079
3080/*!
3081 * \brief Register an endpoint formatter.
3082 *
3083 * \param obj the formatter to register
3084 */
3086
3087/*!
3088 * \brief Unregister an endpoint formatter.
3089 *
3090 * \param obj the formatter to unregister
3091 */
3093
3094/*!
3095 * \brief Converts a sorcery object to a string of object properties.
3096 *
3097 * \param obj the sorcery object to convert
3098 * \param buf the string buffer to write the object data
3099 * \retval 0 Success, non-zero on failure
3100 */
3101int ast_sip_sorcery_object_to_ami(const void *obj, struct ast_str **buf);
3102
3103/*!
3104 * \brief Formats the endpoint and sends over AMI.
3105 *
3106 * \param endpoint the endpoint to format and send
3107 * \param ami AMI variable container
3108 * \param count the number of formatters operated on
3109 * \retval 0 Success, otherwise non-zero on error
3110 */
3112 struct ast_sip_ami *ami, int *count);
3113
3114/*!
3115 * \brief Formats the contact and sends over AMI.
3116 *
3117 * \param obj a pointer an ast_sip_contact_wrapper structure
3118 * \param arg a pointer to an ast_sip_ami structure
3119 * \param flags ignored
3120 * \retval 0 Success, otherwise non-zero on error
3121 */
3122int ast_sip_format_contact_ami(void *obj, void *arg, int flags);
3123
3124/*!
3125 * \brief Format auth details for AMI.
3126 *
3127 * \param auths an auth array
3128 * \param ami ami variable container
3129 * \retval 0 Success, non-zero on failure
3130 */
3131int ast_sip_format_auths_ami(const struct ast_sip_auth_vector *auths,
3132 struct ast_sip_ami *ami);
3133
3134/*!
3135 * \brief Retrieve the endpoint snapshot for an endpoint
3136 *
3137 * \param endpoint The endpoint whose snapshot is to be retrieved.
3138 * \retval The endpoint snapshot
3139 */
3141 const struct ast_sip_endpoint *endpoint);
3142
3143/*!
3144 * \brief Retrieve the device state for an endpoint.
3145 *
3146 * \param endpoint The endpoint whose state is to be retrieved.
3147 * \retval The device state.
3148 */
3149const char *ast_sip_get_device_state(const struct ast_sip_endpoint *endpoint);
3150
3151/*!
3152 * \brief For every channel snapshot on an endpoint snapshot call the given
3153 * 'on_channel_snapshot' handler.
3154 *
3155 * \param endpoint_snapshot snapshot of an endpoint
3156 * \param on_channel_snapshot callback for each channel snapshot
3157 * \param arg user data passed to handler
3158 * \retval 0 Success, non-zero on failure
3159 */
3160int ast_sip_for_each_channel_snapshot(const struct ast_endpoint_snapshot *endpoint_snapshot,
3161 ao2_callback_fn on_channel_snapshot,
3162 void *arg);
3163
3164/*!
3165 * \brief For every channel snapshot on an endpoint all the given
3166 * 'on_channel_snapshot' handler.
3167 *
3168 * \param endpoint endpoint
3169 * \param on_channel_snapshot callback for each channel snapshot
3170 * \param arg user data passed to handler
3171 * \retval 0 Success, non-zero on failure
3172 */
3173int ast_sip_for_each_channel(const struct ast_sip_endpoint *endpoint,
3174 ao2_callback_fn on_channel_snapshot,
3175 void *arg);
3176
3178 /*! Top priority. Supplements with this priority are those that need to run before any others */
3180 /*! Channel creation priority.
3181 * chan_pjsip creates a channel at this priority. If your supplement depends on being run before
3182 * or after channel creation, then set your priority to be lower or higher than this value.
3183 */
3185 /*! Lowest priority. Supplements with this priority should be run after all other supplements */
3187};
3188
3189/*!
3190 * \brief A supplement to SIP message processing
3191 *
3192 * These can be registered by any module in order to add
3193 * processing to incoming and outgoing SIP out of dialog
3194 * requests and responses
3195 */
3197 /*! Method on which to call the callbacks. If NULL, call on all methods */
3198 const char *method;
3199 /*! Priority for this supplement. Lower numbers are visited before higher numbers */
3201 /*!
3202 * \brief Called on incoming SIP request
3203 * This method can indicate a failure in processing in its return. If there
3204 * is a failure, it is required that this method sends a response to the request.
3205 * This method is always called from a SIP servant thread.
3206 *
3207 * \note
3208 * The following PJSIP methods will not work properly:
3209 * pjsip_rdata_get_dlg()
3210 * pjsip_rdata_get_tsx()
3211 * The reason is that the rdata passed into this function is a cloned rdata structure,
3212 * and its module data is not copied during the cloning operation.
3213 * If you need to get the dialog, you can get it via session->inv_session->dlg.
3214 *
3215 * \note
3216 * There is no guarantee that a channel will be present on the session when this is called.
3217 */
3218 int (*incoming_request)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
3219 /*!
3220 * \brief Called on an incoming SIP response
3221 * This method is always called from a SIP servant thread.
3222 *
3223 * \note
3224 * The following PJSIP methods will not work properly:
3225 * pjsip_rdata_get_dlg()
3226 * pjsip_rdata_get_tsx()
3227 * The reason is that the rdata passed into this function is a cloned rdata structure,
3228 * and its module data is not copied during the cloning operation.
3229 * If you need to get the dialog, you can get it via session->inv_session->dlg.
3230 *
3231 * \note
3232 * There is no guarantee that a channel will be present on the session when this is called.
3233 */
3234 void (*incoming_response)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
3235 /*!
3236 * \brief Called on an outgoing SIP request
3237 * This method is always called from a SIP servant thread.
3238 */
3239 void (*outgoing_request)(struct ast_sip_endpoint *endpoint, struct ast_sip_contact *contact, struct pjsip_tx_data *tdata);
3240 /*!
3241 * \brief Called on an outgoing SIP response
3242 * This method is always called from a SIP servant thread.
3243 */
3244 void (*outgoing_response)(struct ast_sip_endpoint *endpoint, struct ast_sip_contact *contact, struct pjsip_tx_data *tdata);
3245 /*! Next item in the list */
3247};
3248
3249/*!
3250 * \brief Register a supplement to SIP out of dialog processing
3251 *
3252 * This allows for someone to insert themselves in the processing of out
3253 * of dialog SIP requests and responses. This, for example could allow for
3254 * a module to set channel data based on headers in an incoming message.
3255 * Similarly, a module could reject an incoming request if desired.
3256 *
3257 * \param supplement The supplement to register
3258 */
3259void ast_sip_register_supplement(struct ast_sip_supplement *supplement);
3260
3261/*!
3262 * \brief Unregister a an supplement to SIP out of dialog processing
3263 *
3264 * \param supplement The supplement to unregister
3265 */
3266void ast_sip_unregister_supplement(struct ast_sip_supplement *supplement);
3267
3268/*!
3269 * \brief Retrieve the global MWI taskprocessor high water alert trigger level.
3270 *
3271 * \since 13.12.0
3272 *
3273 * \retval the system MWI taskprocessor high water alert trigger level
3274 */
3275unsigned int ast_sip_get_mwi_tps_queue_high(void);
3276
3277/*!
3278 * \brief Retrieve the global MWI taskprocessor low water clear alert level.
3279 *
3280 * \since 13.12.0
3281 *
3282 * \retval the system MWI taskprocessor low water clear alert level
3283 */
3285
3286/*!
3287 * \brief Retrieve the global setting 'disable sending unsolicited mwi on startup'.
3288 * \since 13.12.0
3289 *
3290 * \retval non zero if disable.
3291 */
3293
3294/*!
3295 * \brief Retrieve the global setting 'allow_sending_180_after_183'.
3296 *
3297 * \retval non zero if disable.
3298 */
3300
3301/*!
3302 * \brief Retrieve the global setting 'use_callerid_contact'.
3303 * \since 13.24.0
3304 *
3305 * \retval non zero if CALLERID(num) is to be used as the default username in the contact
3306 */
3307unsigned int ast_sip_get_use_callerid_contact(void);
3308
3309/*!
3310 * \brief Retrieve the global setting 'norefersub'.
3311 *
3312 * \retval non zero if norefersub is to be sent in "Supported" Headers
3313 */
3314unsigned int ast_sip_get_norefersub(void);
3315
3316/*!
3317 * \brief Retrieve the global setting 'ignore_uri_user_options'.
3318 * \since 13.12.0
3319 *
3320 * \retval non zero if ignore the user field options.
3321 */
3322unsigned int ast_sip_get_ignore_uri_user_options(void);
3323
3324/*!
3325 * \brief Retrieve the global setting 'send_contact_status_on_update_registration'.
3326 * \since 16.2.0
3327 *
3328 * \retval non zero if need to send AMI ContactStatus event when a contact is updated.
3329 */
3331
3332
3333/*!
3334 * \brief Truncate the URI user field options string if enabled.
3335 * \since 13.12.0
3336 *
3337 * \param str URI user field string to truncate if enabled
3338 *
3339 * \details
3340 * We need to be able to handle URI's looking like
3341 * "sip:1235557890;phone-context=national@x.x.x.x;user=phone"
3342 *
3343 * Where the URI user field is:
3344 * "1235557890;phone-context=national"
3345 *
3346 * When truncated the string will become:
3347 * "1235557890"
3348 */
3349#define AST_SIP_USER_OPTIONS_TRUNCATE_CHECK(str) \
3350 do { \
3351 char *__semi = strchr((str), ';'); \
3352 if (__semi && ast_sip_get_ignore_uri_user_options()) { \
3353 *__semi = '\0'; \
3354 } \
3355 } while (0)
3356
3357/*!
3358 * \brief Retrieve the system debug setting (yes|no|host).
3359 *
3360 * \note returned string needs to be de-allocated by caller.
3361 *
3362 * \retval the system debug setting.
3363 */
3364char *ast_sip_get_debug(void);
3365
3366/*!
3367 * \brief Retrieve the global regcontext setting.
3368 *
3369 * \since 13.8.0
3370 *
3371 * \note returned string needs to be de-allocated by caller.
3372 *
3373 * \retval the global regcontext setting
3374 */
3375char *ast_sip_get_regcontext(void);
3376
3377/*!
3378 * \brief Retrieve the global endpoint_identifier_order setting.
3379 *
3380 * Specifies the order by which endpoint identifiers should be regarded.
3381 *
3382 * \retval the global endpoint_identifier_order value
3383 */
3385
3386/*!
3387 * \brief Retrieve the default voicemail extension.
3388 * \since 13.9.0
3389 *
3390 * \note returned string needs to be de-allocated by caller.
3391 *
3392 * \retval the default voicemail extension
3393 */
3395
3396/*!
3397 * \brief Retrieve the global default realm.
3398 *
3399 * This is the value placed in outbound challenges' realm if there
3400 * is no better option (such as an auth-configured realm).
3401 *
3402 * \param[out] realm The default realm
3403 * \param size The buffer size of realm
3404 */
3405void ast_sip_get_default_realm(char *realm, size_t size);
3406
3407/*!
3408 * \brief Retrieve the global default from user.
3409 *
3410 * This is the value placed in outbound requests' From header if there
3411 * is no better option (such as an endpoint-configured from_user or
3412 * caller ID number).
3413 *
3414 * \param[out] from_user The default from user
3415 * \param size The buffer size of from_user
3416 */
3417void ast_sip_get_default_from_user(char *from_user, size_t size);
3418
3419/*!
3420 * \brief Retrieve the system keep alive interval setting.
3421 *
3422 * \retval the keep alive interval.
3423 */
3424unsigned int ast_sip_get_keep_alive_interval(void);
3425
3426/*!
3427 * \brief Retrieve the system contact expiration check interval setting.
3428 *
3429 * \retval the contact expiration check interval.
3430 */
3432
3433/*!
3434 * \brief Retrieve the system setting 'disable multi domain'.
3435 * \since 13.9.0
3436 *
3437 * \retval non zero if disable multi domain.
3438 */
3439unsigned int ast_sip_get_disable_multi_domain(void);
3440
3441/*!
3442 * \brief Retrieve the system max initial qualify time.
3443 *
3444 * \retval the maximum initial qualify time.
3445 */
3446unsigned int ast_sip_get_max_initial_qualify_time(void);
3447
3448/*!
3449 * \brief translate ast_sip_contact_status_type to character string.
3450 *
3451 * \retval the character string equivalent.
3452 */
3453
3456
3457/*!
3458 * \brief Set a request to use the next value in the list of resolved addresses.
3459 *
3460 * \param tdata the tx data from the original request
3461 * \retval 0 No more addresses to try
3462 * \retval 1 The request was successfully re-intialized
3463 */
3464int ast_sip_failover_request(pjsip_tx_data *tdata);
3465
3466/*!
3467 * \brief Retrieve the local host address in IP form
3468 *
3469 * \param af The address family to retrieve
3470 * \param addr A place to store the local host address
3471 *
3472 * \retval 0 success
3473 * \retval -1 failure
3474 *
3475 * \since 13.6.0
3476 */
3477int ast_sip_get_host_ip(int af, pj_sockaddr *addr);
3478
3479/*!
3480 * \brief Retrieve the local host address in string form
3481 *
3482 * \param af The address family to retrieve
3483 *
3484 * \retval non-NULL success
3485 * \retval NULL failure
3486 *
3487 * \since 13.6.0
3488 *
3489 * \note An empty string may be returned if the address family is valid but no local address exists
3490 */
3491const char *ast_sip_get_host_ip_string(int af);
3492
3493/*!
3494 * \brief Return the size of the SIP threadpool's task queue
3495 * \since 13.7.0
3496 */
3498
3499/*!
3500 * \brief Retrieve the SIP threadpool object
3501 */
3503
3504/*!
3505 * \brief Retrieve transport state
3506 * \since 13.7.1
3507 *
3508 * \param transport_id
3509 * \retval transport_state
3510 *
3511 * \note ao2_cleanup(...) or ao2_ref(..., -1) must be called on the returned object
3512 */
3513struct ast_sip_transport_state *ast_sip_get_transport_state(const char *transport_id);
3514
3515/*!
3516 * \brief Return the SIP URI of the Contact header
3517 *
3518 * \param tdata
3519 * \retval Pointer to SIP URI of Contact
3520 * \retval NULL if Contact header not found or not a SIP(S) URI
3521 *
3522 * \note Do not free the returned object.
3523 */
3524pjsip_sip_uri *ast_sip_get_contact_sip_uri(pjsip_tx_data *tdata);
3525
3526/*!
3527 * \brief Returns the transport state currently in use based on request transport details
3528 *
3529 * \param details
3530 * \retval transport_state
3531 *
3532 * \note ao2_cleanup(...) or ao2_ref(..., -1) must be called on the returned object
3533 */
3535
3536/*!
3537 * \brief Sets request transport details based on tdata
3538 *
3539 * \param details pre-allocated request transport details to set
3540 * \param tdata
3541 * \param use_ipv6 if non-zero, ipv6 transports will be considered
3542 * \retval 0 success
3543 * \retval -1 failure
3544 */
3545int ast_sip_set_request_transport_details(struct ast_sip_request_transport_details *details, pjsip_tx_data *tdata, int use_ipv6);
3546
3547/*!
3548 * \brief Replace domain and port of SIP URI to point to (external) signaling address of this Asterisk instance
3549 *
3550 * \param uri
3551 * \param tdata
3552 *
3553 * \retval 0 success
3554 * \retval -1 failure
3555 *
3556 * \note Uses domain and port in Contact header if it exists, otherwise the local URI of the dialog is used if the
3557 * message is sent within the context of a dialog. Further, NAT settings are considered - i.e. if the target
3558 * is not in the localnet, the external_signaling_address and port are used.
3559 */
3560int ast_sip_rewrite_uri_to_local(pjsip_sip_uri *uri, pjsip_tx_data *tdata);
3561
3562/*!
3563 * \brief Retrieves all transport states
3564 * \since 13.7.1
3565 *
3566 * \retval ao2_container
3567 *
3568 * \note ao2_cleanup(...) or ao2_ref(..., -1) must be called on the returned object
3569 */
3571
3572/*!
3573 * \brief Sets pjsip_tpselector from ast_sip_transport
3574 * \since 13.8.0
3575 *
3576 * \param transport The transport to be used
3577 * \param selector The selector to be populated
3578 * \retval 0 success
3579 * \retval -1 failure
3580 *
3581 * \note The transport selector must be unreffed using ast_sip_tpselector_unref
3582 */
3583int ast_sip_set_tpselector_from_transport(const struct ast_sip_transport *transport, pjsip_tpselector *selector);
3584
3585/*!
3586 * \brief Sets pjsip_tpselector from ast_sip_transport
3587 * \since 13.8.0
3588 *
3589 * \param transport_name The name of the transport to be used
3590 * \param selector The selector to be populated
3591 * \retval 0 success
3592 * \retval -1 failure
3593 *
3594 * \note The transport selector must be unreffed using ast_sip_tpselector_unref
3595 */
3596int ast_sip_set_tpselector_from_transport_name(const char *transport_name, pjsip_tpselector *selector);
3597
3598/*!
3599 * \brief Unreference a pjsip_tpselector
3600 * \since 17.0.0
3601 *
3602 * \param selector The selector to be unreffed
3603 */
3604void ast_sip_tpselector_unref(pjsip_tpselector *selector);
3605
3606/*!
3607 * \brief Sets the PJSIP transport on a child transport
3608 * \since 17.0.0
3609 *
3610 * \param transport_name The name of the transport to be updated
3611 * \param transport The PJSIP transport
3612 * \retval 0 success
3613 * \retval -1 failure
3614 */
3615int ast_sip_transport_state_set_transport(const char *transport_name, pjsip_transport *transport);
3616
3617/*!
3618 * \brief Sets the P-Preferred-Identity on a child transport
3619 * \since 17.0.0
3620 *
3621 * \param transport_name The name of the transport to be set on
3622 * \param identity The P-Preferred-Identity to use on requests on this transport
3623 * \retval 0 success
3624 * \retval -1 failure
3625 */
3626int ast_sip_transport_state_set_preferred_identity(const char *transport_name, const char *identity);
3627
3628/*!
3629 * \brief Sets the service routes on a child transport
3630 * \since 17.0.0
3631 *
3632 * \param transport_name The name of the transport to be set on
3633 * \param service_routes A vector of service routes
3634 * \retval 0 success
3635 * \retval -1 failure
3636 *
3637 * \note This assumes ownership of the service routes in both success and failure scenarios
3638 */
3639int ast_sip_transport_state_set_service_routes(const char *transport_name, struct ast_sip_service_route_vector *service_routes);
3640
3641/*!
3642 * \brief Apply the configuration for a transport to an outgoing message
3643 * \since 17.0.0
3644 *
3645 * \param transport_name The name of the transport to apply configuration from
3646 * \param tdata The SIP message
3647 */
3648void ast_sip_message_apply_transport(const char *transport_name, pjsip_tx_data *tdata);
3649
3650/*!
3651 * \brief Allocate a vector of service routes
3652 * \since 17.0.0
3653 *
3654 * \retval non-NULL success
3655 * \retval NULL failure
3656 */
3658
3659/*!
3660 * \brief Destroy a vector of service routes
3661 * \since 17.0.0
3662 *
3663 * \param service_routes A vector of service routes
3664 */
3666
3667/*!
3668 * \brief Set the ID for a connected line update
3669 *
3670 * \retval -1 on failure, 0 on success
3671 */
3672int ast_sip_set_id_connected_line(struct pjsip_rx_data *rdata, struct ast_party_id *id);
3673
3674/*!
3675 * \brief Set the ID from an INVITE
3676 *
3677 * \param rdata
3678 * \param id ID structure to fill
3679 * \param default_id Default ID structure with data to use (for non-trusted endpoints)
3680 * \param trust_inbound Whether or not the endpoint is trusted (controls whether PAI or RPID can be used)
3681 *
3682 * \retval -1 on failure, 0 on success
3683 */
3684int ast_sip_set_id_from_invite(struct pjsip_rx_data *rdata, struct ast_party_id *id, struct ast_party_id *default_id, int trust_inbound);
3685
3686/*!
3687 * \brief Set name and number information on an identity header.
3688 *
3689 * \param pool Memory pool to use for string duplication
3690 * \param id_hdr A From, P-Asserted-Identity, or Remote-Party-ID header to modify
3691 * \param id The identity information to apply to the header
3692 */
3693void ast_sip_modify_id_header(pj_pool_t *pool, pjsip_fromto_hdr *id_hdr,
3694 const struct ast_party_id *id);
3695
3696/*!
3697 * \brief Retrieves an endpoint and URI from the "to" string.
3698 *
3699 * This URI is used as the Request URI.
3700 *
3701 * Expects the given 'to' to be in one of the following formats:
3702 * Why we allow so many is a mystery.
3703 *
3704 * Basic:
3705 *
3706 * endpoint : We'll get URI from the default aor/contact
3707 * endpoint/aor : We'll get the URI from the specific aor/contact
3708 * endpoint@domain : We toss the domain part and just use the endpoint
3709 *
3710 * These all use the endpoint and specified URI:
3711 * \verbatim
3712 endpoint/<sip[s]:host>
3713 endpoint/<sip[s]:user@host>
3714 endpoint/"Bob" <sip[s]:host>
3715 endpoint/"Bob" <sip[s]:user@host>
3716 endpoint/sip[s]:host
3717 endpoint/sip[s]:user@host
3718 endpoint/host
3719 endpoint/user@host
3720 \endverbatim
3721 *
3722 * These all use the default endpoint and specified URI:
3723 * \verbatim
3724 <sip[s]:host>
3725 <sip[s]:user@host>
3726 "Bob" <sip[s]:host>
3727 "Bob" <sip[s]:user@host>
3728 sip[s]:host
3729 sip[s]:user@host
3730 \endverbatim
3731 *
3732 * These use the default endpoint and specified host:
3733 * \verbatim
3734 host
3735 user@host
3736 \endverbatim
3737 *
3738 * This form is similar to a dialstring:
3739 * \verbatim
3740 PJSIP/user@endpoint
3741 \endverbatim
3742 *
3743 * In this case, the user will be added to the endpoint contact's URI.
3744 * If the contact URI already has a user, it will be replaced.
3745 *
3746 * The ones that have the sip[s] scheme are the easiest to parse.
3747 * The rest all have some issue.
3748 *
3749 * endpoint vs host : We have to test for endpoint first
3750 * endpoint/aor vs endpoint/host : We have to test for aor first
3751 * What if there's an aor with the same
3752 * name as the host?
3753 * endpoint@domain vs user@host : We have to test for endpoint first.
3754 * What if there's an endpoint with the
3755 * same name as the user?
3756 *
3757 * \param to 'To' field with possible endpoint
3758 * \param get_default_outbound If nonzero, try to retrieve the default
3759 * outbound endpoint if no endpoint was found.
3760 * Otherwise, return NULL if no endpoint was found.
3761 * \param uri Pointer to a char* which will be set to the URI.
3762 * Always must be ast_free'd by the caller - even if the return value is NULL!
3763 *
3764 * \note The logic below could probably be condensed but then it wouldn't be
3765 * as clear.
3766 */
3767struct ast_sip_endpoint *ast_sip_get_endpoint(const char *to, int get_default_outbound, char **uri);
3768
3769/*!
3770 * \brief Replace the To URI in the tdata with the supplied one
3771 *
3772 * \param tdata the outbound message data structure
3773 * \param to URI to replace the To URI with. Must be a valid SIP URI.
3774 *
3775 * \retval 0: success, -1: failure
3776 */
3777int ast_sip_update_to_uri(pjsip_tx_data *tdata, const char *to);
3778
3779/*!
3780 * \brief Overwrite fields in the outbound 'From' header
3781 *
3782 * The outbound 'From' header is created/added in ast_sip_create_request with
3783 * default data. If available that data may be info specified in the 'from_user'
3784 * and 'from_domain' options found on the endpoint. That information will be
3785 * overwritten with data in the given 'from' parameter.
3786 *
3787 * \param tdata the outbound message data structure
3788 * \param from info to copy into the header.
3789 * Can be either a SIP URI, or in the format user[@domain]
3790 *
3791 * \retval 0: success, -1: failure
3792 */
3793int ast_sip_update_from(pjsip_tx_data *tdata, char *from);
3794
3795/*!
3796 * \brief Retrieve the unidentified request security event thresholds
3797 * \since 13.8.0
3798 *
3799 * \param count The maximum number of unidentified requests per source ip to accumulate before emitting a security event
3800 * \param period The period in seconds over which to accumulate unidentified requests
3801 * \param prune_interval The interval in seconds at which expired entries will be pruned
3802 */
3803void ast_sip_get_unidentified_request_thresholds(unsigned int *count, unsigned int *period,
3804 unsigned int *prune_interval);
3805
3806/*!
3807 * \brief Get the transport name from an endpoint or request uri
3808 * \since 13.15.0
3809 *
3810 * \param endpoint
3811 * \param sip_uri
3812 * \param buf Buffer to receive transport name
3813 * \param buf_len Buffer length
3814 *
3815 * \retval 0 Success
3816 * \retval -1 Failure
3817 *
3818 * \note
3819 * If endpoint->transport is not NULL, it is returned in buf.
3820 * Otherwise if sip_uri has an 'x-ast-txp' parameter AND the sip_uri host is
3821 * an ip4 or ip6 address, its value is returned,
3822 */
3823int ast_sip_get_transport_name(const struct ast_sip_endpoint *endpoint,
3824 pjsip_sip_uri *sip_uri, char *buf, size_t buf_len);
3825
3826/*!
3827 * \brief Sets pjsip_tpselector from an endpoint or uri
3828 * \since 13.15.0
3829 *
3830 * \param endpoint If endpoint->transport is set, it's used
3831 * \param sip_uri If sip_uri contains a x-ast-txp parameter, it's used
3832 * \param selector The selector to be populated
3833 *
3834 * \retval 0 success
3835 * \retval -1 failure
3836 */
3838 pjsip_sip_uri *sip_uri, pjsip_tpselector *selector);
3839
3840/*!
3841 * \brief Set the transport on a dialog
3842 * \since 13.15.0
3843 *
3844 * \param endpoint
3845 * \param dlg
3846 * \param selector (optional)
3847 *
3848 * \note
3849 * This API calls ast_sip_get_transport_name(endpoint, dlg->target) and if the result is
3850 * non-NULL, calls pjsip_dlg_set_transport. If 'selector' is non-NULL, it is updated with
3851 * the selector used.
3852 *
3853 * \note
3854 * It is the responsibility of the caller to unref the passed in selector if one is provided.
3855 */
3856int ast_sip_dlg_set_transport(const struct ast_sip_endpoint *endpoint, pjsip_dialog *dlg,
3857 pjsip_tpselector *selector);
3858
3859/*!
3860 * \brief Convert the DTMF mode enum value into a string
3861 * \since 13.18.0
3862 *
3863 * \param dtmf the dtmf mode
3864 * \param buf Buffer to receive dtmf mode string
3865 * \param buf_len Buffer length
3866 *
3867 * \retval 0 Success
3868 * \retval -1 Failure
3869 *
3870 */
3872 char *buf, size_t buf_len);
3873
3874/*!
3875 * \brief Convert the DTMF mode name into an enum
3876 * \since 13.18.0
3877 *
3878 * \param dtmf_mode dtmf mode as a string
3879 *
3880 * \retval >= 0 The enum value
3881 * \retval -1 Failure
3882 *
3883 */
3884int ast_sip_str_to_dtmf(const char *dtmf_mode);
3885
3886/*!
3887 * \brief Convert the call codec preference flags to a string
3888 * \since 18.0.0
3889 *
3890 * \param pref the call codec preference setting
3891 *
3892 * \returns a constant string with either the setting value or 'unknown'
3893 * \note Don't try to free the string!
3894 *
3895 */
3896const char *ast_sip_call_codec_pref_to_str(struct ast_flags pref);
3897
3898/*!
3899 * \brief Convert a call codec preference string to preference flags
3900 * \since 18.0.0
3901 *
3902 * \param pref A pointer to an ast_flags structure to receive the preference flags
3903 * \param pref_str The call codec preference setting string
3904 * \param is_outgoing Is for outgoing calls?
3905 *
3906 * \retval 0 The string was parsed successfully
3907 * \retval -1 The string option was invalid
3908 */
3909int ast_sip_call_codec_str_to_pref(struct ast_flags *pref, const char *pref_str, int is_outgoing);
3910
3911/*!
3912 * \brief Transport shutdown monitor callback.
3913 * \since 13.18.0
3914 *
3915 * \param data User data to know what to do when transport shuts down.
3916 *
3917 * \note The callback does not need to care that data is an ao2 object.
3918 */
3919typedef void (*ast_transport_monitor_shutdown_cb)(void *data);
3920
3921/*!
3922 * \brief Transport shutdown monitor data matcher
3923 * \since 13.20.0
3924 *
3925 * \param a User data to compare.
3926 * \param b User data to compare.
3927 *
3928 * \retval 1 The data objects match
3929 * \retval 0 The data objects don't match
3930 */
3931typedef int (*ast_transport_monitor_data_matcher)(void *a, void *b);
3932
3934 /*! \brief Successfully registered the transport monitor */
3936 /*! \brief Replaced the already existing transport monitor with new one. */
3938 /*!
3939 * \brief Transport not found to monitor.
3940 * \note Transport is either already shutdown or is not reliable.
3941 */
3943 /*! \brief Error while registering transport monitor. */
3945};
3946
3947/*!
3948 * \brief Register a reliable transport shutdown monitor callback.
3949 * \deprecated Replaced with ast_sip_transport_monitor_register_key().
3950 * \since 13.20.0
3951 *
3952 * \param transport Transport to monitor for shutdown.
3953 * \param cb Who to call when transport is shutdown.
3954 * \param ao2_data Data to pass with the callback.
3955 *
3956 * \note The data object passed will have its reference count automatically
3957 * incremented by this call and automatically decremented after the callback
3958 * runs or when the callback is unregistered.
3959 *
3960 * There is no checking for duplicate registrations.
3961 *
3962 * \return enum ast_transport_monitor_reg
3963 */
3965 ast_transport_monitor_shutdown_cb cb, void *ao2_data);
3966
3967/*!
3968 * \brief Register a reliable transport shutdown monitor callback.
3969 *
3970 * \param transport_key Key for the transport to monitor for shutdown.
3971 * Create the key with AST_SIP_MAKE_REMOTE_IPADDR_PORT_STR.
3972 * \param cb Who to call when transport is shutdown.
3973 * \param ao2_data Data to pass with the callback.
3974 *
3975 * \note The data object passed will have its reference count automatically
3976 * incremented by this call and automatically decremented after the callback
3977 * runs or when the callback is unregistered.
3978 *
3979 * There is no checking for duplicate registrations.
3980 *
3981 * \return enum ast_transport_monitor_reg
3982 */
3984 const char *transport_key, ast_transport_monitor_shutdown_cb cb,
3985 void *ao2_data);
3986
3987/*!
3988 * \brief Register a reliable transport shutdown monitor callback replacing any duplicate.
3989 * \deprecated Replaced with ast_sip_transport_monitor_register_replace_key().
3990 * \since 13.26.0
3991 * \since 16.3.0
3992 *
3993 * \param transport Transport to monitor for shutdown.
3994 * \param cb Who to call when transport is shutdown.
3995 * \param ao2_data Data to pass with the callback.
3996 * \param matches Matcher function that returns true if data matches a previously
3997 * registered data object
3998 *
3999 * \note The data object passed will have its reference count automatically
4000 * incremented by this call and automatically decremented after the callback
4001 * runs or when the callback is unregistered.
4002 *
4003 * This function checks for duplicates, and overwrites/replaces the old monitor
4004 * with the given one.
4005 *
4006 * \return enum ast_transport_monitor_reg
4007 */
4010
4011/*!
4012 * \brief Register a reliable transport shutdown monitor callback replacing any duplicate.
4013 *
4014 * \param transport_key Key for the transport to monitor for shutdown.
4015 * Create the key with AST_SIP_MAKE_REMOTE_IPADDR_PORT_STR.
4016 * \param cb Who to call when transport is shutdown.
4017 * \param ao2_data Data to pass with the callback.
4018 * \param matches Matcher function that returns true if data matches a previously
4019 * registered data object
4020 *
4021 * \note The data object passed will have its reference count automatically
4022 * incremented by this call and automatically decremented after the callback
4023 * runs or when the callback is unregistered.
4024 *
4025 * This function checks for duplicates, and overwrites/replaces the old monitor
4026 * with the given one.
4027 *
4028 * \return enum ast_transport_monitor_reg
4029 */
4031 const char *transport_key, ast_transport_monitor_shutdown_cb cb,
4032 void *ao2_data, ast_transport_monitor_data_matcher matches);
4033
4034/*!
4035 * \brief Unregister a reliable transport shutdown monitor
4036 * \deprecated Replaced with ast_sip_transport_monitor_unregister_key().
4037 * \since 13.20.0
4038 *
4039 * \param transport Transport to monitor for shutdown.
4040 * \param cb The callback that was used for the original register.
4041 * \param data Data to pass to the matcher. May be NULL and does NOT need to be an ao2 object.
4042 * If NULL, all monitors with the provided callback are unregistered.
4043 * \param matches Matcher function that returns true if data matches the previously
4044 * registered data object. If NULL, a simple pointer comparison is done.
4045 *
4046 * \note The data object passed into the original register will have its reference count
4047 * automatically decremented.
4048 */
4051
4052/*!
4053 * \brief Unregister a reliable transport shutdown monitor
4054 *
4055 * \param transport_key Key for the transport to monitor for shutdown.
4056 * Create the key with AST_SIP_MAKE_REMOTE_IPADDR_PORT_STR.
4057 * \param cb The callback that was used for the original register.
4058 * \param data Data to pass to the matcher. May be NULL and does NOT need to be an ao2 object.
4059 * If NULL, all monitors with the provided callback are unregistered.
4060 * \param matches Matcher function that returns true if data matches the previously
4061 * registered data object. If NULL, a simple pointer comparison is done.
4062 *
4063 * \note The data object passed into the original register will have its reference count
4064 * automatically decremented.
4065 */
4066void ast_sip_transport_monitor_unregister_key(const char *transport_key,
4068
4069/*!
4070 * \brief Unregister a transport shutdown monitor from all reliable transports
4071 * \since 13.20.0
4072 *
4073 * \param cb The callback that was used for the original register.
4074 * \param data Data to pass to the matcher. May be NULL and does NOT need to be an ao2 object.
4075 * If NULL, all monitors with the provided callback are unregistered.
4076 * \param matches Matcher function that returns true if ao2_data matches the previously
4077 * registered data object. If NULL, a simple pointer comparison is done.
4078 *
4079 * \note The data object passed into the original register will have its reference count
4080 * automatically decremented.
4081 */
4083 void *data, ast_transport_monitor_data_matcher matches);
4084
4085/*! Transport state notification registration element. */
4087 /*! PJPROJECT transport state notification callback */
4088 pjsip_tp_state_callback cb;
4090};
4091
4092/*!
4093 * \brief Register a transport state notification callback element.
4094 * \since 13.18.0
4095 *
4096 * \param element What we are registering.
4097 */
4099
4100/*!
4101 * \brief Unregister a transport state notification callback element.
4102 * \since 13.18.0
4103 *
4104 * \param element What we are unregistering.
4105 */
4107
4108/*!
4109 * \brief Check whether a pjsip_uri is SIP/SIPS or not
4110 * \since 16.28.0
4111 *
4112 * \param uri The pjsip_uri to check
4113 *
4114 * \retval 1 if true
4115 * \retval 0 if false
4116 */
4117int ast_sip_is_uri_sip_sips(pjsip_uri *uri);
4118
4119/*!
4120 * \brief Check whether a pjsip_uri is allowed or not
4121 * \since 16.28.0
4122 *
4123 * \param uri The pjsip_uri to check
4124 *
4125 * \retval 1 if allowed
4126 * \retval 0 if not allowed
4127 */
4128int ast_sip_is_allowed_uri(pjsip_uri *uri);
4129
4130/*!
4131 * \brief Get the user portion of the pjsip_uri
4132 * \since 16.28.0
4133 *
4134 * \param uri The pjsip_uri to get the user from
4135 *
4136 * \note This function will check what kind of URI it receives and return
4137 * the user based off of that
4138 *
4139 * \return User string or empty string if not present
4140 */
4141const pj_str_t *ast_sip_pjsip_uri_get_username(pjsip_uri *uri);
4142
4143/*!
4144 * \brief Get the host portion of the pjsip_uri
4145 * \since 16.28.0
4146 *
4147 * \param uri The pjsip_uri to get the host from
4148 *
4149 * \note This function will check what kind of URI it receives and return
4150 * the host based off of that
4151 *
4152 * \return Host string or empty string if not present
4153 */
4154const pj_str_t *ast_sip_pjsip_uri_get_hostname(pjsip_uri *uri);
4155
4156/*!
4157 * \brief Find an 'other' SIP/SIPS URI parameter by name
4158 * \since 16.28.0
4159 *
4160 * A convenience function to find a named parameter from a SIP/SIPS URI. This
4161 * function will not find the following standard SIP/SIPS URI parameters which
4162 * are stored separately by PJSIP:
4163 *
4164 * \li `user`
4165 * \li `method`
4166 * \li `transport`
4167 * \li `ttl`
4168 * \li `lr`
4169 * \li `maddr`
4170 *
4171 * \param uri The pjsip_uri to get the parameter from
4172 * \param param_str The name of the parameter to find
4173 *
4174 * \note This function will check what kind of URI it receives and return
4175 * the parameter based off of that
4176 *
4177 * \return Find parameter or NULL if not present
4178 */
4179struct pjsip_param *ast_sip_pjsip_uri_get_other_param(pjsip_uri *uri, const pj_str_t *param_str);
4180
4181/*!
4182 * \brief Retrieve the system setting 'all_codecs_on_empty_reinvite'.
4183 *
4184 * \retval non zero if we should return all codecs on empty re-INVITE
4185 */
4187
4188
4189/*!
4190 * \brief Convert SIP hangup causes to Asterisk hangup causes
4191 *
4192 * \param cause SIP cause
4193 *
4194 * \retval matched cause code from causes.h
4195 */
4196const int ast_sip_hangup_sip2cause(int cause);
4197
4198/*!
4199 * \brief Convert name to SIP response code
4200 *
4201 * \param name SIP response code name matching one of the
4202 * enum names defined in "enum pjsip_status_code"
4203 * defined in sip_msg.h. May be specified with or
4204 * without the PJSIP_SC_ prefix.
4205 *
4206 * \retval SIP response code
4207 * \retval -1 if matching code not found
4208 */
4209int ast_sip_str2rc(const char *name);
4210
4211#endif /* _RES_PJSIP_H */
jack_status_t status
Definition: app_jack.c:146
const char * str
Definition: app_jack.c:147
int() ao2_callback_fn(void *obj, void *arg, int flags)
Type of a generic callback function.
Definition: astobj2.h:1226
static const char type[]
Definition: chan_ooh323.c:109
General Asterisk PBX channel definitions.
unsigned long long ast_group_t
Definition: channel.h:213
#define AST_MAX_CONTEXT
Definition: channel.h:135
#define attribute_sentinel
Definition: compiler.h:65
Background DNS update manager.
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
Endpoint abstractions.
ast_endpoint_state
Valid states for an endpoint.
Definition: endpoints.h:51
char * address
Definition: f2c.h:59
static const char name[]
Definition: format_mp3.c:68
static int replace(struct ast_channel *chan, const char *cmd, char *data, struct ast_str **buf, ssize_t len)
Definition: func_strings.c:888
static int array(struct ast_channel *chan, const char *cmd, char *var, const char *value)
struct ast_sip_endpoint * ast_sip_dialog_get_endpoint(pjsip_dialog *dlg)
Get the endpoint associated with this dialog.
int(* ast_sip_task)(void *user_data)
Definition: res_pjsip.h:1868
int ast_sip_sched_task_get_times2(struct ast_sip_sched_task *schtd, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end, int *interval, int *time_left, struct timeval *next_start)
Gets the queued, last start, last_end, time left, interval, next run.
struct ast_taskprocessor * ast_sip_get_distributor_serializer(pjsip_rx_data *rdata)
Determine the distributor serializer for the SIP message.
ast_sip_scheduler_task_flags
Task flags for the res_pjsip scheduler.
Definition: res_pjsip.h:2062
int ast_sip_sched_task_cancel_by_name(const char *name)
Cancels the next invocation of a task by name.
int ast_sip_push_task(struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
Pushes a task to SIP servants.
Definition: res_pjsip.c:2099
struct ast_taskprocessor * ast_sip_create_serializer(const char *name)
Create a new serializer for SIP tasks.
Definition: res_pjsip.c:2094
struct ast_taskprocessor * ast_sip_create_serializer_group(const char *name, struct ast_serializer_shutdown_group *shutdown_group)
Create a new serializer for SIP tasks.
Definition: res_pjsip.c:2089
struct ast_sip_sched_task * ast_sip_schedule_task(struct ast_taskprocessor *serializer, int interval, ast_sip_task sip_task, const char *name, void *task_data, enum ast_sip_scheduler_task_flags flags)
Schedule a task to run in the res_pjsip thread pool.
void ast_sip_dialog_set_endpoint(pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint)
Set an endpoint on a SIP dialog so in-dialog requests do not undergo endpoint lookup.
int ast_sip_sched_task_cancel(struct ast_sip_sched_task *schtd)
Cancels the next invocation of a task.
int ast_sip_sched_is_task_running(struct ast_sip_sched_task *schtd)
Checks if the task is currently running.
int ast_sip_thread_is_servant(void)
Determine if the current thread is a SIP servant thread.
Definition: res_pjsip.c:2310
int ast_sip_sched_task_get_name(struct ast_sip_sched_task *schtd, char *name, size_t maxlen)
Gets the task name.
int ast_sip_sched_task_get_next_run(struct ast_sip_sched_task *schtd)
Gets the number of milliseconds until the next invocation.
void ast_sip_dialog_set_serializer(pjsip_dialog *dlg, struct ast_taskprocessor *serializer)
Set a serializer on a SIP dialog so requests and responses are automatically serialized.
int ast_sip_push_task_synchronous(struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
Push a task to SIP servants and wait for it to complete.
Definition: res_pjsip.c:2174
int ast_sip_sched_task_get_times(struct ast_sip_sched_task *schtd, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end)
Gets the last start and end times of the task.
int ast_sip_push_task_wait_servant(struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
Push a task to SIP servants and wait for it to complete.
Definition: res_pjsip.c:2165
int ast_sip_sched_task_get_next_run_by_name(const char *name)
Gets the number of milliseconds until the next invocation.
int ast_sip_push_task_wait_serializer(struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
Push a task to the serializer and wait for it to complete.
Definition: res_pjsip.c:2179
int ast_sip_sched_is_task_running_by_name(const char *name)
Checks if the task is currently running.
int ast_sip_sched_task_get_times_by_name2(const char *name, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end, int *interval, int *time_left, struct timeval *next_start)
Gets the queued, last start, last_end, time left, interval, next run by task name.
int ast_sip_sched_task_get_times_by_name(const char *name, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end)
Gets the last start and end times of the task by name.
@ AST_SIP_SCHED_TASK_ONESHOT
Definition: res_pjsip.h:2085
@ AST_SIP_SCHED_TASK_DELAY
The next invocation of the task is at last finish + interval.
Definition: res_pjsip.h:2117
@ AST_SIP_SCHED_TASK_TRACK
The scheduled task's events are tracked in the debug log.
Definition: res_pjsip.h:2124
@ AST_SIP_SCHED_TASK_DATA_NOT_AO2
Definition: res_pjsip.h:2090
@ AST_SIP_SCHED_TASK_DEFAULTS
Definition: res_pjsip.h:2066
@ AST_SIP_SCHED_TASK_FIXED
Definition: res_pjsip.h:2073
@ AST_SIP_SCHED_TASK_PERIODIC
The task is scheduled at multiples of interval.
Definition: res_pjsip.h:2112
@ AST_SIP_SCHED_TASK_DATA_AO2
Definition: res_pjsip.h:2096
@ AST_SIP_SCHED_TASK_DATA_FREE
Definition: res_pjsip.h:2106
@ AST_SIP_SCHED_TASK_DATA_NO_CLEANUP
Definition: res_pjsip.h:2101
@ AST_SIP_SCHED_TASK_VARIABLE
Definition: res_pjsip.h:2079
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
#define AST_RWLIST_ENTRY
Definition: linkedlists.h:415
Network socket handling.
ast_transport
Definition: netsock2.h:59
static struct ast_serializer_shutdown_group * shutdown_group
Shutdown group for options serializers.
const char * method
Definition: res_pjsip.c:1279
ast_sip_security_mechanism_type
The security mechanism type.
Definition: res_pjsip.h:364
@ AST_SIP_SECURITY_MECH_DTLS_SRTP
Definition: res_pjsip.h:371
@ AST_SIP_SECURITY_MECH_SDES_SRTP
Definition: res_pjsip.h:369
@ AST_SIP_SECURITY_MECH_MSRP_TLS
Definition: res_pjsip.h:367
@ AST_SIP_SECURITY_MECH_NONE
Definition: res_pjsip.h:365
struct ast_sip_auth * ast_sip_get_artificial_auth(void)
Retrieves a reference to the artificial auth.
int ast_sip_dialog_setup_outbound_authentication(pjsip_dialog *dlg, const struct ast_sip_endpoint *endpoint, ast_sip_dialog_outbound_auth_cb cb, void *user_data)
Set up outbound authentication on a SIP dialog.
void ast_sip_unregister_supplement(struct ast_sip_supplement *supplement)
Unregister a an supplement to SIP out of dialog processing.
Definition: res_pjsip.c:1476
struct ast_sip_endpoint * ast_sip_get_endpoint(const char *to, int get_default_outbound, char **uri)
Retrieves an endpoint and URI from the "to" string.
Definition: res_pjsip.c:3249
void ast_sip_add_usereqphone(const struct ast_sip_endpoint *endpoint, pj_pool_t *pool, pjsip_uri *uri)
Add 'user=phone' parameter to URI if enabled and user is a phone number.
Definition: res_pjsip.c:930
unsigned int ast_sip_get_norefersub(void)
Retrieve the global setting 'norefersub'.
struct pjsip_param * ast_sip_pjsip_uri_get_other_param(pjsip_uri *uri, const pj_str_t *param_str)
Find an 'other' SIP/SIPS URI parameter by name.
Definition: res_pjsip.c:3511
const pj_str_t * ast_sip_pjsip_uri_get_username(pjsip_uri *uri)
Get the user portion of the pjsip_uri.
Definition: res_pjsip.c:3477
void ast_sip_header_to_security_mechanism(const pjsip_generic_string_hdr *hdr, struct ast_sip_security_mechanism_vector *security_mechanisms)
Append to security mechanism vector from SIP header.
unsigned int ast_sip_get_max_initial_qualify_time(void)
Retrieve the system max initial qualify time.
unsigned int ast_sip_get_keep_alive_interval(void)
Retrieve the system keep alive interval setting.
void ast_sip_persistent_endpoint_publish_contact_state(const char *endpoint_name, const struct ast_sip_contact_status *contact_status)
Publish the change of state for a contact.
int ast_sip_set_security_negotiation(enum ast_sip_security_negotiation *security_negotiation, const char *val)
Set the security negotiation based on a given string.
void ast_sip_unregister_service(pjsip_module *module)
Definition: res_pjsip.c:133
unsigned int ast_sip_get_allow_sending_180_after_183(void)
Retrieve the global setting 'allow_sending_180_after_183'.
ast_sip_endpoint_identifier_type
Different methods by which incoming requests can be matched to endpoints.
Definition: res_pjsip.h:609
@ AST_SIP_ENDPOINT_IDENTIFY_BY_HEADER
Definition: res_pjsip.h:617
@ AST_SIP_ENDPOINT_IDENTIFY_BY_USERNAME
Definition: res_pjsip.h:611
@ AST_SIP_ENDPOINT_IDENTIFY_BY_REQUEST_URI
Definition: res_pjsip.h:619
@ AST_SIP_ENDPOINT_IDENTIFY_BY_IP
Definition: res_pjsip.h:615
@ AST_SIP_ENDPOINT_IDENTIFY_BY_AUTH_USERNAME
Definition: res_pjsip.h:613
const char * ast_sip_get_host_ip_string(int af)
Retrieve the local host address in string form.
Definition: res_pjsip.c:2493
char * ast_sip_get_endpoint_identifier_order(void)
Retrieve the global endpoint_identifier_order setting.
int(* ast_transport_monitor_data_matcher)(void *a, void *b)
Transport shutdown monitor data matcher.
Definition: res_pjsip.h:3931
void ast_sip_security_mechanisms_vector_copy(struct ast_sip_security_mechanism_vector *dst, const struct ast_sip_security_mechanism_vector *src)
Duplicate a security mechanism.
pjsip_media_type pjsip_media_type_application_media_control_xml
Definition: res_pjsip.c:3910
int ast_sip_call_codec_str_to_pref(struct ast_flags *pref, const char *pref_str, int is_outgoing)
Convert a call codec preference string to preference flags.
Definition: res_pjsip.c:2577
int ast_sip_transport_state_set_transport(const char *transport_name, pjsip_transport *transport)
Sets the PJSIP transport on a child transport.
char * ast_sip_rdata_get_header_value(pjsip_rx_data *rdata, const pj_str_t str)
Get a specific header value from rdata.
Definition: res_pjsip.c:345
pjsip_dialog * ast_sip_create_dialog_uas(const struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pj_status_t *status)
General purpose method for creating a UAS dialog with an endpoint.
Definition: res_pjsip.c:1176
struct ast_sip_contact * ast_sip_location_retrieve_contact_from_aor_list(const char *aor_list)
Retrieve the first bound contact from a list of AORs.
Definition: location.c:304
int ast_sip_location_add_contact(struct ast_sip_aor *aor, const char *uri, struct timeval expiration_time, const char *path_info, const char *user_agent, const char *via_addr, int via_port, const char *call_id, struct ast_sip_endpoint *endpoint)
Add a new contact to an AOR.
Definition: location.c:429
void ast_sip_location_retrieve_contact_and_aor_from_list(const char *aor_list, struct ast_sip_aor **aor, struct ast_sip_contact **contact)
Retrieve the first bound contact AND the AOR chosen from a list of AORs.
Definition: location.c:266
struct ast_sip_endpoint * ast_sip_get_artificial_endpoint(void)
Retrieves a reference to the artificial endpoint.
pjsip_media_type pjsip_media_type_application_json
Definition: res_pjsip.c:3909
int ast_sip_requires_authentication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Determine if an incoming request requires authentication.
Definition: res_pjsip.c:163
void ast_sip_report_mem_limit(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Send a security event notification for when a memory limit is hit.
int ast_sip_send_response(pjsip_response_addr *res_addr, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint)
Send a response to an out of dialog request.
Definition: res_pjsip.c:2396
pjsip_generic_string_hdr * ast_sip_add_header2(pjsip_tx_data *tdata, const char *name, const char *value)
Add a header to an outbound SIP message, returning a pointer to the header.
Definition: res_pjsip.c:2023
void ast_sip_report_req_no_support(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, const char *req_type)
Send a security event notification for when a request is not supported.
struct ao2_container * ast_sip_get_endpoints(void)
Retrieve any endpoints available to sorcery.
int ast_copy_pj_str2(char **dest, const pj_str_t *src)
Create and copy a pj_str_t into a standard character buffer.
Definition: res_pjsip.c:2208
int ast_sip_get_host_ip(int af, pj_sockaddr *addr)
Retrieve the local host address in IP form.
Definition: res_pjsip.c:2480
int ast_sip_for_each_auth(const struct ast_sip_auth_vector *array, ao2_callback_fn on_auth, void *arg)
For every auth in the array call the given 'on_auth' handler.
Definition: config_auth.c:135
void ast_sip_report_auth_success(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Send a security event notification for when authentication succeeds.
struct ao2_container * ast_sip_get_transport_states(void)
Retrieves all transport states.
ast_sip_session_redirect
Definition: res_pjsip.h:654
@ AST_SIP_REDIRECT_URI_CORE
Definition: res_pjsip.h:658
@ AST_SIP_REDIRECT_URI_PJSIP
Definition: res_pjsip.h:660
@ AST_SIP_REDIRECT_USER
Definition: res_pjsip.h:656
int ast_sip_create_response(const pjsip_rx_data *rdata, int st_code, struct ast_sip_contact *contact, pjsip_tx_data **p_tdata)
General purpose method for creating a SIP response.
Definition: res_pjsip.c:2468
int ast_sip_register_service(pjsip_module *module)
Register a SIP service in Asterisk.
Definition: res_pjsip.c:117
void * ast_sip_endpoint_alloc(const char *name)
Allocate a new SIP endpoint.
struct ast_sip_aor * ast_sip_location_retrieve_aor(const char *aor_name)
Retrieve a named AOR.
Definition: location.c:147
int ast_sip_is_allowed_uri(pjsip_uri *uri)
Check whether a pjsip_uri is allowed or not.
Definition: res_pjsip.c:3472
pjsip_dialog * ast_sip_create_dialog_uac(const struct ast_sip_endpoint *endpoint, const char *aor_name, const char *request_user)
General purpose method for creating a UAC dialog with an endpoint.
Definition: res_pjsip.c:964
int ast_sip_for_each_channel_snapshot(const struct ast_endpoint_snapshot *endpoint_snapshot, ao2_callback_fn on_channel_snapshot, void *arg)
For every channel snapshot on an endpoint snapshot call the given 'on_channel_snapshot' handler.
struct ao2_container * ast_sip_location_retrieve_aor_contacts_nolock_filtered(const struct ast_sip_aor *aor, unsigned int flags)
Retrieve all contacts currently available for an AOR without locking the AOR and filter based on flag...
Definition: location.c:219
void ast_sip_transport_state_register(struct ast_sip_tpmgr_state_callback *element)
Register a transport state notification callback element.
void ast_sip_cleanup_auths(struct ast_sip_auth *auths[], size_t num_auths)
Clean up retrieved auth structures from memory.
int ast_sip_for_each_contact(const struct ast_sip_aor *aor, ao2_callback_fn on_contact, void *arg)
For every contact on an AOR call the given 'on_contact' handler.
Definition: location.c:722
const int ast_sip_hangup_sip2cause(int cause)
Convert SIP hangup causes to Asterisk hangup causes.
Definition: res_pjsip.c:3531
enum ast_transport_monitor_reg ast_sip_transport_monitor_register_key(const char *transport_key, ast_transport_monitor_shutdown_cb cb, void *ao2_data)
Register a reliable transport shutdown monitor callback.
int ast_sip_rewrite_uri_to_local(pjsip_sip_uri *uri, pjsip_tx_data *tdata)
Replace domain and port of SIP URI to point to (external) signaling address of this Asterisk instance...
Definition: res_pjsip.c:605
int ast_sip_format_auths_ami(const struct ast_sip_auth_vector *auths, struct ast_sip_ami *ami)
Format auth details for AMI.
Definition: config_auth.c:195
int ast_sip_create_request_with_auth(const struct ast_sip_auth_vector *auths, pjsip_rx_data *challenge, pjsip_tx_data *tdata, pjsip_tx_data **new_request)
Create a response to an authentication challenge.
Definition: res_pjsip.c:214
int ast_sip_for_each_aor(const char *aors, ao2_callback_fn on_aor, void *arg)
For every aor in the comma separated aors string call the given 'on_aor' handler.
Definition: location.c:687
struct ast_sip_contact * ast_sip_location_retrieve_first_aor_contact_filtered(const struct ast_sip_aor *aor, unsigned int flags)
Retrieve the first bound contact for an AOR and filter based on flags.
Definition: location.c:199
int ast_sip_set_id_connected_line(struct pjsip_rx_data *rdata, struct ast_party_id *id)
Set the ID for a connected line update.
Definition: res_pjsip.c:2822
pjsip_media_type pjsip_media_type_application_sdp
Definition: res_pjsip.c:3916
ast_sip_session_media_encryption
Definition: res_pjsip.h:643
@ AST_SIP_MEDIA_ENCRYPT_SDES
Definition: res_pjsip.h:649
@ AST_SIP_MEDIA_TRANSPORT_INVALID
Definition: res_pjsip.h:645
@ AST_SIP_MEDIA_ENCRYPT_NONE
Definition: res_pjsip.h:647
@ AST_SIP_MEDIA_ENCRYPT_DTLS
Definition: res_pjsip.h:651
void ast_sip_register_supplement(struct ast_sip_supplement *supplement)
Register a supplement to SIP out of dialog processing.
Definition: res_pjsip.c:1456
void ast_sip_add_date_header(pjsip_tx_data *tdata)
Adds a Date header to the tdata, formatted like: Date: Wed, 01 Jan 2021 14:53:01 GMT.
Definition: res_pjsip.c:90
pjsip_media_type pjsip_media_type_text_plain
Definition: res_pjsip.c:3920
void ast_sip_report_auth_challenge_sent(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pjsip_tx_data *tdata)
Send a security event notification for when an authentication challenge is sent.
void ast_sip_message_apply_transport(const char *transport_name, pjsip_tx_data *tdata)
Apply the configuration for a transport to an outgoing message.
void ast_sip_unregister_outbound_authenticator(struct ast_sip_outbound_authenticator *auth)
Unregister an outbound SIP authenticator.
Definition: res_pjsip.c:203
int ast_sip_set_id_from_invite(struct pjsip_rx_data *rdata, struct ast_party_id *id, struct ast_party_id *default_id, int trust_inbound)
Set the ID from an INVITE.
Definition: res_pjsip.c:2827
enum ast_transport_monitor_reg ast_sip_transport_monitor_register_replace(pjsip_transport *transport, ast_transport_monitor_shutdown_cb cb, void *ao2_data, ast_transport_monitor_data_matcher matches)
Register a reliable transport shutdown monitor callback replacing any duplicate.
pjsip_media_type pjsip_media_type_application_pidf_xml
Definition: res_pjsip.c:3911
void ast_sip_transport_monitor_unregister(pjsip_transport *transport, ast_transport_monitor_shutdown_cb cb, void *data, ast_transport_monitor_data_matcher matches)
Unregister a reliable transport shutdown monitor.
int ast_sip_auths_to_str(const struct ast_sip_auth_vector *auths, char **buf)
Converts an auths array to a string of comma separated values.
int ast_sip_create_rdata(pjsip_rx_data *rdata, char *packet, const char *src_name, int src_port, char *transport_type, const char *local_name, int local_port)
General purpose method for creating an rdata structure using specific information.
Definition: res_pjsip.c:1266
enum ast_sip_check_auth_result ast_sip_check_authentication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pjsip_tx_data *tdata)
Method to determine authentication status of an incoming request.
Definition: res_pjsip.c:179
pjsip_endpoint * ast_sip_get_pjsip_endpoint(void)
Get a pointer to the PJSIP endpoint.
Definition: res_pjsip.c:520
int ast_sip_register_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier)
Register a SIP endpoint identifier.
Definition: res_pjsip.c:310
struct ast_endpoint_snapshot * ast_sip_get_endpoint_snapshot(const struct ast_sip_endpoint *endpoint)
Retrieve the endpoint snapshot for an endpoint.
void * ast_sip_dict_get(void *ht, const char *key)
Retrieves the value associated with the given key.
Definition: res_pjsip.c:2327
unsigned int ast_sip_get_send_contact_status_on_update_registration(void)
Retrieve the global setting 'send_contact_status_on_update_registration'.
int ast_sip_update_from(pjsip_tx_data *tdata, char *from)
Overwrite fields in the outbound 'From' header.
Definition: res_pjsip.c:3383
ast_sip_supplement_priority
Definition: res_pjsip.h:3177
@ AST_SIP_SUPPLEMENT_PRIORITY_CHANNEL
Definition: res_pjsip.h:3184
@ AST_SIP_SUPPLEMENT_PRIORITY_FIRST
Definition: res_pjsip.h:3179
@ AST_SIP_SUPPLEMENT_PRIORITY_LAST
Definition: res_pjsip.h:3186
int ast_sip_format_endpoint_ami(struct ast_sip_endpoint *endpoint, struct ast_sip_ami *ami, int *count)
Formats the endpoint and sends over AMI.
Definition: res_pjsip.c:501
int ast_sip_dtmf_to_str(const enum ast_sip_dtmf_mode dtmf, char *buf, size_t buf_len)
Convert the DTMF mode enum value into a string.
Definition: res_pjsip.c:2504
int ast_sip_str2rc(const char *name)
Convert name to SIP response code.
Definition: res_pjsip.c:3714
int ast_sip_set_tpselector_from_transport(const struct ast_sip_transport *transport, pjsip_tpselector *selector)
Sets pjsip_tpselector from ast_sip_transport.
Definition: res_pjsip.c:843
int ast_sip_retrieve_auths(const struct ast_sip_auth_vector *auths, struct ast_sip_auth **out)
Retrieve relevant SIP auth structures from sorcery.
struct ast_sip_endpoint * ast_pjsip_rdata_get_endpoint(pjsip_rx_data *rdata)
Get the looked-up endpoint on an out-of dialog request or response.
int ast_sip_is_uri_sip_sips(pjsip_uri *uri)
Check whether a pjsip_uri is SIP/SIPS or not.
Definition: res_pjsip.c:3467
int ast_sip_set_tpselector_from_ep_or_uri(const struct ast_sip_endpoint *endpoint, pjsip_sip_uri *sip_uri, pjsip_tpselector *selector)
Sets pjsip_tpselector from an endpoint or uri.
Definition: res_pjsip.c:911
void ast_sip_service_route_vector_destroy(struct ast_sip_service_route_vector *service_routes)
Destroy a vector of service routes.
void ast_sip_unregister_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier)
Unregister a SIP endpoint identifier.
Definition: res_pjsip.c:315
const char * ast_sip_get_contact_short_status_label(const enum ast_sip_contact_status_type status)
void ast_copy_pj_str(char *dest, const pj_str_t *src, size_t size)
Copy a pj_str_t into a standard character buffer.
Definition: res_pjsip.c:2201
void ast_sip_security_mechanisms_vector_destroy(struct ast_sip_security_mechanism_vector *security_mechanisms)
Free contents of a security mechanism vector.
void ast_sip_transport_monitor_unregister_all(ast_transport_monitor_shutdown_cb cb, void *data, ast_transport_monitor_data_matcher matches)
Unregister a transport shutdown monitor from all reliable transports.
const char * ast_sip_call_codec_pref_to_str(struct ast_flags pref)
Convert the call codec preference flags to a string.
Definition: res_pjsip.c:2554
struct ast_sip_endpoint * ast_sip_identify_endpoint(pjsip_rx_data *rdata)
Determine the endpoint that has sent a SIP message.
Definition: res_pjsip.c:330
int ast_sip_send_out_of_dialog_request(pjsip_tx_data *tdata, struct ast_sip_endpoint *endpoint, int timeout, void *token, void(*callback)(void *token, pjsip_event *e))
General purpose method for sending an Out-Of-Dialog SIP request.
Definition: res_pjsip.c:1938
pjsip_dialog * ast_sip_create_dialog_uas_locked(const struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pj_status_t *status)
General purpose method for creating a UAS dialog with an endpoint.
Definition: res_pjsip.c:1192
pjsip_media_type pjsip_media_type_application_simple_message_summary
Definition: res_pjsip.c:3915
struct ast_sip_transport_state * ast_sip_find_transport_state_in_use(struct ast_sip_request_transport_details *details)
Returns the transport state currently in use based on request transport details.
Definition: res_pjsip.c:595
int ast_sip_format_contact_ami(void *obj, void *arg, int flags)
Formats the contact and sends over AMI.
#define SIP_TLS_MAX_CIPHERS
Maximum number of ciphers supported for a TLS transport.
Definition: res_pjsip.h:107
int ast_sip_dlg_set_transport(const struct ast_sip_endpoint *endpoint, pjsip_dialog *dlg, pjsip_tpselector *selector)
Set the transport on a dialog.
Definition: res_pjsip.c:727
int ast_sip_is_media_type_in(pjsip_media_type *a,...) attribute_sentinel
Check if a media type is in a list of others.
Definition: res_pjsip.c:2228
enum ast_transport_monitor_reg ast_sip_transport_monitor_register_replace_key(const char *transport_key, ast_transport_monitor_shutdown_cb cb, void *ao2_data, ast_transport_monitor_data_matcher matches)
Register a reliable transport shutdown monitor callback replacing any duplicate.
unsigned int ast_sip_get_use_callerid_contact(void)
Retrieve the global setting 'use_callerid_contact'.
char * ast_sip_get_default_voicemail_extension(void)
Retrieve the default voicemail extension.
ast_sip_contact_filter
Contact retrieval filtering flags.
Definition: res_pjsip.h:1299
@ AST_SIP_CONTACT_FILTER_REACHABLE
Return only reachable or unknown contacts.
Definition: res_pjsip.h:1304
@ AST_SIP_CONTACT_FILTER_DEFAULT
Default filter flags.
Definition: res_pjsip.h:1301
void ast_sip_unregister_authenticator(struct ast_sip_authenticator *auth)
Unregister a SIP authenticator.
Definition: res_pjsip.c:152
unsigned int ast_sip_get_contact_expiration_check_interval(void)
Retrieve the system contact expiration check interval setting.
int ast_sip_persistent_endpoint_update_state(const char *endpoint_name, enum ast_endpoint_state state)
Change state of a persistent endpoint.
int ast_sip_send_request(pjsip_tx_data *tdata, struct pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint, void *token, void(*callback)(void *token, pjsip_event *e))
General purpose method for sending a SIP request.
Definition: res_pjsip.c:1979
const char * ast_sip_get_device_state(const struct ast_sip_endpoint *endpoint)
Retrieve the device state for an endpoint.
long ast_sip_threadpool_queue_size(void)
Return the size of the SIP threadpool's task queue.
Definition: res_pjsip.c:3457
struct ast_sip_endpoint * ast_sip_default_outbound_endpoint(void)
Retrieve the default outbound endpoint.
int ast_sip_set_request_transport_details(struct ast_sip_request_transport_details *details, pjsip_tx_data *tdata, int use_ipv6)
Sets request transport details based on tdata.
Definition: res_pjsip.c:648
void ast_sip_report_invalid_endpoint(const char *name, pjsip_rx_data *rdata)
Send a security event notification for when an invalid endpoint is requested.
int ast_sip_register_outbound_authenticator(struct ast_sip_outbound_authenticator *outbound_auth)
Register an outbound SIP authenticator.
Definition: res_pjsip.c:191
void ast_sip_register_endpoint_formatter(struct ast_sip_endpoint_formatter *obj)
Register an endpoint formatter.
Definition: res_pjsip.c:481
int ast_sip_add_global_request_header(const char *name, const char *value, int replace)
int ast_sip_add_body(pjsip_tx_data *tdata, const struct ast_sip_body *body)
Add a body to an outbound SIP message.
Definition: res_pjsip.c:2052
int ast_sip_security_mechanisms_to_str(const struct ast_sip_security_mechanism_vector *security_mechanisms, int add_qvalue, char **buf)
Writes the security mechanisms of an endpoint into a buffer as a string and returns the buffer.
void * ast_sip_dict_set(pj_pool_t *pool, void *ht, const char *key, void *val)
Set the value for the given key.
Definition: res_pjsip.c:2338
int ast_sip_are_media_types_equal(pjsip_media_type *a, pjsip_media_type *b)
Compare pjsip media types.
Definition: res_pjsip.c:2219
void ast_sip_tpselector_unref(pjsip_tpselector *selector)
Unreference a pjsip_tpselector.
Definition: res_pjsip.c:923
void ast_sip_get_default_realm(char *realm, size_t size)
Retrieve the global default realm.
struct ao2_container * ast_sip_location_retrieve_aor_contacts_nolock(const struct ast_sip_aor *aor)
Retrieve all contacts currently available for an AOR without locking the AOR.
Definition: location.c:214
int ast_sip_get_transport_name(const struct ast_sip_endpoint *endpoint, pjsip_sip_uri *sip_uri, char *buf, size_t buf_len)
Get the transport name from an endpoint or request uri.
Definition: res_pjsip.c:698
unsigned int ast_sip_get_disable_multi_domain(void)
Retrieve the system setting 'disable multi domain'.
void ast_sip_unregister_endpoint_formatter(struct ast_sip_endpoint_formatter *obj)
Unregister an endpoint formatter.
Definition: res_pjsip.c:487
int ast_sip_retrieve_auths_vector(const struct ast_sip_auth_vector *auth_ids, struct ast_sip_auth_objects_vector *auth_objects)
Retrieve relevant SIP auth structures from sorcery as a vector.
ast_sip_dtmf_mode
DTMF modes for SIP endpoints.
Definition: res_pjsip.h:543
@ AST_SIP_DTMF_NONE
Definition: res_pjsip.h:545
@ AST_SIP_DTMF_AUTO_INFO
Definition: res_pjsip.h:556
@ AST_SIP_DTMF_AUTO
Definition: res_pjsip.h:554
@ AST_SIP_DTMF_INBAND
Definition: res_pjsip.h:550
@ AST_SIP_DTMF_INFO
Definition: res_pjsip.h:552
@ AST_SIP_DTMF_RFC_4733
Definition: res_pjsip.h:548
unsigned int ast_sip_get_ignore_uri_user_options(void)
Retrieve the global setting 'ignore_uri_user_options'.
int ast_sip_register_authenticator(struct ast_sip_authenticator *auth)
Register a SIP authenticator.
Definition: res_pjsip.c:140
static const pj_str_t AST_PJ_STR_EMPTY
Definition: res_pjsip.h:114
struct ast_sip_service_route_vector * ast_sip_service_route_vector_alloc(void)
Allocate a vector of service routes.
struct ast_sip_contact * ast_sip_location_retrieve_contact(const char *contact_name)
Retrieve a named contact.
Definition: location.c:350
enum ast_transport_monitor_reg ast_sip_transport_monitor_register(pjsip_transport *transport, ast_transport_monitor_shutdown_cb cb, void *ao2_data)
Register a reliable transport shutdown monitor callback.
int ast_sip_str_to_security_mechanism(struct ast_sip_security_mechanism **security_mechanism, const char *value)
Allocate a security mechanism from a string.
int ast_sip_sorcery_object_to_ami(const void *obj, struct ast_str **buf)
Converts a sorcery object to a string of object properties.
void ast_sip_transport_state_unregister(struct ast_sip_tpmgr_state_callback *element)
Unregister a transport state notification callback element.
int ast_sip_add_body_multipart(pjsip_tx_data *tdata, const struct ast_sip_body *bodies[], int num_bodies)
Add a multipart body to an outbound SIP message.
Definition: res_pjsip.c:2059
ast_sip_auth_type
Methods of storing SIP digest authentication credentials.
Definition: res_pjsip.h:566
@ AST_SIP_AUTH_TYPE_GOOGLE_OAUTH
Definition: res_pjsip.h:572
@ AST_SIP_AUTH_TYPE_ARTIFICIAL
Definition: res_pjsip.h:574
@ AST_SIP_AUTH_TYPE_MD5
Definition: res_pjsip.h:570
@ AST_SIP_AUTH_TYPE_USER_PASS
Definition: res_pjsip.h:568
pjsip_media_type pjsip_media_type_application_rlmi_xml
Definition: res_pjsip.c:3914
ast_transport_monitor_reg
Definition: res_pjsip.h:3933
@ AST_TRANSPORT_MONITOR_REG_NOT_FOUND
Transport not found to monitor.
Definition: res_pjsip.h:3942
@ AST_TRANSPORT_MONITOR_REG_REPLACED
Replaced the already existing transport monitor with new one.
Definition: res_pjsip.h:3937
@ AST_TRANSPORT_MONITOR_REG_FAILED
Error while registering transport monitor.
Definition: res_pjsip.h:3944
@ AST_TRANSPORT_MONITOR_REG_SUCCESS
Successfully registered the transport monitor.
Definition: res_pjsip.h:3935
void(* ast_transport_monitor_shutdown_cb)(void *data)
Transport shutdown monitor callback.
Definition: res_pjsip.h:3919
int ast_sip_add_global_response_header(const char *name, const char *value, int replace)
struct ao2_container * ast_sip_location_retrieve_contacts_from_aor_list(const char *aor_list)
Retrieve all contacts from a list of AORs.
Definition: location.c:335
int ast_sip_update_to_uri(pjsip_tx_data *tdata, const char *to)
Replace the To URI in the tdata with the supplied one.
Definition: res_pjsip.c:3323
pjsip_media_type pjsip_media_type_multipart_mixed
Definition: res_pjsip.c:3918
void ast_sip_report_auth_failed_challenge_response(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Send a security event notification for when a challenge response has failed.
void ast_sip_remove_headers_by_name_and_value(pjsip_msg *msg, const pj_str_t *hdr_name, const char *value)
Removes all headers of a specific name and value from a pjsip_msg.
pjsip_media_type pjsip_media_type_application_xpidf_xml
Definition: res_pjsip.c:3912
void ast_sip_location_retrieve_contact_and_aor_from_list_filtered(const char *aor_list, unsigned int flags, struct ast_sip_aor **aor, struct ast_sip_contact **contact)
Retrieve the first bound contact AND the AOR chosen from a list of AORs and filter based on flags.
Definition: location.c:272
int ast_sip_set_outbound_proxy(pjsip_tx_data *tdata, const char *proxy)
Set the outbound proxy for an outbound SIP message.
Definition: res_pjsip.c:1992
struct ast_sip_transport_state * ast_sip_get_transport_state(const char *transport_id)
Retrieve transport state.
unsigned int ast_sip_get_mwi_disable_initial_unsolicited(void)
Retrieve the global setting 'disable sending unsolicited mwi on startup'.
void ast_sip_auth_vector_destroy(struct ast_sip_auth_vector *vector)
Free contents of an auth vector.
struct ast_threadpool * ast_sip_threadpool(void)
Retrieve the SIP threadpool object.
Definition: res_pjsip.c:3462
int ast_sip_register_endpoint_identifier_with_name(struct ast_sip_endpoint_identifier *identifier, const char *name)
Register a SIP endpoint identifier with a name.
Definition: res_pjsip.c:233
pjsip_media_type pjsip_media_type_multipart_alternative
Definition: res_pjsip.c:3917
ast_sip_security_negotiation
The kind of security negotiation.
Definition: res_pjsip.h:353
@ AST_SIP_SECURITY_NEG_MEDIASEC
Definition: res_pjsip.h:357
@ AST_SIP_SECURITY_NEG_NONE
Definition: res_pjsip.h:355
int ast_sip_set_tpselector_from_transport_name(const char *transport_name, pjsip_tpselector *selector)
Sets pjsip_tpselector from ast_sip_transport.
Definition: res_pjsip.c:893
int ast_sip_create_request(const char *method, struct pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint, const char *uri, struct ast_sip_contact *contact, pjsip_tx_data **tdata)
General purpose method for creating a SIP request.
Definition: res_pjsip.c:1435
struct ast_str * ast_sip_create_ami_event(const char *event, struct ast_sip_ami *ami)
Creates a string to store AMI event data in.
int ast_sip_get_mwi_tps_queue_low(void)
Retrieve the global MWI taskprocessor low water clear alert level.
struct ast_sip_contact * ast_sip_location_create_contact(struct ast_sip_aor *aor, const char *uri, struct timeval expiration_time, const char *path_info, const char *user_agent, const char *via_addr, int via_port, const char *call_id, int prune_on_boot, struct ast_sip_endpoint *endpoint)
Create a new contact for an AOR without locking the AOR.
Definition: location.c:355
int ast_sip_str_to_dtmf(const char *dtmf_mode)
Convert the DTMF mode name into an enum.
Definition: res_pjsip.c:2533
int ast_sip_add_header(pjsip_tx_data *tdata, const char *name, const char *value)
Add a header to an outbound SIP message.
Definition: res_pjsip.c:2008
struct ast_sorcery * ast_sip_get_sorcery(void)
Get a pointer to the SIP sorcery structure.
const pj_str_t * ast_sip_pjsip_uri_get_hostname(pjsip_uri *uri)
Get the host portion of the pjsip_uri.
Definition: res_pjsip.c:3496
char * ast_sip_get_regcontext(void)
Retrieve the global regcontext setting.
ast_sip_check_auth_result
Possible returns from ast_sip_check_authentication.
Definition: res_pjsip.h:1227
@ AST_SIP_AUTHENTICATION_CHALLENGE
Definition: res_pjsip.h:1229
@ AST_SIP_AUTHENTICATION_ERROR
Definition: res_pjsip.h:1235
@ AST_SIP_AUTHENTICATION_SUCCESS
Definition: res_pjsip.h:1231
@ AST_SIP_AUTHENTICATION_FAILED
Definition: res_pjsip.h:1233
ast_sip_call_codec_pref
Incoming/Outgoing call offer/answer joint codec preference.
Definition: res_pjsip.h:668
@ AST_SIP_CALL_CODEC_PREF_ALL
Definition: res_pjsip.h:677
@ AST_SIP_CALL_CODEC_PREF_LOCAL
Definition: res_pjsip.h:683
@ AST_SIP_CALL_CODEC_PREF_REMOTE
Definition: res_pjsip.h:685
@ AST_SIP_CALL_CODEC_PREF_UNION
Definition: res_pjsip.h:673
@ AST_SIP_CALL_CODEC_PREF_FIRST
Definition: res_pjsip.h:679
@ AST_SIP_CALL_CODEC_PREF_INTERSECT
Definition: res_pjsip.h:671
const char * ast_sip_auth_type_to_str(enum ast_sip_auth_type type)
Converts the given auth type to a string.
Definition: config_auth.c:80
struct ast_sip_contact_status * ast_sip_get_contact_status(const struct ast_sip_contact *contact)
Retrieve the current status for a contact.
int(* ast_sip_dialog_outbound_auth_cb)(pjsip_dialog *dlg, pjsip_tx_data *tdata, void *user_data)
Callback called when an outbound request with authentication credentials is to be sent in dialog.
Definition: res_pjsip.h:1763
int ast_sip_security_mechanism_vector_init(struct ast_sip_security_mechanism_vector *security_mechanism, const char *value)
Initialize security mechanism vector from string of security mechanisms.
int ast_sip_location_update_contact(struct ast_sip_contact *contact)
Update a contact.
Definition: location.c:445
const char * ast_sip_get_contact_status_label(const enum ast_sip_contact_status_type status)
translate ast_sip_contact_status_type to character string.
int ast_sip_send_stateful_response(pjsip_rx_data *rdata, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint)
Send a stateful response to an out of dialog request.
Definition: res_pjsip.c:2424
int ast_sip_for_each_channel(const struct ast_sip_endpoint *endpoint, ao2_callback_fn on_channel_snapshot, void *arg)
For every channel snapshot on an endpoint all the given 'on_channel_snapshot' handler.
int ast_sip_auth_vector_init(struct ast_sip_auth_vector *vector, const char *auth_names)
Initialize an auth vector with the configured values.
ast_sip_contact_status_type
Status type for a contact.
Definition: res_pjsip.h:434
@ AVAILABLE
Definition: res_pjsip.h:438
@ UNAVAILABLE
Definition: res_pjsip.h:436
@ REMOVED
Definition: res_pjsip.h:443
@ UNKNOWN
Definition: res_pjsip.h:440
@ CREATED
Definition: res_pjsip.h:442
void ast_sip_get_default_from_user(char *from_user, size_t size)
Retrieve the global default from user.
unsigned int ast_sip_get_mwi_tps_queue_high(void)
Retrieve the global MWI taskprocessor high water alert trigger level.
int ast_sip_is_content_type(pjsip_media_type *content_type, char *type, char *subtype)
Checks if the given content type matches type/subtype.
Definition: res_pjsip.c:2248
void ast_sip_transport_monitor_unregister_key(const char *transport_key, ast_transport_monitor_shutdown_cb cb, void *data, ast_transport_monitor_data_matcher matches)
Unregister a reliable transport shutdown monitor.
int ast_sip_append_body(pjsip_tx_data *tdata, const char *body_text)
Append body data to a SIP message.
Definition: res_pjsip.c:2075
int ast_sip_add_security_headers(struct ast_sip_security_mechanism_vector *security_mechanisms, const char *header_name, int add_qval, pjsip_tx_data *tdata)
Add security headers to transmission data.
int ast_sip_contact_to_str(void *object, void *arg, int flags)
Handler used to convert a contact to a string.
Definition: location.c:770
struct ast_sip_contact * ast_sip_location_retrieve_first_aor_contact(const struct ast_sip_aor *aor)
Retrieve the first bound contact for an AOR.
Definition: location.c:194
int ast_sip_transport_state_set_preferred_identity(const char *transport_name, const char *identity)
Sets the P-Preferred-Identity on a child transport.
unsigned int ast_sip_get_all_codecs_on_empty_reinvite(void)
Retrieve the system setting 'all_codecs_on_empty_reinvite'.
void ast_sip_location_prune_boot_contacts(void)
Prune the prune_on_boot contacts.
Definition: location.c:469
ast_sip_100rel_mode
100rel modes for SIP endpoints
Definition: res_pjsip.h:529
@ AST_SIP_100REL_PEER_SUPPORTED
Definition: res_pjsip.h:535
@ AST_SIP_100REL_UNSUPPORTED
Definition: res_pjsip.h:531
@ AST_SIP_100REL_SUPPORTED
Definition: res_pjsip.h:533
@ AST_SIP_100REL_REQUIRED
Definition: res_pjsip.h:537
struct ao2_container * ast_sip_location_retrieve_aor_contacts(const struct ast_sip_aor *aor)
Retrieve all contacts currently available for an AOR.
Definition: location.c:247
ast_sip_direct_media_glare_mitigation
Definition: res_pjsip.h:630
@ AST_SIP_DIRECT_MEDIA_GLARE_MITIGATION_NONE
Definition: res_pjsip.h:632
@ AST_SIP_DIRECT_MEDIA_GLARE_MITIGATION_INCOMING
Definition: res_pjsip.h:640
@ AST_SIP_DIRECT_MEDIA_GLARE_MITIGATION_OUTGOING
Definition: res_pjsip.h:636
pjsip_media_type pjsip_media_type_application_cpim_xpidf_xml
Definition: res_pjsip.c:3913
struct ao2_container * ast_sip_location_retrieve_aor_contacts_filtered(const struct ast_sip_aor *aor, unsigned int flags)
Retrieve all contacts currently available for an AOR and filter based on flags.
Definition: location.c:252
pjsip_sip_uri * ast_sip_get_contact_sip_uri(pjsip_tx_data *tdata)
Return the SIP URI of the Contact header.
Definition: res_pjsip.c:564
int ast_sip_location_delete_contact(struct ast_sip_contact *contact)
Delete a contact.
Definition: location.c:450
int ast_sip_create_rdata_with_contact(pjsip_rx_data *rdata, char *packet, const char *src_name, int src_port, char *transport_type, const char *local_name, int local_port, const char *contact_uri)
General purpose method for creating an rdata structure using specific information.
Definition: res_pjsip.c:1214
pjsip_media_type pjsip_media_type_multipart_related
Definition: res_pjsip.c:3919
int ast_sip_failover_request(pjsip_tx_data *tdata)
Set a request to use the next value in the list of resolved addresses.
Definition: res_pjsip.c:1816
void ast_sip_report_failed_acl(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, const char *name)
Send a security event notification for when an ACL check fails.
int ast_sip_location_add_contact_nolock(struct ast_sip_aor *aor, const char *uri, struct timeval expiration_time, const char *path_info, const char *user_agent, const char *via_addr, int via_port, const char *call_id, struct ast_sip_endpoint *endpoint)
Add a new contact to an AOR without locking the AOR.
Definition: location.c:416
int ast_sip_transport_state_set_service_routes(const char *transport_name, struct ast_sip_service_route_vector *service_routes)
Sets the service routes on a child transport.
ast_sip_session_refresh_method
Definition: res_pjsip.h:623
@ AST_SIP_SESSION_REFRESH_METHOD_UPDATE
Definition: res_pjsip.h:627
@ AST_SIP_SESSION_REFRESH_METHOD_INVITE
Definition: res_pjsip.h:625
void ast_sip_get_unidentified_request_thresholds(unsigned int *count, unsigned int *period, unsigned int *prune_interval)
Retrieve the unidentified request security event thresholds.
char * ast_sip_get_debug(void)
Retrieve the system debug setting (yes|no|host).
void ast_sip_modify_id_header(pj_pool_t *pool, pjsip_fromto_hdr *id_hdr, const struct ast_party_id *id)
Set name and number information on an identity header.
Definition: res_pjsip.c:2850
static void challenge(const char *realm, pjsip_tx_data *tdata, const pjsip_rx_data *rdata, int is_stale)
astobj2 callback for adding digest challenges to responses
Pluggable RTP Architecture.
Sorcery Data Access Layer API.
Endpoint abstractions.
Media Stream API.
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Generic container type.
Wrapper for an ast_acl linked list.
Definition: acl.h:76
Definition: dnsmgr.c:66
A snapshot of an endpoint's state.
Structure used to handle boolean flags.
Definition: utils.h:199
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
internal representation of ACL entries In principle user applications would have no need for this,...
Definition: acl.h:51
Information needed to identify an endpoint in a call.
Definition: channel.h:338
DTLS configuration structure.
Definition: rtp_engine.h:602
AMI variable container.
Definition: res_pjsip.h:3045
const char * action_id
Definition: res_pjsip.h:3051
struct mansession * s
Definition: res_pjsip.h:3047
void * arg
Definition: res_pjsip.h:3053
const struct message * m
Definition: res_pjsip.h:3049
A SIP address of record.
Definition: res_pjsip.h:478
SORCERY_OBJECT(details)
unsigned int minimum_expiration
Definition: res_pjsip.h:488
unsigned int remove_existing
Definition: res_pjsip.h:500
double qualify_timeout
Definition: res_pjsip.h:506
char * voicemail_extension
Definition: res_pjsip.h:508
unsigned int max_contacts
Definition: res_pjsip.h:498
unsigned int support_path
Definition: res_pjsip.h:504
struct ao2_container * permanent_contacts
Definition: res_pjsip.h:502
unsigned int remove_unavailable
Definition: res_pjsip.h:510
const ast_string_field outbound_proxy
Definition: res_pjsip.h:486
unsigned int maximum_expiration
Definition: res_pjsip.h:490
const ast_string_field mailboxes
Definition: res_pjsip.h:486
unsigned int default_expiration
Definition: res_pjsip.h:492
int authenticate_qualify
Definition: res_pjsip.h:496
unsigned int qualify_frequency
Definition: res_pjsip.h:494
SORCERY_OBJECT(details)
const ast_string_field oauth_clientid
Definition: res_pjsip.h:597
const ast_string_field oauth_secret
Definition: res_pjsip.h:597
const ast_string_field md5_creds
Definition: res_pjsip.h:597
const ast_string_field realm
Definition: res_pjsip.h:597
unsigned int nonce_lifetime
Definition: res_pjsip.h:599
const ast_string_field auth_user
Definition: res_pjsip.h:597
const ast_string_field refresh_token
Definition: res_pjsip.h:597
const ast_string_field auth_pass
Definition: res_pjsip.h:597
enum ast_sip_auth_type type
Definition: res_pjsip.h:601
An interchangeable way of handling digest authentication for SIP.
Definition: res_pjsip.h:1245
enum ast_sip_check_auth_result(* check_authentication)(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pjsip_tx_data *tdata)
Check that an incoming request passes authentication.
Definition: res_pjsip.h:1260
int(* requires_authentication)(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Check if a request requires authentication See ast_sip_requires_authentication for more details.
Definition: res_pjsip.h:1250
SIP body description.
Definition: res_pjsip.h:2323
const char * type
Definition: res_pjsip.h:2325
const char * body_text
Definition: res_pjsip.h:2329
const char * subtype
Definition: res_pjsip.h:2327
A contact's status.
Definition: res_pjsip.h:451
const ast_string_field uri
Definition: res_pjsip.h:457
enum ast_sip_contact_status_type status
Definition: res_pjsip.h:468
enum ast_sip_contact_status_type last_status
Definition: res_pjsip.h:470
const ast_string_field aor
Definition: res_pjsip.h:457
struct ast_sip_security_mechanism_vector security_mechanisms
Definition: res_pjsip.h:466
A wrapper for contact that adds the aor_id and a consistent contact id. Used by ast_sip_for_each_cont...
Definition: res_pjsip.h:517
struct ast_sip_contact * contact
Definition: res_pjsip.h:523
Contact associated with an address of record.
Definition: res_pjsip.h:392
SORCERY_OBJECT(details)
const ast_string_field uri
Definition: res_pjsip.h:414
double qualify_timeout
Definition: res_pjsip.h:422
struct ast_sip_endpoint * endpoint
Definition: res_pjsip.h:424
const ast_string_field via_addr
Definition: res_pjsip.h:414
const ast_string_field call_id
Definition: res_pjsip.h:414
const ast_string_field aor
Definition: res_pjsip.h:414
const ast_string_field outbound_proxy
Definition: res_pjsip.h:414
struct timeval expiration_time
Definition: res_pjsip.h:416
const ast_string_field path
Definition: res_pjsip.h:414
const ast_string_field endpoint_name
Definition: res_pjsip.h:414
int authenticate_qualify
Definition: res_pjsip.h:420
const ast_string_field reg_server
Definition: res_pjsip.h:414
const ast_string_field user_agent
Definition: res_pjsip.h:414
unsigned int qualify_frequency
Definition: res_pjsip.h:418
Direct media options for SIP endpoints.
Definition: res_pjsip.h:874
enum ast_sip_direct_media_glare_mitigation glare_mitigation
Definition: res_pjsip.h:880
enum ast_sip_session_refresh_method method
Definition: res_pjsip.h:878
const ast_string_field domain
Definition: res_pjsip.h:323
Endpoint configuration for SIP extensions.
Definition: res_pjsip.h:715
struct ast_sip_timer_options timer
Definition: res_pjsip.h:719
An entity responsible formatting endpoint information.
Definition: res_pjsip.h:3071
int(* format_ami)(const struct ast_sip_endpoint *endpoint, struct ast_sip_ami *ami)
Callback used to format endpoint information over AMI.
Definition: res_pjsip.h:3075
Party identification options for endpoints.
Definition: res_pjsip.h:769
struct ast_party_id self
Definition: res_pjsip.h:770
enum ast_sip_session_refresh_method refresh_method
Definition: res_pjsip.h:788