8c589ef85ea8bd84c286cd8d65cf334f6cbbce49
[asterisk/asterisk.git] / include / asterisk / 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 #include <pjlib.h>
28
29 #include "asterisk/stringfields.h"
30 /* Needed for struct ast_sockaddr */
31 #include "asterisk/netsock2.h"
32 /* Needed for linked list macros */
33 #include "asterisk/linkedlists.h"
34 /* Needed for ast_party_id */
35 #include "asterisk/channel.h"
36 /* Needed for ast_sorcery */
37 #include "asterisk/sorcery.h"
38 /* Needed for ast_dnsmgr */
39 #include "asterisk/dnsmgr.h"
40 /* Needed for ast_endpoint */
41 #include "asterisk/endpoints.h"
42 /* Needed for ast_t38_ec_modes */
43 #include "asterisk/udptl.h"
44 /* Needed for pj_sockaddr */
45 #include <pjlib.h>
46 /* Needed for ast_rtp_dtls_cfg struct */
47 #include "asterisk/rtp_engine.h"
48 /* Needed for AST_VECTOR macro */
49 #include "asterisk/vector.h"
50 /* Needed for ast_sip_for_each_channel_snapshot struct */
51 #include "asterisk/stasis_channels.h"
52 #include "asterisk/stasis_endpoints.h"
53
54 /* Forward declarations of PJSIP stuff */
55 struct pjsip_rx_data;
56 struct pjsip_module;
57 struct pjsip_tx_data;
58 struct pjsip_dialog;
59 struct pjsip_transport;
60 struct pjsip_tpfactory;
61 struct pjsip_tls_setting;
62 struct pjsip_tpselector;
63
64 /*! \brief Maximum number of ciphers supported for a TLS transport */
65 #define SIP_TLS_MAX_CIPHERS 64
66
67 /*!
68  * \brief Structure for SIP transport information
69  */
70 struct ast_sip_transport_state {
71         /*! \brief Transport itself */
72         struct pjsip_transport *transport;
73         /*! \brief Transport factory */
74         struct pjsip_tpfactory *factory;
75         /*!
76          * Transport id
77          * \since 13.8.0
78          */
79         char *id;
80         /*!
81          * Transport type
82          * \since 13.8.0
83          */
84         enum ast_transport type;
85         /*!
86          * Address and port to bind to
87          * \since 13.8.0
88          */
89         pj_sockaddr host;
90         /*!
91          * TLS settings
92          * \since 13.8.0
93          */
94         pjsip_tls_setting tls;
95         /*!
96          * Configured TLS ciphers
97          * \since 13.8.0
98          */
99         pj_ssl_cipher ciphers[SIP_TLS_MAX_CIPHERS];
100         /*!
101          * Optional local network information, used for NAT purposes
102          * \since 13.8.0
103          */
104         struct ast_ha *localnet;
105         /*!
106          * DNS manager for refreshing the external address
107          * \since 13.8.0
108          */
109         struct ast_dnsmgr_entry *external_address_refresher;
110         /*!
111          * Optional external address information
112          * \since 13.8.0
113          */
114         struct ast_sockaddr external_address;
115 };
116
117 /*
118  * \brief Transport to bind to
119  */
120 struct ast_sip_transport {
121         /*! Sorcery object details */
122         SORCERY_OBJECT(details);
123         AST_DECLARE_STRING_FIELDS(
124                 /*! Certificate of authority list file */
125                 AST_STRING_FIELD(ca_list_file);
126                 /*! Certificate of authority list path */
127                 AST_STRING_FIELD(ca_list_path);
128                 /*! Public certificate file */
129                 AST_STRING_FIELD(cert_file);
130                 /*! Optional private key of the certificate file */
131                 AST_STRING_FIELD(privkey_file);
132                 /*! Password to open the private key */
133                 AST_STRING_FIELD(password);
134                 /*! External signaling address */
135                 AST_STRING_FIELD(external_signaling_address);
136                 /*! External media address */
137                 AST_STRING_FIELD(external_media_address);
138                 /*! Optional domain to use for messages if provided could not be found */
139                 AST_STRING_FIELD(domain);
140                 );
141         /*! Type of transport */
142         enum ast_transport type;
143         /*!
144          * \deprecated Moved to ast_sip_transport_state
145          * \version 13.8.0 deprecated
146          * Address and port to bind to
147          */
148         pj_sockaddr host;
149         /*! Number of simultaneous asynchronous operations */
150         unsigned int async_operations;
151         /*! Optional external port for signaling */
152         unsigned int external_signaling_port;
153         /*!
154          * \deprecated Moved to ast_sip_transport_state
155          * \version 13.7.1 deprecated
156          * TLS settings
157          */
158         pjsip_tls_setting tls;
159         /*!
160          * \deprecated Moved to ast_sip_transport_state
161          * \version 13.7.1 deprecated
162          * Configured TLS ciphers
163          */
164         pj_ssl_cipher ciphers[SIP_TLS_MAX_CIPHERS];
165         /*!
166          * \deprecated Moved to ast_sip_transport_state
167          * \version 13.7.1 deprecated
168          * Optional local network information, used for NAT purposes
169          */
170         struct ast_ha *localnet;
171         /*!
172          * \deprecated Moved to ast_sip_transport_state
173          * \version 13.7.1 deprecated
174          * DNS manager for refreshing the external address
175          */
176         struct ast_dnsmgr_entry *external_address_refresher;
177         /*!
178          * \deprecated Moved to ast_sip_transport_state
179          * \version 13.7.1 deprecated
180          * Optional external address information
181          */
182         struct ast_sockaddr external_address;
183         /*!
184          * \deprecated
185          * \version 13.7.1 deprecated
186          * Transport state information
187          */
188         struct ast_sip_transport_state *state;
189         /*! QOS DSCP TOS bits */
190         unsigned int tos;
191         /*! QOS COS value */
192         unsigned int cos;
193         /*! Write timeout */
194         int write_timeout;
195         /*! Allow reload */
196         int allow_reload;
197         /*! Automatically send requests out the same transport requests have come in on */
198         int symmetric_transport;
199 };
200
201 #define SIP_SORCERY_DOMAIN_ALIAS_TYPE "domain_alias"
202
203 /*!
204  * Details about a SIP domain alias
205  */
206 struct ast_sip_domain_alias {
207         /*! Sorcery object details */
208         SORCERY_OBJECT(details);
209         AST_DECLARE_STRING_FIELDS(
210                 /*! Domain to be aliased to */
211                 AST_STRING_FIELD(domain);
212         );
213 };
214
215 /*!
216  * \brief Structure for SIP nat hook information
217  */
218 struct ast_sip_nat_hook {
219         /*! Sorcery object details */
220         SORCERY_OBJECT(details);
221         /*! Callback for when a message is going outside of our local network */
222         void (*outgoing_external_message)(struct pjsip_tx_data *tdata, struct ast_sip_transport *transport);
223 };
224
225 /*!
226  * \brief Contact associated with an address of record
227  */
228 struct ast_sip_contact {
229         /*! Sorcery object details, the id is the aor name plus a random string */
230         SORCERY_OBJECT(details);
231         AST_DECLARE_STRING_FIELDS(
232                 /*! Full URI of the contact */
233                 AST_STRING_FIELD(uri);
234                 /*! Outbound proxy to use for qualify */
235                 AST_STRING_FIELD(outbound_proxy);
236                 /*! Path information to place in Route headers */
237                 AST_STRING_FIELD(path);
238                 /*! Content of the User-Agent header in REGISTER request */
239                 AST_STRING_FIELD(user_agent);
240                 /*! The name of the aor this contact belongs to */
241                 AST_STRING_FIELD(aor);
242         );
243         /*! Absolute time that this contact is no longer valid after */
244         struct timeval expiration_time;
245         /*! Frequency to send OPTIONS requests to contact. 0 is disabled. */
246         unsigned int qualify_frequency;
247         /*! If true authenticate the qualify if needed */
248         int authenticate_qualify;
249         /*! Qualify timeout. 0 is diabled. */
250         double qualify_timeout;
251         /*! Endpoint that added the contact, only available in observers */
252         struct ast_sip_endpoint *endpoint;
253         /*! Asterisk Server name */
254         AST_STRING_FIELD_EXTENDED(reg_server);
255         /*! IP-address of the Via header in REGISTER request */
256         AST_STRING_FIELD_EXTENDED(via_addr);
257         /* Port of the Via header in REGISTER request */
258         int via_port;
259         /*! Content of the Call-ID header in REGISTER request */
260         AST_STRING_FIELD_EXTENDED(call_id);
261         /*! The name of the endpoint that added the contact */
262         AST_STRING_FIELD_EXTENDED(endpoint_name);
263 };
264
265 #define CONTACT_STATUS "contact_status"
266
267 /*!
268  * \brief Status type for a contact.
269  */
270 enum ast_sip_contact_status_type {
271         UNAVAILABLE,
272         AVAILABLE,
273         UNKNOWN,
274         CREATED,
275         REMOVED,
276 };
277
278 /*!
279  * \brief A contact's status.
280  *
281  * \detail Maintains a contact's current status and round trip time
282  *         if available.
283  */
284 struct ast_sip_contact_status {
285         SORCERY_OBJECT(details);
286         AST_DECLARE_STRING_FIELDS(
287                 /*! The original contact's URI */
288                 AST_STRING_FIELD(uri);
289                 /*! The name of the aor this contact_status belongs to */
290                 AST_STRING_FIELD(aor);
291         );
292         /*! Current status for a contact (default - unavailable) */
293         enum ast_sip_contact_status_type status;
294         /*! The round trip start time set before sending a qualify request */
295         struct timeval rtt_start;
296         /*! The round trip time in microseconds */
297         int64_t rtt;
298         /*! Last status for a contact (default - unavailable) */
299         enum ast_sip_contact_status_type last_status;
300         /*! TRUE if the contact was refreshed. e.g., re-registered */
301         unsigned int refresh:1;
302 };
303
304 /*!
305  * \brief A SIP address of record
306  */
307 struct ast_sip_aor {
308         /*! Sorcery object details, the id is the AOR name */
309         SORCERY_OBJECT(details);
310         AST_DECLARE_STRING_FIELDS(
311                 /*! Voicemail boxes for this AOR */
312                 AST_STRING_FIELD(mailboxes);
313                 /*! Outbound proxy for OPTIONS requests */
314                 AST_STRING_FIELD(outbound_proxy);
315         );
316         /*! Minimum expiration time */
317         unsigned int minimum_expiration;
318         /*! Maximum expiration time */
319         unsigned int maximum_expiration;
320         /*! Default contact expiration if one is not provided in the contact */
321         unsigned int default_expiration;
322         /*! Frequency to send OPTIONS requests to AOR contacts. 0 is disabled. */
323         unsigned int qualify_frequency;
324         /*! If true authenticate the qualify if needed */
325         int authenticate_qualify;
326         /*! Maximum number of external contacts, 0 to disable */
327         unsigned int max_contacts;
328         /*! Whether to remove any existing contacts not related to an incoming REGISTER when it comes in */
329         unsigned int remove_existing;
330         /*! Any permanent configured contacts */
331         struct ao2_container *permanent_contacts;
332         /*! Determines whether SIP Path headers are supported */
333         unsigned int support_path;
334         /*! Qualify timeout. 0 is diabled. */
335         double qualify_timeout;
336         /* Voicemail extension to set in Message-Account */
337         char *voicemail_extension;
338 };
339
340 /*!
341  * \brief A wrapper for contact that adds the aor_id and
342  * a consistent contact id.  Used by ast_sip_for_each_contact.
343  */
344 struct ast_sip_contact_wrapper {
345         /*! The id of the parent aor. */
346         char *aor_id;
347         /*! The id of contact in form of aor_id/contact_uri. */
348         char *contact_id;
349         /*! Pointer to the actual contact. */
350         struct ast_sip_contact *contact;
351 };
352
353 /*!
354  * \brief DTMF modes for SIP endpoints
355  */
356 enum ast_sip_dtmf_mode {
357         /*! No DTMF to be used */
358         AST_SIP_DTMF_NONE,
359         /* XXX Should this be 2833 instead? */
360         /*! Use RFC 4733 events for DTMF */
361         AST_SIP_DTMF_RFC_4733,
362         /*! Use DTMF in the audio stream */
363         AST_SIP_DTMF_INBAND,
364         /*! Use SIP INFO DTMF (blech) */
365         AST_SIP_DTMF_INFO,
366         /*! Use SIP 4733 if supported by the other side or INBAND if not */
367         AST_SIP_DTMF_AUTO,
368 };
369
370 /*!
371  * \brief Methods of storing SIP digest authentication credentials.
372  *
373  * Note that both methods result in MD5 digest authentication being
374  * used. The two methods simply alter how Asterisk determines the
375  * credentials for a SIP authentication
376  */
377 enum ast_sip_auth_type {
378         /*! Credentials stored as a username and password combination */
379         AST_SIP_AUTH_TYPE_USER_PASS,
380         /*! Credentials stored as an MD5 sum */
381         AST_SIP_AUTH_TYPE_MD5,
382         /*! Credentials not stored this is a fake auth */
383         AST_SIP_AUTH_TYPE_ARTIFICIAL
384 };
385
386 #define SIP_SORCERY_AUTH_TYPE "auth"
387
388 struct ast_sip_auth {
389         /*! Sorcery ID of the auth is its name */
390         SORCERY_OBJECT(details);
391         AST_DECLARE_STRING_FIELDS(
392                 /*! Identification for these credentials */
393                 AST_STRING_FIELD(realm);
394                 /*! Authentication username */
395                 AST_STRING_FIELD(auth_user);
396                 /*! Authentication password */
397                 AST_STRING_FIELD(auth_pass);
398                 /*! Authentication credentials in MD5 format (hash of user:realm:pass) */
399                 AST_STRING_FIELD(md5_creds);
400         );
401         /*! The time period (in seconds) that a nonce may be reused */
402         unsigned int nonce_lifetime;
403         /*! Used to determine what to use when authenticating */
404         enum ast_sip_auth_type type;
405 };
406
407 AST_VECTOR(ast_sip_auth_vector, const char *);
408
409 /*!
410  * \brief Different methods by which incoming requests can be matched to endpoints
411  */
412 enum ast_sip_endpoint_identifier_type {
413         /*! Identify based on user name in From header */
414         AST_SIP_ENDPOINT_IDENTIFY_BY_USERNAME = (1 << 0),
415         /*! Identify based on user name in Auth header first, then From header */
416         AST_SIP_ENDPOINT_IDENTIFY_BY_AUTH_USERNAME = (1 << 1),
417 };
418 AST_VECTOR(ast_sip_identify_by_vector, enum ast_sip_endpoint_identifier_type);
419
420 enum ast_sip_session_refresh_method {
421         /*! Use reinvite to negotiate direct media */
422         AST_SIP_SESSION_REFRESH_METHOD_INVITE,
423         /*! Use UPDATE to negotiate direct media */
424         AST_SIP_SESSION_REFRESH_METHOD_UPDATE,
425 };
426
427 enum ast_sip_direct_media_glare_mitigation {
428         /*! Take no special action to mitigate reinvite glare */
429         AST_SIP_DIRECT_MEDIA_GLARE_MITIGATION_NONE,
430         /*! Do not send an initial direct media session refresh on outgoing call legs
431          * Subsequent session refreshes will be sent no matter the session direction
432          */
433         AST_SIP_DIRECT_MEDIA_GLARE_MITIGATION_OUTGOING,
434         /*! Do not send an initial direct media session refresh on incoming call legs
435          * Subsequent session refreshes will be sent no matter the session direction
436          */
437         AST_SIP_DIRECT_MEDIA_GLARE_MITIGATION_INCOMING,
438 };
439
440 enum ast_sip_session_media_encryption {
441         /*! Invalid media encryption configuration */
442         AST_SIP_MEDIA_TRANSPORT_INVALID = 0,
443         /*! Do not allow any encryption of session media */
444         AST_SIP_MEDIA_ENCRYPT_NONE,
445         /*! Offer SDES-encrypted session media */
446         AST_SIP_MEDIA_ENCRYPT_SDES,
447         /*! Offer encrypted session media with datagram TLS key exchange */
448         AST_SIP_MEDIA_ENCRYPT_DTLS,
449 };
450
451 enum ast_sip_session_redirect {
452         /*! User portion of the target URI should be used as the target in the dialplan */
453         AST_SIP_REDIRECT_USER = 0,
454         /*! Target URI should be used as the target in the dialplan */
455         AST_SIP_REDIRECT_URI_CORE,
456         /*! Target URI should be used as the target within chan_pjsip itself */
457         AST_SIP_REDIRECT_URI_PJSIP,
458 };
459
460 /*!
461  * \brief Session timers options
462  */
463 struct ast_sip_timer_options {
464         /*! Minimum session expiration period, in seconds */
465         unsigned int min_se;
466         /*! Session expiration period, in seconds */
467         unsigned int sess_expires;
468 };
469
470 /*!
471  * \brief Endpoint configuration for SIP extensions.
472  *
473  * SIP extensions, in this case refers to features
474  * indicated in Supported or Required headers.
475  */
476 struct ast_sip_endpoint_extensions {
477         /*! Enabled SIP extensions */
478         unsigned int flags;
479         /*! Timer options */
480         struct ast_sip_timer_options timer;
481 };
482
483 /*!
484  * \brief Endpoint configuration for unsolicited MWI
485  */
486 struct ast_sip_mwi_configuration {
487         AST_DECLARE_STRING_FIELDS(
488                 /*! Configured voicemail boxes for this endpoint. Used for MWI */
489                 AST_STRING_FIELD(mailboxes);
490                 /*! Username to use when sending MWI NOTIFYs to this endpoint */
491                 AST_STRING_FIELD(fromuser);
492         );
493         /* Should mailbox states be combined into a single notification? */
494         unsigned int aggregate;
495         /* Should a subscribe replace unsolicited notifies? */
496         unsigned int subscribe_replaces_unsolicited;
497         /* Voicemail extension to set in Message-Account */
498         char *voicemail_extension;
499 };
500
501 /*!
502  * \brief Endpoint subscription configuration
503  */
504 struct ast_sip_endpoint_subscription_configuration {
505         /*! Indicates if endpoint is allowed to initiate subscriptions */
506         unsigned int allow;
507         /*! The minimum allowed expiration for subscriptions from endpoint */
508         unsigned int minexpiry;
509         /*! Message waiting configuration */
510         struct ast_sip_mwi_configuration mwi;
511         /* Context for SUBSCRIBE requests */
512         char context[AST_MAX_CONTEXT];
513 };
514
515 /*!
516  * \brief NAT configuration options for endpoints
517  */
518 struct ast_sip_endpoint_nat_configuration {
519         /*! Whether to force using the source IP address/port for sending responses */
520         unsigned int force_rport;
521         /*! Whether to rewrite the Contact header with the source IP address/port or not */
522         unsigned int rewrite_contact;
523 };
524
525 /*!
526  * \brief Party identification options for endpoints
527  *
528  * This includes caller ID, connected line, and redirecting-related options
529  */
530 struct ast_sip_endpoint_id_configuration {
531         struct ast_party_id self;
532         /*! Do we accept identification information from this endpoint */
533         unsigned int trust_inbound;
534         /*! Do we send private identification information to this endpoint? */
535         unsigned int trust_outbound;
536         /*! Do we send P-Asserted-Identity headers to this endpoint? */
537         unsigned int send_pai;
538         /*! Do we send Remote-Party-ID headers to this endpoint? */
539         unsigned int send_rpid;
540         /*! Do we send messages for connected line updates for unanswered incoming calls immediately to this endpoint? */
541         unsigned int rpid_immediate;
542         /*! Do we add Diversion headers to applicable outgoing requests/responses? */
543         unsigned int send_diversion;
544         /*! When performing connected line update, which method should be used */
545         enum ast_sip_session_refresh_method refresh_method;
546 };
547
548 /*!
549  * \brief Call pickup configuration options for endpoints
550  */
551 struct ast_sip_endpoint_pickup_configuration {
552         /*! Call group */
553         ast_group_t callgroup;
554         /*! Pickup group */
555         ast_group_t pickupgroup;
556         /*! Named call group */
557         struct ast_namedgroups *named_callgroups;
558         /*! Named pickup group */
559         struct ast_namedgroups *named_pickupgroups;
560 };
561
562 /*!
563  * \brief Configuration for one-touch INFO recording
564  */
565 struct ast_sip_info_recording_configuration {
566         AST_DECLARE_STRING_FIELDS(
567                 /*! Feature to enact when one-touch recording INFO with Record: On is received */
568                 AST_STRING_FIELD(onfeature);
569                 /*! Feature to enact when one-touch recording INFO with Record: Off is received */
570                 AST_STRING_FIELD(offfeature);
571         );
572         /*! Is one-touch recording permitted? */
573         unsigned int enabled;
574 };
575
576 /*!
577  * \brief Endpoint configuration options for INFO packages
578  */
579 struct ast_sip_endpoint_info_configuration {
580         /*! Configuration for one-touch recording */
581         struct ast_sip_info_recording_configuration recording;
582 };
583
584 /*!
585  * \brief RTP configuration for SIP endpoints
586  */
587 struct ast_sip_media_rtp_configuration {
588         AST_DECLARE_STRING_FIELDS(
589                 /*! Configured RTP engine for this endpoint. */
590                 AST_STRING_FIELD(engine);
591         );
592         /*! Whether IPv6 RTP is enabled or not */
593         unsigned int ipv6;
594         /*! Whether symmetric RTP is enabled or not */
595         unsigned int symmetric;
596         /*! Whether ICE support is enabled or not */
597         unsigned int ice_support;
598         /*! Whether to use the "ptime" attribute received from the endpoint or not */
599         unsigned int use_ptime;
600         /*! Do we use AVPF exclusively for this endpoint? */
601         unsigned int use_avpf;
602         /*! Do we force AVP, AVPF, SAVP, or SAVPF even for DTLS media streams? */
603         unsigned int force_avp;
604         /*! Do we use the received media transport in our answer SDP */
605         unsigned int use_received_transport;
606         /*! \brief DTLS-SRTP configuration information */
607         struct ast_rtp_dtls_cfg dtls_cfg;
608         /*! Should SRTP use a 32 byte tag instead of an 80 byte tag? */
609         unsigned int srtp_tag_32;
610         /*! Do we use media encryption? what type? */
611         enum ast_sip_session_media_encryption encryption;
612         /*! Do we want to optimistically support encryption if possible? */
613         unsigned int encryption_optimistic;
614         /*! Number of seconds between RTP keepalive packets */
615         unsigned int keepalive;
616         /*! Number of seconds before terminating channel due to lack of RTP (when not on hold) */
617         unsigned int timeout;
618         /*! Number of seconds before terminating channel due to lack of RTP (when on hold) */
619         unsigned int timeout_hold;
620 };
621
622 /*!
623  * \brief Direct media options for SIP endpoints
624  */
625 struct ast_sip_direct_media_configuration {
626         /*! Boolean indicating if direct_media is permissible */
627         unsigned int enabled;
628         /*! When using direct media, which method should be used */
629         enum ast_sip_session_refresh_method method;
630         /*! Take steps to mitigate glare for direct media */
631         enum ast_sip_direct_media_glare_mitigation glare_mitigation;
632         /*! Do not attempt direct media session refreshes if a media NAT is detected */
633         unsigned int disable_on_nat;
634 };
635
636 struct ast_sip_t38_configuration {
637         /*! Whether T.38 UDPTL support is enabled or not */
638         unsigned int enabled;
639         /*! Error correction setting for T.38 UDPTL */
640         enum ast_t38_ec_modes error_correction;
641         /*! Explicit T.38 max datagram value, may be 0 to indicate the remote side can be trusted */
642         unsigned int maxdatagram;
643         /*! Whether NAT Support is enabled for T.38 UDPTL sessions or not */
644         unsigned int nat;
645         /*! Whether to use IPv6 for UDPTL or not */
646         unsigned int ipv6;
647 };
648
649 /*!
650  * \brief Media configuration for SIP endpoints
651  */
652 struct ast_sip_endpoint_media_configuration {
653         AST_DECLARE_STRING_FIELDS(
654                 /*! Optional media address to use in SDP */
655                 AST_STRING_FIELD(address);
656                 /*! SDP origin username */
657                 AST_STRING_FIELD(sdpowner);
658                 /*! SDP session name */
659                 AST_STRING_FIELD(sdpsession);
660         );
661         /*! RTP media configuration */
662         struct ast_sip_media_rtp_configuration rtp;
663         /*! Direct media options */
664         struct ast_sip_direct_media_configuration direct_media;
665         /*! T.38 (FoIP) options */
666         struct ast_sip_t38_configuration t38;
667         /*! Configured codecs */
668         struct ast_format_cap *codecs;
669         /*! DSCP TOS bits for audio streams */
670         unsigned int tos_audio;
671         /*! Priority for audio streams */
672         unsigned int cos_audio;
673         /*! DSCP TOS bits for video streams */
674         unsigned int tos_video;
675         /*! Priority for video streams */
676         unsigned int cos_video;
677         /*! Is g.726 packed in a non standard way */
678         unsigned int g726_non_standard;
679         /*! Bind the RTP instance to the media_address */
680         unsigned int bind_rtp_to_media_address;
681         /*! Use RTCP-MUX */
682         unsigned int rtcp_mux;
683 };
684
685 /*!
686  * \brief An entity with which Asterisk communicates
687  */
688 struct ast_sip_endpoint {
689         SORCERY_OBJECT(details);
690         AST_DECLARE_STRING_FIELDS(
691                 /*! Context to send incoming calls to */
692                 AST_STRING_FIELD(context);
693                 /*! Name of an explicit transport to use */
694                 AST_STRING_FIELD(transport);
695                 /*! Outbound proxy to use */
696                 AST_STRING_FIELD(outbound_proxy);
697                 /*! Explicit AORs to dial if none are specified */
698                 AST_STRING_FIELD(aors);
699                 /*! Musiconhold class to suggest that the other side use when placing on hold */
700                 AST_STRING_FIELD(mohsuggest);
701                 /*! Configured tone zone for this endpoint. */
702                 AST_STRING_FIELD(zone);
703                 /*! Configured language for this endpoint. */
704                 AST_STRING_FIELD(language);
705                 /*! Default username to place in From header */
706                 AST_STRING_FIELD(fromuser);
707                 /*! Domain to place in From header */
708                 AST_STRING_FIELD(fromdomain);
709                 /*! Context to route incoming MESSAGE requests to */
710                 AST_STRING_FIELD(message_context);
711                 /*! Accountcode to auto-set on channels */
712                 AST_STRING_FIELD(accountcode);
713         );
714         /*! Configuration for extensions */
715         struct ast_sip_endpoint_extensions extensions;
716         /*! Configuration relating to media */
717         struct ast_sip_endpoint_media_configuration media;
718         /*! SUBSCRIBE/NOTIFY configuration options */
719         struct ast_sip_endpoint_subscription_configuration subscription;
720         /*! NAT configuration */
721         struct ast_sip_endpoint_nat_configuration nat;
722         /*! Party identification options */
723         struct ast_sip_endpoint_id_configuration id;
724         /*! Configuration options for INFO packages */
725         struct ast_sip_endpoint_info_configuration info;
726         /*! Call pickup configuration */
727         struct ast_sip_endpoint_pickup_configuration pickup;
728         /*! Inbound authentication credentials */
729         struct ast_sip_auth_vector inbound_auths;
730         /*! Outbound authentication credentials */
731         struct ast_sip_auth_vector outbound_auths;
732         /*! DTMF mode to use with this endpoint */
733         enum ast_sip_dtmf_mode dtmf;
734         /*! Method(s) by which the endpoint should be identified. */
735         enum ast_sip_endpoint_identifier_type ident_method;
736         /*! Order of the method(s) by which the endpoint should be identified. */
737         struct ast_sip_identify_by_vector ident_method_order;
738         /*! Boolean indicating if ringing should be sent as inband progress */
739         unsigned int inband_progress;
740         /*! Pointer to the persistent Asterisk endpoint */
741         struct ast_endpoint *persistent;
742         /*! The number of channels at which busy device state is returned */
743         unsigned int devicestate_busy_at;
744         /*! Whether fax detection is enabled or not (CNG tone detection) */
745         unsigned int faxdetect;
746         /*! Determines if transfers (using REFER) are allowed by this endpoint */
747         unsigned int allowtransfer;
748         /*! Method used when handling redirects */
749         enum ast_sip_session_redirect redirect_method;
750         /*! Variables set on channel creation */
751         struct ast_variable *channel_vars;
752         /*! Whether to place a 'user=phone' parameter into the request URI if user is a number */
753         unsigned int usereqphone;
754         /*! Whether to pass through hold and unhold using re-invites with recvonly and sendrecv */
755         unsigned int moh_passthrough;
756         /*! Access control list */
757         struct ast_acl_list *acl;
758         /*! Restrict what IPs are allowed in the Contact header (for registration) */
759         struct ast_acl_list *contact_acl;
760         /*! The number of seconds into call to disable fax detection.  (0 = disabled) */
761         unsigned int faxdetect_timeout;
762         /*! Override the user on the outgoing Contact header with this value. */
763         char *contact_user;
764         /*! Whether to response SDP offer with single most preferred codec. */
765         unsigned int preferred_codec_only;
766         /*! Do we allow an asymmetric RTP codec? */
767         unsigned int asymmetric_rtp_codec;
768         /*! Do we allow overlap dialling? */
769         unsigned int allow_overlap;
770         /*! Whether to notifies all the progress details on blind transfer */
771         unsigned int refer_blind_progress;
772 };
773
774 /*! URI parameter for symmetric transport */
775 #define AST_SIP_X_AST_TXP "x-ast-txp"
776 #define AST_SIP_X_AST_TXP_LEN 9
777
778 /*!
779  * \brief Initialize an auth vector with the configured values.
780  *
781  * \param vector Vector to initialize
782  * \param auth_names Comma-separated list of names to set in the array
783  * \retval 0 Success
784  * \retval non-zero Failure
785  */
786 int ast_sip_auth_vector_init(struct ast_sip_auth_vector *vector, const char *auth_names);
787
788 /*!
789  * \brief Free contents of an auth vector.
790  *
791  * \param array Vector whose contents are to be freed
792  */
793 void ast_sip_auth_vector_destroy(struct ast_sip_auth_vector *vector);
794
795 /*!
796  * \brief Possible returns from ast_sip_check_authentication
797  */
798 enum ast_sip_check_auth_result {
799     /*! Authentication needs to be challenged */
800     AST_SIP_AUTHENTICATION_CHALLENGE,
801     /*! Authentication succeeded */
802     AST_SIP_AUTHENTICATION_SUCCESS,
803     /*! Authentication failed */
804     AST_SIP_AUTHENTICATION_FAILED,
805     /*! Authentication encountered some internal error */
806     AST_SIP_AUTHENTICATION_ERROR,
807 };
808
809 /*!
810  * \brief An interchangeable way of handling digest authentication for SIP.
811  *
812  * An authenticator is responsible for filling in the callbacks provided below. Each is called from a publicly available
813  * function in res_sip. The authenticator can use configuration or other local policy to determine whether authentication
814  * should take place and what credentials should be used when challenging and authenticating a request.
815  */
816 struct ast_sip_authenticator {
817     /*!
818      * \brief Check if a request requires authentication
819      * See ast_sip_requires_authentication for more details
820      */
821     int (*requires_authentication)(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
822         /*!
823          * \brief Check that an incoming request passes authentication.
824          *
825          * The tdata parameter is useful for adding information such as digest challenges.
826          *
827          * \param endpoint The endpoint sending the incoming request
828          * \param rdata The incoming request
829          * \param tdata Tentative outgoing request.
830          */
831         enum ast_sip_check_auth_result (*check_authentication)(struct ast_sip_endpoint *endpoint,
832                         pjsip_rx_data *rdata, pjsip_tx_data *tdata);
833 };
834
835 /*!
836  * \brief an interchangeable way of responding to authentication challenges
837  *
838  * An outbound authenticator takes incoming challenges and formulates a new SIP request with
839  * credentials.
840  */
841 struct ast_sip_outbound_authenticator {
842         /*!
843          * \brief Create a new request with authentication credentials
844          *
845          * \param auths A vector of IDs of auth sorcery objects
846          * \param challenge The SIP response with authentication challenge(s)
847          * \param old_request The request that received the auth challenge(s)
848          * \param new_request The new SIP request with challenge response(s)
849          * \retval 0 Successfully created new request
850          * \retval -1 Failed to create a new request
851          */
852         int (*create_request_with_auth)(const struct ast_sip_auth_vector *auths, struct pjsip_rx_data *challenge,
853                         struct pjsip_tx_data *old_request, struct pjsip_tx_data **new_request);
854 };
855
856 /*!
857  * \brief An entity responsible for identifying the source of a SIP message
858  */
859 struct ast_sip_endpoint_identifier {
860     /*!
861      * \brief Callback used to identify the source of a message.
862      * See ast_sip_identify_endpoint for more details
863      */
864     struct ast_sip_endpoint *(*identify_endpoint)(pjsip_rx_data *rdata);
865 };
866
867 /*!
868  * \brief Contact retrieval filtering flags
869  */
870 enum ast_sip_contact_filter {
871         /*! \brief Default filter flags */
872         AST_SIP_CONTACT_FILTER_DEFAULT = 0,
873
874         /*! \brief Return only reachable or unknown contacts */
875         AST_SIP_CONTACT_FILTER_REACHABLE = (1 << 0),
876 };
877
878 /*!
879  * \brief Register a SIP service in Asterisk.
880  *
881  * This is more-or-less a wrapper around pjsip_endpt_register_module().
882  * Registering a service makes it so that PJSIP will call into the
883  * service at appropriate times. For more information about PJSIP module
884  * callbacks, see the PJSIP documentation. Asterisk modules that call
885  * this function will likely do so at module load time.
886  *
887  * \param module The module that is to be registered with PJSIP
888  * \retval 0 Success
889  * \retval -1 Failure
890  */
891 int ast_sip_register_service(pjsip_module *module);
892
893 /*!
894  * This is the opposite of ast_sip_register_service().  Unregistering a
895  * service means that PJSIP will no longer call into the module any more.
896  * This will likely occur when an Asterisk module is unloaded.
897  *
898  * \param module The PJSIP module to unregister
899  */
900 void ast_sip_unregister_service(pjsip_module *module);
901
902 /*!
903  * \brief Register a SIP authenticator
904  *
905  * An authenticator has three main purposes:
906  * 1) Determining if authentication should be performed on an incoming request
907  * 2) Gathering credentials necessary for issuing an authentication challenge
908  * 3) Authenticating a request that has credentials
909  *
910  * Asterisk provides a default authenticator, but it may be replaced by a
911  * custom one if desired.
912  *
913  * \param auth The authenticator to register
914  * \retval 0 Success
915  * \retval -1 Failure
916  */
917 int ast_sip_register_authenticator(struct ast_sip_authenticator *auth);
918
919 /*!
920  * \brief Unregister a SIP authenticator
921  *
922  * When there is no authenticator registered, requests cannot be challenged
923  * or authenticated.
924  *
925  * \param auth The authenticator to unregister
926  */
927 void ast_sip_unregister_authenticator(struct ast_sip_authenticator *auth);
928
929  /*!
930  * \brief Register an outbound SIP authenticator
931  *
932  * An outbound authenticator is responsible for creating responses to
933  * authentication challenges by remote endpoints.
934  *
935  * \param auth The authenticator to register
936  * \retval 0 Success
937  * \retval -1 Failure
938  */
939 int ast_sip_register_outbound_authenticator(struct ast_sip_outbound_authenticator *outbound_auth);
940
941 /*!
942  * \brief Unregister an outbound SIP authenticator
943  *
944  * When there is no outbound authenticator registered, authentication challenges
945  * will be handled as any other final response would be.
946  *
947  * \param auth The authenticator to unregister
948  */
949 void ast_sip_unregister_outbound_authenticator(struct ast_sip_outbound_authenticator *auth);
950
951 /*!
952  * \brief Register a SIP endpoint identifier with a name.
953  *
954  * An endpoint identifier's purpose is to determine which endpoint a given SIP
955  * message has come from.
956  *
957  * Multiple endpoint identifiers may be registered so that if an endpoint
958  * cannot be identified by one identifier, it may be identified by another.
959  *
960  * \param identifier The SIP endpoint identifier to register
961  * \param name The name of the endpoint identifier
962  * \retval 0 Success
963  * \retval -1 Failure
964  */
965 int ast_sip_register_endpoint_identifier_with_name(struct ast_sip_endpoint_identifier *identifier,
966                                                    const char *name);
967
968 /*!
969  * \brief Register a SIP endpoint identifier
970  *
971  * An endpoint identifier's purpose is to determine which endpoint a given SIP
972  * message has come from.
973  *
974  * Multiple endpoint identifiers may be registered so that if an endpoint
975  * cannot be identified by one identifier, it may be identified by another.
976  *
977  * Asterisk provides two endpoint identifiers. One identifies endpoints based
978  * on the user part of the From header URI. The other identifies endpoints based
979  * on the source IP address.
980  *
981  * If the order in which endpoint identifiers is run is important to you, then
982  * be sure to load individual endpoint identifier modules in the order you wish
983  * for them to be run in modules.conf
984  *
985  * \note endpoint identifiers registered using this method (no name specified)
986  *       are placed at the front of the endpoint identifiers list ahead of any
987  *       named identifiers.
988  *
989  * \param identifier The SIP endpoint identifier to register
990  * \retval 0 Success
991  * \retval -1 Failure
992  */
993 int ast_sip_register_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier);
994
995 /*!
996  * \brief Unregister a SIP endpoint identifier
997  *
998  * This stops an endpoint identifier from being used.
999  *
1000  * \param identifier The SIP endoint identifier to unregister
1001  */
1002 void ast_sip_unregister_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier);
1003
1004 /*!
1005  * \brief Allocate a new SIP endpoint
1006  *
1007  * This will return an endpoint with its refcount increased by one. This reference
1008  * can be released using ao2_ref().
1009  *
1010  * \param name The name of the endpoint.
1011  * \retval NULL Endpoint allocation failed
1012  * \retval non-NULL The newly allocated endpoint
1013  */
1014 void *ast_sip_endpoint_alloc(const char *name);
1015
1016 /*!
1017  * \brief Change state of a persistent endpoint.
1018  *
1019  * \param endpoint The SIP endpoint name to change state.
1020  * \param state The new state
1021  * \retval 0 Success
1022  * \retval -1 Endpoint not found
1023  */
1024 int ast_sip_persistent_endpoint_update_state(const char *endpoint_name, enum ast_endpoint_state state);
1025
1026 /*!
1027  * \brief Get a pointer to the PJSIP endpoint.
1028  *
1029  * This is useful when modules have specific information they need
1030  * to register with the PJSIP core.
1031  * \retval NULL endpoint has not been created yet.
1032  * \retval non-NULL PJSIP endpoint.
1033  */
1034 pjsip_endpoint *ast_sip_get_pjsip_endpoint(void);
1035
1036 /*!
1037  * \brief Get a pointer to the SIP sorcery structure.
1038  *
1039  * \retval NULL sorcery has not been initialized
1040  * \retval non-NULL sorcery structure
1041  */
1042 struct ast_sorcery *ast_sip_get_sorcery(void);
1043
1044 /*!
1045  * \brief Retrieve a named AOR
1046  *
1047  * \param aor_name Name of the AOR
1048  *
1049  * \retval NULL if not found
1050  * \retval non-NULL if found
1051  */
1052 struct ast_sip_aor *ast_sip_location_retrieve_aor(const char *aor_name);
1053
1054 /*!
1055  * \brief Retrieve the first bound contact for an AOR
1056  *
1057  * \param aor Pointer to the AOR
1058  * \retval NULL if no contacts available
1059  * \retval non-NULL if contacts available
1060  */
1061 struct ast_sip_contact *ast_sip_location_retrieve_first_aor_contact(const struct ast_sip_aor *aor);
1062
1063 /*!
1064  * \brief Retrieve the first bound contact for an AOR and filter based on flags
1065  * \since 13.16.0
1066  *
1067  * \param aor Pointer to the AOR
1068  * \param flags Filtering flags
1069  * \retval NULL if no contacts available
1070  * \retval non-NULL if contacts available
1071  */
1072 struct ast_sip_contact *ast_sip_location_retrieve_first_aor_contact_filtered(const struct ast_sip_aor *aor,
1073         unsigned int flags);
1074
1075 /*!
1076  * \brief Retrieve all contacts currently available for an AOR
1077  *
1078  * \param aor Pointer to the AOR
1079  *
1080  * \retval NULL if no contacts available
1081  * \retval non-NULL if contacts available
1082  *
1083  * \warning
1084  * Since this function prunes expired contacts before returning, it holds a named write
1085  * lock on the aor.  If you already hold the lock, call ast_sip_location_retrieve_aor_contacts_nolock instead.
1086  */
1087 struct ao2_container *ast_sip_location_retrieve_aor_contacts(const struct ast_sip_aor *aor);
1088
1089 /*!
1090  * \brief Retrieve all contacts currently available for an AOR and filter based on flags
1091  * \since 13.16.0
1092  *
1093  * \param aor Pointer to the AOR
1094  * \param flags Filtering flags
1095  *
1096  * \retval NULL if no contacts available
1097  * \retval non-NULL if contacts available
1098  *
1099  * \warning
1100  * Since this function prunes expired contacts before returning, it holds a named write
1101  * lock on the aor.  If you already hold the lock, call ast_sip_location_retrieve_aor_contacts_nolock instead.
1102  */
1103 struct ao2_container *ast_sip_location_retrieve_aor_contacts_filtered(const struct ast_sip_aor *aor,
1104         unsigned int flags);
1105
1106 /*!
1107  * \brief Retrieve all contacts currently available for an AOR without locking the AOR
1108  * \since 13.9.0
1109  *
1110  * \param aor Pointer to the AOR
1111  *
1112  * \retval NULL if no contacts available
1113  * \retval non-NULL if contacts available
1114  *
1115  * \warning
1116  * This function should only be called if you already hold a named write lock on the aor.
1117  */
1118 struct ao2_container *ast_sip_location_retrieve_aor_contacts_nolock(const struct ast_sip_aor *aor);
1119
1120 /*!
1121  * \brief Retrieve all contacts currently available for an AOR without locking the AOR and filter based on flags
1122  * \since 13.16.0
1123  *
1124  * \param aor Pointer to the AOR
1125  * \param flags Filtering flags
1126  *
1127  * \retval NULL if no contacts available
1128  * \retval non-NULL if contacts available
1129  *
1130  * \warning
1131  * This function should only be called if you already hold a named write lock on the aor.
1132  */
1133 struct ao2_container *ast_sip_location_retrieve_aor_contacts_nolock_filtered(const struct ast_sip_aor *aor,
1134         unsigned int flags);
1135
1136 /*!
1137  * \brief Retrieve the first bound contact from a list of AORs
1138  *
1139  * \param aor_list A comma-separated list of AOR names
1140  * \retval NULL if no contacts available
1141  * \retval non-NULL if contacts available
1142  */
1143 struct ast_sip_contact *ast_sip_location_retrieve_contact_from_aor_list(const char *aor_list);
1144
1145 /*!
1146  * \brief Retrieve all contacts from a list of AORs
1147  *
1148  * \param aor_list A comma-separated list of AOR names
1149  * \retval NULL if no contacts available
1150  * \retval non-NULL container (which must be freed) if contacts available
1151  */
1152 struct ao2_container *ast_sip_location_retrieve_contacts_from_aor_list(const char *aor_list);
1153
1154 /*!
1155  * \brief Retrieve the first bound contact AND the AOR chosen from a list of AORs
1156  *
1157  * \param aor_list A comma-separated list of AOR names
1158  * \param aor The chosen AOR
1159  * \param contact The chosen contact
1160  */
1161  void ast_sip_location_retrieve_contact_and_aor_from_list(const char *aor_list, struct ast_sip_aor **aor,
1162         struct ast_sip_contact **contact);
1163
1164 /*!
1165  * \brief Retrieve the first bound contact AND the AOR chosen from a list of AORs and filter based on flags
1166  * \since 13.16.0
1167  *
1168  * \param aor_list A comma-separated list of AOR names
1169  * \param flags Filtering flags
1170  * \param aor The chosen AOR
1171  * \param contact The chosen contact
1172  */
1173 void ast_sip_location_retrieve_contact_and_aor_from_list_filtered(const char *aor_list, unsigned int flags,
1174         struct ast_sip_aor **aor, struct ast_sip_contact **contact);
1175
1176 /*!
1177  * \brief Retrieve a named contact
1178  *
1179  * \param contact_name Name of the contact
1180  *
1181  * \retval NULL if not found
1182  * \retval non-NULL if found
1183  */
1184 struct ast_sip_contact *ast_sip_location_retrieve_contact(const char *contact_name);
1185
1186 /*!
1187  * \brief Add a new contact to an AOR
1188  *
1189  * \param aor Pointer to the AOR
1190  * \param uri Full contact URI
1191  * \param expiration_time Optional expiration time of the contact
1192  * \param path_info Path information
1193  * \param user_agent User-Agent header from REGISTER request
1194  * \param endpoint The endpoint that resulted in the contact being added
1195  *
1196  * \retval -1 failure
1197  * \retval 0 success
1198  *
1199  * \warning
1200  * This function holds a named write lock on the aor.  If you already hold the lock
1201  * you should call ast_sip_location_add_contact_nolock instead.
1202  */
1203 int ast_sip_location_add_contact(struct ast_sip_aor *aor, const char *uri,
1204         struct timeval expiration_time, const char *path_info, const char *user_agent,
1205         const char *via_addr, int via_port, const char *call_id,
1206         struct ast_sip_endpoint *endpoint);
1207
1208 /*!
1209  * \brief Add a new contact to an AOR without locking the AOR
1210  * \since 13.9.0
1211  *
1212  * \param aor Pointer to the AOR
1213  * \param uri Full contact URI
1214  * \param expiration_time Optional expiration time of the contact
1215  * \param path_info Path information
1216  * \param user_agent User-Agent header from REGISTER request
1217  * \param endpoint The endpoint that resulted in the contact being added
1218  *
1219  * \retval -1 failure
1220  * \retval 0 success
1221  *
1222  * \warning
1223  * This function should only be called if you already hold a named write lock on the aor.
1224  */
1225 int ast_sip_location_add_contact_nolock(struct ast_sip_aor *aor, const char *uri,
1226         struct timeval expiration_time, const char *path_info, const char *user_agent,
1227         const char *via_addr, int via_port, const char *call_id,
1228         struct ast_sip_endpoint *endpoint);
1229
1230 /*!
1231  * \brief Update a contact
1232  *
1233  * \param contact New contact object with details
1234  *
1235  * \retval -1 failure
1236  * \retval 0 success
1237  */
1238 int ast_sip_location_update_contact(struct ast_sip_contact *contact);
1239
1240 /*!
1241 * \brief Delete a contact
1242 *
1243 * \param contact Contact object to delete
1244 *
1245 * \retval -1 failure
1246 * \retval 0 success
1247 */
1248 int ast_sip_location_delete_contact(struct ast_sip_contact *contact);
1249
1250 /*!
1251  * \brief Callback called when an outbound request with authentication credentials is to be sent in dialog
1252  *
1253  * This callback will have the created request on it. The callback's purpose is to do any extra
1254  * housekeeping that needs to be done as well as to send the request out.
1255  *
1256  * This callback is only necessary if working with a PJSIP API that sits between the application
1257  * and the dialog layer.
1258  *
1259  * \param dlg The dialog to which the request belongs
1260  * \param tdata The created request to be sent out
1261  * \param user_data Data supplied with the callback
1262  *
1263  * \retval 0 Success
1264  * \retval -1 Failure
1265  */
1266 typedef int (*ast_sip_dialog_outbound_auth_cb)(pjsip_dialog *dlg, pjsip_tx_data *tdata, void *user_data);
1267
1268 /*!
1269  * \brief Set up outbound authentication on a SIP dialog
1270  *
1271  * This sets up the infrastructure so that all requests associated with a created dialog
1272  * can be re-sent with authentication credentials if the original request is challenged.
1273  *
1274  * \param dlg The dialog on which requests will be authenticated
1275  * \param endpoint The endpoint whom this dialog pertains to
1276  * \param cb Callback to call to send requests with authentication
1277  * \param user_data Data to be provided to the callback when it is called
1278  *
1279  * \retval 0 Success
1280  * \retval -1 Failure
1281  */
1282 int ast_sip_dialog_setup_outbound_authentication(pjsip_dialog *dlg, const struct ast_sip_endpoint *endpoint,
1283                 ast_sip_dialog_outbound_auth_cb cb, void *user_data);
1284
1285 /*!
1286  * \brief Retrieves a reference to the artificial auth.
1287  *
1288  * \retval The artificial auth
1289  */
1290 struct ast_sip_auth *ast_sip_get_artificial_auth(void);
1291
1292 /*!
1293  * \brief Retrieves a reference to the artificial endpoint.
1294  *
1295  * \retval The artificial endpoint
1296  */
1297 struct ast_sip_endpoint *ast_sip_get_artificial_endpoint(void);
1298
1299 /*! \defgroup pjsip_threading PJSIP Threading Model
1300  * @{
1301  * \page PJSIP PJSIP Threading Model
1302  *
1303  * There are three major types of threads that SIP will have to deal with:
1304  * \li Asterisk threads
1305  * \li PJSIP threads
1306  * \li SIP threadpool threads (a.k.a. "servants")
1307  *
1308  * \par Asterisk Threads
1309  *
1310  * Asterisk threads are those that originate from outside of SIP but within
1311  * Asterisk. The most common of these threads are PBX (channel) threads and
1312  * the autoservice thread. Most interaction with these threads will be through
1313  * channel technology callbacks. Within these threads, it is fine to handle
1314  * Asterisk data from outside of SIP, but any handling of SIP data should be
1315  * left to servants, \b especially if you wish to call into PJSIP for anything.
1316  * Asterisk threads are not registered with PJLIB, so attempting to call into
1317  * PJSIP will cause an assertion to be triggered, thus causing the program to
1318  * crash.
1319  *
1320  * \par PJSIP Threads
1321  *
1322  * PJSIP threads are those that originate from handling of PJSIP events, such
1323  * as an incoming SIP request or response, or a transaction timeout. The role
1324  * of these threads is to process information as quickly as possible so that
1325  * the next item on the SIP socket(s) can be serviced. On incoming messages,
1326  * Asterisk automatically will push the request to a servant thread. When your
1327  * module callback is called, processing will already be in a servant. However,
1328  * for other PSJIP events, such as transaction state changes due to timer
1329  * expirations, your module will be called into from a PJSIP thread. If you
1330  * are called into from a PJSIP thread, then you should push whatever processing
1331  * is needed to a servant as soon as possible. You can discern if you are currently
1332  * in a SIP servant thread using the \ref ast_sip_thread_is_servant function.
1333  *
1334  * \par Servants
1335  *
1336  * Servants are where the bulk of SIP work should be performed. These threads
1337  * exist in order to do the work that Asterisk threads and PJSIP threads hand
1338  * off to them. Servant threads register themselves with PJLIB, meaning that
1339  * they are capable of calling PJSIP and PJLIB functions if they wish.
1340  *
1341  * \par Serializer
1342  *
1343  * Tasks are handed off to servant threads using the API call \ref ast_sip_push_task.
1344  * The first parameter of this call is a serializer. If this pointer
1345  * is NULL, then the work will be handed off to whatever servant can currently handle
1346  * the task. If this pointer is non-NULL, then the task will not be executed until
1347  * previous tasks pushed with the same serializer have completed. For more information
1348  * on serializers and the benefits they provide, see \ref ast_threadpool_serializer
1349  *
1350  * \par Scheduler
1351  *
1352  * Some situations require that a task run periodically or at a future time.  Normally
1353  * the ast_sched functionality would be used but ast_sched only uses 1 thread for all
1354  * tasks and that thread isn't registered with PJLIB and therefore can't do any PJSIP
1355  * related work.
1356  *
1357  * ast_sip_sched uses ast_sched only as a scheduled queue.  When a task is ready to run,
1358  * it's pushed to a Serializer to be invoked asynchronously by a Servant.  This ensures
1359  * that the task is executed in a PJLIB registered thread and allows the ast_sched thread
1360  * to immediately continue processing the queue.  The Serializer used by ast_sip_sched
1361  * is one of your choosing or a random one from the res_pjsip pool if you don't choose one.
1362  *
1363  * \note
1364  *
1365  * Do not make assumptions about individual threads based on a corresponding serializer.
1366  * In other words, just because several tasks use the same serializer when being pushed
1367  * to servants, it does not mean that the same thread is necessarily going to execute those
1368  * tasks, even though they are all guaranteed to be executed in sequence.
1369  */
1370
1371 typedef int (*ast_sip_task)(void *user_data);
1372
1373 /*!
1374  * \brief Create a new serializer for SIP tasks
1375  * \since 13.8.0
1376  *
1377  * See \ref ast_threadpool_serializer for more information on serializers.
1378  * SIP creates serializers so that tasks operating on similar data will run
1379  * in sequence.
1380  *
1381  * \param name Name of the serializer. (must be unique)
1382  *
1383  * \retval NULL Failure
1384  * \retval non-NULL Newly-created serializer
1385  */
1386 struct ast_taskprocessor *ast_sip_create_serializer(const char *name);
1387
1388 struct ast_serializer_shutdown_group;
1389
1390 /*!
1391  * \brief Create a new serializer for SIP tasks
1392  * \since 13.8.0
1393  *
1394  * See \ref ast_threadpool_serializer for more information on serializers.
1395  * SIP creates serializers so that tasks operating on similar data will run
1396  * in sequence.
1397  *
1398  * \param name Name of the serializer. (must be unique)
1399  * \param shutdown_group Group shutdown controller. (NULL if no group association)
1400  *
1401  * \retval NULL Failure
1402  * \retval non-NULL Newly-created serializer
1403  */
1404 struct ast_taskprocessor *ast_sip_create_serializer_group(const char *name, struct ast_serializer_shutdown_group *shutdown_group);
1405
1406 /*!
1407  * \brief Determine the distributor serializer for the SIP message.
1408  * \since 13.10.0
1409  *
1410  * \param rdata The incoming message.
1411  *
1412  * \retval Calculated distributor serializer on success.
1413  * \retval NULL on error.
1414  */
1415 struct ast_taskprocessor *ast_sip_get_distributor_serializer(pjsip_rx_data *rdata);
1416
1417 /*!
1418  * \brief Set a serializer on a SIP dialog so requests and responses are automatically serialized
1419  *
1420  * Passing a NULL serializer is a way to remove a serializer from a dialog.
1421  *
1422  * \param dlg The SIP dialog itself
1423  * \param serializer The serializer to use
1424  */
1425 void ast_sip_dialog_set_serializer(pjsip_dialog *dlg, struct ast_taskprocessor *serializer);
1426
1427 /*!
1428  * \brief Set an endpoint on a SIP dialog so in-dialog requests do not undergo endpoint lookup.
1429  *
1430  * \param dlg The SIP dialog itself
1431  * \param endpoint The endpoint that this dialog is communicating with
1432  */
1433 void ast_sip_dialog_set_endpoint(pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint);
1434
1435 /*!
1436  * \brief Get the endpoint associated with this dialog
1437  *
1438  * This function increases the refcount of the endpoint by one. Release
1439  * the reference once you are finished with the endpoint.
1440  *
1441  * \param dlg The SIP dialog from which to retrieve the endpoint
1442  * \retval NULL No endpoint associated with this dialog
1443  * \retval non-NULL The endpoint.
1444  */
1445 struct ast_sip_endpoint *ast_sip_dialog_get_endpoint(pjsip_dialog *dlg);
1446
1447 /*!
1448  * \brief Pushes a task to SIP servants
1449  *
1450  * This uses the serializer provided to determine how to push the task.
1451  * If the serializer is NULL, then the task will be pushed to the
1452  * servants directly. If the serializer is non-NULL, then the task will be
1453  * queued behind other tasks associated with the same serializer.
1454  *
1455  * \param serializer The serializer to which the task belongs. Can be NULL
1456  * \param sip_task The task to execute
1457  * \param task_data The parameter to pass to the task when it executes
1458  * \retval 0 Success
1459  * \retval -1 Failure
1460  */
1461 int ast_sip_push_task(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1462
1463 /*!
1464  * \brief Push a task to SIP servants and wait for it to complete
1465  *
1466  * Like \ref ast_sip_push_task except that it blocks until the task completes.
1467  *
1468  * \warning \b Never use this function in a SIP servant thread. This can potentially
1469  * cause a deadlock. If you are in a SIP servant thread, just call your function
1470  * in-line.
1471  *
1472  * \warning \b Never hold locks that may be acquired by a SIP servant thread when
1473  * calling this function. Doing so may cause a deadlock if all SIP servant threads
1474  * are blocked waiting to acquire the lock while the thread holding the lock is
1475  * waiting for a free SIP servant thread.
1476  *
1477  * \param serializer The SIP serializer to which the task belongs. May be NULL.
1478  * \param sip_task The task to execute
1479  * \param task_data The parameter to pass to the task when it executes
1480  * \retval 0 Success
1481  * \retval -1 Failure
1482  */
1483 int ast_sip_push_task_synchronous(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1484
1485 /*!
1486  * \brief Determine if the current thread is a SIP servant thread
1487  *
1488  * \retval 0 This is not a SIP servant thread
1489  * \retval 1 This is a SIP servant thread
1490  */
1491 int ast_sip_thread_is_servant(void);
1492
1493 /*!
1494  * \brief Task flags for the res_pjsip scheduler
1495  *
1496  * The default is AST_SIP_SCHED_TASK_FIXED
1497  *                | AST_SIP_SCHED_TASK_DATA_NOT_AO2
1498  *                | AST_SIP_SCHED_TASK_DATA_NO_CLEANUP
1499  *                | AST_SIP_SCHED_TASK_PERIODIC
1500  */
1501 enum ast_sip_scheduler_task_flags {
1502         /*!
1503          * The defaults
1504          */
1505         AST_SIP_SCHED_TASK_DEFAULTS = (0 << 0),
1506
1507         /*!
1508          * Run at a fixed interval.
1509          * Stop scheduling if the callback returns 0.
1510          * Any other value is ignored.
1511          */
1512         AST_SIP_SCHED_TASK_FIXED = (0 << 0),
1513         /*!
1514          * Run at a variable interval.
1515          * Stop scheduling if the callback returns 0.
1516          * Any other return value is used as the new interval.
1517          */
1518         AST_SIP_SCHED_TASK_VARIABLE = (1 << 0),
1519
1520         /*!
1521          * The task data is not an AO2 object.
1522          */
1523         AST_SIP_SCHED_TASK_DATA_NOT_AO2 = (0 << 1),
1524         /*!
1525          * The task data is an AO2 object.
1526          * A reference count will be held by the scheduler until
1527          * after the task has run for the final time (if ever).
1528          */
1529         AST_SIP_SCHED_TASK_DATA_AO2 = (1 << 1),
1530
1531         /*!
1532          * Don't take any cleanup action on the data
1533          */
1534         AST_SIP_SCHED_TASK_DATA_NO_CLEANUP = (0 << 3),
1535         /*!
1536          * If AST_SIP_SCHED_TASK_DATA_AO2 is set, decrement the reference count
1537          * otherwise call ast_free on it.
1538          */
1539         AST_SIP_SCHED_TASK_DATA_FREE = ( 1 << 3 ),
1540
1541         /*! \brief AST_SIP_SCHED_TASK_PERIODIC
1542          * The task is scheduled at multiples of interval
1543          * \see Interval
1544          */
1545         AST_SIP_SCHED_TASK_PERIODIC = (0 << 4),
1546         /*! \brief AST_SIP_SCHED_TASK_DELAY
1547          * The next invocation of the task is at last finish + interval
1548          * \see Interval
1549          */
1550         AST_SIP_SCHED_TASK_DELAY = (1 << 4),
1551 };
1552
1553 /*!
1554  * \brief Scheduler task data structure
1555  */
1556 struct ast_sip_sched_task;
1557
1558 /*!
1559  * \brief Schedule a task to run in the res_pjsip thread pool
1560  * \since 13.9.0
1561  *
1562  * \param serializer The serializer to use.  If NULL, don't use a serializer (see note below)
1563  * \param interval The invocation interval in milliseconds (see note below)
1564  * \param sip_task The task to invoke
1565  * \param name An optional name to associate with the task
1566  * \param task_data Optional data to pass to the task
1567  * \param flags One of enum ast_sip_scheduler_task_type
1568  *
1569  * \returns Pointer to \ref ast_sip_sched_task ao2 object which must be dereferenced when done.
1570  *
1571  * \paragraph Serialization
1572  *
1573  * Specifying a serializer guarantees serialized execution but NOT specifying a serializer
1574  * may still result in tasks being effectively serialized if the thread pool is busy.
1575  * The point of the serializer BTW is not to prevent parallel executions of the SAME task.
1576  * That happens automatically (see below).  It's to prevent the task from running at the same
1577  * time as other work using the same serializer, whether or not it's being run by the scheduler.
1578  *
1579  * \paragraph Interval
1580  *
1581  * The interval is used to calculate the next time the task should run.  There are two models.
1582  *
1583  * \ref AST_SIP_SCHED_TASK_PERIODIC specifies that the invocations of the task occur at the
1584  * specific interval.  That is, every \ref "interval" milliseconds, regardless of how long the task
1585  * takes. If the task takes longer than \ref interval, it will be scheduled at the next available
1586  * multiple of \ref interval.  For exmaple: If the task has an interval of 60 seconds and the task
1587  * takes 70 seconds, the next invocation will happen at 120 seconds.
1588  *
1589  * \ref AST_SIP_SCHED_TASK_DELAY specifies that the next invocation of the task should start
1590  * at \ref interval milliseconds after the current invocation has finished.
1591  *
1592  */
1593 struct ast_sip_sched_task *ast_sip_schedule_task(struct ast_taskprocessor *serializer,
1594         int interval, ast_sip_task sip_task, char *name, void *task_data,
1595         enum ast_sip_scheduler_task_flags flags);
1596
1597 /*!
1598  * \brief Cancels the next invocation of a task
1599  * \since 13.9.0
1600  *
1601  * \param schtd The task structure pointer
1602  * \retval 0 Success
1603  * \retval -1 Failure
1604  * \note Only cancels future invocations not the currently running invocation.
1605  */
1606 int ast_sip_sched_task_cancel(struct ast_sip_sched_task *schtd);
1607
1608 /*!
1609  * \brief Cancels the next invocation of a task by name
1610  * \since 13.9.0
1611  *
1612  * \param name The task name
1613  * \retval 0 Success
1614  * \retval -1 Failure
1615  * \note Only cancels future invocations not the currently running invocation.
1616  */
1617 int ast_sip_sched_task_cancel_by_name(const char *name);
1618
1619 /*!
1620  * \brief Gets the last start and end times of the task
1621  * \since 13.9.0
1622  *
1623  * \param schtd The task structure pointer
1624  * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
1625  * \param[out] last_start Pointer to a timeval structure to contain the time when last started
1626  * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
1627  * \retval 0 Success
1628  * \retval -1 Failure
1629  * \note Any of the pointers can be NULL if you don't need them.
1630  */
1631 int ast_sip_sched_task_get_times(struct ast_sip_sched_task *schtd,
1632         struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end);
1633
1634 /*!
1635  * \brief Gets the last start and end times of the task by name
1636  * \since 13.9.0
1637  *
1638  * \param name The task name
1639  * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
1640  * \param[out] last_start Pointer to a timeval structure to contain the time when last started
1641  * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
1642  * \retval 0 Success
1643  * \retval -1 Failure
1644  * \note Any of the pointers can be NULL if you don't need them.
1645  */
1646 int ast_sip_sched_task_get_times_by_name(const char *name,
1647         struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end);
1648
1649 /*!
1650  * \brief Gets the number of milliseconds until the next invocation
1651  * \since 13.9.0
1652  *
1653  * \param schtd The task structure pointer
1654  * \return The number of milliseconds until the next invocation or -1 if the task isn't scheduled
1655  */
1656 int ast_sip_sched_task_get_next_run(struct ast_sip_sched_task *schtd);
1657
1658 /*!
1659  * \brief Gets the number of milliseconds until the next invocation
1660  * \since 13.9.0
1661  *
1662  * \param name The task name
1663  * \return The number of milliseconds until the next invocation or -1 if the task isn't scheduled
1664  */
1665 int ast_sip_sched_task_get_next_run_by_name(const char *name);
1666
1667 /*!
1668  * \brief Checks if the task is currently running
1669  * \since 13.9.0
1670  *
1671  * \param schtd The task structure pointer
1672  * \retval 0 not running
1673  * \retval 1 running
1674  */
1675 int ast_sip_sched_is_task_running(struct ast_sip_sched_task *schtd);
1676
1677 /*!
1678  * \brief Checks if the task is currently running
1679  * \since 13.9.0
1680  *
1681  * \param name The task name
1682  * \retval 0 not running or not found
1683  * \retval 1 running
1684  */
1685 int ast_sip_sched_is_task_running_by_name(const char *name);
1686
1687 /*!
1688  * \brief Gets the task name
1689  * \since 13.9.0
1690  *
1691  * \param schtd The task structure pointer
1692  * \retval 0 success
1693  * \retval 1 failure
1694  */
1695 int ast_sip_sched_task_get_name(struct ast_sip_sched_task *schtd, char *name, size_t maxlen);
1696
1697 /*!
1698  *  @}
1699  */
1700
1701 /*!
1702  * \brief SIP body description
1703  *
1704  * This contains a type and subtype that will be added as
1705  * the "Content-Type" for the message as well as the body
1706  * text.
1707  */
1708 struct ast_sip_body {
1709         /*! Type of the body, such as "application" */
1710         const char *type;
1711         /*! Subtype of the body, such as "sdp" */
1712         const char *subtype;
1713         /*! The text to go in the body */
1714         const char *body_text;
1715 };
1716
1717 /*!
1718  * \brief General purpose method for creating a UAC dialog with an endpoint
1719  *
1720  * \param endpoint A pointer to the endpoint
1721  * \param aor_name Optional name of the AOR to target, may even be an explicit SIP URI
1722  * \param request_user Optional user to place into the target URI
1723  *
1724  * \retval non-NULL success
1725  * \retval NULL failure
1726  */
1727 pjsip_dialog *ast_sip_create_dialog_uac(const struct ast_sip_endpoint *endpoint, const char *aor_name, const char *request_user);
1728
1729 /*!
1730  * \brief General purpose method for creating a UAS dialog with an endpoint
1731  *
1732  * \param endpoint A pointer to the endpoint
1733  * \param rdata The request that is starting the dialog
1734  * \param[out] status On failure, the reason for failure in creating the dialog
1735  */
1736 pjsip_dialog *ast_sip_create_dialog_uas(const struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pj_status_t *status);
1737
1738 /*!
1739  * \brief General purpose method for creating an rdata structure using specific information
1740  * \since 13.15.0
1741  *
1742  * \param rdata[out] The rdata structure that will be populated
1743  * \param packet A SIP message
1744  * \param src_name The source IP address of the message
1745  * \param src_port The source port of the message
1746  * \param transport_type The type of transport the message was received on
1747  * \param local_name The local IP address the message was received on
1748  * \param local_port The local port the message was received on
1749  * \param contact_uri The contact URI of the message
1750  *
1751  * \retval 0 success
1752  * \retval -1 failure
1753  */
1754 int ast_sip_create_rdata_with_contact(pjsip_rx_data *rdata, char *packet,
1755         const char *src_name, int src_port, char *transport_type, const char *local_name,
1756         int local_port, const char *contact_uri);
1757
1758 /*!
1759  * \brief General purpose method for creating an rdata structure using specific information
1760  *
1761  * \param rdata[out] The rdata structure that will be populated
1762  * \param packet A SIP message
1763  * \param src_name The source IP address of the message
1764  * \param src_port The source port of the message
1765  * \param transport_type The type of transport the message was received on
1766  * \param local_name The local IP address the message was received on
1767  * \param local_port The local port the message was received on
1768  *
1769  * \retval 0 success
1770  * \retval -1 failure
1771  */
1772 int ast_sip_create_rdata(pjsip_rx_data *rdata, char *packet, const char *src_name,
1773         int src_port, char *transport_type, const char *local_name, int local_port);
1774
1775 /*!
1776  * \brief General purpose method for creating a SIP request
1777  *
1778  * Its typical use would be to create one-off requests such as an out of dialog
1779  * SIP MESSAGE.
1780  *
1781  * The request can either be in- or out-of-dialog. If in-dialog, the
1782  * dlg parameter MUST be present. If out-of-dialog the endpoint parameter
1783  * MUST be present. If both are present, then we will assume that the message
1784  * is to be sent in-dialog.
1785  *
1786  * The uri parameter can be specified if the request should be sent to an explicit
1787  * URI rather than one configured on the endpoint.
1788  *
1789  * \param method The method of the SIP request to send
1790  * \param dlg Optional. If specified, the dialog on which to request the message.
1791  * \param endpoint Optional. If specified, the request will be created out-of-dialog to the endpoint.
1792  * \param uri Optional. If specified, the request will be sent to this URI rather
1793  * than one configured for the endpoint.
1794  * \param contact The contact with which this request is associated for out-of-dialog requests.
1795  * \param[out] tdata The newly-created request
1796  *
1797  * The provided contact is attached to tdata with its reference bumped, but will
1798  * not survive for the entire lifetime of tdata since the contact is cleaned up
1799  * when all supplements have completed execution.
1800  *
1801  * \retval 0 Success
1802  * \retval -1 Failure
1803  */
1804 int ast_sip_create_request(const char *method, struct pjsip_dialog *dlg,
1805                 struct ast_sip_endpoint *endpoint, const char *uri,
1806                 struct ast_sip_contact *contact, pjsip_tx_data **tdata);
1807
1808 /*!
1809  * \brief General purpose method for sending a SIP request
1810  *
1811  * This is a companion function for \ref ast_sip_create_request. The request
1812  * created there can be passed to this function, though any request may be
1813  * passed in.
1814  *
1815  * This will automatically set up handling outbound authentication challenges if
1816  * they arrive.
1817  *
1818  * \param tdata The request to send
1819  * \param dlg Optional. The dialog in which the request is sent.  Otherwise it is out-of-dialog.
1820  * \param endpoint Optional. If specified, the out-of-dialog request is sent to the endpoint.
1821  * \param token Data to be passed to the callback upon receipt of out-of-dialog response.
1822  * \param callback Callback to be called upon receipt of out-of-dialog response.
1823  *
1824  * \retval 0 Success
1825  * \retval -1 Failure (out-of-dialog callback will not be called.)
1826  */
1827 int ast_sip_send_request(pjsip_tx_data *tdata, struct pjsip_dialog *dlg,
1828         struct ast_sip_endpoint *endpoint, void *token,
1829         void (*callback)(void *token, pjsip_event *e));
1830
1831 /*!
1832  * \brief General purpose method for sending an Out-Of-Dialog SIP request
1833  *
1834  * This is a companion function for \ref ast_sip_create_request. The request
1835  * created there can be passed to this function, though any request may be
1836  * passed in.
1837  *
1838  * This will automatically set up handling outbound authentication challenges if
1839  * they arrive.
1840  *
1841  * \param tdata The request to send
1842  * \param endpoint Optional. If specified, the out-of-dialog request is sent to the endpoint.
1843  * \param timeout.  If non-zero, after the timeout the transaction will be terminated
1844  * and the callback will be called with the PJSIP_EVENT_TIMER type.
1845  * \param token Data to be passed to the callback upon receipt of out-of-dialog response.
1846  * \param callback Callback to be called upon receipt of out-of-dialog response.
1847  *
1848  * \retval 0 Success
1849  * \retval -1 Failure (out-of-dialog callback will not be called.)
1850  *
1851  * \note Timeout processing:
1852  * There are 2 timers associated with this request, PJSIP timer_b which is
1853  * set globally in the "system" section of pjsip.conf, and the timeout specified
1854  * on this call.  The timer that expires first (before normal completion) will
1855  * cause the callback to be run with e->body.tsx_state.type = PJSIP_EVENT_TIMER.
1856  * The timer that expires second is simply ignored and the callback is not run again.
1857  */
1858 int ast_sip_send_out_of_dialog_request(pjsip_tx_data *tdata,
1859         struct ast_sip_endpoint *endpoint, int timeout, void *token,
1860         void (*callback)(void *token, pjsip_event *e));
1861
1862 /*!
1863  * \brief General purpose method for creating a SIP response
1864  *
1865  * Its typical use would be to create responses for out of dialog
1866  * requests.
1867  *
1868  * \param rdata The rdata from the incoming request.
1869  * \param st_code The response code to transmit.
1870  * \param contact The contact with which this request is associated.
1871  * \param[out] tdata The newly-created response
1872  *
1873  * The provided contact is attached to tdata with its reference bumped, but will
1874  * not survive for the entire lifetime of tdata since the contact is cleaned up
1875  * when all supplements have completed execution.
1876  *
1877  * \retval 0 Success
1878  * \retval -1 Failure
1879  */
1880 int ast_sip_create_response(const pjsip_rx_data *rdata, int st_code,
1881         struct ast_sip_contact *contact, pjsip_tx_data **p_tdata);
1882
1883 /*!
1884  * \brief Send a response to an out of dialog request
1885  *
1886  * Use this function sparingly, since this does not create a transaction
1887  * within PJSIP. This means that if the request is retransmitted, it is
1888  * your responsibility to detect this and not process the same request
1889  * twice, and to send the same response for each retransmission.
1890  *
1891  * \param res_addr The response address for this response
1892  * \param tdata The response to send
1893  * \param endpoint The ast_sip_endpoint associated with this response
1894  *
1895  * \retval 0 Success
1896  * \retval -1 Failure
1897  */
1898 int ast_sip_send_response(pjsip_response_addr *res_addr, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint);
1899
1900 /*!
1901  * \brief Send a stateful response to an out of dialog request
1902  *
1903  * This creates a transaction within PJSIP, meaning that if the request
1904  * that we are responding to is retransmitted, we will not attempt to
1905  * re-handle the request.
1906  *
1907  * \param rdata The request that is being responded to
1908  * \param tdata The response to send
1909  * \param endpoint The ast_sip_endpoint associated with this response
1910  *
1911  * \since 13.4.0
1912  *
1913  * \retval 0 Success
1914  * \retval -1 Failure
1915  */
1916 int ast_sip_send_stateful_response(pjsip_rx_data *rdata, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint);
1917
1918 /*!
1919  * \brief Determine if an incoming request requires authentication
1920  *
1921  * This calls into the registered authenticator's requires_authentication callback
1922  * in order to determine if the request requires authentication.
1923  *
1924  * If there is no registered authenticator, then authentication will be assumed
1925  * not to be required.
1926  *
1927  * \param endpoint The endpoint from which the request originates
1928  * \param rdata The incoming SIP request
1929  * \retval non-zero The request requires authentication
1930  * \retval 0 The request does not require authentication
1931  */
1932 int ast_sip_requires_authentication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
1933
1934 /*!
1935  * \brief Method to determine authentication status of an incoming request
1936  *
1937  * This will call into a registered authenticator. The registered authenticator will
1938  * do what is necessary to determine whether the incoming request passes authentication.
1939  * A tentative response is passed into this function so that if, say, a digest authentication
1940  * challenge should be sent in the ensuing response, it can be added to the response.
1941  *
1942  * \param endpoint The endpoint from the request was sent
1943  * \param rdata The request to potentially authenticate
1944  * \param tdata Tentative response to the request
1945  * \return The result of checking authentication.
1946  */
1947 enum ast_sip_check_auth_result ast_sip_check_authentication(struct ast_sip_endpoint *endpoint,
1948                 pjsip_rx_data *rdata, pjsip_tx_data *tdata);
1949
1950 /*!
1951  * \brief Create a response to an authentication challenge
1952  *
1953  * This will call into an outbound authenticator's create_request_with_auth callback
1954  * to create a new request with authentication credentials. See the create_request_with_auth
1955  * callback in the \ref ast_sip_outbound_authenticator structure for details about
1956  * the parameters and return values.
1957  */
1958 int ast_sip_create_request_with_auth(const struct ast_sip_auth_vector *auths, pjsip_rx_data *challenge,
1959                 pjsip_tx_data *tdata, pjsip_tx_data **new_request);
1960
1961 /*!
1962  * \brief Determine the endpoint that has sent a SIP message
1963  *
1964  * This will call into each of the registered endpoint identifiers'
1965  * identify_endpoint() callbacks until one returns a non-NULL endpoint.
1966  * This will return an ao2 object. Its reference count will need to be
1967  * decremented when completed using the endpoint.
1968  *
1969  * \param rdata The inbound SIP message to use when identifying the endpoint.
1970  * \retval NULL No matching endpoint
1971  * \retval non-NULL The matching endpoint
1972  */
1973 struct ast_sip_endpoint *ast_sip_identify_endpoint(pjsip_rx_data *rdata);
1974
1975 /*!
1976  * \brief Set the outbound proxy for an outbound SIP message
1977  *
1978  * \param tdata The message to set the outbound proxy on
1979  * \param proxy SIP uri of the proxy
1980  * \retval 0 Success
1981  * \retval -1 Failure
1982  */
1983 int ast_sip_set_outbound_proxy(pjsip_tx_data *tdata, const char *proxy);
1984
1985 /*!
1986  * \brief Add a header to an outbound SIP message
1987  *
1988  * \param tdata The message to add the header to
1989  * \param name The header name
1990  * \param value The header value
1991  * \retval 0 Success
1992  * \retval -1 Failure
1993  */
1994 int ast_sip_add_header(pjsip_tx_data *tdata, const char *name, const char *value);
1995
1996 /*!
1997  * \brief Add a body to an outbound SIP message
1998  *
1999  * If this is called multiple times, the latest body will replace the current
2000  * body.
2001  *
2002  * \param tdata The message to add the body to
2003  * \param body The message body to add
2004  * \retval 0 Success
2005  * \retval -1 Failure
2006  */
2007 int ast_sip_add_body(pjsip_tx_data *tdata, const struct ast_sip_body *body);
2008
2009 /*!
2010  * \brief Add a multipart body to an outbound SIP message
2011  *
2012  * This will treat each part of the input vector as part of a multipart body and
2013  * add each part to the SIP message.
2014  *
2015  * \param tdata The message to add the body to
2016  * \param bodies The parts of the body to add
2017  * \retval 0 Success
2018  * \retval -1 Failure
2019  */
2020 int ast_sip_add_body_multipart(pjsip_tx_data *tdata, const struct ast_sip_body *bodies[], int num_bodies);
2021
2022 /*!
2023  * \brief Append body data to a SIP message
2024  *
2025  * This acts mostly the same as ast_sip_add_body, except that rather than replacing
2026  * a body if it currently exists, it appends data to an existing body.
2027  *
2028  * \param tdata The message to append the body to
2029  * \param body The string to append to the end of the current body
2030  * \retval 0 Success
2031  * \retval -1 Failure
2032  */
2033 int ast_sip_append_body(pjsip_tx_data *tdata, const char *body_text);
2034
2035 /*!
2036  * \brief Copy a pj_str_t into a standard character buffer.
2037  *
2038  * pj_str_t is not NULL-terminated. Any place that expects a NULL-
2039  * terminated string needs to have the pj_str_t copied into a separate
2040  * buffer.
2041  *
2042  * This method copies the pj_str_t contents into the destination buffer
2043  * and NULL-terminates the buffer.
2044  *
2045  * \param dest The destination buffer
2046  * \param src The pj_str_t to copy
2047  * \param size The size of the destination buffer.
2048  */
2049 void ast_copy_pj_str(char *dest, const pj_str_t *src, size_t size);
2050
2051 /*!
2052  * \brief Get the looked-up endpoint on an out-of dialog request or response
2053  *
2054  * The function may ONLY be called on out-of-dialog requests or responses. For
2055  * in-dialog requests and responses, it is required that the user of the dialog
2056  * has the looked-up endpoint stored locally.
2057  *
2058  * This function should never return NULL if the message is out-of-dialog. It will
2059  * always return NULL if the message is in-dialog.
2060  *
2061  * This function will increase the reference count of the returned endpoint by one.
2062  * Release your reference using the ao2_ref function when finished.
2063  *
2064  * \param rdata Out-of-dialog request or response
2065  * \return The looked up endpoint
2066  */
2067 struct ast_sip_endpoint *ast_pjsip_rdata_get_endpoint(pjsip_rx_data *rdata);
2068
2069 /*!
2070  * \brief Add 'user=phone' parameter to URI if enabled and user is a phone number.
2071  *
2072  * \param endpoint The endpoint to use for configuration
2073  * \param pool The memory pool to allocate the parameter from
2074  * \param uri The URI to check for user and to add parameter to
2075  */
2076 void ast_sip_add_usereqphone(const struct ast_sip_endpoint *endpoint, pj_pool_t *pool, pjsip_uri *uri);
2077
2078 /*!
2079  * \brief Retrieve any endpoints available to sorcery.
2080  *
2081  * \retval Endpoints available to sorcery, NULL if no endpoints found.
2082  */
2083 struct ao2_container *ast_sip_get_endpoints(void);
2084
2085 /*!
2086  * \brief Retrieve the default outbound endpoint.
2087  *
2088  * \retval The default outbound endpoint, NULL if not found.
2089  */
2090 struct ast_sip_endpoint *ast_sip_default_outbound_endpoint(void);
2091
2092 /*!
2093  * \brief Retrieve relevant SIP auth structures from sorcery
2094  *
2095  * \param auths Vector of sorcery IDs of auth credentials to retrieve
2096  * \param[out] out The retrieved auths are stored here
2097  */
2098 int ast_sip_retrieve_auths(const struct ast_sip_auth_vector *auths, struct ast_sip_auth **out);
2099
2100 /*!
2101  * \brief Clean up retrieved auth structures from memory
2102  *
2103  * Call this function once you have completed operating on auths
2104  * retrieved from \ref ast_sip_retrieve_auths
2105  *
2106  * \param auths An vector of auth structures to clean up
2107  * \param num_auths The number of auths in the vector
2108  */
2109 void ast_sip_cleanup_auths(struct ast_sip_auth *auths[], size_t num_auths);
2110
2111 /*!
2112  * \brief Checks if the given content type matches type/subtype.
2113  *
2114  * Compares the pjsip_media_type with the passed type and subtype and
2115  * returns the result of that comparison.  The media type parameters are
2116  * ignored.
2117  *
2118  * \param content_type The pjsip_media_type structure to compare
2119  * \param type The media type to compare
2120  * \param subtype The media subtype to compare
2121  * \retval 0 No match
2122  * \retval -1 Match
2123  */
2124 int ast_sip_is_content_type(pjsip_media_type *content_type, char *type, char *subtype);
2125
2126 /*!
2127  * \brief Send a security event notification for when an invalid endpoint is requested
2128  *
2129  * \param name Name of the endpoint requested
2130  * \param rdata Received message
2131  */
2132 void ast_sip_report_invalid_endpoint(const char *name, pjsip_rx_data *rdata);
2133
2134 /*!
2135  * \brief Send a security event notification for when an ACL check fails
2136  *
2137  * \param endpoint Pointer to the endpoint in use
2138  * \param rdata Received message
2139  * \param name Name of the ACL
2140  */
2141 void ast_sip_report_failed_acl(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, const char *name);
2142
2143 /*!
2144  * \brief Send a security event notification for when a challenge response has failed
2145  *
2146  * \param endpoint Pointer to the endpoint in use
2147  * \param rdata Received message
2148  */
2149 void ast_sip_report_auth_failed_challenge_response(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2150
2151 /*!
2152  * \brief Send a security event notification for when authentication succeeds
2153  *
2154  * \param endpoint Pointer to the endpoint in use
2155  * \param rdata Received message
2156  */
2157 void ast_sip_report_auth_success(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2158
2159 /*!
2160  * \brief Send a security event notification for when an authentication challenge is sent
2161  *
2162  * \param endpoint Pointer to the endpoint in use
2163  * \param rdata Received message
2164  * \param tdata Sent message
2165  */
2166 void ast_sip_report_auth_challenge_sent(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pjsip_tx_data *tdata);
2167
2168 /*!
2169  * \brief Send a security event notification for when a request is not supported
2170  *
2171  * \param endpoint Pointer to the endpoint in use
2172  * \param rdata Received message
2173  * \param req_type the type of request
2174  */
2175 void ast_sip_report_req_no_support(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata,
2176                                    const char* req_type);
2177
2178 /*!
2179  * \brief Send a security event notification for when a memory limit is hit.
2180  *
2181  * \param endpoint Pointer to the endpoint in use
2182  * \param rdata Received message
2183  */
2184 void ast_sip_report_mem_limit(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2185
2186 int ast_sip_add_global_request_header(const char *name, const char *value, int replace);
2187 int ast_sip_add_global_response_header(const char *name, const char *value, int replace);
2188
2189 /*!
2190  * \brief Retrieves the value associated with the given key.
2191  *
2192  * \param ht the hash table/dictionary to search
2193  * \param key the key to find
2194  *
2195  * \retval the value associated with the key, NULL otherwise.
2196  */
2197 void *ast_sip_dict_get(void *ht, const char *key);
2198
2199 /*!
2200  * \brief Using the dictionary stored in mod_data array at a given id,
2201  *        retrieve the value associated with the given key.
2202  *
2203  * \param mod_data a module data array
2204  * \param id the mod_data array index
2205  * \param key the key to find
2206  *
2207  * \retval the value associated with the key, NULL otherwise.
2208  */
2209 #define ast_sip_mod_data_get(mod_data, id, key)         \
2210         ast_sip_dict_get(mod_data[id], key)
2211
2212 /*!
2213  * \brief Set the value for the given key.
2214  *
2215  * Note - if the hash table does not exist one is created first, the key/value
2216  * pair is set, and the hash table returned.
2217  *
2218  * \param pool the pool to allocate memory in
2219  * \param ht the hash table/dictionary in which to store the key/value pair
2220  * \param key the key to associate a value with
2221  * \param val the value to associate with a key
2222  *
2223  * \retval the given, or newly created, hash table.
2224  */
2225 void *ast_sip_dict_set(pj_pool_t* pool, void *ht,
2226                        const char *key, void *val);
2227
2228 /*!
2229  * \brief Utilizing a mod_data array for a given id, set the value
2230  *        associated with the given key.
2231  *
2232  * For a given structure's mod_data array set the element indexed by id to
2233  * be a dictionary containing the key/val pair.
2234  *
2235  * \param pool a memory allocation pool
2236  * \param mod_data a module data array
2237  * \param id the mod_data array index
2238  * \param key the key to find
2239  * \param val the value to associate with a key
2240  */
2241 #define ast_sip_mod_data_set(pool, mod_data, id, key, val)              \
2242         mod_data[id] = ast_sip_dict_set(pool, mod_data[id], key, val)
2243
2244 /*!
2245  * \brief For every contact on an AOR call the given 'on_contact' handler.
2246  *
2247  * \param aor the aor containing a list of contacts to iterate
2248  * \param on_contact callback on each contact on an AOR.  The object
2249  * received by the callback will be a ast_sip_contact_wrapper structure.
2250  * \param arg user data passed to handler
2251  * \retval 0 Success, non-zero on failure
2252  */
2253 int ast_sip_for_each_contact(const struct ast_sip_aor *aor,
2254                 ao2_callback_fn on_contact, void *arg);
2255
2256 /*!
2257  * \brief Handler used to convert a contact to a string.
2258  *
2259  * \param object the ast_sip_aor_contact_pair containing a list of contacts to iterate and the contact
2260  * \param arg user data passed to handler
2261  * \param flags
2262  * \retval 0 Success, non-zero on failure
2263  */
2264 int ast_sip_contact_to_str(void *object, void *arg, int flags);
2265
2266 /*!
2267  * \brief For every aor in the comma separated aors string call the
2268  *        given 'on_aor' handler.
2269  *
2270  * \param aors a comma separated list of aors
2271  * \param on_aor callback for each aor
2272  * \param arg user data passed to handler
2273  * \retval 0 Success, non-zero on failure
2274  */
2275 int ast_sip_for_each_aor(const char *aors, ao2_callback_fn on_aor, void *arg);
2276
2277 /*!
2278  * \brief For every auth in the array call the given 'on_auth' handler.
2279  *
2280  * \param array an array of auths
2281  * \param on_auth callback for each auth
2282  * \param arg user data passed to handler
2283  * \retval 0 Success, non-zero on failure
2284  */
2285 int ast_sip_for_each_auth(const struct ast_sip_auth_vector *array,
2286                           ao2_callback_fn on_auth, void *arg);
2287
2288 /*!
2289  * \brief Converts the given auth type to a string
2290  *
2291  * \param type the auth type to convert
2292  * \retval a string representative of the auth type
2293  */
2294 const char *ast_sip_auth_type_to_str(enum ast_sip_auth_type type);
2295
2296 /*!
2297  * \brief Converts an auths array to a string of comma separated values
2298  *
2299  * \param auths an auth array
2300  * \param buf the string buffer to write the object data
2301  * \retval 0 Success, non-zero on failure
2302  */
2303 int ast_sip_auths_to_str(const struct ast_sip_auth_vector *auths, char **buf);
2304
2305 /*!
2306  * \brief AMI variable container
2307  */
2308 struct ast_sip_ami {
2309         /*! Manager session */
2310         struct mansession *s;
2311         /*! Manager message */
2312         const struct message *m;
2313         /*! Manager Action ID */
2314         const char *action_id;
2315         /*! user specified argument data */
2316         void *arg;
2317         /*! count of objects */
2318         int count;
2319 };
2320
2321 /*!
2322  * \brief Creates a string to store AMI event data in.
2323  *
2324  * \param event the event to set
2325  * \param ami AMI session and message container
2326  * \retval an initialized ast_str or NULL on error.
2327  */
2328 struct ast_str *ast_sip_create_ami_event(const char *event,
2329                                          struct ast_sip_ami *ami);
2330
2331 /*!
2332  * \brief An entity responsible formatting endpoint information.
2333  */
2334 struct ast_sip_endpoint_formatter {
2335         /*!
2336          * \brief Callback used to format endpoint information over AMI.
2337          */
2338         int (*format_ami)(const struct ast_sip_endpoint *endpoint,
2339                           struct ast_sip_ami *ami);
2340         AST_RWLIST_ENTRY(ast_sip_endpoint_formatter) next;
2341 };
2342
2343 /*!
2344  * \brief Register an endpoint formatter.
2345  *
2346  * \param obj the formatter to register
2347  * \retval 0 Success
2348  * \retval -1 Failure
2349  */
2350 int ast_sip_register_endpoint_formatter(struct ast_sip_endpoint_formatter *obj);
2351
2352 /*!
2353  * \brief Unregister an endpoint formatter.
2354  *
2355  * \param obj the formatter to unregister
2356  */
2357 void ast_sip_unregister_endpoint_formatter(struct ast_sip_endpoint_formatter *obj);
2358
2359 /*!
2360  * \brief Converts a sorcery object to a string of object properties.
2361  *
2362  * \param obj the sorcery object to convert
2363  * \param str the string buffer to write the object data
2364  * \retval 0 Success, non-zero on failure
2365  */
2366 int ast_sip_sorcery_object_to_ami(const void *obj, struct ast_str **buf);
2367
2368 /*!
2369  * \brief Formats the endpoint and sends over AMI.
2370  *
2371  * \param endpoint the endpoint to format and send
2372  * \param endpoint ami AMI variable container
2373  * \param count the number of formatters operated on
2374  * \retval 0 Success, otherwise non-zero on error
2375  */
2376 int ast_sip_format_endpoint_ami(struct ast_sip_endpoint *endpoint,
2377                                 struct ast_sip_ami *ami, int *count);
2378
2379 /*!
2380  * \brief Formats the contact and sends over AMI.
2381  *
2382  * \param obj a pointer an ast_sip_contact_wrapper structure
2383  * \param arg a pointer to an ast_sip_ami structure
2384  * \param flags ignored
2385  * \retval 0 Success, otherwise non-zero on error
2386  */
2387 int ast_sip_format_contact_ami(void *obj, void *arg, int flags);
2388
2389 /*!
2390  * \brief Format auth details for AMI.
2391  *
2392  * \param auths an auth array
2393  * \param ami ami variable container
2394  * \retval 0 Success, non-zero on failure
2395  */
2396 int ast_sip_format_auths_ami(const struct ast_sip_auth_vector *auths,
2397                              struct ast_sip_ami *ami);
2398
2399 /*!
2400  * \brief Retrieve the endpoint snapshot for an endpoint
2401  *
2402  * \param endpoint The endpoint whose snapshot is to be retreieved.
2403  * \retval The endpoint snapshot
2404  */
2405 struct ast_endpoint_snapshot *ast_sip_get_endpoint_snapshot(
2406         const struct ast_sip_endpoint *endpoint);
2407
2408 /*!
2409  * \brief Retrieve the device state for an endpoint.
2410  *
2411  * \param endpoint The endpoint whose state is to be retrieved.
2412  * \retval The device state.
2413  */
2414 const char *ast_sip_get_device_state(const struct ast_sip_endpoint *endpoint);
2415
2416 /*!
2417  * \brief For every channel snapshot on an endpoint snapshot call the given
2418  *        'on_channel_snapshot' handler.
2419  *
2420  * \param endpoint_snapshot snapshot of an endpoint
2421  * \param on_channel_snapshot callback for each channel snapshot
2422  * \param arg user data passed to handler
2423  * \retval 0 Success, non-zero on failure
2424  */
2425 int ast_sip_for_each_channel_snapshot(const struct ast_endpoint_snapshot *endpoint_snapshot,
2426                 ao2_callback_fn on_channel_snapshot,
2427                                       void *arg);
2428
2429 /*!
2430  * \brief For every channel snapshot on an endpoint all the given
2431  *        'on_channel_snapshot' handler.
2432  *
2433  * \param endpoint endpoint
2434  * \param on_channel_snapshot callback for each channel snapshot
2435  * \param arg user data passed to handler
2436  * \retval 0 Success, non-zero on failure
2437  */
2438 int ast_sip_for_each_channel(const struct ast_sip_endpoint *endpoint,
2439                 ao2_callback_fn on_channel_snapshot,
2440                                       void *arg);
2441
2442 enum ast_sip_supplement_priority {
2443         /*! Top priority. Supplements with this priority are those that need to run before any others */
2444         AST_SIP_SUPPLEMENT_PRIORITY_FIRST = 0,
2445         /*! Channel creation priority.
2446          * chan_pjsip creates a channel at this priority. If your supplement depends on being run before
2447          * or after channel creation, then set your priority to be lower or higher than this value.
2448          */
2449         AST_SIP_SUPPLEMENT_PRIORITY_CHANNEL = 1000000,
2450         /*! Lowest priority. Supplements with this priority should be run after all other supplements */
2451         AST_SIP_SUPPLEMENT_PRIORITY_LAST = INT_MAX,
2452 };
2453
2454 /*!
2455  * \brief A supplement to SIP message processing
2456  *
2457  * These can be registered by any module in order to add
2458  * processing to incoming and outgoing SIP out of dialog
2459  * requests and responses
2460  */
2461 struct ast_sip_supplement {
2462         /*! Method on which to call the callbacks. If NULL, call on all methods */
2463         const char *method;
2464         /*! Priority for this supplement. Lower numbers are visited before higher numbers */
2465         enum ast_sip_supplement_priority priority;
2466         /*!
2467          * \brief Called on incoming SIP request
2468          * This method can indicate a failure in processing in its return. If there
2469          * is a failure, it is required that this method sends a response to the request.
2470          * This method is always called from a SIP servant thread.
2471          *
2472          * \note
2473          * The following PJSIP methods will not work properly:
2474          * pjsip_rdata_get_dlg()
2475          * pjsip_rdata_get_tsx()
2476          * The reason is that the rdata passed into this function is a cloned rdata structure,
2477          * and its module data is not copied during the cloning operation.
2478          * If you need to get the dialog, you can get it via session->inv_session->dlg.
2479          *
2480          * \note
2481          * There is no guarantee that a channel will be present on the session when this is called.
2482          */
2483         int (*incoming_request)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
2484         /*!
2485          * \brief Called on an incoming SIP response
2486          * This method is always called from a SIP servant thread.
2487          *
2488          * \note
2489          * The following PJSIP methods will not work properly:
2490          * pjsip_rdata_get_dlg()
2491          * pjsip_rdata_get_tsx()
2492          * The reason is that the rdata passed into this function is a cloned rdata structure,
2493          * and its module data is not copied during the cloning operation.
2494          * If you need to get the dialog, you can get it via session->inv_session->dlg.
2495          *
2496          * \note
2497          * There is no guarantee that a channel will be present on the session when this is called.
2498          */
2499         void (*incoming_response)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
2500         /*!
2501          * \brief Called on an outgoing SIP request
2502          * This method is always called from a SIP servant thread.
2503          */
2504         void (*outgoing_request)(struct ast_sip_endpoint *endpoint, struct ast_sip_contact *contact, struct pjsip_tx_data *tdata);
2505         /*!
2506          * \brief Called on an outgoing SIP response
2507          * This method is always called from a SIP servant thread.
2508          */
2509         void (*outgoing_response)(struct ast_sip_endpoint *endpoint, struct ast_sip_contact *contact, struct pjsip_tx_data *tdata);
2510         /*! Next item in the list */
2511         AST_LIST_ENTRY(ast_sip_supplement) next;
2512 };
2513
2514 /*!
2515  * \brief Register a supplement to SIP out of dialog processing
2516  *
2517  * This allows for someone to insert themselves in the processing of out
2518  * of dialog SIP requests and responses. This, for example could allow for
2519  * a module to set channel data based on headers in an incoming message.
2520  * Similarly, a module could reject an incoming request if desired.
2521  *
2522  * \param supplement The supplement to register
2523  * \retval 0 Success
2524  * \retval -1 Failure
2525  */
2526 int ast_sip_register_supplement(struct ast_sip_supplement *supplement);
2527
2528 /*!
2529  * \brief Unregister a an supplement to SIP out of dialog processing
2530  *
2531  * \param supplement The supplement to unregister
2532  */
2533 void ast_sip_unregister_supplement(struct ast_sip_supplement *supplement);
2534
2535 /*!
2536  * \brief Retrieve the global MWI taskprocessor high water alert trigger level.
2537  *
2538  * \since 13.12.0
2539  *
2540  * \retval the system MWI taskprocessor high water alert trigger level
2541  */
2542 unsigned int ast_sip_get_mwi_tps_queue_high(void);
2543
2544 /*!
2545  * \brief Retrieve the global MWI taskprocessor low water clear alert level.
2546  *
2547  * \since 13.12.0
2548  *
2549  * \retval the system MWI taskprocessor low water clear alert level
2550  */
2551 int ast_sip_get_mwi_tps_queue_low(void);
2552
2553 /*!
2554  * \brief Retrieve the global setting 'disable sending unsolicited mwi on startup'.
2555  * \since 13.12.0
2556  *
2557  * \retval non zero if disable.
2558  */
2559 unsigned int ast_sip_get_mwi_disable_initial_unsolicited(void);
2560
2561 /*!
2562  * \brief Retrieve the global setting 'ignore_uri_user_options'.
2563  * \since 13.12.0
2564  *
2565  * \retval non zero if ignore the user field options.
2566  */
2567 unsigned int ast_sip_get_ignore_uri_user_options(void);
2568
2569 /*!
2570  * \brief Truncate the URI user field options string if enabled.
2571  * \since 13.12.0
2572  *
2573  * \param str URI user field string to truncate if enabled
2574  *
2575  * \details
2576  * We need to be able to handle URI's looking like
2577  * "sip:1235557890;phone-context=national@x.x.x.x;user=phone"
2578  *
2579  * Where the URI user field is:
2580  * "1235557890;phone-context=national"
2581  *
2582  * When truncated the string will become:
2583  * "1235557890"
2584  */
2585 #define AST_SIP_USER_OPTIONS_TRUNCATE_CHECK(str)                                \
2586         do {                                                                                                            \
2587                 char *__semi = strchr((str), ';');                                              \
2588                 if (__semi && ast_sip_get_ignore_uri_user_options()) {  \
2589                         *__semi = '\0';                                                                         \
2590                 }                                                                                                               \
2591         } while (0)
2592
2593 /*!
2594  * \brief Retrieve the system debug setting (yes|no|host).
2595  *
2596  * \note returned string needs to be de-allocated by caller.
2597  *
2598  * \retval the system debug setting.
2599  */
2600 char *ast_sip_get_debug(void);
2601
2602 /*!
2603  * \brief Retrieve the global regcontext setting.
2604  *
2605  * \since 13.8.0
2606  *
2607  * \note returned string needs to be de-allocated by caller.
2608  *
2609  * \retval the global regcontext setting
2610  */
2611 char *ast_sip_get_regcontext(void);
2612
2613 /*!
2614  * \brief Retrieve the global endpoint_identifier_order setting.
2615  *
2616  * Specifies the order by which endpoint identifiers should be regarded.
2617  *
2618  * \retval the global endpoint_identifier_order value
2619  */
2620 char *ast_sip_get_endpoint_identifier_order(void);
2621
2622 /*!
2623  * \brief Retrieve the default voicemail extension.
2624  * \since 13.9.0
2625  *
2626  * \note returned string needs to be de-allocated by caller.
2627  *
2628  * \retval the default voicemail extension
2629  */
2630 char *ast_sip_get_default_voicemail_extension(void);
2631
2632 /*!
2633  * \brief Retrieve the global default realm.
2634  *
2635  * This is the value placed in outbound challenges' realm if there
2636  * is no better option (such as an auth-configured realm).
2637  *
2638  * \param[out] realm The default realm
2639  * \param size The buffer size of realm
2640  * \return nothing
2641  */
2642 void ast_sip_get_default_realm(char *realm, size_t size);
2643
2644 /*!
2645  * \brief Retrieve the global default from user.
2646  *
2647  * This is the value placed in outbound requests' From header if there
2648  * is no better option (such as an endpoint-configured from_user or
2649  * caller ID number).
2650  *
2651  * \param[out] from_user The default from user
2652  * \param size The buffer size of from_user
2653  * \return nothing
2654  */
2655 void ast_sip_get_default_from_user(char *from_user, size_t size);
2656
2657 /*! \brief Determines whether the res_pjsip module is loaded */
2658 #define CHECK_PJSIP_MODULE_LOADED()                             \
2659         do {                                                    \
2660                 if (!ast_module_check("res_pjsip.so")           \
2661                         || !ast_sip_get_pjsip_endpoint()) {     \
2662                         return AST_MODULE_LOAD_DECLINE;         \
2663                 }                                               \
2664         } while(0)
2665
2666 /*!
2667  * \brief Retrieve the system keep alive interval setting.
2668  *
2669  * \retval the keep alive interval.
2670  */
2671 unsigned int ast_sip_get_keep_alive_interval(void);
2672
2673 /*!
2674  * \brief Retrieve the system contact expiration check interval setting.
2675  *
2676  * \retval the contact expiration check interval.
2677  */
2678 unsigned int ast_sip_get_contact_expiration_check_interval(void);
2679
2680 /*!
2681  * \brief Retrieve the system setting 'disable multi domain'.
2682  * \since 13.9.0
2683  *
2684  * \retval non zero if disable multi domain.
2685  */
2686 unsigned int ast_sip_get_disable_multi_domain(void);
2687
2688 /*!
2689  * \brief Retrieve the system max initial qualify time.
2690  *
2691  * \retval the maximum initial qualify time.
2692  */
2693 unsigned int ast_sip_get_max_initial_qualify_time(void);
2694
2695 /*!
2696  * \brief translate ast_sip_contact_status_type to character string.
2697  *
2698  * \retval the character string equivalent.
2699  */
2700
2701 const char *ast_sip_get_contact_status_label(const enum ast_sip_contact_status_type status);
2702 const char *ast_sip_get_contact_short_status_label(const enum ast_sip_contact_status_type status);
2703
2704 /*!
2705  * \brief Set a request to use the next value in the list of resolved addresses.
2706  *
2707  * \param tdata the tx data from the original request
2708  * \retval 0 No more addresses to try
2709  * \retval 1 The request was successfully re-intialized
2710  */
2711 int ast_sip_failover_request(pjsip_tx_data *tdata);
2712
2713 /*
2714  * \brief Retrieve the local host address in IP form
2715  *
2716  * \param af The address family to retrieve
2717  * \param addr A place to store the local host address
2718  *
2719  * \retval 0 success
2720  * \retval -1 failure
2721  *
2722  * \since 13.6.0
2723  */
2724 int ast_sip_get_host_ip(int af, pj_sockaddr *addr);
2725
2726 /*!
2727  * \brief Retrieve the local host address in string form
2728  *
2729  * \param af The address family to retrieve
2730  *
2731  * \retval non-NULL success
2732  * \retval NULL failure
2733  *
2734  * \since 13.6.0
2735  *
2736  * \note An empty string may be returned if the address family is valid but no local address exists
2737  */
2738 const char *ast_sip_get_host_ip_string(int af);
2739
2740 /*!
2741  * \brief Return the size of the SIP threadpool's task queue
2742  * \since 13.7.0
2743  */
2744 long ast_sip_threadpool_queue_size(void);
2745
2746 /*!
2747  * \brief Retrieve transport state
2748  * \since 13.7.1
2749  *
2750  * @param transport_id
2751  * @returns transport_state
2752  *
2753  * \note ao2_cleanup(...) or ao2_ref(...,  -1) must be called on the returned object
2754  */
2755 struct ast_sip_transport_state *ast_sip_get_transport_state(const char *transport_id);
2756
2757 /*!
2758  * \brief Retrieves all transport states
2759  * \since 13.7.1
2760  *
2761  * @returns ao2_container
2762  *
2763  * \note ao2_cleanup(...) or ao2_ref(...,  -1) must be called on the returned object
2764  */
2765 struct ao2_container *ast_sip_get_transport_states(void);
2766
2767 /*!
2768  * \brief Sets pjsip_tpselector from ast_sip_transport
2769  * \since 13.8.0
2770  *
2771  * \param transport The transport to be used
2772  * \param selector The selector to be populated
2773  * \retval 0 success
2774  * \retval -1 failure
2775  */
2776 int ast_sip_set_tpselector_from_transport(const struct ast_sip_transport *transport, pjsip_tpselector *selector);
2777
2778 /*!
2779  * \brief Sets pjsip_tpselector from ast_sip_transport
2780  * \since 13.8.0
2781  *
2782  * \param transport_name The name of the transport to be used
2783  * \param selector The selector to be populated
2784  * \retval 0 success
2785  * \retval -1 failure
2786  */
2787 int ast_sip_set_tpselector_from_transport_name(const char *transport_name, pjsip_tpselector *selector);
2788
2789 /*!
2790  * \brief Set name and number information on an identity header.
2791  *
2792  * \param pool Memory pool to use for string duplication
2793  * \param id_hdr A From, P-Asserted-Identity, or Remote-Party-ID header to modify
2794  * \param id The identity information to apply to the header
2795  */
2796 void ast_sip_modify_id_header(pj_pool_t *pool, pjsip_fromto_hdr *id_hdr,
2797         const struct ast_party_id *id);
2798
2799 /*!
2800  * \brief Retrieve the unidentified request security event thresholds
2801  * \since 13.8.0
2802  *
2803  * \param count The maximum number of unidentified requests per source ip to accumulate before emitting a security event
2804  * \param period The period in seconds over which to accumulate unidentified requests
2805  * \param prune_interval The interval in seconds at which expired entries will be pruned
2806  */
2807 void ast_sip_get_unidentified_request_thresholds(unsigned int *count, unsigned int *period,
2808         unsigned int *prune_interval);
2809
2810 /*!
2811  * \brief Get the transport name from an endpoint or request uri
2812  * \since 13.15.0
2813  *
2814  * \param endpoint
2815  * \param sip_uri
2816  * \param buf Buffer to receive transport name
2817  * \param buf_len Buffer length
2818  *
2819  * \retval 0 Success
2820  * \retval -1 Failure
2821  *
2822  * \note
2823  * If endpoint->transport is not NULL, it is returned in buf.
2824  * Otherwise if sip_uri has an 'x-ast-txp' parameter AND the sip_uri host is
2825  * an ip4 or ip6 address, its value is returned,
2826  */
2827 int ast_sip_get_transport_name(const struct ast_sip_endpoint *endpoint,
2828         pjsip_sip_uri *sip_uri, char *buf, size_t buf_len);
2829
2830 /*!
2831  * \brief Sets pjsip_tpselector from an endpoint or uri
2832  * \since 13.15.0
2833  *
2834  * \param endpoint If endpoint->transport is set, it's used
2835  * \param sip_uri If sip_uri contains a x-ast-txp parameter, it's used
2836  * \param selector The selector to be populated
2837  *
2838  * \retval 0 success
2839  * \retval -1 failure
2840  */
2841 int ast_sip_set_tpselector_from_ep_or_uri(const struct ast_sip_endpoint *endpoint,
2842         pjsip_sip_uri *sip_uri, pjsip_tpselector *selector);
2843
2844 /*!
2845  * \brief Set the transport on a dialog
2846  * \since 13.15.0
2847  *
2848  * \param endpoint
2849  * \param dlg
2850  * \param selector (optional)
2851  *
2852  * \note
2853  * This API calls ast_sip_get_transport_name(endpoint, dlg->target) and if the result is
2854  * non-NULL, calls pjsip_dlg_set_transport.  If 'selector' is non-NULL, it is updated with
2855  * the selector used.
2856  */
2857 int ast_sip_dlg_set_transport(const struct ast_sip_endpoint *endpoint, pjsip_dialog *dlg,
2858         pjsip_tpselector *selector);
2859
2860 #endif /* _RES_PJSIP_H */