res_pjsip: New endpoint option "notify_early_inuse_ringing"
[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         /*! Whether to notifies dialog-info 'early' on INUSE && RINGING state */
773         unsigned int notify_early_inuse_ringing;
774 };
775
776 /*! URI parameter for symmetric transport */
777 #define AST_SIP_X_AST_TXP "x-ast-txp"
778 #define AST_SIP_X_AST_TXP_LEN 9
779
780 /*!
781  * \brief Initialize an auth vector with the configured values.
782  *
783  * \param vector Vector to initialize
784  * \param auth_names Comma-separated list of names to set in the array
785  * \retval 0 Success
786  * \retval non-zero Failure
787  */
788 int ast_sip_auth_vector_init(struct ast_sip_auth_vector *vector, const char *auth_names);
789
790 /*!
791  * \brief Free contents of an auth vector.
792  *
793  * \param array Vector whose contents are to be freed
794  */
795 void ast_sip_auth_vector_destroy(struct ast_sip_auth_vector *vector);
796
797 /*!
798  * \brief Possible returns from ast_sip_check_authentication
799  */
800 enum ast_sip_check_auth_result {
801     /*! Authentication needs to be challenged */
802     AST_SIP_AUTHENTICATION_CHALLENGE,
803     /*! Authentication succeeded */
804     AST_SIP_AUTHENTICATION_SUCCESS,
805     /*! Authentication failed */
806     AST_SIP_AUTHENTICATION_FAILED,
807     /*! Authentication encountered some internal error */
808     AST_SIP_AUTHENTICATION_ERROR,
809 };
810
811 /*!
812  * \brief An interchangeable way of handling digest authentication for SIP.
813  *
814  * An authenticator is responsible for filling in the callbacks provided below. Each is called from a publicly available
815  * function in res_sip. The authenticator can use configuration or other local policy to determine whether authentication
816  * should take place and what credentials should be used when challenging and authenticating a request.
817  */
818 struct ast_sip_authenticator {
819     /*!
820      * \brief Check if a request requires authentication
821      * See ast_sip_requires_authentication for more details
822      */
823     int (*requires_authentication)(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
824         /*!
825          * \brief Check that an incoming request passes authentication.
826          *
827          * The tdata parameter is useful for adding information such as digest challenges.
828          *
829          * \param endpoint The endpoint sending the incoming request
830          * \param rdata The incoming request
831          * \param tdata Tentative outgoing request.
832          */
833         enum ast_sip_check_auth_result (*check_authentication)(struct ast_sip_endpoint *endpoint,
834                         pjsip_rx_data *rdata, pjsip_tx_data *tdata);
835 };
836
837 /*!
838  * \brief an interchangeable way of responding to authentication challenges
839  *
840  * An outbound authenticator takes incoming challenges and formulates a new SIP request with
841  * credentials.
842  */
843 struct ast_sip_outbound_authenticator {
844         /*!
845          * \brief Create a new request with authentication credentials
846          *
847          * \param auths A vector of IDs of auth sorcery objects
848          * \param challenge The SIP response with authentication challenge(s)
849          * \param old_request The request that received the auth challenge(s)
850          * \param new_request The new SIP request with challenge response(s)
851          * \retval 0 Successfully created new request
852          * \retval -1 Failed to create a new request
853          */
854         int (*create_request_with_auth)(const struct ast_sip_auth_vector *auths, struct pjsip_rx_data *challenge,
855                         struct pjsip_tx_data *old_request, struct pjsip_tx_data **new_request);
856 };
857
858 /*!
859  * \brief An entity responsible for identifying the source of a SIP message
860  */
861 struct ast_sip_endpoint_identifier {
862     /*!
863      * \brief Callback used to identify the source of a message.
864      * See ast_sip_identify_endpoint for more details
865      */
866     struct ast_sip_endpoint *(*identify_endpoint)(pjsip_rx_data *rdata);
867 };
868
869 /*!
870  * \brief Contact retrieval filtering flags
871  */
872 enum ast_sip_contact_filter {
873         /*! \brief Default filter flags */
874         AST_SIP_CONTACT_FILTER_DEFAULT = 0,
875
876         /*! \brief Return only reachable or unknown contacts */
877         AST_SIP_CONTACT_FILTER_REACHABLE = (1 << 0),
878 };
879
880 /*!
881  * \brief Register a SIP service in Asterisk.
882  *
883  * This is more-or-less a wrapper around pjsip_endpt_register_module().
884  * Registering a service makes it so that PJSIP will call into the
885  * service at appropriate times. For more information about PJSIP module
886  * callbacks, see the PJSIP documentation. Asterisk modules that call
887  * this function will likely do so at module load time.
888  *
889  * \param module The module that is to be registered with PJSIP
890  * \retval 0 Success
891  * \retval -1 Failure
892  */
893 int ast_sip_register_service(pjsip_module *module);
894
895 /*!
896  * This is the opposite of ast_sip_register_service().  Unregistering a
897  * service means that PJSIP will no longer call into the module any more.
898  * This will likely occur when an Asterisk module is unloaded.
899  *
900  * \param module The PJSIP module to unregister
901  */
902 void ast_sip_unregister_service(pjsip_module *module);
903
904 /*!
905  * \brief Register a SIP authenticator
906  *
907  * An authenticator has three main purposes:
908  * 1) Determining if authentication should be performed on an incoming request
909  * 2) Gathering credentials necessary for issuing an authentication challenge
910  * 3) Authenticating a request that has credentials
911  *
912  * Asterisk provides a default authenticator, but it may be replaced by a
913  * custom one if desired.
914  *
915  * \param auth The authenticator to register
916  * \retval 0 Success
917  * \retval -1 Failure
918  */
919 int ast_sip_register_authenticator(struct ast_sip_authenticator *auth);
920
921 /*!
922  * \brief Unregister a SIP authenticator
923  *
924  * When there is no authenticator registered, requests cannot be challenged
925  * or authenticated.
926  *
927  * \param auth The authenticator to unregister
928  */
929 void ast_sip_unregister_authenticator(struct ast_sip_authenticator *auth);
930
931  /*!
932  * \brief Register an outbound SIP authenticator
933  *
934  * An outbound authenticator is responsible for creating responses to
935  * authentication challenges by remote endpoints.
936  *
937  * \param auth The authenticator to register
938  * \retval 0 Success
939  * \retval -1 Failure
940  */
941 int ast_sip_register_outbound_authenticator(struct ast_sip_outbound_authenticator *outbound_auth);
942
943 /*!
944  * \brief Unregister an outbound SIP authenticator
945  *
946  * When there is no outbound authenticator registered, authentication challenges
947  * will be handled as any other final response would be.
948  *
949  * \param auth The authenticator to unregister
950  */
951 void ast_sip_unregister_outbound_authenticator(struct ast_sip_outbound_authenticator *auth);
952
953 /*!
954  * \brief Register a SIP endpoint identifier with a name.
955  *
956  * An endpoint identifier's purpose is to determine which endpoint a given SIP
957  * message has come from.
958  *
959  * Multiple endpoint identifiers may be registered so that if an endpoint
960  * cannot be identified by one identifier, it may be identified by another.
961  *
962  * \param identifier The SIP endpoint identifier to register
963  * \param name The name of the endpoint identifier
964  * \retval 0 Success
965  * \retval -1 Failure
966  */
967 int ast_sip_register_endpoint_identifier_with_name(struct ast_sip_endpoint_identifier *identifier,
968                                                    const char *name);
969
970 /*!
971  * \brief Register a SIP endpoint identifier
972  *
973  * An endpoint identifier's purpose is to determine which endpoint a given SIP
974  * message has come from.
975  *
976  * Multiple endpoint identifiers may be registered so that if an endpoint
977  * cannot be identified by one identifier, it may be identified by another.
978  *
979  * Asterisk provides two endpoint identifiers. One identifies endpoints based
980  * on the user part of the From header URI. The other identifies endpoints based
981  * on the source IP address.
982  *
983  * If the order in which endpoint identifiers is run is important to you, then
984  * be sure to load individual endpoint identifier modules in the order you wish
985  * for them to be run in modules.conf
986  *
987  * \note endpoint identifiers registered using this method (no name specified)
988  *       are placed at the front of the endpoint identifiers list ahead of any
989  *       named identifiers.
990  *
991  * \param identifier The SIP endpoint identifier to register
992  * \retval 0 Success
993  * \retval -1 Failure
994  */
995 int ast_sip_register_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier);
996
997 /*!
998  * \brief Unregister a SIP endpoint identifier
999  *
1000  * This stops an endpoint identifier from being used.
1001  *
1002  * \param identifier The SIP endoint identifier to unregister
1003  */
1004 void ast_sip_unregister_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier);
1005
1006 /*!
1007  * \brief Allocate a new SIP endpoint
1008  *
1009  * This will return an endpoint with its refcount increased by one. This reference
1010  * can be released using ao2_ref().
1011  *
1012  * \param name The name of the endpoint.
1013  * \retval NULL Endpoint allocation failed
1014  * \retval non-NULL The newly allocated endpoint
1015  */
1016 void *ast_sip_endpoint_alloc(const char *name);
1017
1018 /*!
1019  * \brief Change state of a persistent endpoint.
1020  *
1021  * \param endpoint The SIP endpoint name to change state.
1022  * \param state The new state
1023  * \retval 0 Success
1024  * \retval -1 Endpoint not found
1025  */
1026 int ast_sip_persistent_endpoint_update_state(const char *endpoint_name, enum ast_endpoint_state state);
1027
1028 /*!
1029  * \brief Get a pointer to the PJSIP endpoint.
1030  *
1031  * This is useful when modules have specific information they need
1032  * to register with the PJSIP core.
1033  * \retval NULL endpoint has not been created yet.
1034  * \retval non-NULL PJSIP endpoint.
1035  */
1036 pjsip_endpoint *ast_sip_get_pjsip_endpoint(void);
1037
1038 /*!
1039  * \brief Get a pointer to the SIP sorcery structure.
1040  *
1041  * \retval NULL sorcery has not been initialized
1042  * \retval non-NULL sorcery structure
1043  */
1044 struct ast_sorcery *ast_sip_get_sorcery(void);
1045
1046 /*!
1047  * \brief Retrieve a named AOR
1048  *
1049  * \param aor_name Name of the AOR
1050  *
1051  * \retval NULL if not found
1052  * \retval non-NULL if found
1053  */
1054 struct ast_sip_aor *ast_sip_location_retrieve_aor(const char *aor_name);
1055
1056 /*!
1057  * \brief Retrieve the first bound contact for an AOR
1058  *
1059  * \param aor Pointer to the AOR
1060  * \retval NULL if no contacts available
1061  * \retval non-NULL if contacts available
1062  */
1063 struct ast_sip_contact *ast_sip_location_retrieve_first_aor_contact(const struct ast_sip_aor *aor);
1064
1065 /*!
1066  * \brief Retrieve the first bound contact for an AOR and filter based on flags
1067  * \since 13.16.0
1068  *
1069  * \param aor Pointer to the AOR
1070  * \param flags Filtering flags
1071  * \retval NULL if no contacts available
1072  * \retval non-NULL if contacts available
1073  */
1074 struct ast_sip_contact *ast_sip_location_retrieve_first_aor_contact_filtered(const struct ast_sip_aor *aor,
1075         unsigned int flags);
1076
1077 /*!
1078  * \brief Retrieve all contacts currently available for an AOR
1079  *
1080  * \param aor Pointer to the AOR
1081  *
1082  * \retval NULL if no contacts available
1083  * \retval non-NULL if contacts available
1084  *
1085  * \warning
1086  * Since this function prunes expired contacts before returning, it holds a named write
1087  * lock on the aor.  If you already hold the lock, call ast_sip_location_retrieve_aor_contacts_nolock instead.
1088  */
1089 struct ao2_container *ast_sip_location_retrieve_aor_contacts(const struct ast_sip_aor *aor);
1090
1091 /*!
1092  * \brief Retrieve all contacts currently available for an AOR and filter based on flags
1093  * \since 13.16.0
1094  *
1095  * \param aor Pointer to the AOR
1096  * \param flags Filtering flags
1097  *
1098  * \retval NULL if no contacts available
1099  * \retval non-NULL if contacts available
1100  *
1101  * \warning
1102  * Since this function prunes expired contacts before returning, it holds a named write
1103  * lock on the aor.  If you already hold the lock, call ast_sip_location_retrieve_aor_contacts_nolock instead.
1104  */
1105 struct ao2_container *ast_sip_location_retrieve_aor_contacts_filtered(const struct ast_sip_aor *aor,
1106         unsigned int flags);
1107
1108 /*!
1109  * \brief Retrieve all contacts currently available for an AOR without locking the AOR
1110  * \since 13.9.0
1111  *
1112  * \param aor Pointer to the AOR
1113  *
1114  * \retval NULL if no contacts available
1115  * \retval non-NULL if contacts available
1116  *
1117  * \warning
1118  * This function should only be called if you already hold a named write lock on the aor.
1119  */
1120 struct ao2_container *ast_sip_location_retrieve_aor_contacts_nolock(const struct ast_sip_aor *aor);
1121
1122 /*!
1123  * \brief Retrieve all contacts currently available for an AOR without locking the AOR and filter based on flags
1124  * \since 13.16.0
1125  *
1126  * \param aor Pointer to the AOR
1127  * \param flags Filtering flags
1128  *
1129  * \retval NULL if no contacts available
1130  * \retval non-NULL if contacts available
1131  *
1132  * \warning
1133  * This function should only be called if you already hold a named write lock on the aor.
1134  */
1135 struct ao2_container *ast_sip_location_retrieve_aor_contacts_nolock_filtered(const struct ast_sip_aor *aor,
1136         unsigned int flags);
1137
1138 /*!
1139  * \brief Retrieve the first bound contact from a list of AORs
1140  *
1141  * \param aor_list A comma-separated list of AOR names
1142  * \retval NULL if no contacts available
1143  * \retval non-NULL if contacts available
1144  */
1145 struct ast_sip_contact *ast_sip_location_retrieve_contact_from_aor_list(const char *aor_list);
1146
1147 /*!
1148  * \brief Retrieve all contacts from a list of AORs
1149  *
1150  * \param aor_list A comma-separated list of AOR names
1151  * \retval NULL if no contacts available
1152  * \retval non-NULL container (which must be freed) if contacts available
1153  */
1154 struct ao2_container *ast_sip_location_retrieve_contacts_from_aor_list(const char *aor_list);
1155
1156 /*!
1157  * \brief Retrieve the first bound contact AND the AOR chosen from a list of AORs
1158  *
1159  * \param aor_list A comma-separated list of AOR names
1160  * \param aor The chosen AOR
1161  * \param contact The chosen contact
1162  */
1163  void ast_sip_location_retrieve_contact_and_aor_from_list(const char *aor_list, struct ast_sip_aor **aor,
1164         struct ast_sip_contact **contact);
1165
1166 /*!
1167  * \brief Retrieve the first bound contact AND the AOR chosen from a list of AORs and filter based on flags
1168  * \since 13.16.0
1169  *
1170  * \param aor_list A comma-separated list of AOR names
1171  * \param flags Filtering flags
1172  * \param aor The chosen AOR
1173  * \param contact The chosen contact
1174  */
1175 void ast_sip_location_retrieve_contact_and_aor_from_list_filtered(const char *aor_list, unsigned int flags,
1176         struct ast_sip_aor **aor, struct ast_sip_contact **contact);
1177
1178 /*!
1179  * \brief Retrieve a named contact
1180  *
1181  * \param contact_name Name of the contact
1182  *
1183  * \retval NULL if not found
1184  * \retval non-NULL if found
1185  */
1186 struct ast_sip_contact *ast_sip_location_retrieve_contact(const char *contact_name);
1187
1188 /*!
1189  * \brief Add a new contact to an AOR
1190  *
1191  * \param aor Pointer to the AOR
1192  * \param uri Full contact URI
1193  * \param expiration_time Optional expiration time of the contact
1194  * \param path_info Path information
1195  * \param user_agent User-Agent header from REGISTER request
1196  * \param endpoint The endpoint that resulted in the contact being added
1197  *
1198  * \retval -1 failure
1199  * \retval 0 success
1200  *
1201  * \warning
1202  * This function holds a named write lock on the aor.  If you already hold the lock
1203  * you should call ast_sip_location_add_contact_nolock instead.
1204  */
1205 int ast_sip_location_add_contact(struct ast_sip_aor *aor, const char *uri,
1206         struct timeval expiration_time, const char *path_info, const char *user_agent,
1207         const char *via_addr, int via_port, const char *call_id,
1208         struct ast_sip_endpoint *endpoint);
1209
1210 /*!
1211  * \brief Add a new contact to an AOR without locking the AOR
1212  * \since 13.9.0
1213  *
1214  * \param aor Pointer to the AOR
1215  * \param uri Full contact URI
1216  * \param expiration_time Optional expiration time of the contact
1217  * \param path_info Path information
1218  * \param user_agent User-Agent header from REGISTER request
1219  * \param endpoint The endpoint that resulted in the contact being added
1220  *
1221  * \retval -1 failure
1222  * \retval 0 success
1223  *
1224  * \warning
1225  * This function should only be called if you already hold a named write lock on the aor.
1226  */
1227 int ast_sip_location_add_contact_nolock(struct ast_sip_aor *aor, const char *uri,
1228         struct timeval expiration_time, const char *path_info, const char *user_agent,
1229         const char *via_addr, int via_port, const char *call_id,
1230         struct ast_sip_endpoint *endpoint);
1231
1232 /*!
1233  * \brief Update a contact
1234  *
1235  * \param contact New contact object with details
1236  *
1237  * \retval -1 failure
1238  * \retval 0 success
1239  */
1240 int ast_sip_location_update_contact(struct ast_sip_contact *contact);
1241
1242 /*!
1243 * \brief Delete a contact
1244 *
1245 * \param contact Contact object to delete
1246 *
1247 * \retval -1 failure
1248 * \retval 0 success
1249 */
1250 int ast_sip_location_delete_contact(struct ast_sip_contact *contact);
1251
1252 /*!
1253  * \brief Callback called when an outbound request with authentication credentials is to be sent in dialog
1254  *
1255  * This callback will have the created request on it. The callback's purpose is to do any extra
1256  * housekeeping that needs to be done as well as to send the request out.
1257  *
1258  * This callback is only necessary if working with a PJSIP API that sits between the application
1259  * and the dialog layer.
1260  *
1261  * \param dlg The dialog to which the request belongs
1262  * \param tdata The created request to be sent out
1263  * \param user_data Data supplied with the callback
1264  *
1265  * \retval 0 Success
1266  * \retval -1 Failure
1267  */
1268 typedef int (*ast_sip_dialog_outbound_auth_cb)(pjsip_dialog *dlg, pjsip_tx_data *tdata, void *user_data);
1269
1270 /*!
1271  * \brief Set up outbound authentication on a SIP dialog
1272  *
1273  * This sets up the infrastructure so that all requests associated with a created dialog
1274  * can be re-sent with authentication credentials if the original request is challenged.
1275  *
1276  * \param dlg The dialog on which requests will be authenticated
1277  * \param endpoint The endpoint whom this dialog pertains to
1278  * \param cb Callback to call to send requests with authentication
1279  * \param user_data Data to be provided to the callback when it is called
1280  *
1281  * \retval 0 Success
1282  * \retval -1 Failure
1283  */
1284 int ast_sip_dialog_setup_outbound_authentication(pjsip_dialog *dlg, const struct ast_sip_endpoint *endpoint,
1285                 ast_sip_dialog_outbound_auth_cb cb, void *user_data);
1286
1287 /*!
1288  * \brief Retrieves a reference to the artificial auth.
1289  *
1290  * \retval The artificial auth
1291  */
1292 struct ast_sip_auth *ast_sip_get_artificial_auth(void);
1293
1294 /*!
1295  * \brief Retrieves a reference to the artificial endpoint.
1296  *
1297  * \retval The artificial endpoint
1298  */
1299 struct ast_sip_endpoint *ast_sip_get_artificial_endpoint(void);
1300
1301 /*! \defgroup pjsip_threading PJSIP Threading Model
1302  * @{
1303  * \page PJSIP PJSIP Threading Model
1304  *
1305  * There are three major types of threads that SIP will have to deal with:
1306  * \li Asterisk threads
1307  * \li PJSIP threads
1308  * \li SIP threadpool threads (a.k.a. "servants")
1309  *
1310  * \par Asterisk Threads
1311  *
1312  * Asterisk threads are those that originate from outside of SIP but within
1313  * Asterisk. The most common of these threads are PBX (channel) threads and
1314  * the autoservice thread. Most interaction with these threads will be through
1315  * channel technology callbacks. Within these threads, it is fine to handle
1316  * Asterisk data from outside of SIP, but any handling of SIP data should be
1317  * left to servants, \b especially if you wish to call into PJSIP for anything.
1318  * Asterisk threads are not registered with PJLIB, so attempting to call into
1319  * PJSIP will cause an assertion to be triggered, thus causing the program to
1320  * crash.
1321  *
1322  * \par PJSIP Threads
1323  *
1324  * PJSIP threads are those that originate from handling of PJSIP events, such
1325  * as an incoming SIP request or response, or a transaction timeout. The role
1326  * of these threads is to process information as quickly as possible so that
1327  * the next item on the SIP socket(s) can be serviced. On incoming messages,
1328  * Asterisk automatically will push the request to a servant thread. When your
1329  * module callback is called, processing will already be in a servant. However,
1330  * for other PSJIP events, such as transaction state changes due to timer
1331  * expirations, your module will be called into from a PJSIP thread. If you
1332  * are called into from a PJSIP thread, then you should push whatever processing
1333  * is needed to a servant as soon as possible. You can discern if you are currently
1334  * in a SIP servant thread using the \ref ast_sip_thread_is_servant function.
1335  *
1336  * \par Servants
1337  *
1338  * Servants are where the bulk of SIP work should be performed. These threads
1339  * exist in order to do the work that Asterisk threads and PJSIP threads hand
1340  * off to them. Servant threads register themselves with PJLIB, meaning that
1341  * they are capable of calling PJSIP and PJLIB functions if they wish.
1342  *
1343  * \par Serializer
1344  *
1345  * Tasks are handed off to servant threads using the API call \ref ast_sip_push_task.
1346  * The first parameter of this call is a serializer. If this pointer
1347  * is NULL, then the work will be handed off to whatever servant can currently handle
1348  * the task. If this pointer is non-NULL, then the task will not be executed until
1349  * previous tasks pushed with the same serializer have completed. For more information
1350  * on serializers and the benefits they provide, see \ref ast_threadpool_serializer
1351  *
1352  * \par Scheduler
1353  *
1354  * Some situations require that a task run periodically or at a future time.  Normally
1355  * the ast_sched functionality would be used but ast_sched only uses 1 thread for all
1356  * tasks and that thread isn't registered with PJLIB and therefore can't do any PJSIP
1357  * related work.
1358  *
1359  * ast_sip_sched uses ast_sched only as a scheduled queue.  When a task is ready to run,
1360  * it's pushed to a Serializer to be invoked asynchronously by a Servant.  This ensures
1361  * that the task is executed in a PJLIB registered thread and allows the ast_sched thread
1362  * to immediately continue processing the queue.  The Serializer used by ast_sip_sched
1363  * is one of your choosing or a random one from the res_pjsip pool if you don't choose one.
1364  *
1365  * \note
1366  *
1367  * Do not make assumptions about individual threads based on a corresponding serializer.
1368  * In other words, just because several tasks use the same serializer when being pushed
1369  * to servants, it does not mean that the same thread is necessarily going to execute those
1370  * tasks, even though they are all guaranteed to be executed in sequence.
1371  */
1372
1373 typedef int (*ast_sip_task)(void *user_data);
1374
1375 /*!
1376  * \brief Create a new serializer for SIP tasks
1377  * \since 13.8.0
1378  *
1379  * See \ref ast_threadpool_serializer for more information on serializers.
1380  * SIP creates serializers so that tasks operating on similar data will run
1381  * in sequence.
1382  *
1383  * \param name Name of the serializer. (must be unique)
1384  *
1385  * \retval NULL Failure
1386  * \retval non-NULL Newly-created serializer
1387  */
1388 struct ast_taskprocessor *ast_sip_create_serializer(const char *name);
1389
1390 struct ast_serializer_shutdown_group;
1391
1392 /*!
1393  * \brief Create a new serializer for SIP tasks
1394  * \since 13.8.0
1395  *
1396  * See \ref ast_threadpool_serializer for more information on serializers.
1397  * SIP creates serializers so that tasks operating on similar data will run
1398  * in sequence.
1399  *
1400  * \param name Name of the serializer. (must be unique)
1401  * \param shutdown_group Group shutdown controller. (NULL if no group association)
1402  *
1403  * \retval NULL Failure
1404  * \retval non-NULL Newly-created serializer
1405  */
1406 struct ast_taskprocessor *ast_sip_create_serializer_group(const char *name, struct ast_serializer_shutdown_group *shutdown_group);
1407
1408 /*!
1409  * \brief Determine the distributor serializer for the SIP message.
1410  * \since 13.10.0
1411  *
1412  * \param rdata The incoming message.
1413  *
1414  * \retval Calculated distributor serializer on success.
1415  * \retval NULL on error.
1416  */
1417 struct ast_taskprocessor *ast_sip_get_distributor_serializer(pjsip_rx_data *rdata);
1418
1419 /*!
1420  * \brief Set a serializer on a SIP dialog so requests and responses are automatically serialized
1421  *
1422  * Passing a NULL serializer is a way to remove a serializer from a dialog.
1423  *
1424  * \param dlg The SIP dialog itself
1425  * \param serializer The serializer to use
1426  */
1427 void ast_sip_dialog_set_serializer(pjsip_dialog *dlg, struct ast_taskprocessor *serializer);
1428
1429 /*!
1430  * \brief Set an endpoint on a SIP dialog so in-dialog requests do not undergo endpoint lookup.
1431  *
1432  * \param dlg The SIP dialog itself
1433  * \param endpoint The endpoint that this dialog is communicating with
1434  */
1435 void ast_sip_dialog_set_endpoint(pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint);
1436
1437 /*!
1438  * \brief Get the endpoint associated with this dialog
1439  *
1440  * This function increases the refcount of the endpoint by one. Release
1441  * the reference once you are finished with the endpoint.
1442  *
1443  * \param dlg The SIP dialog from which to retrieve the endpoint
1444  * \retval NULL No endpoint associated with this dialog
1445  * \retval non-NULL The endpoint.
1446  */
1447 struct ast_sip_endpoint *ast_sip_dialog_get_endpoint(pjsip_dialog *dlg);
1448
1449 /*!
1450  * \brief Pushes a task to SIP servants
1451  *
1452  * This uses the serializer provided to determine how to push the task.
1453  * If the serializer is NULL, then the task will be pushed to the
1454  * servants directly. If the serializer is non-NULL, then the task will be
1455  * queued behind other tasks associated with the same serializer.
1456  *
1457  * \param serializer The serializer to which the task belongs. Can be NULL
1458  * \param sip_task The task to execute
1459  * \param task_data The parameter to pass to the task when it executes
1460  * \retval 0 Success
1461  * \retval -1 Failure
1462  */
1463 int ast_sip_push_task(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1464
1465 /*!
1466  * \brief Push a task to SIP servants and wait for it to complete
1467  *
1468  * Like \ref ast_sip_push_task except that it blocks until the task completes.
1469  *
1470  * \warning \b Never use this function in a SIP servant thread. This can potentially
1471  * cause a deadlock. If you are in a SIP servant thread, just call your function
1472  * in-line.
1473  *
1474  * \warning \b Never hold locks that may be acquired by a SIP servant thread when
1475  * calling this function. Doing so may cause a deadlock if all SIP servant threads
1476  * are blocked waiting to acquire the lock while the thread holding the lock is
1477  * waiting for a free SIP servant thread.
1478  *
1479  * \param serializer The SIP serializer to which the task belongs. May be NULL.
1480  * \param sip_task The task to execute
1481  * \param task_data The parameter to pass to the task when it executes
1482  * \retval 0 Success
1483  * \retval -1 Failure
1484  */
1485 int ast_sip_push_task_synchronous(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1486
1487 /*!
1488  * \brief Determine if the current thread is a SIP servant thread
1489  *
1490  * \retval 0 This is not a SIP servant thread
1491  * \retval 1 This is a SIP servant thread
1492  */
1493 int ast_sip_thread_is_servant(void);
1494
1495 /*!
1496  * \brief Task flags for the res_pjsip scheduler
1497  *
1498  * The default is AST_SIP_SCHED_TASK_FIXED
1499  *                | AST_SIP_SCHED_TASK_DATA_NOT_AO2
1500  *                | AST_SIP_SCHED_TASK_DATA_NO_CLEANUP
1501  *                | AST_SIP_SCHED_TASK_PERIODIC
1502  */
1503 enum ast_sip_scheduler_task_flags {
1504         /*!
1505          * The defaults
1506          */
1507         AST_SIP_SCHED_TASK_DEFAULTS = (0 << 0),
1508
1509         /*!
1510          * Run at a fixed interval.
1511          * Stop scheduling if the callback returns 0.
1512          * Any other value is ignored.
1513          */
1514         AST_SIP_SCHED_TASK_FIXED = (0 << 0),
1515         /*!
1516          * Run at a variable interval.
1517          * Stop scheduling if the callback returns 0.
1518          * Any other return value is used as the new interval.
1519          */
1520         AST_SIP_SCHED_TASK_VARIABLE = (1 << 0),
1521
1522         /*!
1523          * The task data is not an AO2 object.
1524          */
1525         AST_SIP_SCHED_TASK_DATA_NOT_AO2 = (0 << 1),
1526         /*!
1527          * The task data is an AO2 object.
1528          * A reference count will be held by the scheduler until
1529          * after the task has run for the final time (if ever).
1530          */
1531         AST_SIP_SCHED_TASK_DATA_AO2 = (1 << 1),
1532
1533         /*!
1534          * Don't take any cleanup action on the data
1535          */
1536         AST_SIP_SCHED_TASK_DATA_NO_CLEANUP = (0 << 3),
1537         /*!
1538          * If AST_SIP_SCHED_TASK_DATA_AO2 is set, decrement the reference count
1539          * otherwise call ast_free on it.
1540          */
1541         AST_SIP_SCHED_TASK_DATA_FREE = ( 1 << 3 ),
1542
1543         /*! \brief AST_SIP_SCHED_TASK_PERIODIC
1544          * The task is scheduled at multiples of interval
1545          * \see Interval
1546          */
1547         AST_SIP_SCHED_TASK_PERIODIC = (0 << 4),
1548         /*! \brief AST_SIP_SCHED_TASK_DELAY
1549          * The next invocation of the task is at last finish + interval
1550          * \see Interval
1551          */
1552         AST_SIP_SCHED_TASK_DELAY = (1 << 4),
1553 };
1554
1555 /*!
1556  * \brief Scheduler task data structure
1557  */
1558 struct ast_sip_sched_task;
1559
1560 /*!
1561  * \brief Schedule a task to run in the res_pjsip thread pool
1562  * \since 13.9.0
1563  *
1564  * \param serializer The serializer to use.  If NULL, don't use a serializer (see note below)
1565  * \param interval The invocation interval in milliseconds (see note below)
1566  * \param sip_task The task to invoke
1567  * \param name An optional name to associate with the task
1568  * \param task_data Optional data to pass to the task
1569  * \param flags One of enum ast_sip_scheduler_task_type
1570  *
1571  * \returns Pointer to \ref ast_sip_sched_task ao2 object which must be dereferenced when done.
1572  *
1573  * \paragraph Serialization
1574  *
1575  * Specifying a serializer guarantees serialized execution but NOT specifying a serializer
1576  * may still result in tasks being effectively serialized if the thread pool is busy.
1577  * The point of the serializer BTW is not to prevent parallel executions of the SAME task.
1578  * That happens automatically (see below).  It's to prevent the task from running at the same
1579  * time as other work using the same serializer, whether or not it's being run by the scheduler.
1580  *
1581  * \paragraph Interval
1582  *
1583  * The interval is used to calculate the next time the task should run.  There are two models.
1584  *
1585  * \ref AST_SIP_SCHED_TASK_PERIODIC specifies that the invocations of the task occur at the
1586  * specific interval.  That is, every \ref "interval" milliseconds, regardless of how long the task
1587  * takes. If the task takes longer than \ref interval, it will be scheduled at the next available
1588  * multiple of \ref interval.  For exmaple: If the task has an interval of 60 seconds and the task
1589  * takes 70 seconds, the next invocation will happen at 120 seconds.
1590  *
1591  * \ref AST_SIP_SCHED_TASK_DELAY specifies that the next invocation of the task should start
1592  * at \ref interval milliseconds after the current invocation has finished.
1593  *
1594  */
1595 struct ast_sip_sched_task *ast_sip_schedule_task(struct ast_taskprocessor *serializer,
1596         int interval, ast_sip_task sip_task, char *name, void *task_data,
1597         enum ast_sip_scheduler_task_flags flags);
1598
1599 /*!
1600  * \brief Cancels the next invocation of a task
1601  * \since 13.9.0
1602  *
1603  * \param schtd The task structure pointer
1604  * \retval 0 Success
1605  * \retval -1 Failure
1606  * \note Only cancels future invocations not the currently running invocation.
1607  */
1608 int ast_sip_sched_task_cancel(struct ast_sip_sched_task *schtd);
1609
1610 /*!
1611  * \brief Cancels the next invocation of a task by name
1612  * \since 13.9.0
1613  *
1614  * \param name The task name
1615  * \retval 0 Success
1616  * \retval -1 Failure
1617  * \note Only cancels future invocations not the currently running invocation.
1618  */
1619 int ast_sip_sched_task_cancel_by_name(const char *name);
1620
1621 /*!
1622  * \brief Gets the last start and end times of the task
1623  * \since 13.9.0
1624  *
1625  * \param schtd The task structure pointer
1626  * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
1627  * \param[out] last_start Pointer to a timeval structure to contain the time when last started
1628  * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
1629  * \retval 0 Success
1630  * \retval -1 Failure
1631  * \note Any of the pointers can be NULL if you don't need them.
1632  */
1633 int ast_sip_sched_task_get_times(struct ast_sip_sched_task *schtd,
1634         struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end);
1635
1636 /*!
1637  * \brief Gets the last start and end times of the task by name
1638  * \since 13.9.0
1639  *
1640  * \param name The task name
1641  * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
1642  * \param[out] last_start Pointer to a timeval structure to contain the time when last started
1643  * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
1644  * \retval 0 Success
1645  * \retval -1 Failure
1646  * \note Any of the pointers can be NULL if you don't need them.
1647  */
1648 int ast_sip_sched_task_get_times_by_name(const char *name,
1649         struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end);
1650
1651 /*!
1652  * \brief Gets the number of milliseconds until the next invocation
1653  * \since 13.9.0
1654  *
1655  * \param schtd The task structure pointer
1656  * \return The number of milliseconds until the next invocation or -1 if the task isn't scheduled
1657  */
1658 int ast_sip_sched_task_get_next_run(struct ast_sip_sched_task *schtd);
1659
1660 /*!
1661  * \brief Gets the number of milliseconds until the next invocation
1662  * \since 13.9.0
1663  *
1664  * \param name The task name
1665  * \return The number of milliseconds until the next invocation or -1 if the task isn't scheduled
1666  */
1667 int ast_sip_sched_task_get_next_run_by_name(const char *name);
1668
1669 /*!
1670  * \brief Checks if the task is currently running
1671  * \since 13.9.0
1672  *
1673  * \param schtd The task structure pointer
1674  * \retval 0 not running
1675  * \retval 1 running
1676  */
1677 int ast_sip_sched_is_task_running(struct ast_sip_sched_task *schtd);
1678
1679 /*!
1680  * \brief Checks if the task is currently running
1681  * \since 13.9.0
1682  *
1683  * \param name The task name
1684  * \retval 0 not running or not found
1685  * \retval 1 running
1686  */
1687 int ast_sip_sched_is_task_running_by_name(const char *name);
1688
1689 /*!
1690  * \brief Gets the task name
1691  * \since 13.9.0
1692  *
1693  * \param schtd The task structure pointer
1694  * \retval 0 success
1695  * \retval 1 failure
1696  */
1697 int ast_sip_sched_task_get_name(struct ast_sip_sched_task *schtd, char *name, size_t maxlen);
1698
1699 /*!
1700  *  @}
1701  */
1702
1703 /*!
1704  * \brief SIP body description
1705  *
1706  * This contains a type and subtype that will be added as
1707  * the "Content-Type" for the message as well as the body
1708  * text.
1709  */
1710 struct ast_sip_body {
1711         /*! Type of the body, such as "application" */
1712         const char *type;
1713         /*! Subtype of the body, such as "sdp" */
1714         const char *subtype;
1715         /*! The text to go in the body */
1716         const char *body_text;
1717 };
1718
1719 /*!
1720  * \brief General purpose method for creating a UAC dialog with an endpoint
1721  *
1722  * \param endpoint A pointer to the endpoint
1723  * \param aor_name Optional name of the AOR to target, may even be an explicit SIP URI
1724  * \param request_user Optional user to place into the target URI
1725  *
1726  * \retval non-NULL success
1727  * \retval NULL failure
1728  */
1729 pjsip_dialog *ast_sip_create_dialog_uac(const struct ast_sip_endpoint *endpoint, const char *aor_name, const char *request_user);
1730
1731 /*!
1732  * \brief General purpose method for creating a UAS dialog with an endpoint
1733  *
1734  * \param endpoint A pointer to the endpoint
1735  * \param rdata The request that is starting the dialog
1736  * \param[out] status On failure, the reason for failure in creating the dialog
1737  */
1738 pjsip_dialog *ast_sip_create_dialog_uas(const struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pj_status_t *status);
1739
1740 /*!
1741  * \brief General purpose method for creating an rdata structure using specific information
1742  * \since 13.15.0
1743  *
1744  * \param rdata[out] The rdata structure that will be populated
1745  * \param packet A SIP message
1746  * \param src_name The source IP address of the message
1747  * \param src_port The source port of the message
1748  * \param transport_type The type of transport the message was received on
1749  * \param local_name The local IP address the message was received on
1750  * \param local_port The local port the message was received on
1751  * \param contact_uri The contact URI of the message
1752  *
1753  * \retval 0 success
1754  * \retval -1 failure
1755  */
1756 int ast_sip_create_rdata_with_contact(pjsip_rx_data *rdata, char *packet,
1757         const char *src_name, int src_port, char *transport_type, const char *local_name,
1758         int local_port, const char *contact_uri);
1759
1760 /*!
1761  * \brief General purpose method for creating an rdata structure using specific information
1762  *
1763  * \param rdata[out] The rdata structure that will be populated
1764  * \param packet A SIP message
1765  * \param src_name The source IP address of the message
1766  * \param src_port The source port of the message
1767  * \param transport_type The type of transport the message was received on
1768  * \param local_name The local IP address the message was received on
1769  * \param local_port The local port the message was received on
1770  *
1771  * \retval 0 success
1772  * \retval -1 failure
1773  */
1774 int ast_sip_create_rdata(pjsip_rx_data *rdata, char *packet, const char *src_name,
1775         int src_port, char *transport_type, const char *local_name, int local_port);
1776
1777 /*!
1778  * \brief General purpose method for creating a SIP request
1779  *
1780  * Its typical use would be to create one-off requests such as an out of dialog
1781  * SIP MESSAGE.
1782  *
1783  * The request can either be in- or out-of-dialog. If in-dialog, the
1784  * dlg parameter MUST be present. If out-of-dialog the endpoint parameter
1785  * MUST be present. If both are present, then we will assume that the message
1786  * is to be sent in-dialog.
1787  *
1788  * The uri parameter can be specified if the request should be sent to an explicit
1789  * URI rather than one configured on the endpoint.
1790  *
1791  * \param method The method of the SIP request to send
1792  * \param dlg Optional. If specified, the dialog on which to request the message.
1793  * \param endpoint Optional. If specified, the request will be created out-of-dialog to the endpoint.
1794  * \param uri Optional. If specified, the request will be sent to this URI rather
1795  * than one configured for the endpoint.
1796  * \param contact The contact with which this request is associated for out-of-dialog requests.
1797  * \param[out] tdata The newly-created request
1798  *
1799  * The provided contact is attached to tdata with its reference bumped, but will
1800  * not survive for the entire lifetime of tdata since the contact is cleaned up
1801  * when all supplements have completed execution.
1802  *
1803  * \retval 0 Success
1804  * \retval -1 Failure
1805  */
1806 int ast_sip_create_request(const char *method, struct pjsip_dialog *dlg,
1807                 struct ast_sip_endpoint *endpoint, const char *uri,
1808                 struct ast_sip_contact *contact, pjsip_tx_data **tdata);
1809
1810 /*!
1811  * \brief General purpose method for sending a SIP request
1812  *
1813  * This is a companion function for \ref ast_sip_create_request. The request
1814  * created there can be passed to this function, though any request may be
1815  * passed in.
1816  *
1817  * This will automatically set up handling outbound authentication challenges if
1818  * they arrive.
1819  *
1820  * \param tdata The request to send
1821  * \param dlg Optional. The dialog in which the request is sent.  Otherwise it is out-of-dialog.
1822  * \param endpoint Optional. If specified, the out-of-dialog request is sent to the endpoint.
1823  * \param token Data to be passed to the callback upon receipt of out-of-dialog response.
1824  * \param callback Callback to be called upon receipt of out-of-dialog response.
1825  *
1826  * \retval 0 Success
1827  * \retval -1 Failure (out-of-dialog callback will not be called.)
1828  */
1829 int ast_sip_send_request(pjsip_tx_data *tdata, struct pjsip_dialog *dlg,
1830         struct ast_sip_endpoint *endpoint, void *token,
1831         void (*callback)(void *token, pjsip_event *e));
1832
1833 /*!
1834  * \brief General purpose method for sending an Out-Of-Dialog SIP request
1835  *
1836  * This is a companion function for \ref ast_sip_create_request. The request
1837  * created there can be passed to this function, though any request may be
1838  * passed in.
1839  *
1840  * This will automatically set up handling outbound authentication challenges if
1841  * they arrive.
1842  *
1843  * \param tdata The request to send
1844  * \param endpoint Optional. If specified, the out-of-dialog request is sent to the endpoint.
1845  * \param timeout.  If non-zero, after the timeout the transaction will be terminated
1846  * and the callback will be called with the PJSIP_EVENT_TIMER type.
1847  * \param token Data to be passed to the callback upon receipt of out-of-dialog response.
1848  * \param callback Callback to be called upon receipt of out-of-dialog response.
1849  *
1850  * \retval 0 Success
1851  * \retval -1 Failure (out-of-dialog callback will not be called.)
1852  *
1853  * \note Timeout processing:
1854  * There are 2 timers associated with this request, PJSIP timer_b which is
1855  * set globally in the "system" section of pjsip.conf, and the timeout specified
1856  * on this call.  The timer that expires first (before normal completion) will
1857  * cause the callback to be run with e->body.tsx_state.type = PJSIP_EVENT_TIMER.
1858  * The timer that expires second is simply ignored and the callback is not run again.
1859  */
1860 int ast_sip_send_out_of_dialog_request(pjsip_tx_data *tdata,
1861         struct ast_sip_endpoint *endpoint, int timeout, void *token,
1862         void (*callback)(void *token, pjsip_event *e));
1863
1864 /*!
1865  * \brief General purpose method for creating a SIP response
1866  *
1867  * Its typical use would be to create responses for out of dialog
1868  * requests.
1869  *
1870  * \param rdata The rdata from the incoming request.
1871  * \param st_code The response code to transmit.
1872  * \param contact The contact with which this request is associated.
1873  * \param[out] tdata The newly-created response
1874  *
1875  * The provided contact is attached to tdata with its reference bumped, but will
1876  * not survive for the entire lifetime of tdata since the contact is cleaned up
1877  * when all supplements have completed execution.
1878  *
1879  * \retval 0 Success
1880  * \retval -1 Failure
1881  */
1882 int ast_sip_create_response(const pjsip_rx_data *rdata, int st_code,
1883         struct ast_sip_contact *contact, pjsip_tx_data **p_tdata);
1884
1885 /*!
1886  * \brief Send a response to an out of dialog request
1887  *
1888  * Use this function sparingly, since this does not create a transaction
1889  * within PJSIP. This means that if the request is retransmitted, it is
1890  * your responsibility to detect this and not process the same request
1891  * twice, and to send the same response for each retransmission.
1892  *
1893  * \param res_addr The response address for this response
1894  * \param tdata The response to send
1895  * \param endpoint The ast_sip_endpoint associated with this response
1896  *
1897  * \retval 0 Success
1898  * \retval -1 Failure
1899  */
1900 int ast_sip_send_response(pjsip_response_addr *res_addr, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint);
1901
1902 /*!
1903  * \brief Send a stateful response to an out of dialog request
1904  *
1905  * This creates a transaction within PJSIP, meaning that if the request
1906  * that we are responding to is retransmitted, we will not attempt to
1907  * re-handle the request.
1908  *
1909  * \param rdata The request that is being responded to
1910  * \param tdata The response to send
1911  * \param endpoint The ast_sip_endpoint associated with this response
1912  *
1913  * \since 13.4.0
1914  *
1915  * \retval 0 Success
1916  * \retval -1 Failure
1917  */
1918 int ast_sip_send_stateful_response(pjsip_rx_data *rdata, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint);
1919
1920 /*!
1921  * \brief Determine if an incoming request requires authentication
1922  *
1923  * This calls into the registered authenticator's requires_authentication callback
1924  * in order to determine if the request requires authentication.
1925  *
1926  * If there is no registered authenticator, then authentication will be assumed
1927  * not to be required.
1928  *
1929  * \param endpoint The endpoint from which the request originates
1930  * \param rdata The incoming SIP request
1931  * \retval non-zero The request requires authentication
1932  * \retval 0 The request does not require authentication
1933  */
1934 int ast_sip_requires_authentication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
1935
1936 /*!
1937  * \brief Method to determine authentication status of an incoming request
1938  *
1939  * This will call into a registered authenticator. The registered authenticator will
1940  * do what is necessary to determine whether the incoming request passes authentication.
1941  * A tentative response is passed into this function so that if, say, a digest authentication
1942  * challenge should be sent in the ensuing response, it can be added to the response.
1943  *
1944  * \param endpoint The endpoint from the request was sent
1945  * \param rdata The request to potentially authenticate
1946  * \param tdata Tentative response to the request
1947  * \return The result of checking authentication.
1948  */
1949 enum ast_sip_check_auth_result ast_sip_check_authentication(struct ast_sip_endpoint *endpoint,
1950                 pjsip_rx_data *rdata, pjsip_tx_data *tdata);
1951
1952 /*!
1953  * \brief Create a response to an authentication challenge
1954  *
1955  * This will call into an outbound authenticator's create_request_with_auth callback
1956  * to create a new request with authentication credentials. See the create_request_with_auth
1957  * callback in the \ref ast_sip_outbound_authenticator structure for details about
1958  * the parameters and return values.
1959  */
1960 int ast_sip_create_request_with_auth(const struct ast_sip_auth_vector *auths, pjsip_rx_data *challenge,
1961                 pjsip_tx_data *tdata, pjsip_tx_data **new_request);
1962
1963 /*!
1964  * \brief Determine the endpoint that has sent a SIP message
1965  *
1966  * This will call into each of the registered endpoint identifiers'
1967  * identify_endpoint() callbacks until one returns a non-NULL endpoint.
1968  * This will return an ao2 object. Its reference count will need to be
1969  * decremented when completed using the endpoint.
1970  *
1971  * \param rdata The inbound SIP message to use when identifying the endpoint.
1972  * \retval NULL No matching endpoint
1973  * \retval non-NULL The matching endpoint
1974  */
1975 struct ast_sip_endpoint *ast_sip_identify_endpoint(pjsip_rx_data *rdata);
1976
1977 /*!
1978  * \brief Set the outbound proxy for an outbound SIP message
1979  *
1980  * \param tdata The message to set the outbound proxy on
1981  * \param proxy SIP uri of the proxy
1982  * \retval 0 Success
1983  * \retval -1 Failure
1984  */
1985 int ast_sip_set_outbound_proxy(pjsip_tx_data *tdata, const char *proxy);
1986
1987 /*!
1988  * \brief Add a header to an outbound SIP message
1989  *
1990  * \param tdata The message to add the header to
1991  * \param name The header name
1992  * \param value The header value
1993  * \retval 0 Success
1994  * \retval -1 Failure
1995  */
1996 int ast_sip_add_header(pjsip_tx_data *tdata, const char *name, const char *value);
1997
1998 /*!
1999  * \brief Add a body to an outbound SIP message
2000  *
2001  * If this is called multiple times, the latest body will replace the current
2002  * body.
2003  *
2004  * \param tdata The message to add the body to
2005  * \param body The message body to add
2006  * \retval 0 Success
2007  * \retval -1 Failure
2008  */
2009 int ast_sip_add_body(pjsip_tx_data *tdata, const struct ast_sip_body *body);
2010
2011 /*!
2012  * \brief Add a multipart body to an outbound SIP message
2013  *
2014  * This will treat each part of the input vector as part of a multipart body and
2015  * add each part to the SIP message.
2016  *
2017  * \param tdata The message to add the body to
2018  * \param bodies The parts of the body to add
2019  * \retval 0 Success
2020  * \retval -1 Failure
2021  */
2022 int ast_sip_add_body_multipart(pjsip_tx_data *tdata, const struct ast_sip_body *bodies[], int num_bodies);
2023
2024 /*!
2025  * \brief Append body data to a SIP message
2026  *
2027  * This acts mostly the same as ast_sip_add_body, except that rather than replacing
2028  * a body if it currently exists, it appends data to an existing body.
2029  *
2030  * \param tdata The message to append the body to
2031  * \param body The string to append to the end of the current body
2032  * \retval 0 Success
2033  * \retval -1 Failure
2034  */
2035 int ast_sip_append_body(pjsip_tx_data *tdata, const char *body_text);
2036
2037 /*!
2038  * \brief Copy a pj_str_t into a standard character buffer.
2039  *
2040  * pj_str_t is not NULL-terminated. Any place that expects a NULL-
2041  * terminated string needs to have the pj_str_t copied into a separate
2042  * buffer.
2043  *
2044  * This method copies the pj_str_t contents into the destination buffer
2045  * and NULL-terminates the buffer.
2046  *
2047  * \param dest The destination buffer
2048  * \param src The pj_str_t to copy
2049  * \param size The size of the destination buffer.
2050  */
2051 void ast_copy_pj_str(char *dest, const pj_str_t *src, size_t size);
2052
2053 /*!
2054  * \brief Get the looked-up endpoint on an out-of dialog request or response
2055  *
2056  * The function may ONLY be called on out-of-dialog requests or responses. For
2057  * in-dialog requests and responses, it is required that the user of the dialog
2058  * has the looked-up endpoint stored locally.
2059  *
2060  * This function should never return NULL if the message is out-of-dialog. It will
2061  * always return NULL if the message is in-dialog.
2062  *
2063  * This function will increase the reference count of the returned endpoint by one.
2064  * Release your reference using the ao2_ref function when finished.
2065  *
2066  * \param rdata Out-of-dialog request or response
2067  * \return The looked up endpoint
2068  */
2069 struct ast_sip_endpoint *ast_pjsip_rdata_get_endpoint(pjsip_rx_data *rdata);
2070
2071 /*!
2072  * \brief Add 'user=phone' parameter to URI if enabled and user is a phone number.
2073  *
2074  * \param endpoint The endpoint to use for configuration
2075  * \param pool The memory pool to allocate the parameter from
2076  * \param uri The URI to check for user and to add parameter to
2077  */
2078 void ast_sip_add_usereqphone(const struct ast_sip_endpoint *endpoint, pj_pool_t *pool, pjsip_uri *uri);
2079
2080 /*!
2081  * \brief Retrieve any endpoints available to sorcery.
2082  *
2083  * \retval Endpoints available to sorcery, NULL if no endpoints found.
2084  */
2085 struct ao2_container *ast_sip_get_endpoints(void);
2086
2087 /*!
2088  * \brief Retrieve the default outbound endpoint.
2089  *
2090  * \retval The default outbound endpoint, NULL if not found.
2091  */
2092 struct ast_sip_endpoint *ast_sip_default_outbound_endpoint(void);
2093
2094 /*!
2095  * \brief Retrieve relevant SIP auth structures from sorcery
2096  *
2097  * \param auths Vector of sorcery IDs of auth credentials to retrieve
2098  * \param[out] out The retrieved auths are stored here
2099  */
2100 int ast_sip_retrieve_auths(const struct ast_sip_auth_vector *auths, struct ast_sip_auth **out);
2101
2102 /*!
2103  * \brief Clean up retrieved auth structures from memory
2104  *
2105  * Call this function once you have completed operating on auths
2106  * retrieved from \ref ast_sip_retrieve_auths
2107  *
2108  * \param auths An vector of auth structures to clean up
2109  * \param num_auths The number of auths in the vector
2110  */
2111 void ast_sip_cleanup_auths(struct ast_sip_auth *auths[], size_t num_auths);
2112
2113 /*!
2114  * \brief Checks if the given content type matches type/subtype.
2115  *
2116  * Compares the pjsip_media_type with the passed type and subtype and
2117  * returns the result of that comparison.  The media type parameters are
2118  * ignored.
2119  *
2120  * \param content_type The pjsip_media_type structure to compare
2121  * \param type The media type to compare
2122  * \param subtype The media subtype to compare
2123  * \retval 0 No match
2124  * \retval -1 Match
2125  */
2126 int ast_sip_is_content_type(pjsip_media_type *content_type, char *type, char *subtype);
2127
2128 /*!
2129  * \brief Send a security event notification for when an invalid endpoint is requested
2130  *
2131  * \param name Name of the endpoint requested
2132  * \param rdata Received message
2133  */
2134 void ast_sip_report_invalid_endpoint(const char *name, pjsip_rx_data *rdata);
2135
2136 /*!
2137  * \brief Send a security event notification for when an ACL check fails
2138  *
2139  * \param endpoint Pointer to the endpoint in use
2140  * \param rdata Received message
2141  * \param name Name of the ACL
2142  */
2143 void ast_sip_report_failed_acl(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, const char *name);
2144
2145 /*!
2146  * \brief Send a security event notification for when a challenge response has failed
2147  *
2148  * \param endpoint Pointer to the endpoint in use
2149  * \param rdata Received message
2150  */
2151 void ast_sip_report_auth_failed_challenge_response(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2152
2153 /*!
2154  * \brief Send a security event notification for when authentication succeeds
2155  *
2156  * \param endpoint Pointer to the endpoint in use
2157  * \param rdata Received message
2158  */
2159 void ast_sip_report_auth_success(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2160
2161 /*!
2162  * \brief Send a security event notification for when an authentication challenge is sent
2163  *
2164  * \param endpoint Pointer to the endpoint in use
2165  * \param rdata Received message
2166  * \param tdata Sent message
2167  */
2168 void ast_sip_report_auth_challenge_sent(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pjsip_tx_data *tdata);
2169
2170 /*!
2171  * \brief Send a security event notification for when a request is not supported
2172  *
2173  * \param endpoint Pointer to the endpoint in use
2174  * \param rdata Received message
2175  * \param req_type the type of request
2176  */
2177 void ast_sip_report_req_no_support(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata,
2178                                    const char* req_type);
2179
2180 /*!
2181  * \brief Send a security event notification for when a memory limit is hit.
2182  *
2183  * \param endpoint Pointer to the endpoint in use
2184  * \param rdata Received message
2185  */
2186 void ast_sip_report_mem_limit(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2187
2188 int ast_sip_add_global_request_header(const char *name, const char *value, int replace);
2189 int ast_sip_add_global_response_header(const char *name, const char *value, int replace);
2190
2191 /*!
2192  * \brief Retrieves the value associated with the given key.
2193  *
2194  * \param ht the hash table/dictionary to search
2195  * \param key the key to find
2196  *
2197  * \retval the value associated with the key, NULL otherwise.
2198  */
2199 void *ast_sip_dict_get(void *ht, const char *key);
2200
2201 /*!
2202  * \brief Using the dictionary stored in mod_data array at a given id,
2203  *        retrieve the value associated with the given key.
2204  *
2205  * \param mod_data a module data array
2206  * \param id the mod_data array index
2207  * \param key the key to find
2208  *
2209  * \retval the value associated with the key, NULL otherwise.
2210  */
2211 #define ast_sip_mod_data_get(mod_data, id, key)         \
2212         ast_sip_dict_get(mod_data[id], key)
2213
2214 /*!
2215  * \brief Set the value for the given key.
2216  *
2217  * Note - if the hash table does not exist one is created first, the key/value
2218  * pair is set, and the hash table returned.
2219  *
2220  * \param pool the pool to allocate memory in
2221  * \param ht the hash table/dictionary in which to store the key/value pair
2222  * \param key the key to associate a value with
2223  * \param val the value to associate with a key
2224  *
2225  * \retval the given, or newly created, hash table.
2226  */
2227 void *ast_sip_dict_set(pj_pool_t* pool, void *ht,
2228                        const char *key, void *val);
2229
2230 /*!
2231  * \brief Utilizing a mod_data array for a given id, set the value
2232  *        associated with the given key.
2233  *
2234  * For a given structure's mod_data array set the element indexed by id to
2235  * be a dictionary containing the key/val pair.
2236  *
2237  * \param pool a memory allocation pool
2238  * \param mod_data a module data array
2239  * \param id the mod_data array index
2240  * \param key the key to find
2241  * \param val the value to associate with a key
2242  */
2243 #define ast_sip_mod_data_set(pool, mod_data, id, key, val)              \
2244         mod_data[id] = ast_sip_dict_set(pool, mod_data[id], key, val)
2245
2246 /*!
2247  * \brief For every contact on an AOR call the given 'on_contact' handler.
2248  *
2249  * \param aor the aor containing a list of contacts to iterate
2250  * \param on_contact callback on each contact on an AOR.  The object
2251  * received by the callback will be a ast_sip_contact_wrapper structure.
2252  * \param arg user data passed to handler
2253  * \retval 0 Success, non-zero on failure
2254  */
2255 int ast_sip_for_each_contact(const struct ast_sip_aor *aor,
2256                 ao2_callback_fn on_contact, void *arg);
2257
2258 /*!
2259  * \brief Handler used to convert a contact to a string.
2260  *
2261  * \param object the ast_sip_aor_contact_pair containing a list of contacts to iterate and the contact
2262  * \param arg user data passed to handler
2263  * \param flags
2264  * \retval 0 Success, non-zero on failure
2265  */
2266 int ast_sip_contact_to_str(void *object, void *arg, int flags);
2267
2268 /*!
2269  * \brief For every aor in the comma separated aors string call the
2270  *        given 'on_aor' handler.
2271  *
2272  * \param aors a comma separated list of aors
2273  * \param on_aor callback for each aor
2274  * \param arg user data passed to handler
2275  * \retval 0 Success, non-zero on failure
2276  */
2277 int ast_sip_for_each_aor(const char *aors, ao2_callback_fn on_aor, void *arg);
2278
2279 /*!
2280  * \brief For every auth in the array call the given 'on_auth' handler.
2281  *
2282  * \param array an array of auths
2283  * \param on_auth callback for each auth
2284  * \param arg user data passed to handler
2285  * \retval 0 Success, non-zero on failure
2286  */
2287 int ast_sip_for_each_auth(const struct ast_sip_auth_vector *array,
2288                           ao2_callback_fn on_auth, void *arg);
2289
2290 /*!
2291  * \brief Converts the given auth type to a string
2292  *
2293  * \param type the auth type to convert
2294  * \retval a string representative of the auth type
2295  */
2296 const char *ast_sip_auth_type_to_str(enum ast_sip_auth_type type);
2297
2298 /*!
2299  * \brief Converts an auths array to a string of comma separated values
2300  *
2301  * \param auths an auth array
2302  * \param buf the string buffer to write the object data
2303  * \retval 0 Success, non-zero on failure
2304  */
2305 int ast_sip_auths_to_str(const struct ast_sip_auth_vector *auths, char **buf);
2306
2307 /*!
2308  * \brief AMI variable container
2309  */
2310 struct ast_sip_ami {
2311         /*! Manager session */
2312         struct mansession *s;
2313         /*! Manager message */
2314         const struct message *m;
2315         /*! Manager Action ID */
2316         const char *action_id;
2317         /*! user specified argument data */
2318         void *arg;
2319         /*! count of objects */
2320         int count;
2321 };
2322
2323 /*!
2324  * \brief Creates a string to store AMI event data in.
2325  *
2326  * \param event the event to set
2327  * \param ami AMI session and message container
2328  * \retval an initialized ast_str or NULL on error.
2329  */
2330 struct ast_str *ast_sip_create_ami_event(const char *event,
2331                                          struct ast_sip_ami *ami);
2332
2333 /*!
2334  * \brief An entity responsible formatting endpoint information.
2335  */
2336 struct ast_sip_endpoint_formatter {
2337         /*!
2338          * \brief Callback used to format endpoint information over AMI.
2339          */
2340         int (*format_ami)(const struct ast_sip_endpoint *endpoint,
2341                           struct ast_sip_ami *ami);
2342         AST_RWLIST_ENTRY(ast_sip_endpoint_formatter) next;
2343 };
2344
2345 /*!
2346  * \brief Register an endpoint formatter.
2347  *
2348  * \param obj the formatter to register
2349  * \retval 0 Success
2350  * \retval -1 Failure
2351  */
2352 int ast_sip_register_endpoint_formatter(struct ast_sip_endpoint_formatter *obj);
2353
2354 /*!
2355  * \brief Unregister an endpoint formatter.
2356  *
2357  * \param obj the formatter to unregister
2358  */
2359 void ast_sip_unregister_endpoint_formatter(struct ast_sip_endpoint_formatter *obj);
2360
2361 /*!
2362  * \brief Converts a sorcery object to a string of object properties.
2363  *
2364  * \param obj the sorcery object to convert
2365  * \param str the string buffer to write the object data
2366  * \retval 0 Success, non-zero on failure
2367  */
2368 int ast_sip_sorcery_object_to_ami(const void *obj, struct ast_str **buf);
2369
2370 /*!
2371  * \brief Formats the endpoint and sends over AMI.
2372  *
2373  * \param endpoint the endpoint to format and send
2374  * \param endpoint ami AMI variable container
2375  * \param count the number of formatters operated on
2376  * \retval 0 Success, otherwise non-zero on error
2377  */
2378 int ast_sip_format_endpoint_ami(struct ast_sip_endpoint *endpoint,
2379                                 struct ast_sip_ami *ami, int *count);
2380
2381 /*!
2382  * \brief Formats the contact and sends over AMI.
2383  *
2384  * \param obj a pointer an ast_sip_contact_wrapper structure
2385  * \param arg a pointer to an ast_sip_ami structure
2386  * \param flags ignored
2387  * \retval 0 Success, otherwise non-zero on error
2388  */
2389 int ast_sip_format_contact_ami(void *obj, void *arg, int flags);
2390
2391 /*!
2392  * \brief Format auth details for AMI.
2393  *
2394  * \param auths an auth array
2395  * \param ami ami variable container
2396  * \retval 0 Success, non-zero on failure
2397  */
2398 int ast_sip_format_auths_ami(const struct ast_sip_auth_vector *auths,
2399                              struct ast_sip_ami *ami);
2400
2401 /*!
2402  * \brief Retrieve the endpoint snapshot for an endpoint
2403  *
2404  * \param endpoint The endpoint whose snapshot is to be retreieved.
2405  * \retval The endpoint snapshot
2406  */
2407 struct ast_endpoint_snapshot *ast_sip_get_endpoint_snapshot(
2408         const struct ast_sip_endpoint *endpoint);
2409
2410 /*!
2411  * \brief Retrieve the device state for an endpoint.
2412  *
2413  * \param endpoint The endpoint whose state is to be retrieved.
2414  * \retval The device state.
2415  */
2416 const char *ast_sip_get_device_state(const struct ast_sip_endpoint *endpoint);
2417
2418 /*!
2419  * \brief For every channel snapshot on an endpoint snapshot call the given
2420  *        'on_channel_snapshot' handler.
2421  *
2422  * \param endpoint_snapshot snapshot of an endpoint
2423  * \param on_channel_snapshot callback for each channel snapshot
2424  * \param arg user data passed to handler
2425  * \retval 0 Success, non-zero on failure
2426  */
2427 int ast_sip_for_each_channel_snapshot(const struct ast_endpoint_snapshot *endpoint_snapshot,
2428                 ao2_callback_fn on_channel_snapshot,
2429                                       void *arg);
2430
2431 /*!
2432  * \brief For every channel snapshot on an endpoint all the given
2433  *        'on_channel_snapshot' handler.
2434  *
2435  * \param endpoint endpoint
2436  * \param on_channel_snapshot callback for each channel snapshot
2437  * \param arg user data passed to handler
2438  * \retval 0 Success, non-zero on failure
2439  */
2440 int ast_sip_for_each_channel(const struct ast_sip_endpoint *endpoint,
2441                 ao2_callback_fn on_channel_snapshot,
2442                                       void *arg);
2443
2444 enum ast_sip_supplement_priority {
2445         /*! Top priority. Supplements with this priority are those that need to run before any others */
2446         AST_SIP_SUPPLEMENT_PRIORITY_FIRST = 0,
2447         /*! Channel creation priority.
2448          * chan_pjsip creates a channel at this priority. If your supplement depends on being run before
2449          * or after channel creation, then set your priority to be lower or higher than this value.
2450          */
2451         AST_SIP_SUPPLEMENT_PRIORITY_CHANNEL = 1000000,
2452         /*! Lowest priority. Supplements with this priority should be run after all other supplements */
2453         AST_SIP_SUPPLEMENT_PRIORITY_LAST = INT_MAX,
2454 };
2455
2456 /*!
2457  * \brief A supplement to SIP message processing
2458  *
2459  * These can be registered by any module in order to add
2460  * processing to incoming and outgoing SIP out of dialog
2461  * requests and responses
2462  */
2463 struct ast_sip_supplement {
2464         /*! Method on which to call the callbacks. If NULL, call on all methods */
2465         const char *method;
2466         /*! Priority for this supplement. Lower numbers are visited before higher numbers */
2467         enum ast_sip_supplement_priority priority;
2468         /*!
2469          * \brief Called on incoming SIP request
2470          * This method can indicate a failure in processing in its return. If there
2471          * is a failure, it is required that this method sends a response to the request.
2472          * This method is always called from a SIP servant thread.
2473          *
2474          * \note
2475          * The following PJSIP methods will not work properly:
2476          * pjsip_rdata_get_dlg()
2477          * pjsip_rdata_get_tsx()
2478          * The reason is that the rdata passed into this function is a cloned rdata structure,
2479          * and its module data is not copied during the cloning operation.
2480          * If you need to get the dialog, you can get it via session->inv_session->dlg.
2481          *
2482          * \note
2483          * There is no guarantee that a channel will be present on the session when this is called.
2484          */
2485         int (*incoming_request)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
2486         /*!
2487          * \brief Called on an incoming SIP response
2488          * This method is always called from a SIP servant thread.
2489          *
2490          * \note
2491          * The following PJSIP methods will not work properly:
2492          * pjsip_rdata_get_dlg()
2493          * pjsip_rdata_get_tsx()
2494          * The reason is that the rdata passed into this function is a cloned rdata structure,
2495          * and its module data is not copied during the cloning operation.
2496          * If you need to get the dialog, you can get it via session->inv_session->dlg.
2497          *
2498          * \note
2499          * There is no guarantee that a channel will be present on the session when this is called.
2500          */
2501         void (*incoming_response)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
2502         /*!
2503          * \brief Called on an outgoing SIP request
2504          * This method is always called from a SIP servant thread.
2505          */
2506         void (*outgoing_request)(struct ast_sip_endpoint *endpoint, struct ast_sip_contact *contact, struct pjsip_tx_data *tdata);
2507         /*!
2508          * \brief Called on an outgoing SIP response
2509          * This method is always called from a SIP servant thread.
2510          */
2511         void (*outgoing_response)(struct ast_sip_endpoint *endpoint, struct ast_sip_contact *contact, struct pjsip_tx_data *tdata);
2512         /*! Next item in the list */
2513         AST_LIST_ENTRY(ast_sip_supplement) next;
2514 };
2515
2516 /*!
2517  * \brief Register a supplement to SIP out of dialog processing
2518  *
2519  * This allows for someone to insert themselves in the processing of out
2520  * of dialog SIP requests and responses. This, for example could allow for
2521  * a module to set channel data based on headers in an incoming message.
2522  * Similarly, a module could reject an incoming request if desired.
2523  *
2524  * \param supplement The supplement to register
2525  * \retval 0 Success
2526  * \retval -1 Failure
2527  */
2528 int ast_sip_register_supplement(struct ast_sip_supplement *supplement);
2529
2530 /*!
2531  * \brief Unregister a an supplement to SIP out of dialog processing
2532  *
2533  * \param supplement The supplement to unregister
2534  */
2535 void ast_sip_unregister_supplement(struct ast_sip_supplement *supplement);
2536
2537 /*!
2538  * \brief Retrieve the global MWI taskprocessor high water alert trigger level.
2539  *
2540  * \since 13.12.0
2541  *
2542  * \retval the system MWI taskprocessor high water alert trigger level
2543  */
2544 unsigned int ast_sip_get_mwi_tps_queue_high(void);
2545
2546 /*!
2547  * \brief Retrieve the global MWI taskprocessor low water clear alert level.
2548  *
2549  * \since 13.12.0
2550  *
2551  * \retval the system MWI taskprocessor low water clear alert level
2552  */
2553 int ast_sip_get_mwi_tps_queue_low(void);
2554
2555 /*!
2556  * \brief Retrieve the global setting 'disable sending unsolicited mwi on startup'.
2557  * \since 13.12.0
2558  *
2559  * \retval non zero if disable.
2560  */
2561 unsigned int ast_sip_get_mwi_disable_initial_unsolicited(void);
2562
2563 /*!
2564  * \brief Retrieve the global setting 'ignore_uri_user_options'.
2565  * \since 13.12.0
2566  *
2567  * \retval non zero if ignore the user field options.
2568  */
2569 unsigned int ast_sip_get_ignore_uri_user_options(void);
2570
2571 /*!
2572  * \brief Truncate the URI user field options string if enabled.
2573  * \since 13.12.0
2574  *
2575  * \param str URI user field string to truncate if enabled
2576  *
2577  * \details
2578  * We need to be able to handle URI's looking like
2579  * "sip:1235557890;phone-context=national@x.x.x.x;user=phone"
2580  *
2581  * Where the URI user field is:
2582  * "1235557890;phone-context=national"
2583  *
2584  * When truncated the string will become:
2585  * "1235557890"
2586  */
2587 #define AST_SIP_USER_OPTIONS_TRUNCATE_CHECK(str)                                \
2588         do {                                                                                                            \
2589                 char *__semi = strchr((str), ';');                                              \
2590                 if (__semi && ast_sip_get_ignore_uri_user_options()) {  \
2591                         *__semi = '\0';                                                                         \
2592                 }                                                                                                               \
2593         } while (0)
2594
2595 /*!
2596  * \brief Retrieve the system debug setting (yes|no|host).
2597  *
2598  * \note returned string needs to be de-allocated by caller.
2599  *
2600  * \retval the system debug setting.
2601  */
2602 char *ast_sip_get_debug(void);
2603
2604 /*!
2605  * \brief Retrieve the global regcontext setting.
2606  *
2607  * \since 13.8.0
2608  *
2609  * \note returned string needs to be de-allocated by caller.
2610  *
2611  * \retval the global regcontext setting
2612  */
2613 char *ast_sip_get_regcontext(void);
2614
2615 /*!
2616  * \brief Retrieve the global endpoint_identifier_order setting.
2617  *
2618  * Specifies the order by which endpoint identifiers should be regarded.
2619  *
2620  * \retval the global endpoint_identifier_order value
2621  */
2622 char *ast_sip_get_endpoint_identifier_order(void);
2623
2624 /*!
2625  * \brief Retrieve the default voicemail extension.
2626  * \since 13.9.0
2627  *
2628  * \note returned string needs to be de-allocated by caller.
2629  *
2630  * \retval the default voicemail extension
2631  */
2632 char *ast_sip_get_default_voicemail_extension(void);
2633
2634 /*!
2635  * \brief Retrieve the global default realm.
2636  *
2637  * This is the value placed in outbound challenges' realm if there
2638  * is no better option (such as an auth-configured realm).
2639  *
2640  * \param[out] realm The default realm
2641  * \param size The buffer size of realm
2642  * \return nothing
2643  */
2644 void ast_sip_get_default_realm(char *realm, size_t size);
2645
2646 /*!
2647  * \brief Retrieve the global default from user.
2648  *
2649  * This is the value placed in outbound requests' From header if there
2650  * is no better option (such as an endpoint-configured from_user or
2651  * caller ID number).
2652  *
2653  * \param[out] from_user The default from user
2654  * \param size The buffer size of from_user
2655  * \return nothing
2656  */
2657 void ast_sip_get_default_from_user(char *from_user, size_t size);
2658
2659 /*! \brief Determines whether the res_pjsip module is loaded */
2660 #define CHECK_PJSIP_MODULE_LOADED()                             \
2661         do {                                                    \
2662                 if (!ast_module_check("res_pjsip.so")           \
2663                         || !ast_sip_get_pjsip_endpoint()) {     \
2664                         return AST_MODULE_LOAD_DECLINE;         \
2665                 }                                               \
2666         } while(0)
2667
2668 /*!
2669  * \brief Retrieve the system keep alive interval setting.
2670  *
2671  * \retval the keep alive interval.
2672  */
2673 unsigned int ast_sip_get_keep_alive_interval(void);
2674
2675 /*!
2676  * \brief Retrieve the system contact expiration check interval setting.
2677  *
2678  * \retval the contact expiration check interval.
2679  */
2680 unsigned int ast_sip_get_contact_expiration_check_interval(void);
2681
2682 /*!
2683  * \brief Retrieve the system setting 'disable multi domain'.
2684  * \since 13.9.0
2685  *
2686  * \retval non zero if disable multi domain.
2687  */
2688 unsigned int ast_sip_get_disable_multi_domain(void);
2689
2690 /*!
2691  * \brief Retrieve the system max initial qualify time.
2692  *
2693  * \retval the maximum initial qualify time.
2694  */
2695 unsigned int ast_sip_get_max_initial_qualify_time(void);
2696
2697 /*!
2698  * \brief translate ast_sip_contact_status_type to character string.
2699  *
2700  * \retval the character string equivalent.
2701  */
2702
2703 const char *ast_sip_get_contact_status_label(const enum ast_sip_contact_status_type status);
2704 const char *ast_sip_get_contact_short_status_label(const enum ast_sip_contact_status_type status);
2705
2706 /*!
2707  * \brief Set a request to use the next value in the list of resolved addresses.
2708  *
2709  * \param tdata the tx data from the original request
2710  * \retval 0 No more addresses to try
2711  * \retval 1 The request was successfully re-intialized
2712  */
2713 int ast_sip_failover_request(pjsip_tx_data *tdata);
2714
2715 /*
2716  * \brief Retrieve the local host address in IP form
2717  *
2718  * \param af The address family to retrieve
2719  * \param addr A place to store the local host address
2720  *
2721  * \retval 0 success
2722  * \retval -1 failure
2723  *
2724  * \since 13.6.0
2725  */
2726 int ast_sip_get_host_ip(int af, pj_sockaddr *addr);
2727
2728 /*!
2729  * \brief Retrieve the local host address in string form
2730  *
2731  * \param af The address family to retrieve
2732  *
2733  * \retval non-NULL success
2734  * \retval NULL failure
2735  *
2736  * \since 13.6.0
2737  *
2738  * \note An empty string may be returned if the address family is valid but no local address exists
2739  */
2740 const char *ast_sip_get_host_ip_string(int af);
2741
2742 /*!
2743  * \brief Return the size of the SIP threadpool's task queue
2744  * \since 13.7.0
2745  */
2746 long ast_sip_threadpool_queue_size(void);
2747
2748 /*!
2749  * \brief Retrieve transport state
2750  * \since 13.7.1
2751  *
2752  * @param transport_id
2753  * @returns transport_state
2754  *
2755  * \note ao2_cleanup(...) or ao2_ref(...,  -1) must be called on the returned object
2756  */
2757 struct ast_sip_transport_state *ast_sip_get_transport_state(const char *transport_id);
2758
2759 /*!
2760  * \brief Retrieves all transport states
2761  * \since 13.7.1
2762  *
2763  * @returns ao2_container
2764  *
2765  * \note ao2_cleanup(...) or ao2_ref(...,  -1) must be called on the returned object
2766  */
2767 struct ao2_container *ast_sip_get_transport_states(void);
2768
2769 /*!
2770  * \brief Sets pjsip_tpselector from ast_sip_transport
2771  * \since 13.8.0
2772  *
2773  * \param transport The transport to be used
2774  * \param selector The selector to be populated
2775  * \retval 0 success
2776  * \retval -1 failure
2777  */
2778 int ast_sip_set_tpselector_from_transport(const struct ast_sip_transport *transport, pjsip_tpselector *selector);
2779
2780 /*!
2781  * \brief Sets pjsip_tpselector from ast_sip_transport
2782  * \since 13.8.0
2783  *
2784  * \param transport_name The name of the transport to be used
2785  * \param selector The selector to be populated
2786  * \retval 0 success
2787  * \retval -1 failure
2788  */
2789 int ast_sip_set_tpselector_from_transport_name(const char *transport_name, pjsip_tpselector *selector);
2790
2791 /*!
2792  * \brief Set name and number information on an identity header.
2793  *
2794  * \param pool Memory pool to use for string duplication
2795  * \param id_hdr A From, P-Asserted-Identity, or Remote-Party-ID header to modify
2796  * \param id The identity information to apply to the header
2797  */
2798 void ast_sip_modify_id_header(pj_pool_t *pool, pjsip_fromto_hdr *id_hdr,
2799         const struct ast_party_id *id);
2800
2801 /*!
2802  * \brief Retrieve the unidentified request security event thresholds
2803  * \since 13.8.0
2804  *
2805  * \param count The maximum number of unidentified requests per source ip to accumulate before emitting a security event
2806  * \param period The period in seconds over which to accumulate unidentified requests
2807  * \param prune_interval The interval in seconds at which expired entries will be pruned
2808  */
2809 void ast_sip_get_unidentified_request_thresholds(unsigned int *count, unsigned int *period,
2810         unsigned int *prune_interval);
2811
2812 /*!
2813  * \brief Get the transport name from an endpoint or request uri
2814  * \since 13.15.0
2815  *
2816  * \param endpoint
2817  * \param sip_uri
2818  * \param buf Buffer to receive transport name
2819  * \param buf_len Buffer length
2820  *
2821  * \retval 0 Success
2822  * \retval -1 Failure
2823  *
2824  * \note
2825  * If endpoint->transport is not NULL, it is returned in buf.
2826  * Otherwise if sip_uri has an 'x-ast-txp' parameter AND the sip_uri host is
2827  * an ip4 or ip6 address, its value is returned,
2828  */
2829 int ast_sip_get_transport_name(const struct ast_sip_endpoint *endpoint,
2830         pjsip_sip_uri *sip_uri, char *buf, size_t buf_len);
2831
2832 /*!
2833  * \brief Sets pjsip_tpselector from an endpoint or uri
2834  * \since 13.15.0
2835  *
2836  * \param endpoint If endpoint->transport is set, it's used
2837  * \param sip_uri If sip_uri contains a x-ast-txp parameter, it's used
2838  * \param selector The selector to be populated
2839  *
2840  * \retval 0 success
2841  * \retval -1 failure
2842  */
2843 int ast_sip_set_tpselector_from_ep_or_uri(const struct ast_sip_endpoint *endpoint,
2844         pjsip_sip_uri *sip_uri, pjsip_tpselector *selector);
2845
2846 /*!
2847  * \brief Set the transport on a dialog
2848  * \since 13.15.0
2849  *
2850  * \param endpoint
2851  * \param dlg
2852  * \param selector (optional)
2853  *
2854  * \note
2855  * This API calls ast_sip_get_transport_name(endpoint, dlg->target) and if the result is
2856  * non-NULL, calls pjsip_dlg_set_transport.  If 'selector' is non-NULL, it is updated with
2857  * the selector used.
2858  */
2859 int ast_sip_dlg_set_transport(const struct ast_sip_endpoint *endpoint, pjsip_dialog *dlg,
2860         pjsip_tpselector *selector);
2861
2862 #endif /* _RES_PJSIP_H */