Asterisk - The Open Source Telephony Project  21.4.1
res_pjsip.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Mark Michelson <mmichelson@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 #ifndef _RES_PJSIP_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 
30 #include "asterisk/stringfields.h"
31 /* Needed for struct ast_sockaddr */
32 #include "asterisk/netsock2.h"
33 /* Needed for linked list macros */
34 #include "asterisk/linkedlists.h"
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 */
50 #include "asterisk/stasis_channels.h"
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 */
97 struct pjsip_rx_data;
98 struct pjsip_module;
99 struct pjsip_tx_data;
100 struct pjsip_dialog;
101 struct pjsip_transport;
102 struct pjsip_tpfactory;
103 struct pjsip_tls_setting;
104 struct 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 
114 static 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  */
133  enum ast_transport type;
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  */
148  pj_ssl_cipher ciphers[SIP_TLS_MAX_CIPHERS];
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  */
156  struct ast_ha *localnet;
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 */
223  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 */
243  enum ast_transport type;
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  */
265  pj_ssl_cipher ciphers[SIP_TLS_MAX_CIPHERS];
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  */
271  struct ast_ha *localnet;
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 */
319  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 */
331  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 */
339  enum ast_transport type;
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 */
345  pj_str_t local_address;
346  /*! \brief Local port for transport */
348 };
349 
350 /*!
351  * \brief The kind of security negotiation
352  */
353 enum ast_sip_security_negotiation {
354  /*! No security mechanism negotiation */
355  AST_SIP_SECURITY_NEG_NONE = 0,
356  /*! Use mediasec security mechanism negotiation */
357  AST_SIP_SECURITY_NEG_MEDIASEC,
358  /* Add RFC 3329 (sec-agree) mechanism negotiation in the future */
359 };
360 
361 /*!
362  * \brief The security mechanism type
363  */
364 enum ast_sip_security_mechanism_type {
365  AST_SIP_SECURITY_MECH_NONE = 0,
366  /* Use msrp-tls as security mechanism */
367  AST_SIP_SECURITY_MECH_MSRP_TLS,
368  /* Use sdes-srtp as security mechanism */
369  AST_SIP_SECURITY_MECH_SDES_SRTP,
370  /* Use dtls-srtp as security mechanism */
371  AST_SIP_SECURITY_MECH_DTLS_SRTP,
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. */
380  enum ast_sip_security_mechanism_type type;
381  /* The preference of this security mechanism. The higher the value, the more preferred. */
382  float qvalue;
383  /* Optional mechanism parameters. */
384  struct ast_vector_string 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 */
394  SORCERY_OBJECT(details);
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 */
426  int via_port;
427  /*! If true delete the contact on Asterisk restart/boot */
429 };
430 
431 /*!
432  * \brief Status type for a contact.
433  */
434 enum ast_sip_contact_status_type {
435  /*! Frequency > 0, but no response from remote uri */
436  UNAVAILABLE,
437  /*! Frequency > 0, and got response from remote uri */
438  AVAILABLE,
439  /*! Default last status, and when a contact status object is not found */
440  UNKNOWN,
441  /*! Frequency == 0, has a contact, but don't know status (non-qualified) */
442  CREATED,
443  REMOVED,
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) */
468  enum ast_sip_contact_status_type status;
469  /*! Last status for a contact (default - unavailable) */
470  enum ast_sip_contact_status_type last_status;
471  /*! Name of the contact */
472  char name[0];
473 };
474 
475 /*!
476  * \brief A SIP address of record
477  */
478 struct ast_sip_aor {
479  /*! Sorcery object details, the id is the AOR name */
480  SORCERY_OBJECT(details);
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. */
521  char *contact_id;
522  /*! Pointer to the actual contact. */
523  struct ast_sip_contact *contact;
524 };
525 
526 /*!
527  * \brief 100rel modes for SIP endpoints
528  */
529 enum ast_sip_100rel_mode {
530  /*! Do not support 100rel. (no) */
531  AST_SIP_100REL_UNSUPPORTED = 0,
532  /*! As UAC, indicate 100rel support in Supported header. (yes) */
533  AST_SIP_100REL_SUPPORTED,
534  /*! As UAS, send 1xx responses reliably, if the UAC indicated its support. Otherwise same as AST_SIP_100REL_SUPPORTED. (peer_supported) */
535  AST_SIP_100REL_PEER_SUPPORTED,
536  /*! Require the use of 100rel. (required) */
537  AST_SIP_100REL_REQUIRED,
538 };
539 
540 /*!
541  * \brief DTMF modes for SIP endpoints
542  */
543 enum ast_sip_dtmf_mode {
544  /*! No DTMF to be used */
545  AST_SIP_DTMF_NONE,
546  /* XXX Should this be 2833 instead? */
547  /*! Use RFC 4733 events for DTMF */
548  AST_SIP_DTMF_RFC_4733,
549  /*! Use DTMF in the audio stream */
550  AST_SIP_DTMF_INBAND,
551  /*! Use SIP INFO DTMF (blech) */
552  AST_SIP_DTMF_INFO,
553  /*! Use SIP 4733 if supported by the other side or INBAND if not */
554  AST_SIP_DTMF_AUTO,
555  /*! Use SIP 4733 if supported by the other side or INFO DTMF (blech) if not */
556  AST_SIP_DTMF_AUTO_INFO,
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  */
566 enum ast_sip_auth_type {
567  /*! Credentials stored as a username and password combination */
568  AST_SIP_AUTH_TYPE_USER_PASS,
569  /*! Credentials stored as an MD5 sum */
570  AST_SIP_AUTH_TYPE_MD5,
571  /*! Google Oauth */
572  AST_SIP_AUTH_TYPE_GOOGLE_OAUTH,
573  /*! Credentials not stored this is a fake auth */
574  AST_SIP_AUTH_TYPE_ARTIFICIAL
575 };
576 
577 #define SIP_SORCERY_AUTH_TYPE "auth"
578 
579 struct ast_sip_auth {
580  /*! Sorcery ID of the auth is its name */
581  SORCERY_OBJECT(details);
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 */
601  enum ast_sip_auth_type type;
602 };
603 
604 AST_VECTOR(ast_sip_auth_vector, const char *);
605 
606 /*!
607  * \brief Different methods by which incoming requests can be matched to endpoints
608  */
609 enum ast_sip_endpoint_identifier_type {
610  /*! Identify based on user name in From header */
611  AST_SIP_ENDPOINT_IDENTIFY_BY_USERNAME = (1 << 0),
612  /*! Identify based on user name in Auth header first, then From header */
613  AST_SIP_ENDPOINT_IDENTIFY_BY_AUTH_USERNAME = (1 << 1),
614  /*! Identify based on source IP address */
615  AST_SIP_ENDPOINT_IDENTIFY_BY_IP = (1 << 2),
616  /*! Identify based on arbitrary headers */
617  AST_SIP_ENDPOINT_IDENTIFY_BY_HEADER = (1 << 3),
618  /*! Identify based on request uri */
619  AST_SIP_ENDPOINT_IDENTIFY_BY_REQUEST_URI = (1 << 4),
620 };
621 AST_VECTOR(ast_sip_identify_by_vector, enum ast_sip_endpoint_identifier_type);
622 
623 enum ast_sip_session_refresh_method {
624  /*! Use reinvite to negotiate direct media */
625  AST_SIP_SESSION_REFRESH_METHOD_INVITE,
626  /*! Use UPDATE to negotiate direct media */
627  AST_SIP_SESSION_REFRESH_METHOD_UPDATE,
628 };
629 
630 enum ast_sip_direct_media_glare_mitigation {
631  /*! Take no special action to mitigate reinvite glare */
632  AST_SIP_DIRECT_MEDIA_GLARE_MITIGATION_NONE,
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  */
636  AST_SIP_DIRECT_MEDIA_GLARE_MITIGATION_OUTGOING,
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  */
640  AST_SIP_DIRECT_MEDIA_GLARE_MITIGATION_INCOMING,
641 };
642 
643 enum ast_sip_session_media_encryption {
644  /*! Invalid media encryption configuration */
645  AST_SIP_MEDIA_TRANSPORT_INVALID = 0,
646  /*! Do not allow any encryption of session media */
647  AST_SIP_MEDIA_ENCRYPT_NONE,
648  /*! Offer SDES-encrypted session media */
649  AST_SIP_MEDIA_ENCRYPT_SDES,
650  /*! Offer encrypted session media with datagram TLS key exchange */
651  AST_SIP_MEDIA_ENCRYPT_DTLS,
652 };
653 
654 enum ast_sip_session_redirect {
655  /*! User portion of the target URI should be used as the target in the dialplan */
656  AST_SIP_REDIRECT_USER = 0,
657  /*! Target URI should be used as the target in the dialplan */
658  AST_SIP_REDIRECT_URI_CORE,
659  /*! Target URI should be used as the target within chan_pjsip itself */
660  AST_SIP_REDIRECT_URI_PJSIP,
661 };
662 
663 /*!
664  * \brief Incoming/Outgoing call offer/answer joint codec preference.
665  *
666  * The default is INTERSECT ALL LOCAL.
667  */
668 enum ast_sip_call_codec_pref {
669  /*! Two bits for merge */
670  /*! Intersection of local and remote */
671  AST_SIP_CALL_CODEC_PREF_INTERSECT = 1 << 0,
672  /*! Union of local and remote */
673  AST_SIP_CALL_CODEC_PREF_UNION = 1 << 1,
674 
675  /*! Two bits for filter */
676  /*! No filter */
677  AST_SIP_CALL_CODEC_PREF_ALL = 1 << 2,
678  /*! Only the first */
679  AST_SIP_CALL_CODEC_PREF_FIRST = 1 << 3,
680 
681  /*! Two bits for preference and sort */
682  /*! Prefer, and order by local values */
683  AST_SIP_CALL_CODEC_PREF_LOCAL = 1 << 4,
684  /*! Prefer, and order by remote values */
685  AST_SIP_CALL_CODEC_PREF_REMOTE = 1 << 5,
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 )))
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 */
719  struct ast_sip_timer_options timer;
720 };
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? */
735  unsigned int subscribe_replaces_unsolicited;
736  /*! Voicemail extension to set in Message-Account */
738 };
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 };
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 };
764 /*!
765  * \brief Party identification options for endpoints
766  *
767  * This includes caller ID, connected line, and redirecting-related options
768  */
770  struct ast_party_id self;
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? */
784  unsigned int trust_connected_line;
785  /*! Do we send connected line updates to this endpoint? */
786  unsigned int send_connected_line;
787  /*! When performing connected line update, which method should be used */
788  enum ast_sip_session_refresh_method refresh_method;
789  /*! Do we add History-Info headers to applicable outgoing requests/responses? */
790  unsigned int send_history_info;
791 };
793 /*!
794  * \brief Call pickup configuration options for endpoints
795  */
797  /*! Call group */
798  ast_group_t callgroup;
799  /*! Pickup group */
800  ast_group_t pickupgroup;
801  /*! Named call group */
802  struct ast_namedgroups *named_callgroups;
803  /*! Named pickup group */
804  struct ast_namedgroups *named_pickupgroups;
805 };
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 };
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? */
856  enum ast_sip_session_media_encryption encryption;
857  /*! Do we want to optimistically support encryption if possible? */
858  unsigned int encryption_optimistic;
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 };
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 */
878  enum ast_sip_session_refresh_method method;
879  /*! Take steps to mitigate glare for direct media */
880  enum ast_sip_direct_media_glare_mitigation glare_mitigation;
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 */
889  enum ast_t38_ec_modes error_correction;
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 };
900 /*!
901  * \brief Media configuration for SIP endpoints
902  */
905  /*! Optional media address to use in SDP */
906  AST_STRING_FIELD(address);
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  */
961 struct ast_sip_endpoint {
962  SORCERY_OBJECT(details);
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 */
1010  enum ast_sip_dtmf_mode dtmf;
1011  /*! Method(s) by which the endpoint should be identified. */
1012  enum ast_sip_endpoint_identifier_type ident_method;
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 */
1020  unsigned int devicestate_busy_at;
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 */
1026  enum ast_sip_session_redirect redirect_method;
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. */
1042  unsigned int preferred_codec_only;
1043  /*! Do we allow an asymmetric RTP codec? */
1044  unsigned int 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 */
1048  unsigned int refer_blind_progress;
1049  /*! Whether to notifies dialog-info 'early' on INUSE && RINGING state */
1050  unsigned int notify_early_inuse_ringing;
1051  /*! Suppress Q.850 Reason headers on this endpoint */
1052  unsigned int suppress_q850_reason_headers;
1053  /*! Ignore 183 if no SDP is present */
1054  unsigned int ignore_183_without_sdp;
1055  /*! Type of security negotiation to use (RFC 3329). */
1056  enum ast_sip_security_negotiation security_negotiation;
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? */
1062  unsigned int allow_unauthenticated_options;
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 */
1068  AST_STRING_FIELD_EXTENDED(overlap_context);
1069  /*! 100rel mode to use with this endpoint */
1070  enum ast_sip_100rel_mode rel100;
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 */
1080 extern pjsip_media_type pjsip_media_type_application_json;
1081 extern pjsip_media_type pjsip_media_type_application_media_control_xml;
1082 extern pjsip_media_type pjsip_media_type_application_pidf_xml;
1083 extern pjsip_media_type pjsip_media_type_application_xpidf_xml;
1084 extern pjsip_media_type pjsip_media_type_application_cpim_xpidf_xml;
1085 extern pjsip_media_type pjsip_media_type_application_rlmi_xml;
1086 extern pjsip_media_type pjsip_media_type_application_simple_message_summary;
1087 extern pjsip_media_type pjsip_media_type_application_sdp;
1088 extern pjsip_media_type pjsip_media_type_multipart_alternative;
1089 extern pjsip_media_type pjsip_media_type_multipart_mixed;
1090 extern pjsip_media_type pjsip_media_type_multipart_related;
1091 extern 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  */
1101 int 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  */
1111 int 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  */
1124 int ast_sip_add_security_headers(struct ast_sip_security_mechanism_vector *security_mechanisms,
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  */
1134 void 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  */
1145 int 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  */
1155 void 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  */
1182 int 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  */
1195 int 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  */
1205 int 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  */
1215 int 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  */
1222 void ast_sip_auth_vector_destroy(struct ast_sip_auth_vector *vector);
1223 
1224 /*!
1225  * \brief Possible returns from ast_sip_check_authentication
1226  */
1227 enum ast_sip_check_auth_result {
1228  /*! Authentication needs to be challenged */
1229  AST_SIP_AUTHENTICATION_CHALLENGE,
1230  /*! Authentication succeeded */
1231  AST_SIP_AUTHENTICATION_SUCCESS,
1232  /*! Authentication failed */
1233  AST_SIP_AUTHENTICATION_FAILED,
1234  /*! Authentication encountered some internal error */
1235  AST_SIP_AUTHENTICATION_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  */
1245 struct ast_sip_authenticator {
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  */
1260  enum ast_sip_check_auth_result (*check_authentication)(struct ast_sip_endpoint *endpoint,
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  */
1299 enum ast_sip_contact_filter {
1300  /*! \brief Default filter flags */
1301  AST_SIP_CONTACT_FILTER_DEFAULT = 0,
1302 
1303  /*! \brief Return only reachable or unknown contacts */
1304  AST_SIP_CONTACT_FILTER_REACHABLE = (1 << 0),
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  */
1316 void 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  */
1331 int 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  */
1340 void 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  */
1357 int ast_sip_register_authenticator(struct ast_sip_authenticator *auth);
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  */
1367 void ast_sip_unregister_authenticator(struct ast_sip_authenticator *auth);
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  */
1379 int ast_sip_register_outbound_authenticator(struct ast_sip_outbound_authenticator *outbound_auth);
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  */
1389 void ast_sip_unregister_outbound_authenticator(struct ast_sip_outbound_authenticator *auth);
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  */
1405 int ast_sip_register_endpoint_identifier_with_name(struct ast_sip_endpoint_identifier *identifier,
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  */
1433 int ast_sip_register_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier);
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  */
1442 void ast_sip_unregister_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier);
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  */
1454 void *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  */
1464 int 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  */
1472 void 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  */
1484 struct ast_sip_contact_status *ast_sip_get_contact_status(const struct ast_sip_contact *contact);
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  */
1494 pjsip_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  */
1502 struct 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  */
1512 struct 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  */
1521 struct ast_sip_contact *ast_sip_location_retrieve_first_aor_contact(const struct ast_sip_aor *aor);
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  */
1532 struct ast_sip_contact *ast_sip_location_retrieve_first_aor_contact_filtered(const struct ast_sip_aor *aor,
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  */
1547 struct ao2_container *ast_sip_location_retrieve_aor_contacts(const struct ast_sip_aor *aor);
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  */
1563 struct ao2_container *ast_sip_location_retrieve_aor_contacts_filtered(const struct ast_sip_aor *aor,
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  */
1578 struct ao2_container *ast_sip_location_retrieve_aor_contacts_nolock(const struct ast_sip_aor *aor);
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  */
1593 struct ao2_container *ast_sip_location_retrieve_aor_contacts_nolock_filtered(const struct ast_sip_aor *aor,
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  */
1603 struct ast_sip_contact *ast_sip_location_retrieve_contact_from_aor_list(const char *aor_list);
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  */
1612 struct ao2_container *ast_sip_location_retrieve_contacts_from_aor_list(const char *aor_list);
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  */
1633 void 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  */
1644 struct 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  */
1666 int 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  */
1691 int ast_sip_location_add_contact_nolock(struct ast_sip_aor *aor, const char *uri,
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  */
1716 struct ast_sip_contact *ast_sip_location_create_contact(struct ast_sip_aor *aor,
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,
1719  int prune_on_boot, struct ast_sip_endpoint *endpoint);
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  */
1729 int ast_sip_location_update_contact(struct ast_sip_contact *contact);
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 */
1739 int ast_sip_location_delete_contact(struct ast_sip_contact *contact);
1740 
1741 /*!
1742  * \brief Prune the prune_on_boot contacts
1743  * \since 13.18.0
1744  */
1745 void ast_sip_location_prune_boot_contacts(void);
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  */
1763 typedef 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  */
1779 int ast_sip_dialog_setup_outbound_authentication(pjsip_dialog *dlg, const struct ast_sip_endpoint *endpoint,
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  */
1787 struct ast_sip_auth *ast_sip_get_artificial_auth(void);
1788 
1789 /*!
1790  * \brief Retrieves a reference to the artificial endpoint.
1791  *
1792  * \retval The artificial endpoint
1793  */
1794 struct ast_sip_endpoint *ast_sip_get_artificial_endpoint(void);
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 
1868 typedef 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  */
1883 struct ast_taskprocessor *ast_sip_create_serializer(const char *name);
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  */
1901 struct ast_taskprocessor *ast_sip_create_serializer_group(const char *name, struct ast_serializer_shutdown_group *shutdown_group);
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  */
1912 struct 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  */
1922 void 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  */
1930 void 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  */
1942 struct 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  */
1958 int 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  */
1994 int 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  */
2000 int 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  */
2044 int 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  */
2066  AST_SIP_SCHED_TASK_DEFAULTS = (0 << 0),
2067 
2068  /*!
2069  * Run at a fixed interval.
2070  * Stop scheduling if the callback returns <= 0.
2071  * Any other value is ignored.
2072  */
2073  AST_SIP_SCHED_TASK_FIXED = (0 << 0),
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  */
2079  AST_SIP_SCHED_TASK_VARIABLE = (1 << 0),
2080 
2081  /*!
2082  * Run just once.
2083  * Return values are ignored.
2084  */
2085  AST_SIP_SCHED_TASK_ONESHOT = (1 << 6),
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  */
2096  AST_SIP_SCHED_TASK_DATA_AO2 = (1 << 1),
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  */
2106  AST_SIP_SCHED_TASK_DATA_FREE = ( 1 << 3 ),
2107 
2108  /*!
2109  * \brief The task is scheduled at multiples of interval
2110  * \see Interval
2111  */
2112  AST_SIP_SCHED_TASK_PERIODIC = (0 << 4),
2113  /*!
2114  * \brief The next invocation of the task is at last finish + interval
2115  * \see Interval
2116  */
2117  AST_SIP_SCHED_TASK_DELAY = (1 << 4),
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  */
2124  AST_SIP_SCHED_TASK_TRACK = (1 << 5),
2125 };
2126 
2127 /*!
2128  * \brief Scheduler task data structure
2129  */
2130 struct 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  */
2191 int ast_sip_sched_task_cancel_by_name(const char *name);
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  */
2310 int ast_sip_sched_task_get_name(struct ast_sip_sched_task *schtd, char *name, size_t maxlen);
2312 /*!
2313  * @}
2314  */
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  */
2323 struct ast_sip_body {
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  */
2342 pjsip_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  */
2356 pjsip_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  */
2393 pjsip_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  */
2412 int 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  */
2430 int 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  */
2462 int 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  */
2485 int 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  */
2516 int 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  */
2538 int 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  */
2556 int 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  */
2574 int 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  */
2590 int 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  */
2605 enum ast_sip_check_auth_result ast_sip_check_authentication(struct ast_sip_endpoint *endpoint,
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  */
2616 int 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  */
2631 struct 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  */
2644 char *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  */
2654 int 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  */
2665 int 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  */
2675 pjsip_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  */
2689 int 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  */
2703 int 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  */
2716 int 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  */
2732 void 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  */
2750 int 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  */
2768 struct 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  */
2777 void 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  */
2784 struct ao2_container *ast_sip_get_endpoints(void);
2785 
2786 /*!
2787  * \brief Retrieve the default outbound endpoint.
2788  *
2789  * \retval The default outbound endpoint, NULL if not found.
2790  */
2791 struct ast_sip_endpoint *ast_sip_default_outbound_endpoint(void);
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  */
2799 int 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  */
2810 void 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  */
2832 int 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  */
2861 int 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  */
2869 void 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  */
2878 void 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  */
2886 void 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  */
2894 void 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  */
2903 void 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  */
2912 void 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  */
2921 void ast_sip_report_mem_limit(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2922 
2923 int ast_sip_add_global_request_header(const char *name, const char *value, int replace);
2924 int 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  */
2934 void *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  */
2962 void *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  */
2990 int 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  */
3001 int 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  */
3012 int 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  */
3022 int ast_sip_for_each_auth(const struct ast_sip_auth_vector *array,
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  */
3031 const char *ast_sip_auth_type_to_str(enum ast_sip_auth_type type);
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  */
3040 int ast_sip_auths_to_str(const struct ast_sip_auth_vector *auths, char **buf);
3042 /*!
3043  * \brief AMI variable container
3044  */
3045 struct ast_sip_ami {
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 */
3055  int count;
3056 };
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  */
3065 struct 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);
3077  AST_RWLIST_ENTRY(ast_sip_endpoint_formatter) next;
3078 };
3079 
3080 /*!
3081  * \brief Register an endpoint formatter.
3082  *
3083  * \param obj the formatter to register
3084  */
3085 void ast_sip_register_endpoint_formatter(struct ast_sip_endpoint_formatter *obj);
3086 
3087 /*!
3088  * \brief Unregister an endpoint formatter.
3089  *
3090  * \param obj the formatter to unregister
3091  */
3092 void ast_sip_unregister_endpoint_formatter(struct ast_sip_endpoint_formatter *obj);
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  */
3101 int 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  */
3111 int ast_sip_format_endpoint_ami(struct ast_sip_endpoint *endpoint,
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  */
3122 int 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  */
3131 int 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  */
3140 struct ast_endpoint_snapshot *ast_sip_get_endpoint_snapshot(
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  */
3149 const 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  */
3160 int 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  */
3173 int ast_sip_for_each_channel(const struct ast_sip_endpoint *endpoint,
3174  ao2_callback_fn on_channel_snapshot,
3175  void *arg);
3176 
3177 enum ast_sip_supplement_priority {
3178  /*! Top priority. Supplements with this priority are those that need to run before any others */
3179  AST_SIP_SUPPLEMENT_PRIORITY_FIRST = 0,
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  */
3184  AST_SIP_SUPPLEMENT_PRIORITY_CHANNEL = 1000000,
3185  /*! Lowest priority. Supplements with this priority should be run after all other supplements */
3186  AST_SIP_SUPPLEMENT_PRIORITY_LAST = INT_MAX,
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  */
3196 struct ast_sip_supplement {
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 */
3200  enum ast_sip_supplement_priority priority;
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  */
3259 void 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  */
3266 void 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  */
3275 unsigned 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  */
3284 int ast_sip_get_mwi_tps_queue_low(void);
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  */
3292 unsigned int ast_sip_get_mwi_disable_initial_unsolicited(void);
3293 
3294 /*!
3295  * \brief Retrieve the global setting 'allow_sending_180_after_183'.
3296  *
3297  * \retval non zero if disable.
3298  */
3299 unsigned int ast_sip_get_allow_sending_180_after_183(void);
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  */
3307 unsigned 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  */
3314 unsigned 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  */
3322 unsigned 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  */
3330 unsigned int ast_sip_get_send_contact_status_on_update_registration(void);
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  */
3364 char *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  */
3375 char *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  */
3384 char *ast_sip_get_endpoint_identifier_order(void);
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  */
3394 char *ast_sip_get_default_voicemail_extension(void);
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  */
3405 void 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  */
3417 void 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  */
3424 unsigned 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  */
3431 unsigned int ast_sip_get_contact_expiration_check_interval(void);
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  */
3439 unsigned 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  */
3446 unsigned 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 
3454 const char *ast_sip_get_contact_status_label(const enum ast_sip_contact_status_type status);
3455 const char *ast_sip_get_contact_short_status_label(const enum ast_sip_contact_status_type status);
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  */
3464 int 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  */
3477 int 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  */
3491 const 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  */
3497 long ast_sip_threadpool_queue_size(void);
3498 
3499 /*!
3500  * \brief Retrieve the SIP threadpool object
3501  */
3502 struct ast_threadpool *ast_sip_threadpool(void);
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  */
3513 struct 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  */
3524 pjsip_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  */
3534 struct ast_sip_transport_state *ast_sip_find_transport_state_in_use(struct ast_sip_request_transport_details *details);
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  */
3545 int 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  */
3560 int 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  */
3570 struct ao2_container *ast_sip_get_transport_states(void);
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  */
3583 int 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  */
3596 int 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  */
3604 void 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  */
3615 int 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  */
3626 int 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  */
3639 int 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  */
3648 void 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  */
3657 struct ast_sip_service_route_vector *ast_sip_service_route_vector_alloc(void);
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  */
3665 void ast_sip_service_route_vector_destroy(struct ast_sip_service_route_vector *service_routes);
3666 
3667 /*!
3668  * \brief Set the ID for a connected line update
3669  *
3670  * \retval -1 on failure, 0 on success
3671  */
3672 int 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  */
3684 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);
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  */
3693 void 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  */
3767 struct 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  */
3777 int 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  */
3793 int 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  */
3803 void 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  */
3823 int 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  */
3837 int ast_sip_set_tpselector_from_ep_or_uri(const struct ast_sip_endpoint *endpoint,
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  */
3856 int 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  */
3871 int ast_sip_dtmf_to_str(const enum ast_sip_dtmf_mode dtmf,
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  */
3884 int 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  */
3896 const 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  */
3909 int 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  */
3919 typedef 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  */
3931 typedef int (*ast_transport_monitor_data_matcher)(void *a, void *b);
3932 
3933 enum ast_transport_monitor_reg {
3934  /*! \brief Successfully registered the transport monitor */
3935  AST_TRANSPORT_MONITOR_REG_SUCCESS,
3936  /*! \brief Replaced the already existing transport monitor with new one. */
3937  AST_TRANSPORT_MONITOR_REG_REPLACED,
3938  /*!
3939  * \brief Transport not found to monitor.
3940  * \note Transport is either already shutdown or is not reliable.
3941  */
3942  AST_TRANSPORT_MONITOR_REG_NOT_FOUND,
3943  /*! \brief Error while registering transport monitor. */
3944  AST_TRANSPORT_MONITOR_REG_FAILED,
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  */
3964 enum ast_transport_monitor_reg ast_sip_transport_monitor_register(pjsip_transport *transport,
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  */
3983 enum ast_transport_monitor_reg ast_sip_transport_monitor_register_key(
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  */
4008 enum ast_transport_monitor_reg ast_sip_transport_monitor_register_replace(pjsip_transport *transport,
4009  ast_transport_monitor_shutdown_cb cb, void *ao2_data, ast_transport_monitor_data_matcher matches);
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  */
4030 enum ast_transport_monitor_reg ast_sip_transport_monitor_register_replace_key(
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  */
4049 void ast_sip_transport_monitor_unregister(pjsip_transport *transport,
4050  ast_transport_monitor_shutdown_cb cb, void *data, ast_transport_monitor_data_matcher matches);
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  */
4066 void ast_sip_transport_monitor_unregister_key(const char *transport_key,
4067  ast_transport_monitor_shutdown_cb cb, void *data, ast_transport_monitor_data_matcher matches);
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  */
4082 void ast_sip_transport_monitor_unregister_all(ast_transport_monitor_shutdown_cb cb,
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  */
4117 int 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  */
4128 int 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  */
4141 const 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  */
4154 const 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  */
4179 struct 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  */
4186 unsigned int ast_sip_get_all_codecs_on_empty_reinvite(void);
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  */
4196 const 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  */
4209 int ast_sip_str2rc(const char *name);
4210 
4211 #endif /* _RES_PJSIP_H */
enum ast_transport type
Definition: res_pjsip.h:133
unsigned int encryption_optimistic
Definition: res_pjsip.h:848
double qualify_timeout
Definition: res_pjsip.h:504
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.
struct ast_sip_endpoint_pickup_configuration pickup
Definition: res_pjsip.h:990
unsigned int maxdatagram
Definition: res_pjsip.h:881
Call pickup configuration options for endpoints.
Definition: res_pjsip.h:790
Information needed to identify an endpoint in a call.
Definition: channel.h:338
const char * body_text
Definition: res_pjsip.h:2315
int tcp_keepalive_idle_time
Definition: res_pjsip.h:305
int authenticate_qualify
Definition: res_pjsip.h:420
Definition: test_heap.c:38
struct ast_ha * localnet
Definition: res_pjsip.h:156
enum ast_sip_dtmf_mode dtmf
Definition: res_pjsip.h:996
struct ast_sip_mwi_configuration mwi
Definition: res_pjsip.h:743
struct stat privkey_file_stat
Definition: res_pjsip.h:208
struct ast_dnsmgr_entry * external_address_refresher
Definition: res_pjsip.h:277
enum ast_sip_contact_status_type last_status
Definition: res_pjsip.h:470
A contact's status.
Definition: res_pjsip.h:451
ast_sip_scheduler_task_flags
Task flags for the res_pjsip scheduler.
Definition: res_pjsip.h:2048
const ast_string_field mailboxes
Definition: res_pjsip.h:482
unsigned int sess_expires
Definition: res_pjsip.h:702
const ast_string_field fromuser
Definition: res_pjsip.h:966
A SIP address of record.
Definition: res_pjsip.h:478
char name[0]
Friendly name of the taskprocessor. Subsystem is appended after the name's NULL terminator.
Definition: taskprocessor.c:97
An entity responsible formatting endpoint information.
Definition: res_pjsip.h:3057
The task is scheduled at multiples of interval.
Definition: res_pjsip.h:2098
struct ast_flags outgoing_call_offer_pref
Definition: res_pjsip.h:935
Endpoint configuration options for INFO packages.
Definition: res_pjsip.h:816
const ast_string_field outbound_proxy
Definition: res_pjsip.h:414
int( ao2_callback_fn)(void *obj, void *arg, int flags)
Type of a generic callback function.
Definition: astobj2.h:1226
const ast_string_field oauth_secret
Definition: res_pjsip.h:593
const ast_string_field call_id
Definition: res_pjsip.h:414
const ast_string_field user_agent
Definition: res_pjsip.h:414
int ast_sip_security_mechanism_vector_init(struct ast_sip_security_mechanism_vector *security_mechanisms, const char *value)
Initialize security mechanism vector from string of security mechanisms.
struct ast_rtp_dtls_cfg dtls_cfg
DTLS-SRTP configuration information.
Definition: res_pjsip.h:842
struct timeval last_start
const ast_string_field path
Definition: res_pjsip.h:414
unsigned int remove_existing
Definition: res_pjsip.h:498
const ast_string_field transport
Definition: res_pjsip.h:954
void ast_sip_report_auth_success(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Send a security event notification for when authentication succeeds.
unsigned int devicestate_busy_at
Definition: res_pjsip.h:1006
const struct message * m
Definition: res_pjsip.h:3035
struct ast_sip_endpoint_nat_configuration nat
Definition: res_pjsip.h:984
int ast_sip_sched_task_cancel(struct ast_sip_sched_task *schtd)
Cancels the next invocation of a task.
const ast_string_field md5_creds
Definition: res_pjsip.h:587
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.
struct ast_sip_security_mechanism_vector security_mechanisms
Definition: res_pjsip.h:466
unsigned int max_contacts
Definition: res_pjsip.h:496
enum ast_t38_ec_modes error_correction
Definition: res_pjsip.h:879
Endpoint subscription configuration.
Definition: res_pjsip.h:737
int tcp_keepalive_probe_count
Definition: res_pjsip.h:309
const ast_string_field via_addr
Definition: res_pjsip.h:414
char * contact_user
Definition: res_pjsip.h:1026
const ast_string_field external_media_address
Definition: res_pjsip.h:241
struct ast_ha * localnet
Definition: res_pjsip.h:271
void * arg
Definition: res_pjsip.h:3039
AMI variable container.
Definition: res_pjsip.h:3031
const ast_string_field sdpsession
Definition: res_pjsip.h:899
unsigned int ignore_183_without_sdp
Definition: res_pjsip.h:1040
Party identification options for endpoints.
Definition: res_pjsip.h:763
Structure for variables, used for configurations and for channel variables.
static pj_pool_t * pool
Global memory pool for configuration and timers.
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.
UDPTL support for T.38.
struct ast_sip_auth_vector outbound_auths
Definition: res_pjsip.h:994
struct ast_sip_info_recording_configuration recording
Definition: res_pjsip.h:818
unsigned int asymmetric_rtp_codec
Definition: res_pjsip.h:1030
struct ast_format_cap * codecs
Definition: res_pjsip.h:907
struct ast_sip_endpoint_subscription_configuration subscription
Definition: res_pjsip.h:982
const ast_string_field context
Definition: res_pjsip.h:952
Full structure for sorcery.
Definition: sorcery.c:230
pjsip_tpfactory * factory
Potential pointer to the transport factory itself, if TCP/TLS.
Definition: res_pjsip.h:343
struct timeval when_queued
unsigned int send_aoc
Definition: res_pjsip.h:1058
enum ast_sip_session_refresh_method method
Definition: res_pjsip.h:868
#define SORCERY_OBJECT(details)
Macro which must be used at the beginning of each sorcery capable object.
Definition: sorcery.h:356
Definition: astman.c:222
Direct media options for SIP endpoints.
Definition: res_pjsip.h:864
Background DNS update manager.
unsigned int qualify_frequency
Definition: res_pjsip.h:418
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
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.
Wrapper for an ast_acl linked list.
Definition: acl.h:76
int(* create_request_with_auth)(const struct ast_sip_auth_vector *auths, struct pjsip_rx_data *challenge, struct pjsip_tx_data *old_request, struct pjsip_tx_data **new_request)
Create a new request with authentication credentials.
Definition: res_pjsip.h:1267
pj_sockaddr host
Definition: res_pjsip.h:249
Endpoint abstractions.
Definition: dnsmgr.c:66
Endpoint configuration for SIP extensions.
Definition: res_pjsip.h:711
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:1246
const ast_string_field outbound_proxy
Definition: res_pjsip.h:484
const ast_string_field reg_server
Definition: res_pjsip.h:414
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.
unsigned int cos
Definition: res_pjsip.h:293
const ast_string_field mailboxes
Definition: res_pjsip.h:723
struct ast_sip_transport_state * state
Definition: res_pjsip.h:289
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...
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 tcp_keepalive_interval_time
Definition: res_pjsip.h:307
const ast_string_field uri
Definition: res_pjsip.h:457
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.
enum ast_transport type
Definition: res_pjsip.h:243
unsigned int accept_multiple_sdp_answers
Definition: res_pjsip.h:858
Socket address structure.
Definition: netsock2.h:97
struct ast_sip_direct_media_configuration direct_media
Definition: res_pjsip.h:903
ast_endpoint_state
Valid states for an endpoint.
Definition: endpoints.h:51
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.
enum ast_sip_endpoint_identifier_type ident_method
Definition: res_pjsip.h:998
RTP configuration for SIP endpoints.
Definition: res_pjsip.h:824
unsigned int use_received_transport
Definition: res_pjsip.h:840
Media Stream API.
int ast_sip_sched_is_task_running(struct ast_sip_sched_task *schtd)
Checks if the task is currently running.
char * voicemail_extension
Definition: res_pjsip.h:506
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.
unsigned int inband_progress
Definition: res_pjsip.h:1002
const ast_string_field oauth_clientid
Definition: res_pjsip.h:591
struct ast_sockaddr external_address
Definition: res_pjsip.h:283
struct ast_acl_list * acl
Definition: res_pjsip.h:1020
struct stat cert_file_stat
Definition: res_pjsip.h:204
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.
struct ast_sip_security_mechanism_vector security_mechanisms
Definition: res_pjsip.h:1044
struct ast_sip_endpoint * endpoint
Definition: res_pjsip.h:424
struct ast_sip_endpoint_media_configuration media
Definition: res_pjsip.h:980
internal representation of ACL entries In principle user applications would have no need for this...
Definition: acl.h:51
const ast_string_field password
Definition: res_pjsip.h:241
struct ast_sockaddr external_media_address
Definition: res_pjsip.h:176
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.
const ast_string_field sdpowner
Definition: res_pjsip.h:897
unsigned int qualify_frequency
Definition: res_pjsip.h:492
Structure representing a security mechanism as defined in RFC 3329.
Definition: res_pjsip.h:378
unsigned int min_se
Definition: res_pjsip.h:700
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.
unsigned int remove_unavailable
Definition: res_pjsip.h:508
struct ast_sip_identify_by_vector ident_method_order
Definition: res_pjsip.h:1000
unsigned int follow_early_media_fork
Definition: res_pjsip.h:856
Structure for SIP nat hook information.
Definition: res_pjsip.h:329
const ast_string_field ca_list_path
Definition: res_pjsip.h:241
const ast_string_field endpoint_name
Definition: res_pjsip.h:414
int local_port
Local port for transport.
Definition: res_pjsip.h:347
Structure for SIP transport information.
Definition: res_pjsip.h:119
struct ast_namedgroups * named_pickupgroups
Definition: res_pjsip.h:798
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:515
General Asterisk PBX channel definitions.
void(* outgoing_external_message)(struct pjsip_tx_data *tdata, struct ast_sip_transport *transport)
Definition: res_pjsip.h:333
int ast_sip_sched_task_get_next_run_by_name(const char *name)
Gets the number of milliseconds until the next invocation.
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.
struct ast_acl_list * contact_acl
Definition: res_pjsip.h:1022
SORCERY_OBJECT(details)
const char * type
Definition: res_pjsip.h:2311
struct pjsip_transport * transport
Transport itself.
Definition: res_pjsip.h:121
const ast_string_field language
Definition: res_pjsip.h:964
pjsip_tls_setting tls
Definition: res_pjsip.h:143
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
unsigned int subscribe_replaces_unsolicited
Definition: res_pjsip.h:729
struct ast_sip_endpoint * ast_sip_dialog_get_endpoint(pjsip_dialog *dlg)
Get the endpoint associated with this dialog.
const ast_string_field engine
Definition: res_pjsip.h:826
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
struct ast_sip_media_rtp_configuration rtp
Definition: res_pjsip.h:901
const ast_string_field accountcode
Definition: res_pjsip.h:972
In case you didn't read that giant block of text above the mansession_session struct, the mansession is named this solely to keep the API the same in Asterisk. This structure really represents data that is different from Manager action to Manager action. The mansession_session pointer contained within points to session-specific data.
Definition: manager.c:1785
unsigned int notify_early_inuse_ringing
Definition: res_pjsip.h:1036
unsigned int nonce_lifetime
Definition: res_pjsip.h:595
const ast_string_field offfeature
Definition: res_pjsip.h:808
struct ast_stream_codec_negotiation_prefs codec_prefs_outgoing_answer
Definition: res_pjsip.h:943
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:1236
struct ast_namedgroups * named_callgroups
Definition: res_pjsip.h:796
struct mansession * s
Definition: res_pjsip.h:3033
A set of macros to manage forward-linked lists.
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
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.
double qualify_timeout
Definition: res_pjsip.h:422
#define AST_VECTOR(name, type)
Define a vector structure.
Definition: vector.h:44
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_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.
An entity with which Asterisk communicates.
Definition: res_pjsip.h:949
unsigned int support_path
Definition: res_pjsip.h:502
enum ast_sip_session_refresh_method refresh_method
Definition: res_pjsip.h:782
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_transport * transport
Potential pointer to the transport itself, if UDP.
Definition: res_pjsip.h:341
Network socket handling.
A snapshot of an endpoint's state.
SORCERY_OBJECT(details)
enum ast_transport type
Type of transport.
Definition: res_pjsip.h:339
const ast_string_field zone
Definition: res_pjsip.h:962
enum ast_sip_security_negotiation security_negotiation
Definition: res_pjsip.h:1042
enum ast_sip_contact_status_type status
Definition: res_pjsip.h:468
const ast_string_field outbound_proxy
Definition: res_pjsip.h:956
struct ast_sip_endpoint_id_configuration id
Definition: res_pjsip.h:986
struct ast_sip_contact * contact
Definition: res_pjsip.h:521
enum ast_sip_session_media_encryption encryption
Definition: res_pjsip.h:846
struct ast_sip_endpoint_info_configuration info
Definition: res_pjsip.h:988
const ast_string_field external_signaling_address
Definition: res_pjsip.h:241
unsigned int aggregate
Definition: res_pjsip.h:727
struct ast_sip_auth_vector inbound_auths
Definition: res_pjsip.h:992
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
Support for dynamic strings.
Definition: strings.h:623
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
int ast_sip_sched_is_task_running_by_name(const char *name)
Checks if the task is currently running.
const ast_string_field realm
Definition: res_pjsip.h:581
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_push_task(struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
Pushes a task to SIP servants.
Definition: res_pjsip.c:2099
Media configuration for SIP endpoints.
Definition: res_pjsip.h:893
Transport to bind to.
Definition: res_pjsip.h:221
const ast_string_field message_context
Definition: res_pjsip.h:970
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.
unsigned int async_operations
Definition: res_pjsip.h:251
Contact associated with an address of record.
Definition: res_pjsip.h:392
enum ast_sip_scheduler_task_flags flags
const char * subtype
Definition: res_pjsip.h:2313
struct ast_taskprocessor * ast_sip_create_serializer(const char *name)
Create a new serializer for SIP tasks.
Definition: res_pjsip.c:2094
userdata associated with baseline taskprocessor test
unsigned int faxdetect
Definition: res_pjsip.h:1008
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.
struct ast_sip_t38_configuration t38
Definition: res_pjsip.h:905
const char * action_id
Definition: res_pjsip.h:3037
struct ast_taskprocessor * ast_sip_get_distributor_serializer(pjsip_rx_data *rdata)
Determine the distributor serializer for the SIP message.
unsigned int faxdetect_timeout
Definition: res_pjsip.h:1024
const ast_string_field ca_list_file
Definition: res_pjsip.h:241
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
The next invocation of the task is at last finish + interval.
Definition: res_pjsip.h:2103
unsigned int preferred_codec_only
Definition: res_pjsip.h:1028
int ast_sip_sched_task_get_next_run(struct ast_sip_sched_task *schtd)
Gets the number of milliseconds until the next invocation.
const ast_string_field privkey_file
Definition: res_pjsip.h:241
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.
struct pjsip_tpfactory * factory
Transport factory.
Definition: res_pjsip.h:123
#define AST_MAX_CONTEXT
Definition: channel.h:135
struct timeval expiration_time
Definition: res_pjsip.h:416
Endpoint configuration for unsolicited MWI.
Definition: res_pjsip.h:721
enum ast_sip_direct_media_glare_mitigation glare_mitigation
Definition: res_pjsip.h:870
unsigned int moh_passthrough
Definition: res_pjsip.h:1018
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.
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:3061
const ast_string_field auth_pass
Definition: res_pjsip.h:585
struct ast_stream_codec_negotiation_prefs codec_prefs_incoming_answer
Definition: res_pjsip.h:941
unsigned int refer_blind_progress
Definition: res_pjsip.h:1034
struct ao2_container * permanent_contacts
Definition: res_pjsip.h:500
enum ast_sip_auth_type type
Definition: res_pjsip.h:597
unsigned int allowtransfer
Definition: res_pjsip.h:1010
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.
Vector container support.
pj_str_t local_address
Local address for transport.
Definition: res_pjsip.h:345
const ast_string_field domain
Definition: res_pjsip.h:241
An entity responsible for identifying the source of a SIP message.
Definition: res_pjsip.h:1274
const ast_string_field refresh_token
Definition: res_pjsip.h:589
const ast_string_field stir_shaken_profile
Definition: res_pjsip.h:976
Structure used to handle boolean flags.
Definition: utils.h:199
AST_STRING_FIELD_EXTENDED(geoloc_incoming_call_profile)
The scheduled task's events are tracked in the debug log.
Definition: res_pjsip.h:2110
struct ast_sockaddr external_signaling_address
Definition: res_pjsip.h:166
unsigned int external_signaling_port
Definition: res_pjsip.h:253
struct timeval last_end
struct ast_endpoint * persistent
Definition: res_pjsip.h:1004
unsigned int allow_overlap
Definition: res_pjsip.h:1032
const ast_string_field aor
Definition: res_pjsip.h:414
const ast_string_field onfeature
Definition: res_pjsip.h:806
int tcp_keepalive_enable
Definition: res_pjsip.h:303
An interchangeable way of handling digest authentication for SIP.
Definition: res_pjsip.h:1231
A ast_taskprocessor structure is a singleton by name.
Definition: taskprocessor.c:69
const ast_string_field incoming_mwi_mailbox
Definition: res_pjsip.h:974
enum ast_sip_100rel_mode rel100
Definition: res_pjsip.h:1056
struct ast_stream_topology * topology
Definition: res_pjsip.h:909
const ast_string_field fromuser
Definition: res_pjsip.h:725
const ast_string_field domain
Definition: res_pjsip.h:323
A supplement to SIP message processing.
Definition: res_pjsip.h:3182
An opaque threadpool structure.
Definition: threadpool.c:36
const ast_string_field mohsuggest
Definition: res_pjsip.h:960
pj_ssl_cipher ciphers[SIP_TLS_MAX_CIPHERS]
Definition: res_pjsip.h:265
unsigned int usereqphone
Definition: res_pjsip.h:1016
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 authenticate_qualify
Definition: res_pjsip.h:494
unsigned int allow_unauthenticated_options
Definition: res_pjsip.h:1048
struct ast_sip_endpoint_extensions extensions
Definition: res_pjsip.h:978
unsigned int bind_udptl_to_media_address
Definition: res_pjsip.h:887
unsigned int tos
Definition: res_pjsip.h:291
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.
SORCERY_OBJECT(details)
int ast_sip_str_to_security_mechanism(struct ast_sip_security_mechanism **security_mechanism, const char *value)
Allocate a security mechanism from a string.
struct ast_sip_service_route_vector * service_routes
Definition: res_pjsip.h:191
Generic container type.
Structure which contains information about a transport.
Definition: res_pjsip.h:337
struct ast_variable * channel_vars
Definition: res_pjsip.h:1014
unsigned int stir_shaken
Definition: res_pjsip.h:1046
String vector definitions.
Definition: vector.h:55
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.
an interchangeable way of responding to authentication challenges
Definition: res_pjsip.h:1256
int ast_sip_sched_task_get_name(struct ast_sip_sched_task *schtd, char *name, size_t maxlen)
Gets the task name.
NAT configuration options for endpoints.
Definition: res_pjsip.h:751
void ast_sip_transport_state_unregister(struct ast_sip_tpmgr_state_callback *element)
Unregister a transport state notification callback element.
const ast_string_field aors
Definition: res_pjsip.h:958
struct ast_flags incoming_call_offer_pref
Definition: res_pjsip.h:933
void ast_sip_security_mechanisms_vector_destroy(struct ast_sip_security_mechanism_vector *security_mechanisms)
Free contents of a security mechanism vector.
struct ast_dnsmgr_entry * external_media_address_refresher
Definition: res_pjsip.h:171
const ast_string_field uri
Definition: res_pjsip.h:414
Pluggable RTP Architecture.
unsigned int minimum_expiration
Definition: res_pjsip.h:486
unsigned int default_expiration
Definition: res_pjsip.h:490
unsigned int suppress_q850_reason_headers
Definition: res_pjsip.h:1038
struct ast_stream_codec_negotiation_prefs codec_prefs_outgoing_offer
Definition: res_pjsip.h:939
unsigned int maximum_expiration
Definition: res_pjsip.h:488
struct ast_stream_codec_negotiation_prefs codec_prefs_incoming_offer
Definition: res_pjsip.h:937
enum ast_sip_session_redirect redirect_method
Definition: res_pjsip.h:1012
Endpoint abstractions.
const ast_string_field auth_user
Definition: res_pjsip.h:583
SIP body description.
Definition: res_pjsip.h:2309
const ast_string_field aor
Definition: res_pjsip.h:457
pjsip_tls_setting tls
Definition: res_pjsip.h:259
void ast_sip_transport_state_register(struct ast_sip_tpmgr_state_callback *element)
Register a transport state notification callback element.
Session timers options.
Definition: res_pjsip.h:698
struct ast_dnsmgr_entry * external_signaling_address_refresher
Definition: res_pjsip.h:161
DTLS configuration structure.
Definition: rtp_engine.h:605
int ast_sip_sched_task_cancel_by_name(const char *name)
Cancels the next invocation of a task by name.
const ast_string_field cert_file
Definition: res_pjsip.h:241
Sorcery Data Access Layer API.
const ast_string_field fromdomain
Definition: res_pjsip.h:968
pj_ssl_cipher ciphers[SIP_TLS_MAX_CIPHERS]
Definition: res_pjsip.h:148
Configuration for one-touch INFO recording.
Definition: res_pjsip.h:804