Asterisk - The Open Source Telephony Project  GIT-master-a1fa8df
res_pjsip.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Mark Michelson <mmichelson@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 #ifndef _RES_PJSIP_H
20 #define _RES_PJSIP_H
21 
22 #include <pjsip.h>
23 /* Needed for SUBSCRIBE, NOTIFY, and PUBLISH method definitions */
24 #include <pjsip_simple.h>
25 #include <pjsip/sip_transaction.h>
26 #include <pj/timer.h>
27 /* Needed for pj_sockaddr */
28 #include <pjlib.h>
29 
30 #include "asterisk/stringfields.h"
31 /* Needed for struct ast_sockaddr */
32 #include "asterisk/netsock2.h"
33 /* Needed for linked list macros */
34 #include "asterisk/linkedlists.h"
35 /* Needed for ast_party_id */
36 #include "asterisk/channel.h"
37 /* Needed for ast_sorcery */
38 #include "asterisk/sorcery.h"
39 /* Needed for ast_dnsmgr */
40 #include "asterisk/dnsmgr.h"
41 /* Needed for ast_endpoint */
42 #include "asterisk/endpoints.h"
43 /* Needed for ast_t38_ec_modes */
44 #include "asterisk/udptl.h"
45 /* Needed for ast_rtp_dtls_cfg struct */
46 #include "asterisk/rtp_engine.h"
47 /* Needed for AST_VECTOR macro */
48 #include "asterisk/vector.h"
49 /* Needed for ast_sip_for_each_channel_snapshot struct */
52 #include "asterisk/stream.h"
53 
54 #define PJSIP_MINVERSION(m,n,p) (((m << 24) | (n << 16) | (p << 8)) >= PJ_VERSION_NUM)
55 
56 #ifndef PJSIP_EXPIRES_NOT_SPECIFIED
57 /*
58  * Added in pjproject 2.10.0. However define here if someone compiles against a
59  * version of pjproject < 2.10.0.
60  *
61  * Usually defined in pjsip/include/pjsip/sip_msg.h (included as part of <pjsip.h>)
62  */
63 #define PJSIP_EXPIRES_NOT_SPECIFIED ((pj_uint32_t)-1)
64 #endif
65 
66 /* Forward declarations of PJSIP stuff */
67 struct pjsip_rx_data;
68 struct pjsip_module;
69 struct pjsip_tx_data;
70 struct pjsip_dialog;
71 struct pjsip_transport;
72 struct pjsip_tpfactory;
73 struct pjsip_tls_setting;
74 struct pjsip_tpselector;
75 
76 /*! \brief Maximum number of ciphers supported for a TLS transport */
77 #define SIP_TLS_MAX_CIPHERS 64
78 
79 /*! Maximum number of challenges before assuming that we are in a loop */
80 #define MAX_RX_CHALLENGES 10
81 
82 AST_VECTOR(ast_sip_service_route_vector, char *);
83 
84 /*!
85  * \brief Structure for SIP transport information
86  */
88  /*! \brief Transport itself */
89  struct pjsip_transport *transport;
90  /*! \brief Transport factory */
91  struct pjsip_tpfactory *factory;
92  /*!
93  * Transport id
94  * \since 13.8.0
95  */
96  char *id;
97  /*!
98  * Transport type
99  * \since 13.8.0
100  */
102  /*!
103  * Address and port to bind to
104  * \since 13.8.0
105  */
106  pj_sockaddr host;
107  /*!
108  * TLS settings
109  * \since 13.8.0
110  */
111  pjsip_tls_setting tls;
112  /*!
113  * Configured TLS ciphers
114  * \since 13.8.0
115  */
116  pj_ssl_cipher ciphers[SIP_TLS_MAX_CIPHERS];
117  /*!
118  * Optional local network information, used for NAT purposes.
119  * "deny" (set) means that it's in the local network. Use the
120  * ast_sip_transport_is_nonlocal and ast_sip_transport_is_local
121  * macro's.
122  * \since 13.8.0
123  */
124  struct ast_ha *localnet;
125  /*!
126  * DNS manager for refreshing the external signaling address
127  * \since 13.8.0
128  */
130  /*!
131  * Optional external signaling address information
132  * \since 13.8.0
133  */
135  /*!
136  * DNS manager for refreshing the external media address
137  * \since 13.18.0
138  */
140  /*!
141  * Optional external signaling address information
142  * \since 13.18.0
143  */
145  /*!
146  * Set when this transport is a flow of signaling to a target
147  * \since 17.0.0
148  */
149  int flow;
150  /*!
151  * The P-Preferred-Identity to use on traffic using this transport
152  * \since 17.0.0
153  */
155  /*!
156  * The Service Routes to use on traffic using this transport
157  * \since 17.0.0
158  */
159  struct ast_sip_service_route_vector *service_routes;
160 };
161 
162 #define ast_sip_transport_is_nonlocal(transport_state, addr) \
163  (!transport_state->localnet || ast_apply_ha(transport_state->localnet, addr) == AST_SENSE_ALLOW)
164 
165 #define ast_sip_transport_is_local(transport_state, addr) \
166  (transport_state->localnet && ast_apply_ha(transport_state->localnet, addr) != AST_SENSE_ALLOW)
167 
168 /*!
169  * \brief Transport to bind to
170  */
172  /*! Sorcery object details */
173  SORCERY_OBJECT(details);
175  /*! Certificate of authority list file */
176  AST_STRING_FIELD(ca_list_file);
177  /*! Certificate of authority list path */
178  AST_STRING_FIELD(ca_list_path);
179  /*! Public certificate file */
180  AST_STRING_FIELD(cert_file);
181  /*! Optional private key of the certificate file */
182  AST_STRING_FIELD(privkey_file);
183  /*! Password to open the private key */
184  AST_STRING_FIELD(password);
185  /*! External signaling address */
187  /*! External media address */
189  /*! Optional domain to use for messages if provided could not be found */
191  );
192  /*! Type of transport */
194  /*!
195  * \deprecated Moved to ast_sip_transport_state
196  * \version 13.8.0 deprecated
197  * Address and port to bind to
198  */
199  pj_sockaddr host;
200  /*! Number of simultaneous asynchronous operations */
201  unsigned int async_operations;
202  /*! Optional external port for signaling */
204  /*!
205  * \deprecated Moved to ast_sip_transport_state
206  * \version 13.7.1 deprecated
207  * TLS settings
208  */
209  pjsip_tls_setting tls;
210  /*!
211  * \deprecated Moved to ast_sip_transport_state
212  * \version 13.7.1 deprecated
213  * Configured TLS ciphers
214  */
215  pj_ssl_cipher ciphers[SIP_TLS_MAX_CIPHERS];
216  /*!
217  * \deprecated Moved to ast_sip_transport_state
218  * \version 13.7.1 deprecated
219  * Optional local network information, used for NAT purposes
220  */
221  struct ast_ha *localnet;
222  /*!
223  * \deprecated Moved to ast_sip_transport_state
224  * \version 13.7.1 deprecated
225  * DNS manager for refreshing the external address
226  */
228  /*!
229  * \deprecated Moved to ast_sip_transport_state
230  * \version 13.7.1 deprecated
231  * Optional external address information
232  */
233  struct ast_sockaddr external_address;
234  /*!
235  * \deprecated
236  * \version 13.7.1 deprecated
237  * Transport state information
238  */
240  /*! QOS DSCP TOS bits */
241  unsigned int tos;
242  /*! QOS COS value */
243  unsigned int cos;
244  /*! Write timeout */
246  /*! Allow reload */
248  /*! Automatically send requests out the same transport requests have come in on */
250  /*! This is a flow to another target */
251  int flow;
252 };
253 
254 #define SIP_SORCERY_DOMAIN_ALIAS_TYPE "domain_alias"
255 
256 /*!
257  * Details about a SIP domain alias
258  */
260  /*! Sorcery object details */
261  SORCERY_OBJECT(details);
263  /*! Domain to be aliased to */
265  );
266 };
267 
268 /*!
269  * \brief Structure for SIP nat hook information
270  */
272  /*! Sorcery object details */
273  SORCERY_OBJECT(details);
274  /*! Callback for when a message is going outside of our local network */
275  void (*outgoing_external_message)(struct pjsip_tx_data *tdata, struct ast_sip_transport *transport);
276 };
277 
278 /*!
279  * \brief Contact associated with an address of record
280  */
282  /*! Sorcery object details, the id is the aor name plus a random string */
283  SORCERY_OBJECT(details);
285  /*! Full URI of the contact */
286  AST_STRING_FIELD(uri);
287  /*! Outbound proxy to use for qualify */
288  AST_STRING_FIELD(outbound_proxy);
289  /*! Path information to place in Route headers */
290  AST_STRING_FIELD(path);
291  /*! Content of the User-Agent header in REGISTER request */
292  AST_STRING_FIELD(user_agent);
293  /*! The name of the aor this contact belongs to */
294  AST_STRING_FIELD(aor);
295  /*! Asterisk Server name */
296  AST_STRING_FIELD(reg_server);
297  /*! IP-address of the Via header in REGISTER request */
298  AST_STRING_FIELD(via_addr);
299  /*! Content of the Call-ID header in REGISTER request */
300  AST_STRING_FIELD(call_id);
301  /*! The name of the endpoint that added the contact */
302  AST_STRING_FIELD(endpoint_name);
303  );
304  /*! Absolute time that this contact is no longer valid after */
305  struct timeval expiration_time;
306  /*! Frequency to send OPTIONS requests to contact. 0 is disabled. */
307  unsigned int qualify_frequency;
308  /*! If true authenticate the qualify challenge response if needed */
310  /*! Qualify timeout. 0 is diabled. */
312  /*! Endpoint that added the contact, only available in observers */
314  /*! Port of the Via header in REGISTER request */
315  int via_port;
316  /*! If true delete the contact on Asterisk restart/boot */
318 };
319 
320 /*!
321  * \brief Status type for a contact.
322  */
324  /*! Frequency > 0, but no response from remote uri */
326  /*! Frequency > 0, and got response from remote uri */
328  /*! Default last status, and when a contact status object is not found */
330  /*! Frequency == 0, has a contact, but don't know status (non-qualified) */
333 };
334 
335 /*!
336  * \brief A contact's status.
337  *
338  * \detail Maintains a contact's current status and round trip time
339  * if available.
340  */
343  /*! The original contact's URI */
344  AST_STRING_FIELD(uri);
345  /*! The name of the aor this contact_status belongs to */
346  AST_STRING_FIELD(aor);
347  );
348  /*! The round trip time in microseconds */
349  int64_t rtt;
350  /*! Current status for a contact (default - unavailable) */
352  /*! Last status for a contact (default - unavailable) */
353  enum ast_sip_contact_status_type last_status;
354  /*! Name of the contact */
355  char name[0];
356 };
357 
358 /*!
359  * \brief A SIP address of record
360  */
361 struct ast_sip_aor {
362  /*! Sorcery object details, the id is the AOR name */
363  SORCERY_OBJECT(details);
365  /*! Voicemail boxes for this AOR */
367  /*! Outbound proxy for OPTIONS requests */
368  AST_STRING_FIELD(outbound_proxy);
369  );
370  /*! Minimum expiration time */
371  unsigned int minimum_expiration;
372  /*! Maximum expiration time */
373  unsigned int maximum_expiration;
374  /*! Default contact expiration if one is not provided in the contact */
375  unsigned int default_expiration;
376  /*! Frequency to send OPTIONS requests to AOR contacts. 0 is disabled. */
377  unsigned int qualify_frequency;
378  /*! If true authenticate the qualify challenge response if needed */
379  int authenticate_qualify;
380  /*! Maximum number of external contacts, 0 to disable */
381  unsigned int max_contacts;
382  /*! Whether to remove any existing contacts not related to an incoming REGISTER when it comes in */
383  unsigned int remove_existing;
384  /*! Any permanent configured contacts */
385  struct ao2_container *permanent_contacts;
386  /*! Determines whether SIP Path headers are supported */
387  unsigned int support_path;
388  /*! Qualify timeout. 0 is diabled. */
389  double qualify_timeout;
390  /*! Voicemail extension to set in Message-Account */
391  char *voicemail_extension;
392 };
393 
394 /*!
395  * \brief A wrapper for contact that adds the aor_id and
396  * a consistent contact id. Used by ast_sip_for_each_contact.
397  */
399  /*! The id of the parent aor. */
400  char *aor_id;
401  /*! The id of contact in form of aor_id/contact_uri. */
402  char *contact_id;
403  /*! Pointer to the actual contact. */
404  struct ast_sip_contact *contact;
405 };
406 
407 /*!
408  * \brief DTMF modes for SIP endpoints
409  */
411  /*! No DTMF to be used */
413  /* XXX Should this be 2833 instead? */
414  /*! Use RFC 4733 events for DTMF */
416  /*! Use DTMF in the audio stream */
418  /*! Use SIP INFO DTMF (blech) */
420  /*! Use SIP 4733 if supported by the other side or INBAND if not */
422  /*! Use SIP 4733 if supported by the other side or INFO DTMF (blech) if not */
424 };
425 
426 /*!
427  * \brief Methods of storing SIP digest authentication credentials.
428  *
429  * Note that both methods result in MD5 digest authentication being
430  * used. The two methods simply alter how Asterisk determines the
431  * credentials for a SIP authentication
432  */
434  /*! Credentials stored as a username and password combination */
436  /*! Credentials stored as an MD5 sum */
438  /*! Google Oauth */
440  /*! Credentials not stored this is a fake auth */
442 };
443 
444 #define SIP_SORCERY_AUTH_TYPE "auth"
445 
446 struct ast_sip_auth {
447  /*! Sorcery ID of the auth is its name */
448  SORCERY_OBJECT(details);
450  /*! Identification for these credentials */
451  AST_STRING_FIELD(realm);
452  /*! Authentication username */
453  AST_STRING_FIELD(auth_user);
454  /*! Authentication password */
455  AST_STRING_FIELD(auth_pass);
456  /*! Authentication credentials in MD5 format (hash of user:realm:pass) */
457  AST_STRING_FIELD(md5_creds);
458  /*! Refresh token to use for OAuth authentication */
459  AST_STRING_FIELD(refresh_token);
460  /*! Client ID to use for OAuth authentication */
461  AST_STRING_FIELD(oauth_clientid);
462  /*! Secret to use for OAuth authentication */
463  AST_STRING_FIELD(oauth_secret);
464  );
465  /*! The time period (in seconds) that a nonce may be reused */
466  unsigned int nonce_lifetime;
467  /*! Used to determine what to use when authenticating */
468  enum ast_sip_auth_type type;
469 };
470 
471 AST_VECTOR(ast_sip_auth_vector, const char *);
473 /*!
474  * \brief Different methods by which incoming requests can be matched to endpoints
475  */
477  /*! Identify based on user name in From header */
479  /*! Identify based on user name in Auth header first, then From header */
481  /*! Identify based on source IP address */
483  /*! Identify based on arbitrary headers */
485 };
487 
489  /*! Use reinvite to negotiate direct media */
491  /*! Use UPDATE to negotiate direct media */
493 };
494 
496  /*! Take no special action to mitigate reinvite glare */
498  /*! Do not send an initial direct media session refresh on outgoing call legs
499  * Subsequent session refreshes will be sent no matter the session direction
500  */
502  /*! Do not send an initial direct media session refresh on incoming call legs
503  * Subsequent session refreshes will be sent no matter the session direction
504  */
506 };
507 
509  /*! Invalid media encryption configuration */
511  /*! Do not allow any encryption of session media */
513  /*! Offer SDES-encrypted session media */
515  /*! Offer encrypted session media with datagram TLS key exchange */
517 };
518 
520  /*! User portion of the target URI should be used as the target in the dialplan */
522  /*! Target URI should be used as the target in the dialplan */
524  /*! Target URI should be used as the target within chan_pjsip itself */
526 };
527 
528 /*!
529  * \brief Incoming/Outgoing call offer/answer joint codec preference.
530  *
531  * The default is INTERSECT ALL LOCAL.
532  */
534  /*! Two bits for merge */
535  /*! Intersection of local and remote */
537  /*! Union of local and remote */
539 
540  /*! Two bits for filter */
541  /*! No filter */
543  /*! Only the first */
545 
546  /*! Two bits for preference and sort */
547  /*! Prefer, and order by local values */
549  /*! Prefer, and order by remote values */
551 };
552 
553 /*!
554  * \brief Returns true if the preference is set in the parameter
555  * \since 18.0.0
556  *
557  * \param param A ast_flags struct with one or more of enum ast_sip_call_codec_pref set
558  * \param codec_pref The last component of one of the enum values
559  * \retval 1 if the enum value is set
560  * \retval 0 if not
561  */
562 #define ast_sip_call_codec_pref_test(__param, __codec_pref) (!!(ast_test_flag( &__param, AST_SIP_CALL_CODEC_PREF_ ## __codec_pref )))
564 /*!
565  * \brief Session timers options
566  */
568  /*! Minimum session expiration period, in seconds */
569  unsigned int min_se;
570  /*! Session expiration period, in seconds */
571  unsigned int sess_expires;
572 };
573 
574 /*!
575  * \brief Endpoint configuration for SIP extensions.
576  *
577  * SIP extensions, in this case refers to features
578  * indicated in Supported or Required headers.
579  */
581  /*! Enabled SIP extensions */
582  unsigned int flags;
583  /*! Timer options */
584  struct ast_sip_timer_options timer;
585 };
587 /*!
588  * \brief Endpoint configuration for unsolicited MWI
589  */
592  /*! Configured voicemail boxes for this endpoint. Used for MWI */
594  /*! Username to use when sending MWI NOTIFYs to this endpoint */
595  AST_STRING_FIELD(fromuser);
596  );
597  /*! Should mailbox states be combined into a single notification? */
598  unsigned int aggregate;
599  /*! Should a subscribe replace unsolicited notifies? */
600  unsigned int subscribe_replaces_unsolicited;
601  /*! Voicemail extension to set in Message-Account */
602  char *voicemail_extension;
603 };
605 /*!
606  * \brief Endpoint subscription configuration
607  */
609  /*! Indicates if endpoint is allowed to initiate subscriptions */
610  unsigned int allow;
611  /*! The minimum allowed expiration for subscriptions from endpoint */
612  unsigned int minexpiry;
613  /*! Message waiting configuration */
614  struct ast_sip_mwi_configuration mwi;
615  /*! Context for SUBSCRIBE requests */
617 };
619 /*!
620  * \brief NAT configuration options for endpoints
621  */
623  /*! Whether to force using the source IP address/port for sending responses */
624  unsigned int force_rport;
625  /*! Whether to rewrite the Contact header with the source IP address/port or not */
626  unsigned int rewrite_contact;
627 };
629 /*!
630  * \brief Party identification options for endpoints
631  *
632  * This includes caller ID, connected line, and redirecting-related options
633  */
635  struct ast_party_id self;
636  /*! Do we accept identification information from this endpoint */
637  unsigned int trust_inbound;
638  /*! Do we send private identification information to this endpoint? */
639  unsigned int trust_outbound;
640  /*! Do we send P-Asserted-Identity headers to this endpoint? */
641  unsigned int send_pai;
642  /*! Do we send Remote-Party-ID headers to this endpoint? */
643  unsigned int send_rpid;
644  /*! Do we send messages for connected line updates for unanswered incoming calls immediately to this endpoint? */
645  unsigned int rpid_immediate;
646  /*! Do we add Diversion headers to applicable outgoing requests/responses? */
647  unsigned int send_diversion;
648  /*! Do we accept connected line updates from this endpoint? */
649  unsigned int trust_connected_line;
650  /*! Do we send connected line updates to this endpoint? */
651  unsigned int send_connected_line;
652  /*! When performing connected line update, which method should be used */
653  enum ast_sip_session_refresh_method refresh_method;
654  /*! Do we add History-Info headers to applicable outgoing requests/responses? */
655  unsigned int send_history_info;
656 };
658 /*!
659  * \brief Call pickup configuration options for endpoints
660  */
662  /*! Call group */
663  ast_group_t callgroup;
664  /*! Pickup group */
665  ast_group_t pickupgroup;
666  /*! Named call group */
667  struct ast_namedgroups *named_callgroups;
668  /*! Named pickup group */
669  struct ast_namedgroups *named_pickupgroups;
670 };
672 /*!
673  * \brief Configuration for one-touch INFO recording
674  */
677  /*! Feature to enact when one-touch recording INFO with Record: On is received */
678  AST_STRING_FIELD(onfeature);
679  /*! Feature to enact when one-touch recording INFO with Record: Off is received */
680  AST_STRING_FIELD(offfeature);
681  );
682  /*! Is one-touch recording permitted? */
683  unsigned int enabled;
684 };
685 
686 /*!
687  * \brief Endpoint configuration options for INFO packages
688  */
690  /*! Configuration for one-touch recording */
692 };
694 /*!
695  * \brief RTP configuration for SIP endpoints
696  */
699  /*! Configured RTP engine for this endpoint. */
700  AST_STRING_FIELD(engine);
701  );
702  /*! Whether IPv6 RTP is enabled or not */
703  unsigned int ipv6;
704  /*! Whether symmetric RTP is enabled or not */
705  unsigned int symmetric;
706  /*! Whether ICE support is enabled or not */
707  unsigned int ice_support;
708  /*! Whether to use the "ptime" attribute received from the endpoint or not */
709  unsigned int use_ptime;
710  /*! Do we use AVPF exclusively for this endpoint? */
711  unsigned int use_avpf;
712  /*! Do we force AVP, AVPF, SAVP, or SAVPF even for DTLS media streams? */
713  unsigned int force_avp;
714  /*! Do we use the received media transport in our answer SDP */
715  unsigned int use_received_transport;
716  /*! \brief DTLS-SRTP configuration information */
717  struct ast_rtp_dtls_cfg dtls_cfg;
718  /*! Should SRTP use a 32 byte tag instead of an 80 byte tag? */
719  unsigned int srtp_tag_32;
720  /*! Do we use media encryption? what type? */
722  /*! Do we want to optimistically support encryption if possible? */
723  unsigned int encryption_optimistic;
724  /*! Number of seconds between RTP keepalive packets */
725  unsigned int keepalive;
726  /*! Number of seconds before terminating channel due to lack of RTP (when not on hold) */
727  unsigned int timeout;
728  /*! Number of seconds before terminating channel due to lack of RTP (when on hold) */
729  unsigned int timeout_hold;
730  /*! Follow forked media with a different To tag */
731  unsigned int follow_early_media_fork;
732  /*! Accept updated SDPs on non-100rel 18X and 2XX responses with the same To tag */
733  unsigned int accept_multiple_sdp_answers;
734 };
736 /*!
737  * \brief Direct media options for SIP endpoints
738  */
740  /*! Boolean indicating if direct_media is permissible */
741  unsigned int enabled;
742  /*! When using direct media, which method should be used */
744  /*! Take steps to mitigate glare for direct media */
745  enum ast_sip_direct_media_glare_mitigation glare_mitigation;
746  /*! Do not attempt direct media session refreshes if a media NAT is detected */
747  unsigned int disable_on_nat;
748 };
749 
751  /*! Whether T.38 UDPTL support is enabled or not */
752  unsigned int enabled;
753  /*! Error correction setting for T.38 UDPTL */
754  enum ast_t38_ec_modes error_correction;
755  /*! Explicit T.38 max datagram value, may be 0 to indicate the remote side can be trusted */
756  unsigned int maxdatagram;
757  /*! Whether NAT Support is enabled for T.38 UDPTL sessions or not */
758  unsigned int nat;
759  /*! Whether to use IPv6 for UDPTL or not */
760  unsigned int ipv6;
761 };
763 /*!
764  * \brief Media configuration for SIP endpoints
765  */
768  /*! Optional media address to use in SDP */
770  /*! SDP origin username */
771  AST_STRING_FIELD(sdpowner);
772  /*! SDP session name */
773  AST_STRING_FIELD(sdpsession);
774  );
775  /*! RTP media configuration */
777  /*! Direct media options */
779  /*! T.38 (FoIP) options */
781  /*! Configured codecs */
783  /*! Capabilities in topology form */
784  struct ast_stream_topology *topology;
785  /*! DSCP TOS bits for audio streams */
786  unsigned int tos_audio;
787  /*! Priority for audio streams */
788  unsigned int cos_audio;
789  /*! DSCP TOS bits for video streams */
790  unsigned int tos_video;
791  /*! Priority for video streams */
792  unsigned int cos_video;
793  /*! Is g.726 packed in a non standard way */
794  unsigned int g726_non_standard;
795  /*! Bind the RTP instance to the media_address */
796  unsigned int bind_rtp_to_media_address;
797  /*! Use RTCP-MUX */
798  unsigned int rtcp_mux;
799  /*! Maximum number of audio streams to offer/accept */
800  unsigned int max_audio_streams;
801  /*! Maximum number of video streams to offer/accept */
802  unsigned int max_video_streams;
803  /*! Use BUNDLE */
804  unsigned int bundle;
805  /*! Enable webrtc settings and defaults */
806  unsigned int webrtc;
807  /*! Codec preference for an incoming offer */
808  struct ast_flags incoming_call_offer_pref;
809  /*! Codec preference for an outgoing offer */
810  struct ast_flags outgoing_call_offer_pref;
811  /*! Codec negotiation prefs for incoming offers */
812  struct ast_stream_codec_negotiation_prefs codec_prefs_incoming_offer;
813  /*! Codec negotiation prefs for outgoing offers */
814  struct ast_stream_codec_negotiation_prefs codec_prefs_outgoing_offer;
815  /*! Codec negotiation prefs for incoming answers */
816  struct ast_stream_codec_negotiation_prefs codec_prefs_incoming_answer;
817  /*! Codec negotiation prefs for outgoing answers */
818  struct ast_stream_codec_negotiation_prefs codec_prefs_outgoing_answer;
819 };
820 
821 /*!
822  * \brief An entity with which Asterisk communicates
823  */
824 struct ast_sip_endpoint {
825  SORCERY_OBJECT(details);
827  /*! Context to send incoming calls to */
829  /*! Name of an explicit transport to use */
831  /*! Outbound proxy to use */
832  AST_STRING_FIELD(outbound_proxy);
833  /*! Explicit AORs to dial if none are specified */
834  AST_STRING_FIELD(aors);
835  /*! Musiconhold class to suggest that the other side use when placing on hold */
837  /*! Configured tone zone for this endpoint. */
838  AST_STRING_FIELD(zone);
839  /*! Configured language for this endpoint. */
841  /*! Default username to place in From header */
842  AST_STRING_FIELD(fromuser);
843  /*! Domain to place in From header */
844  AST_STRING_FIELD(fromdomain);
845  /*! Context to route incoming MESSAGE requests to */
846  AST_STRING_FIELD(message_context);
847  /*! Accountcode to auto-set on channels */
849  /*! If set, we'll push incoming MWI NOTIFYs to stasis using this mailbox */
850  AST_STRING_FIELD(incoming_mwi_mailbox);
851  );
852  /*! Configuration for extensions */
853  struct ast_sip_endpoint_extensions extensions;
854  /*! Configuration relating to media */
856  /*! SUBSCRIBE/NOTIFY configuration options */
858  /*! NAT configuration */
860  /*! Party identification options */
862  /*! Configuration options for INFO packages */
864  /*! Call pickup configuration */
866  /*! Inbound authentication credentials */
867  struct ast_sip_auth_vector inbound_auths;
868  /*! Outbound authentication credentials */
869  struct ast_sip_auth_vector outbound_auths;
870  /*! DTMF mode to use with this endpoint */
871  enum ast_sip_dtmf_mode dtmf;
872  /*! Method(s) by which the endpoint should be identified. */
874  /*! Order of the method(s) by which the endpoint should be identified. */
875  struct ast_sip_identify_by_vector ident_method_order;
876  /*! Boolean indicating if ringing should be sent as inband progress */
877  unsigned int inband_progress;
878  /*! Pointer to the persistent Asterisk endpoint */
879  struct ast_endpoint *persistent;
880  /*! The number of channels at which busy device state is returned */
881  unsigned int devicestate_busy_at;
882  /*! Whether fax detection is enabled or not (CNG tone detection) */
883  unsigned int faxdetect;
884  /*! Determines if transfers (using REFER) are allowed by this endpoint */
885  unsigned int allowtransfer;
886  /*! Method used when handling redirects */
887  enum ast_sip_session_redirect redirect_method;
888  /*! Variables set on channel creation */
889  struct ast_variable *channel_vars;
890  /*! Whether to place a 'user=phone' parameter into the request URI if user is a number */
891  unsigned int usereqphone;
892  /*! Whether to pass through hold and unhold using re-invites with recvonly and sendrecv */
893  unsigned int moh_passthrough;
894  /*! Access control list */
895  struct ast_acl_list *acl;
896  /*! Restrict what IPs are allowed in the Contact header (for registration) */
897  struct ast_acl_list *contact_acl;
898  /*! The number of seconds into call to disable fax detection. (0 = disabled) */
899  unsigned int faxdetect_timeout;
900  /*! Override the user on the outgoing Contact header with this value. */
901  char *contact_user;
902  /*! Whether to response SDP offer with single most preferred codec. */
903  unsigned int preferred_codec_only;
904  /*! Do we allow an asymmetric RTP codec? */
905  unsigned int asymmetric_rtp_codec;
906  /*! Do we allow overlap dialling? */
907  unsigned int allow_overlap;
908  /*! Whether to notifies all the progress details on blind transfer */
909  unsigned int refer_blind_progress;
910  /*! Whether to notifies dialog-info 'early' on INUSE && RINGING state */
911  unsigned int notify_early_inuse_ringing;
912  /*! Suppress Q.850 Reason headers on this endpoint */
913  unsigned int suppress_q850_reason_headers;
914  /*! Ignore 183 if no SDP is present */
915  unsigned int ignore_183_without_sdp;
916  /*! Enable STIR/SHAKEN support on this endpoint */
917  unsigned int stir_shaken;
918  /*! Should we authenticate OPTIONS requests per RFC 3261? */
919  unsigned int allow_unauthenticated_options;
920 };
921 
922 /*! URI parameter for symmetric transport */
923 #define AST_SIP_X_AST_TXP "x-ast-txp"
924 #define AST_SIP_X_AST_TXP_LEN 9
925 
926 /*!
927  * \brief Initialize an auth vector with the configured values.
928  *
929  * \param vector Vector to initialize
930  * \param auth_names Comma-separated list of names to set in the array
931  * \retval 0 Success
932  * \retval non-zero Failure
933  */
934 int ast_sip_auth_vector_init(struct ast_sip_auth_vector *vector, const char *auth_names);
935 
936 /*!
937  * \brief Free contents of an auth vector.
938  *
939  * \param array Vector whose contents are to be freed
940  */
942 
943 /*!
944  * \brief Possible returns from ast_sip_check_authentication
945  */
947  /*! Authentication needs to be challenged */
949  /*! Authentication succeeded */
951  /*! Authentication failed */
953  /*! Authentication encountered some internal error */
955 };
956 
957 /*!
958  * \brief An interchangeable way of handling digest authentication for SIP.
959  *
960  * An authenticator is responsible for filling in the callbacks provided below. Each is called from a publicly available
961  * function in res_sip. The authenticator can use configuration or other local policy to determine whether authentication
962  * should take place and what credentials should be used when challenging and authenticating a request.
963  */
964 struct ast_sip_authenticator {
965  /*!
966  * \brief Check if a request requires authentication
967  * See ast_sip_requires_authentication for more details
968  */
969  int (*requires_authentication)(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
970  /*!
971  * \brief Check that an incoming request passes authentication.
972  *
973  * The tdata parameter is useful for adding information such as digest challenges.
974  *
975  * \param endpoint The endpoint sending the incoming request
976  * \param rdata The incoming request
977  * \param tdata Tentative outgoing request.
978  */
979  enum ast_sip_check_auth_result (*check_authentication)(struct ast_sip_endpoint *endpoint,
980  pjsip_rx_data *rdata, pjsip_tx_data *tdata);
981 };
982 
983 /*!
984  * \brief an interchangeable way of responding to authentication challenges
985  *
986  * An outbound authenticator takes incoming challenges and formulates a new SIP request with
987  * credentials.
988  */
990  /*!
991  * \brief Create a new request with authentication credentials
992  *
993  * \param auths A vector of IDs of auth sorcery objects
994  * \param challenge The SIP response with authentication challenge(s)
995  * \param old_request The request that received the auth challenge(s)
996  * \param new_request The new SIP request with challenge response(s)
997  * \retval 0 Successfully created new request
998  * \retval -1 Failed to create a new request
999  */
1000  int (*create_request_with_auth)(const struct ast_sip_auth_vector *auths, struct pjsip_rx_data *challenge,
1001  struct pjsip_tx_data *old_request, struct pjsip_tx_data **new_request);
1002 };
1003 
1004 /*!
1005  * \brief An entity responsible for identifying the source of a SIP message
1006  */
1008  /*!
1009  * \brief Callback used to identify the source of a message.
1010  * See ast_sip_identify_endpoint for more details
1011  */
1012  struct ast_sip_endpoint *(*identify_endpoint)(pjsip_rx_data *rdata);
1013 };
1014 
1015 /*!
1016  * \brief Contact retrieval filtering flags
1017  */
1019  /*! \brief Default filter flags */
1021 
1022  /*! \brief Return only reachable or unknown contacts */
1024 };
1025 
1026 /*!
1027  * \brief Adds a Date header to the tdata, formatted like:
1028  * Date: Wed, 01 Jan 2021 14:53:01 GMT
1029  * \since 16.19.0
1030  *
1031  * \note There is no checking done to see if the header already exists
1032  * before adding it. It's up to the caller of this function to determine
1033  * if that needs to be done or not.
1034  */
1035 void ast_sip_add_date_header(pjsip_tx_data *tdata);
1036 
1037 /*!
1038  * \brief Register a SIP service in Asterisk.
1039  *
1040  * This is more-or-less a wrapper around pjsip_endpt_register_module().
1041  * Registering a service makes it so that PJSIP will call into the
1042  * service at appropriate times. For more information about PJSIP module
1043  * callbacks, see the PJSIP documentation. Asterisk modules that call
1044  * this function will likely do so at module load time.
1045  *
1046  * \param module The module that is to be registered with PJSIP
1047  * \retval 0 Success
1048  * \retval -1 Failure
1049  */
1050 int ast_sip_register_service(pjsip_module *module);
1051 
1052 /*!
1053  * This is the opposite of ast_sip_register_service(). Unregistering a
1054  * service means that PJSIP will no longer call into the module any more.
1055  * This will likely occur when an Asterisk module is unloaded.
1056  *
1057  * \param module The PJSIP module to unregister
1058  */
1059 void ast_sip_unregister_service(pjsip_module *module);
1060 
1061 /*!
1062  * \brief Register a SIP authenticator
1063  *
1064  * An authenticator has three main purposes:
1065  * 1) Determining if authentication should be performed on an incoming request
1066  * 2) Gathering credentials necessary for issuing an authentication challenge
1067  * 3) Authenticating a request that has credentials
1068  *
1069  * Asterisk provides a default authenticator, but it may be replaced by a
1070  * custom one if desired.
1071  *
1072  * \param auth The authenticator to register
1073  * \retval 0 Success
1074  * \retval -1 Failure
1075  */
1077 
1078 /*!
1079  * \brief Unregister a SIP authenticator
1080  *
1081  * When there is no authenticator registered, requests cannot be challenged
1082  * or authenticated.
1083  *
1084  * \param auth The authenticator to unregister
1085  */
1087 
1088  /*!
1089  * \brief Register an outbound SIP authenticator
1090  *
1091  * An outbound authenticator is responsible for creating responses to
1092  * authentication challenges by remote endpoints.
1093  *
1094  * \param auth The authenticator to register
1095  * \retval 0 Success
1096  * \retval -1 Failure
1097  */
1099 
1100 /*!
1101  * \brief Unregister an outbound SIP authenticator
1102  *
1103  * When there is no outbound authenticator registered, authentication challenges
1104  * will be handled as any other final response would be.
1105  *
1106  * \param auth The authenticator to unregister
1107  */
1109 
1110 /*!
1111  * \brief Register a SIP endpoint identifier with a name.
1112  *
1113  * An endpoint identifier's purpose is to determine which endpoint a given SIP
1114  * message has come from.
1115  *
1116  * Multiple endpoint identifiers may be registered so that if an endpoint
1117  * cannot be identified by one identifier, it may be identified by another.
1118  *
1119  * \param identifier The SIP endpoint identifier to register
1120  * \param name The name of the endpoint identifier
1121  * \retval 0 Success
1122  * \retval -1 Failure
1123  */
1125  const char *name);
1126 
1127 /*!
1128  * \brief Register a SIP endpoint identifier
1129  *
1130  * An endpoint identifier's purpose is to determine which endpoint a given SIP
1131  * message has come from.
1132  *
1133  * Multiple endpoint identifiers may be registered so that if an endpoint
1134  * cannot be identified by one identifier, it may be identified by another.
1135  *
1136  * Asterisk provides two endpoint identifiers. One identifies endpoints based
1137  * on the user part of the From header URI. The other identifies endpoints based
1138  * on the source IP address.
1139  *
1140  * If the order in which endpoint identifiers is run is important to you, then
1141  * be sure to load individual endpoint identifier modules in the order you wish
1142  * for them to be run in modules.conf
1143  *
1144  * \note endpoint identifiers registered using this method (no name specified)
1145  * are placed at the front of the endpoint identifiers list ahead of any
1146  * named identifiers.
1147  *
1148  * \param identifier The SIP endpoint identifier to register
1149  * \retval 0 Success
1150  * \retval -1 Failure
1151  */
1153 
1154 /*!
1155  * \brief Unregister a SIP endpoint identifier
1156  *
1157  * This stops an endpoint identifier from being used.
1158  *
1159  * \param identifier The SIP endoint identifier to unregister
1160  */
1162 
1163 /*!
1164  * \brief Allocate a new SIP endpoint
1165  *
1166  * This will return an endpoint with its refcount increased by one. This reference
1167  * can be released using ao2_ref().
1168  *
1169  * \param name The name of the endpoint.
1170  * \retval NULL Endpoint allocation failed
1171  * \retval non-NULL The newly allocated endpoint
1172  */
1173 void *ast_sip_endpoint_alloc(const char *name);
1174 
1175 /*!
1176  * \brief Change state of a persistent endpoint.
1177  *
1178  * \param endpoint_name The SIP endpoint name to change state.
1179  * \param state The new state
1180  * \retval 0 Success
1181  * \retval -1 Endpoint not found
1182  */
1183 int ast_sip_persistent_endpoint_update_state(const char *endpoint_name, enum ast_endpoint_state state);
1184 
1185 /*!
1186  * \brief Publish the change of state for a contact.
1187  *
1188  * \param endpoint_name The SIP endpoint name.
1189  * \param contact_status The contact status.
1190  */
1191 void ast_sip_persistent_endpoint_publish_contact_state(const char *endpoint_name, const struct ast_sip_contact_status *contact_status);
1192 
1193 /*!
1194  * \brief Retrieve the current status for a contact.
1195  *
1196  * \param contact The contact.
1197  *
1198  * \retval non-NULL Success
1199  * \retval NULL Status information not found
1200  *
1201  * \note The returned contact status object is immutable.
1202  */
1204 
1205 /*!
1206  * \brief Get a pointer to the PJSIP endpoint.
1207  *
1208  * This is useful when modules have specific information they need
1209  * to register with the PJSIP core.
1210  * \retval NULL endpoint has not been created yet.
1211  * \retval non-NULL PJSIP endpoint.
1212  */
1213 pjsip_endpoint *ast_sip_get_pjsip_endpoint(void);
1214 
1215 /*!
1216  * \brief Get a pointer to the SIP sorcery structure.
1217  *
1218  * \retval NULL sorcery has not been initialized
1219  * \retval non-NULL sorcery structure
1220  */
1221 struct ast_sorcery *ast_sip_get_sorcery(void);
1222 
1223 /*!
1224  * \brief Retrieve a named AOR
1225  *
1226  * \param aor_name Name of the AOR
1227  *
1228  * \retval NULL if not found
1229  * \retval non-NULL if found
1230  */
1231 struct ast_sip_aor *ast_sip_location_retrieve_aor(const char *aor_name);
1232 
1233 /*!
1234  * \brief Retrieve the first bound contact for an AOR
1235  *
1236  * \param aor Pointer to the AOR
1237  * \retval NULL if no contacts available
1238  * \retval non-NULL if contacts available
1239  */
1241 
1242 /*!
1243  * \brief Retrieve the first bound contact for an AOR and filter based on flags
1244  * \since 13.16.0
1245  *
1246  * \param aor Pointer to the AOR
1247  * \param flags Filtering flags
1248  * \retval NULL if no contacts available
1249  * \retval non-NULL if contacts available
1250  */
1252  unsigned int flags);
1253 
1254 /*!
1255  * \brief Retrieve all contacts currently available for an AOR
1256  *
1257  * \param aor Pointer to the AOR
1258  *
1259  * \retval NULL if no contacts available
1260  * \retval non-NULL if contacts available
1261  *
1262  * \warning
1263  * Since this function prunes expired contacts before returning, it holds a named write
1264  * lock on the aor. If you already hold the lock, call ast_sip_location_retrieve_aor_contacts_nolock instead.
1265  */
1267 
1268 /*!
1269  * \brief Retrieve all contacts currently available for an AOR and filter based on flags
1270  * \since 13.16.0
1271  *
1272  * \param aor Pointer to the AOR
1273  * \param flags Filtering flags
1274  *
1275  * \retval NULL if no contacts available
1276  * \retval non-NULL if contacts available
1277  *
1278  * \warning
1279  * Since this function prunes expired contacts before returning, it holds a named write
1280  * lock on the aor. If you already hold the lock, call ast_sip_location_retrieve_aor_contacts_nolock instead.
1281  */
1283  unsigned int flags);
1284 
1285 /*!
1286  * \brief Retrieve all contacts currently available for an AOR without locking the AOR
1287  * \since 13.9.0
1288  *
1289  * \param aor Pointer to the AOR
1290  *
1291  * \retval NULL if no contacts available
1292  * \retval non-NULL if contacts available
1293  *
1294  * \warning
1295  * This function should only be called if you already hold a named write lock on the aor.
1296  */
1298 
1299 /*!
1300  * \brief Retrieve all contacts currently available for an AOR without locking the AOR and filter based on flags
1301  * \since 13.16.0
1302  *
1303  * \param aor Pointer to the AOR
1304  * \param flags Filtering flags
1305  *
1306  * \retval NULL if no contacts available
1307  * \retval non-NULL if contacts available
1308  *
1309  * \warning
1310  * This function should only be called if you already hold a named write lock on the aor.
1311  */
1313  unsigned int flags);
1314 
1315 /*!
1316  * \brief Retrieve the first bound contact from a list of AORs
1317  *
1318  * \param aor_list A comma-separated list of AOR names
1319  * \retval NULL if no contacts available
1320  * \retval non-NULL if contacts available
1321  */
1323 
1324 /*!
1325  * \brief Retrieve all contacts from a list of AORs
1326  *
1327  * \param aor_list A comma-separated list of AOR names
1328  * \retval NULL if no contacts available
1329  * \retval non-NULL container (which must be freed) if contacts available
1330  */
1332 
1333 /*!
1334  * \brief Retrieve the first bound contact AND the AOR chosen from a list of AORs
1335  *
1336  * \param aor_list A comma-separated list of AOR names
1337  * \param aor The chosen AOR
1338  * \param contact The chosen contact
1339  */
1340  void ast_sip_location_retrieve_contact_and_aor_from_list(const char *aor_list, struct ast_sip_aor **aor,
1341  struct ast_sip_contact **contact);
1342 
1343 /*!
1344  * \brief Retrieve the first bound contact AND the AOR chosen from a list of AORs and filter based on flags
1345  * \since 13.16.0
1346  *
1347  * \param aor_list A comma-separated list of AOR names
1348  * \param flags Filtering flags
1349  * \param aor The chosen AOR
1350  * \param contact The chosen contact
1351  */
1352 void ast_sip_location_retrieve_contact_and_aor_from_list_filtered(const char *aor_list, unsigned int flags,
1353  struct ast_sip_aor **aor, struct ast_sip_contact **contact);
1354 
1355 /*!
1356  * \brief Retrieve a named contact
1357  *
1358  * \param contact_name Name of the contact
1359  *
1360  * \retval NULL if not found
1361  * \retval non-NULL if found
1362  */
1363 struct ast_sip_contact *ast_sip_location_retrieve_contact(const char *contact_name);
1364 
1365 /*!
1366  * \brief Add a new contact to an AOR
1367  *
1368  * \param aor Pointer to the AOR
1369  * \param uri Full contact URI
1370  * \param expiration_time Optional expiration time of the contact
1371  * \param path_info Path information
1372  * \param user_agent User-Agent header from REGISTER request
1373  * \param via_addr
1374  * \param via_port
1375  * \param call_id
1376  * \param endpoint The endpoint that resulted in the contact being added
1377  *
1378  * \retval -1 failure
1379  * \retval 0 success
1380  *
1381  * \warning
1382  * This function holds a named write lock on the aor. If you already hold the lock
1383  * you should call ast_sip_location_add_contact_nolock instead.
1384  */
1385 int ast_sip_location_add_contact(struct ast_sip_aor *aor, const char *uri,
1386  struct timeval expiration_time, const char *path_info, const char *user_agent,
1387  const char *via_addr, int via_port, const char *call_id,
1388  struct ast_sip_endpoint *endpoint);
1389 
1390 /*!
1391  * \brief Add a new contact to an AOR without locking the AOR
1392  * \since 13.9.0
1393  *
1394  * \param aor Pointer to the AOR
1395  * \param uri Full contact URI
1396  * \param expiration_time Optional expiration time of the contact
1397  * \param path_info Path information
1398  * \param user_agent User-Agent header from REGISTER request
1399  * \param via_addr
1400  * \param via_port
1401  * \param call_id
1402  * \param endpoint The endpoint that resulted in the contact being added
1403  *
1404  * \retval -1 failure
1405  * \retval 0 success
1406  *
1407  * \warning
1408  * This function should only be called if you already hold a named write lock on the aor.
1409  */
1410 int ast_sip_location_add_contact_nolock(struct ast_sip_aor *aor, const char *uri,
1411  struct timeval expiration_time, const char *path_info, const char *user_agent,
1412  const char *via_addr, int via_port, const char *call_id,
1413  struct ast_sip_endpoint *endpoint);
1414 
1415 /*!
1416  * \brief Create a new contact for an AOR without locking the AOR
1417  * \since 13.18.0
1418  *
1419  * \param aor Pointer to the AOR
1420  * \param uri Full contact URI
1421  * \param expiration_time Optional expiration time of the contact
1422  * \param path_info Path information
1423  * \param user_agent User-Agent header from REGISTER request
1424  * \param via_addr
1425  * \param via_port
1426  * \param call_id
1427  * \param prune_on_boot Non-zero if the contact cannot survive a restart/boot.
1428  * \param endpoint The endpoint that resulted in the contact being added
1429  *
1430  * \return The created contact or NULL on failure.
1431  *
1432  * \warning
1433  * This function should only be called if you already hold a named write lock on the aor.
1434  */
1436  const char *uri, struct timeval expiration_time, const char *path_info,
1437  const char *user_agent, const char *via_addr, int via_port, const char *call_id,
1438  int prune_on_boot, struct ast_sip_endpoint *endpoint);
1439 
1440 /*!
1441  * \brief Update a contact
1442  *
1443  * \param contact New contact object with details
1444  *
1445  * \retval -1 failure
1446  * \retval 0 success
1447  */
1449 
1450 /*!
1451 * \brief Delete a contact
1452 *
1453 * \param contact Contact object to delete
1454 *
1455 * \retval -1 failure
1456 * \retval 0 success
1457 */
1459 
1460 /*!
1461  * \brief Prune the prune_on_boot contacts
1462  * \since 13.18.0
1463  */
1465 
1466 /*!
1467  * \brief Callback called when an outbound request with authentication credentials is to be sent in dialog
1468  *
1469  * This callback will have the created request on it. The callback's purpose is to do any extra
1470  * housekeeping that needs to be done as well as to send the request out.
1471  *
1472  * This callback is only necessary if working with a PJSIP API that sits between the application
1473  * and the dialog layer.
1474  *
1475  * \param dlg The dialog to which the request belongs
1476  * \param tdata The created request to be sent out
1477  * \param user_data Data supplied with the callback
1478  *
1479  * \retval 0 Success
1480  * \retval -1 Failure
1481  */
1482 typedef int (*ast_sip_dialog_outbound_auth_cb)(pjsip_dialog *dlg, pjsip_tx_data *tdata, void *user_data);
1483 
1484 /*!
1485  * \brief Set up outbound authentication on a SIP dialog
1486  *
1487  * This sets up the infrastructure so that all requests associated with a created dialog
1488  * can be re-sent with authentication credentials if the original request is challenged.
1489  *
1490  * \param dlg The dialog on which requests will be authenticated
1491  * \param endpoint The endpoint whom this dialog pertains to
1492  * \param cb Callback to call to send requests with authentication
1493  * \param user_data Data to be provided to the callback when it is called
1494  *
1495  * \retval 0 Success
1496  * \retval -1 Failure
1497  */
1498 int ast_sip_dialog_setup_outbound_authentication(pjsip_dialog *dlg, const struct ast_sip_endpoint *endpoint,
1499  ast_sip_dialog_outbound_auth_cb cb, void *user_data);
1500 
1501 /*!
1502  * \brief Retrieves a reference to the artificial auth.
1503  *
1504  * \retval The artificial auth
1505  */
1507 
1508 /*!
1509  * \brief Retrieves a reference to the artificial endpoint.
1510  *
1511  * \retval The artificial endpoint
1512  */
1514 
1515 /*! \defgroup pjsip_threading PJSIP Threading Model
1516  * @{
1517  * \page PJSIP PJSIP Threading Model
1518  *
1519  * There are three major types of threads that SIP will have to deal with:
1520  * \li Asterisk threads
1521  * \li PJSIP threads
1522  * \li SIP threadpool threads (a.k.a. "servants")
1523  *
1524  * \par Asterisk Threads
1525  *
1526  * Asterisk threads are those that originate from outside of SIP but within
1527  * Asterisk. The most common of these threads are PBX (channel) threads and
1528  * the autoservice thread. Most interaction with these threads will be through
1529  * channel technology callbacks. Within these threads, it is fine to handle
1530  * Asterisk data from outside of SIP, but any handling of SIP data should be
1531  * left to servants, \b especially if you wish to call into PJSIP for anything.
1532  * Asterisk threads are not registered with PJLIB, so attempting to call into
1533  * PJSIP will cause an assertion to be triggered, thus causing the program to
1534  * crash.
1535  *
1536  * \par PJSIP Threads
1537  *
1538  * PJSIP threads are those that originate from handling of PJSIP events, such
1539  * as an incoming SIP request or response, or a transaction timeout. The role
1540  * of these threads is to process information as quickly as possible so that
1541  * the next item on the SIP socket(s) can be serviced. On incoming messages,
1542  * Asterisk automatically will push the request to a servant thread. When your
1543  * module callback is called, processing will already be in a servant. However,
1544  * for other PJSIP events, such as transaction state changes due to timer
1545  * expirations, your module will be called into from a PJSIP thread. If you
1546  * are called into from a PJSIP thread, then you should push whatever processing
1547  * is needed to a servant as soon as possible. You can discern if you are currently
1548  * in a SIP servant thread using the \ref ast_sip_thread_is_servant function.
1549  *
1550  * \par Servants
1551  *
1552  * Servants are where the bulk of SIP work should be performed. These threads
1553  * exist in order to do the work that Asterisk threads and PJSIP threads hand
1554  * off to them. Servant threads register themselves with PJLIB, meaning that
1555  * they are capable of calling PJSIP and PJLIB functions if they wish.
1556  *
1557  * \par Serializer
1558  *
1559  * Tasks are handed off to servant threads using the API call \ref ast_sip_push_task.
1560  * The first parameter of this call is a serializer. If this pointer
1561  * is NULL, then the work will be handed off to whatever servant can currently handle
1562  * the task. If this pointer is non-NULL, then the task will not be executed until
1563  * previous tasks pushed with the same serializer have completed. For more information
1564  * on serializers and the benefits they provide, see \ref ast_threadpool_serializer
1565  *
1566  * \par Scheduler
1567  *
1568  * Some situations require that a task run periodically or at a future time. Normally
1569  * the ast_sched functionality would be used but ast_sched only uses 1 thread for all
1570  * tasks and that thread isn't registered with PJLIB and therefore can't do any PJSIP
1571  * related work.
1572  *
1573  * ast_sip_sched uses ast_sched only as a scheduled queue. When a task is ready to run,
1574  * it's pushed to a Serializer to be invoked asynchronously by a Servant. This ensures
1575  * that the task is executed in a PJLIB registered thread and allows the ast_sched thread
1576  * to immediately continue processing the queue. The Serializer used by ast_sip_sched
1577  * is one of your choosing or a random one from the res_pjsip pool if you don't choose one.
1578  *
1579  * \note
1580  *
1581  * Do not make assumptions about individual threads based on a corresponding serializer.
1582  * In other words, just because several tasks use the same serializer when being pushed
1583  * to servants, it does not mean that the same thread is necessarily going to execute those
1584  * tasks, even though they are all guaranteed to be executed in sequence.
1585  */
1586 
1587 typedef int (*ast_sip_task)(void *user_data);
1588 
1589 /*!
1590  * \brief Create a new serializer for SIP tasks
1591  * \since 13.8.0
1592  *
1593  * See \ref ast_threadpool_serializer for more information on serializers.
1594  * SIP creates serializers so that tasks operating on similar data will run
1595  * in sequence.
1596  *
1597  * \param name Name of the serializer. (must be unique)
1598  *
1599  * \retval NULL Failure
1600  * \retval non-NULL Newly-created serializer
1601  */
1602 struct ast_taskprocessor *ast_sip_create_serializer(const char *name);
1603 
1605 
1606 /*!
1607  * \brief Create a new serializer for SIP tasks
1608  * \since 13.8.0
1609  *
1610  * See \ref ast_threadpool_serializer for more information on serializers.
1611  * SIP creates serializers so that tasks operating on similar data will run
1612  * in sequence.
1613  *
1614  * \param name Name of the serializer. (must be unique)
1615  * \param shutdown_group Group shutdown controller. (NULL if no group association)
1616  *
1617  * \retval NULL Failure
1618  * \retval non-NULL Newly-created serializer
1619  */
1621 
1622 /*!
1623  * \brief Determine the distributor serializer for the SIP message.
1624  * \since 13.10.0
1625  *
1626  * \param rdata The incoming message.
1627  *
1628  * \retval Calculated distributor serializer on success.
1629  * \retval NULL on error.
1630  */
1631 struct ast_taskprocessor *ast_sip_get_distributor_serializer(pjsip_rx_data *rdata);
1632 
1633 /*!
1634  * \brief Set a serializer on a SIP dialog so requests and responses are automatically serialized
1635  *
1636  * Passing a NULL serializer is a way to remove a serializer from a dialog.
1637  *
1638  * \param dlg The SIP dialog itself
1639  * \param serializer The serializer to use
1640  */
1641 void ast_sip_dialog_set_serializer(pjsip_dialog *dlg, struct ast_taskprocessor *serializer);
1642 
1643 /*!
1644  * \brief Set an endpoint on a SIP dialog so in-dialog requests do not undergo endpoint lookup.
1645  *
1646  * \param dlg The SIP dialog itself
1647  * \param endpoint The endpoint that this dialog is communicating with
1648  */
1649 void ast_sip_dialog_set_endpoint(pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint);
1650 
1651 /*!
1652  * \brief Get the endpoint associated with this dialog
1653  *
1654  * This function increases the refcount of the endpoint by one. Release
1655  * the reference once you are finished with the endpoint.
1656  *
1657  * \param dlg The SIP dialog from which to retrieve the endpoint
1658  * \retval NULL No endpoint associated with this dialog
1659  * \retval non-NULL The endpoint.
1660  */
1661 struct ast_sip_endpoint *ast_sip_dialog_get_endpoint(pjsip_dialog *dlg);
1662 
1663 /*!
1664  * \brief Pushes a task to SIP servants
1665  *
1666  * This uses the serializer provided to determine how to push the task.
1667  * If the serializer is NULL, then the task will be pushed to the
1668  * servants directly. If the serializer is non-NULL, then the task will be
1669  * queued behind other tasks associated with the same serializer.
1670  *
1671  * \param serializer The serializer to which the task belongs. Can be NULL
1672  * \param sip_task The task to execute
1673  * \param task_data The parameter to pass to the task when it executes
1674  * \retval 0 Success
1675  * \retval -1 Failure
1676  */
1677 int ast_sip_push_task(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1678 
1679 /*!
1680  * \brief Push a task to SIP servants and wait for it to complete.
1681  *
1682  * Like \ref ast_sip_push_task except that it blocks until the task
1683  * completes. If the current thread is a SIP servant thread then the
1684  * task executes immediately. Otherwise, the specified serializer
1685  * executes the task and the current thread waits for it to complete.
1686  *
1687  * \note PJPROJECT callbacks tend to have locks already held when
1688  * called.
1689  *
1690  * \warning \b Never hold locks that may be acquired by a SIP servant
1691  * thread when calling this function. Doing so may cause a deadlock
1692  * if all SIP servant threads are blocked waiting to acquire the lock
1693  * while the thread holding the lock is waiting for a free SIP servant
1694  * thread.
1695  *
1696  * \warning \b Use of this function in an ao2 destructor callback is a
1697  * bad idea. You don't have control over which thread executes the
1698  * destructor. Attempting to shift execution to another thread with
1699  * this function is likely to cause deadlock.
1700  *
1701  * \param serializer The SIP serializer to execute the task if the
1702  * current thread is not a SIP servant. NULL if any of the default
1703  * serializers can be used.
1704  * \param sip_task The task to execute
1705  * \param task_data The parameter to pass to the task when it executes
1706  *
1707  * \note The sip_task() return value may need to be distinguished from
1708  * the failure to push the task.
1709  *
1710  * \return sip_task() return value on success.
1711  * \retval -1 Failure to push the task.
1712  */
1713 int ast_sip_push_task_wait_servant(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1714 
1715 /*!
1716  * \brief Push a task to SIP servants and wait for it to complete.
1717  * \deprecated Replaced with ast_sip_push_task_wait_servant().
1718  */
1719 int ast_sip_push_task_synchronous(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1720 
1721 /*!
1722  * \brief Push a task to the serializer and wait for it to complete.
1723  *
1724  * Like \ref ast_sip_push_task except that it blocks until the task is
1725  * completed by the specified serializer. If the specified serializer
1726  * is the current thread then the task executes immediately.
1727  *
1728  * \note PJPROJECT callbacks tend to have locks already held when
1729  * called.
1730  *
1731  * \warning \b Never hold locks that may be acquired by a SIP servant
1732  * thread when calling this function. Doing so may cause a deadlock
1733  * if all SIP servant threads are blocked waiting to acquire the lock
1734  * while the thread holding the lock is waiting for a free SIP servant
1735  * thread for the serializer to execute in.
1736  *
1737  * \warning \b Never hold locks that may be acquired by the serializer
1738  * when calling this function. Doing so will cause a deadlock.
1739  *
1740  * \warning \b Never use this function in the pjsip monitor thread (It
1741  * is a SIP servant thread). This is likely to cause a deadlock.
1742  *
1743  * \warning \b Use of this function in an ao2 destructor callback is a
1744  * bad idea. You don't have control over which thread executes the
1745  * destructor. Attempting to shift execution to another thread with
1746  * this function is likely to cause deadlock.
1747  *
1748  * \param serializer The SIP serializer to execute the task. NULL if
1749  * any of the default serializers can be used.
1750  * \param sip_task The task to execute
1751  * \param task_data The parameter to pass to the task when it executes
1752  *
1753  * \note It is generally better to call
1754  * ast_sip_push_task_wait_servant() if you pass NULL for the
1755  * serializer parameter.
1756  *
1757  * \note The sip_task() return value may need to be distinguished from
1758  * the failure to push the task.
1759  *
1760  * \return sip_task() return value on success.
1761  * \retval -1 Failure to push the task.
1762  */
1763 int ast_sip_push_task_wait_serializer(struct ast_taskprocessor *serializer, int (*sip_task)(void *), void *task_data);
1764 
1765 /*!
1766  * \brief Determine if the current thread is a SIP servant thread
1767  *
1768  * \retval 0 This is not a SIP servant thread
1769  * \retval 1 This is a SIP servant thread
1770  */
1772 
1773 /*!
1774  * \brief Task flags for the res_pjsip scheduler
1775  *
1776  * The default is AST_SIP_SCHED_TASK_FIXED
1777  * | AST_SIP_SCHED_TASK_DATA_NOT_AO2
1778  * | AST_SIP_SCHED_TASK_DATA_NO_CLEANUP
1779  * | AST_SIP_SCHED_TASK_PERIODIC
1780  */
1782  /*!
1783  * The defaults
1784  */
1785  AST_SIP_SCHED_TASK_DEFAULTS = (0 << 0),
1786 
1787  /*!
1788  * Run at a fixed interval.
1789  * Stop scheduling if the callback returns <= 0.
1790  * Any other value is ignored.
1791  */
1792  AST_SIP_SCHED_TASK_FIXED = (0 << 0),
1793  /*!
1794  * Run at a variable interval.
1795  * Stop scheduling if the callback returns <= 0.
1796  * Any other return value is used as the new interval.
1797  */
1798  AST_SIP_SCHED_TASK_VARIABLE = (1 << 0),
1799 
1800  /*!
1801  * Run just once.
1802  * Return values are ignored.
1803  */
1804  AST_SIP_SCHED_TASK_ONESHOT = (1 << 6),
1805 
1806  /*!
1807  * The task data is not an AO2 object.
1808  */
1810  /*!
1811  * The task data is an AO2 object.
1812  * A reference count will be held by the scheduler until
1813  * after the task has run for the final time (if ever).
1814  */
1815  AST_SIP_SCHED_TASK_DATA_AO2 = (1 << 1),
1816 
1817  /*!
1818  * Don't take any cleanup action on the data
1819  */
1821  /*!
1822  * If AST_SIP_SCHED_TASK_DATA_AO2 is set, decrement the reference count
1823  * otherwise call ast_free on it.
1824  */
1825  AST_SIP_SCHED_TASK_DATA_FREE = ( 1 << 3 ),
1826 
1827  /*!
1828  * \brief The task is scheduled at multiples of interval
1829  * \see Interval
1830  */
1831  AST_SIP_SCHED_TASK_PERIODIC = (0 << 4),
1832  /*!
1833  * \brief The next invocation of the task is at last finish + interval
1834  * \see Interval
1835  */
1836  AST_SIP_SCHED_TASK_DELAY = (1 << 4),
1837  /*!
1838  * \brief The scheduled task's events are tracked in the debug log.
1839  * \details
1840  * Schedule events such as scheduling, running, rescheduling, canceling,
1841  * and destroying are logged about the task.
1842  */
1843  AST_SIP_SCHED_TASK_TRACK = (1 << 5),
1844 };
1845 
1846 /*!
1847  * \brief Scheduler task data structure
1848  */
1849 struct ast_sip_sched_task;
1850 
1851 /*!
1852  * \brief Schedule a task to run in the res_pjsip thread pool
1853  * \since 13.9.0
1854  *
1855  * \param serializer The serializer to use. If NULL, don't use a serializer (see note below)
1856  * \param interval The invocation interval in milliseconds (see note below)
1857  * \param sip_task The task to invoke
1858  * \param name An optional name to associate with the task
1859  * \param task_data Optional data to pass to the task
1860  * \param flags One of enum ast_sip_scheduler_task_type
1861  *
1862  * \returns Pointer to \ref ast_sip_sched_task ao2 object which must be dereferenced when done.
1863  *
1864  * \paragraph Serialization
1865  *
1866  * Specifying a serializer guarantees serialized execution but NOT specifying a serializer
1867  * may still result in tasks being effectively serialized if the thread pool is busy.
1868  * The point of the serializer BTW is not to prevent parallel executions of the SAME task.
1869  * That happens automatically (see below). It's to prevent the task from running at the same
1870  * time as other work using the same serializer, whether or not it's being run by the scheduler.
1871  *
1872  * \paragraph Interval
1873  *
1874  * The interval is used to calculate the next time the task should run. There are two models.
1875  *
1876  * \ref AST_SIP_SCHED_TASK_PERIODIC specifies that the invocations of the task occur at the
1877  * specific interval. That is, every \ref "interval" milliseconds, regardless of how long the task
1878  * takes. If the task takes longer than \ref interval, it will be scheduled at the next available
1879  * multiple of \ref interval. For exmaple: If the task has an interval of 60 seconds and the task
1880  * takes 70 seconds, the next invocation will happen at 120 seconds.
1881  *
1882  * \ref AST_SIP_SCHED_TASK_DELAY specifies that the next invocation of the task should start
1883  * at \ref interval milliseconds after the current invocation has finished.
1884  *
1885  */
1887  int interval, ast_sip_task sip_task, const char *name, void *task_data,
1888  enum ast_sip_scheduler_task_flags flags);
1889 
1890 /*!
1891  * \brief Cancels the next invocation of a task
1892  * \since 13.9.0
1893  *
1894  * \param schtd The task structure pointer
1895  * \retval 0 Success
1896  * \retval -1 Failure
1897  * \note Only cancels future invocations not the currently running invocation.
1898  */
1900 
1901 /*!
1902  * \brief Cancels the next invocation of a task by name
1903  * \since 13.9.0
1904  *
1905  * \param name The task name
1906  * \retval 0 Success
1907  * \retval -1 Failure
1908  * \note Only cancels future invocations not the currently running invocation.
1909  */
1910 int ast_sip_sched_task_cancel_by_name(const char *name);
1911 
1912 /*!
1913  * \brief Gets the last start and end times of the task
1914  * \since 13.9.0
1915  *
1916  * \param schtd The task structure pointer
1917  * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
1918  * \param[out] last_start Pointer to a timeval structure to contain the time when last started
1919  * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
1920  * \retval 0 Success
1921  * \retval -1 Failure
1922  * \note Any of the pointers can be NULL if you don't need them.
1923  */
1925  struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end);
1926 
1927 /*!
1928  * \brief Gets the queued, last start, last_end, time left, interval, next run
1929  * \since 16.15.0
1930  * \since 18.1.0
1931  *
1932  * \param schtd The task structure pointer
1933  * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
1934  * \param[out] last_start Pointer to a timeval structure to contain the time when last started
1935  * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
1936  * \param[out] interval Pointer to an int to contain the interval in ms
1937  * \param[out] time_left Pointer to an int to contain the ms left to the next run
1938  * \param[out] last_end Pointer to a timeval structure to contain the next run time
1939  * \retval 0 Success
1940  * \retval -1 Failure
1941  * \note Any of the pointers can be NULL if you don't need them.
1942  */
1944  struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end,
1945  int *interval, int *time_left, struct timeval *next_start);
1946 
1947 /*!
1948  * \brief Gets the last start and end times of the task by name
1949  * \since 13.9.0
1950  *
1951  * \param name The task name
1952  * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
1953  * \param[out] last_start Pointer to a timeval structure to contain the time when last started
1954  * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
1955  * \retval 0 Success
1956  * \retval -1 Failure
1957  * \note Any of the pointers can be NULL if you don't need them.
1958  */
1959 int ast_sip_sched_task_get_times_by_name(const char *name,
1960  struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end);
1961 
1962 /*!
1963  * \brief Gets the queued, last start, last_end, time left, interval, next run by task name
1964  * \since 16.15.0
1965  * \since 18.1.0
1966  *
1967  * \param name The task name
1968  * \param[out] when_queued Pointer to a timeval structure to contain the time when queued
1969  * \param[out] last_start Pointer to a timeval structure to contain the time when last started
1970  * \param[out] last_end Pointer to a timeval structure to contain the time when last ended
1971  * \param[out] interval Pointer to an int to contain the interval in ms
1972  * \param[out] time_left Pointer to an int to contain the ms left to the next run
1973  * \param[out] last_end Pointer to a timeval structure to contain the next run time
1974  * \retval 0 Success
1975  * \retval -1 Failure
1976  * \note Any of the pointers can be NULL if you don't need them.
1977  */
1978 int ast_sip_sched_task_get_times_by_name2(const char *name,
1979  struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end,
1980  int *interval, int *time_left, struct timeval *next_start);
1981 
1982 /*!
1983  * \brief Gets the number of milliseconds until the next invocation
1984  * \since 13.9.0
1985  *
1986  * \param schtd The task structure pointer
1987  * \return The number of milliseconds until the next invocation or -1 if the task isn't scheduled
1988  */
1990 
1991 /*!
1992  * \brief Gets the number of milliseconds until the next invocation
1993  * \since 13.9.0
1994  *
1995  * \param name The task name
1996  * \return The number of milliseconds until the next invocation or -1 if the task isn't scheduled
1997  */
1998 int ast_sip_sched_task_get_next_run_by_name(const char *name);
1999 
2000 /*!
2001  * \brief Checks if the task is currently running
2002  * \since 13.9.0
2003  *
2004  * \param schtd The task structure pointer
2005  * \retval 0 not running
2006  * \retval 1 running
2007  */
2009 
2010 /*!
2011  * \brief Checks if the task is currently running
2012  * \since 13.9.0
2013  *
2014  * \param name The task name
2015  * \retval 0 not running or not found
2016  * \retval 1 running
2017  */
2018 int ast_sip_sched_is_task_running_by_name(const char *name);
2019 
2020 /*!
2021  * \brief Gets the task name
2022  * \since 13.9.0
2023  *
2024  * \param schtd The task structure pointer
2025  * \retval 0 success
2026  * \retval 1 failure
2027  */
2028 int ast_sip_sched_task_get_name(struct ast_sip_sched_task *schtd, char *name, size_t maxlen);
2030 /*!
2031  * @}
2032  */
2034 /*!
2035  * \brief SIP body description
2036  *
2037  * This contains a type and subtype that will be added as
2038  * the "Content-Type" for the message as well as the body
2039  * text.
2040  */
2041 struct ast_sip_body {
2042  /*! Type of the body, such as "application" */
2043  const char *type;
2044  /*! Subtype of the body, such as "sdp" */
2045  const char *subtype;
2046  /*! The text to go in the body */
2047  const char *body_text;
2048 };
2049 
2050 /*!
2051  * \brief General purpose method for creating a UAC dialog with an endpoint
2052  *
2053  * \param endpoint A pointer to the endpoint
2054  * \param aor_name Optional name of the AOR to target, may even be an explicit SIP URI
2055  * \param request_user Optional user to place into the target URI
2056  *
2057  * \retval non-NULL success
2058  * \retval NULL failure
2059  */
2060 pjsip_dialog *ast_sip_create_dialog_uac(const struct ast_sip_endpoint *endpoint, const char *aor_name, const char *request_user);
2061 
2062 /*!
2063  * \brief General purpose method for creating a UAS dialog with an endpoint
2064  *
2065  * \deprecated This function is unsafe (due to the returned object not being locked nor
2066  * having its reference incremented) and should no longer be used. Instead
2067  * use ast_sip_create_dialog_uas_locked so a properly locked and referenced
2068  * object is returned.
2069  *
2070  * \param endpoint A pointer to the endpoint
2071  * \param rdata The request that is starting the dialog
2072  * \param[out] status On failure, the reason for failure in creating the dialog
2073  */
2074 pjsip_dialog *ast_sip_create_dialog_uas(const struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pj_status_t *status);
2075 
2076 /*!
2077  * \brief General purpose method for creating a UAS dialog with an endpoint
2078  *
2079  * This function creates and returns a locked, and referenced counted pjsip
2080  * dialog object. The caller is thus responsible for freeing the allocated
2081  * memory, decrementing the reference, and releasing the lock when done with
2082  * the returned object.
2083  *
2084  * \note The safest way to unlock the object, and decrement its reference is by
2085  * calling pjsip_dlg_dec_lock. Alternatively, pjsip_dlg_dec_session can be
2086  * used to decrement the reference only.
2087  *
2088  * The dialog is returned locked and with a reference in order to ensure that the
2089  * dialog object, and any of its associated objects (e.g. transaction) are not
2090  * untimely destroyed. For instance, that could happen when a transport error
2091  * occurs.
2092  *
2093  * As long as the caller maintains a reference to the dialog there should be no
2094  * worry that it might unknowningly be destroyed. However, once the caller unlocks
2095  * the dialog there is a danger that some of the dialog's internal objects could
2096  * be lost and/or compromised. For example, when the aforementioned transport error
2097  * occurs the dialog's associated transaction gets destroyed (see pjsip_dlg_on_tsx_state
2098  * in sip_dialog.c, and mod_inv_on_tsx_state in sip_inv.c).
2099  *
2100  * In this case and before using the dialog again the caller should re-lock the
2101  * dialog, check to make sure the dialog is still established, and the transaction
2102  * still exists and has not been destroyed.
2103  *
2104  * \param endpoint A pointer to the endpoint
2105  * \param rdata The request that is starting the dialog
2106  * \param[out] status On failure, the reason for failure in creating the dialog
2107  *
2108  * \retval A locked, and reference counted pjsip_dialog object.
2109  * \retval NULL on failure
2110  */
2111 pjsip_dialog *ast_sip_create_dialog_uas_locked(const struct ast_sip_endpoint *endpoint,
2112  pjsip_rx_data *rdata, pj_status_t *status);
2113 
2114 /*!
2115  * \brief General purpose method for creating an rdata structure using specific information
2116  * \since 13.15.0
2117  *
2118  * \param rdata[out] The rdata structure that will be populated
2119  * \param packet A SIP message
2120  * \param src_name The source IP address of the message
2121  * \param src_port The source port of the message
2122  * \param transport_type The type of transport the message was received on
2123  * \param local_name The local IP address the message was received on
2124  * \param local_port The local port the message was received on
2125  * \param contact_uri The contact URI of the message
2126  *
2127  * \retval 0 success
2128  * \retval -1 failure
2129  */
2130 int ast_sip_create_rdata_with_contact(pjsip_rx_data *rdata, char *packet,
2131  const char *src_name, int src_port, char *transport_type, const char *local_name,
2132  int local_port, const char *contact_uri);
2133 
2134 /*!
2135  * \brief General purpose method for creating an rdata structure using specific information
2136  *
2137  * \param rdata[out] The rdata structure that will be populated
2138  * \param packet A SIP message
2139  * \param src_name The source IP address of the message
2140  * \param src_port The source port of the message
2141  * \param transport_type The type of transport the message was received on
2142  * \param local_name The local IP address the message was received on
2143  * \param local_port The local port the message was received on
2144  *
2145  * \retval 0 success
2146  * \retval -1 failure
2147  */
2148 int ast_sip_create_rdata(pjsip_rx_data *rdata, char *packet, const char *src_name,
2149  int src_port, char *transport_type, const char *local_name, int local_port);
2150 
2151 /*!
2152  * \brief General purpose method for creating a SIP request
2153  *
2154  * Its typical use would be to create one-off requests such as an out of dialog
2155  * SIP MESSAGE.
2156  *
2157  * The request can either be in- or out-of-dialog. If in-dialog, the
2158  * dlg parameter MUST be present. If out-of-dialog the endpoint parameter
2159  * MUST be present. If both are present, then we will assume that the message
2160  * is to be sent in-dialog.
2161  *
2162  * The uri parameter can be specified if the request should be sent to an explicit
2163  * URI rather than one configured on the endpoint.
2164  *
2165  * \param method The method of the SIP request to send
2166  * \param dlg Optional. If specified, the dialog on which to request the message.
2167  * \param endpoint Optional. If specified, the request will be created out-of-dialog to the endpoint.
2168  * \param uri Optional. If specified, the request will be sent to this URI rather
2169  * than one configured for the endpoint.
2170  * \param contact The contact with which this request is associated for out-of-dialog requests.
2171  * \param[out] tdata The newly-created request
2172  *
2173  * The provided contact is attached to tdata with its reference bumped, but will
2174  * not survive for the entire lifetime of tdata since the contact is cleaned up
2175  * when all supplements have completed execution.
2176  *
2177  * \retval 0 Success
2178  * \retval -1 Failure
2179  */
2180 int ast_sip_create_request(const char *method, struct pjsip_dialog *dlg,
2181  struct ast_sip_endpoint *endpoint, const char *uri,
2182  struct ast_sip_contact *contact, pjsip_tx_data **tdata);
2183 
2184 /*!
2185  * \brief General purpose method for sending a SIP request
2186  *
2187  * This is a companion function for \ref ast_sip_create_request. The request
2188  * created there can be passed to this function, though any request may be
2189  * passed in.
2190  *
2191  * This will automatically set up handling outbound authentication challenges if
2192  * they arrive.
2193  *
2194  * \param tdata The request to send
2195  * \param dlg Optional. The dialog in which the request is sent. Otherwise it is out-of-dialog.
2196  * \param endpoint Optional. If specified, the out-of-dialog request is sent to the endpoint.
2197  * \param token Data to be passed to the callback upon receipt of out-of-dialog response.
2198  * \param callback Callback to be called upon receipt of out-of-dialog response.
2199  *
2200  * \retval 0 Success
2201  * \retval -1 Failure (out-of-dialog callback will not be called.)
2202  */
2203 int ast_sip_send_request(pjsip_tx_data *tdata, struct pjsip_dialog *dlg,
2204  struct ast_sip_endpoint *endpoint, void *token,
2205  void (*callback)(void *token, pjsip_event *e));
2206 
2207 /*!
2208  * \brief General purpose method for sending an Out-Of-Dialog SIP request
2209  *
2210  * This is a companion function for \ref ast_sip_create_request. The request
2211  * created there can be passed to this function, though any request may be
2212  * passed in.
2213  *
2214  * This will automatically set up handling outbound authentication challenges if
2215  * they arrive.
2216  *
2217  * \param tdata The request to send
2218  * \param endpoint Optional. If specified, the out-of-dialog request is sent to the endpoint.
2219  * \param timeout. If non-zero, after the timeout the transaction will be terminated
2220  * and the callback will be called with the PJSIP_EVENT_TIMER type.
2221  * \param token Data to be passed to the callback upon receipt of out-of-dialog response.
2222  * \param callback Callback to be called upon receipt of out-of-dialog response.
2223  *
2224  * \retval 0 Success
2225  * \retval -1 Failure (out-of-dialog callback will not be called.)
2226  *
2227  * \note Timeout processing:
2228  * There are 2 timers associated with this request, PJSIP timer_b which is
2229  * set globally in the "system" section of pjsip.conf, and the timeout specified
2230  * on this call. The timer that expires first (before normal completion) will
2231  * cause the callback to be run with e->body.tsx_state.type = PJSIP_EVENT_TIMER.
2232  * The timer that expires second is simply ignored and the callback is not run again.
2233  */
2234 int ast_sip_send_out_of_dialog_request(pjsip_tx_data *tdata,
2235  struct ast_sip_endpoint *endpoint, int timeout, void *token,
2236  void (*callback)(void *token, pjsip_event *e));
2237 
2238 /*!
2239  * \brief General purpose method for creating a SIP response
2240  *
2241  * Its typical use would be to create responses for out of dialog
2242  * requests.
2243  *
2244  * \param rdata The rdata from the incoming request.
2245  * \param st_code The response code to transmit.
2246  * \param contact The contact with which this request is associated.
2247  * \param[out] tdata The newly-created response
2248  *
2249  * The provided contact is attached to tdata with its reference bumped, but will
2250  * not survive for the entire lifetime of tdata since the contact is cleaned up
2251  * when all supplements have completed execution.
2252  *
2253  * \retval 0 Success
2254  * \retval -1 Failure
2255  */
2256 int ast_sip_create_response(const pjsip_rx_data *rdata, int st_code,
2257  struct ast_sip_contact *contact, pjsip_tx_data **p_tdata);
2258 
2259 /*!
2260  * \brief Send a response to an out of dialog request
2261  *
2262  * Use this function sparingly, since this does not create a transaction
2263  * within PJSIP. This means that if the request is retransmitted, it is
2264  * your responsibility to detect this and not process the same request
2265  * twice, and to send the same response for each retransmission.
2266  *
2267  * \param res_addr The response address for this response
2268  * \param tdata The response to send
2269  * \param endpoint The ast_sip_endpoint associated with this response
2270  *
2271  * \retval 0 Success
2272  * \retval -1 Failure
2273  */
2274 int ast_sip_send_response(pjsip_response_addr *res_addr, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint);
2275 
2276 /*!
2277  * \brief Send a stateful response to an out of dialog request
2278  *
2279  * This creates a transaction within PJSIP, meaning that if the request
2280  * that we are responding to is retransmitted, we will not attempt to
2281  * re-handle the request.
2282  *
2283  * \param rdata The request that is being responded to
2284  * \param tdata The response to send
2285  * \param endpoint The ast_sip_endpoint associated with this response
2286  *
2287  * \since 13.4.0
2288  *
2289  * \retval 0 Success
2290  * \retval -1 Failure
2291  */
2292 int ast_sip_send_stateful_response(pjsip_rx_data *rdata, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint);
2293 
2294 /*!
2295  * \brief Determine if an incoming request requires authentication
2296  *
2297  * This calls into the registered authenticator's requires_authentication callback
2298  * in order to determine if the request requires authentication.
2299  *
2300  * If there is no registered authenticator, then authentication will be assumed
2301  * not to be required.
2302  *
2303  * \param endpoint The endpoint from which the request originates
2304  * \param rdata The incoming SIP request
2305  * \retval non-zero The request requires authentication
2306  * \retval 0 The request does not require authentication
2307  */
2308 int ast_sip_requires_authentication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2309 
2310 /*!
2311  * \brief Method to determine authentication status of an incoming request
2312  *
2313  * This will call into a registered authenticator. The registered authenticator will
2314  * do what is necessary to determine whether the incoming request passes authentication.
2315  * A tentative response is passed into this function so that if, say, a digest authentication
2316  * challenge should be sent in the ensuing response, it can be added to the response.
2317  *
2318  * \param endpoint The endpoint from the request was sent
2319  * \param rdata The request to potentially authenticate
2320  * \param tdata Tentative response to the request
2321  * \return The result of checking authentication.
2322  */
2324  pjsip_rx_data *rdata, pjsip_tx_data *tdata);
2325 
2326 /*!
2327  * \brief Create a response to an authentication challenge
2328  *
2329  * This will call into an outbound authenticator's create_request_with_auth callback
2330  * to create a new request with authentication credentials. See the create_request_with_auth
2331  * callback in the \ref ast_sip_outbound_authenticator structure for details about
2332  * the parameters and return values.
2333  */
2334 int ast_sip_create_request_with_auth(const struct ast_sip_auth_vector *auths, pjsip_rx_data *challenge,
2335  pjsip_tx_data *tdata, pjsip_tx_data **new_request);
2336 
2337 /*!
2338  * \brief Determine the endpoint that has sent a SIP message
2339  *
2340  * This will call into each of the registered endpoint identifiers'
2341  * identify_endpoint() callbacks until one returns a non-NULL endpoint.
2342  * This will return an ao2 object. Its reference count will need to be
2343  * decremented when completed using the endpoint.
2344  *
2345  * \param rdata The inbound SIP message to use when identifying the endpoint.
2346  * \retval NULL No matching endpoint
2347  * \retval non-NULL The matching endpoint
2348  */
2349 struct ast_sip_endpoint *ast_sip_identify_endpoint(pjsip_rx_data *rdata);
2350 
2351 /*!
2352  * \brief Get a specific header value from rdata
2353  *
2354  * \note The returned value does not need to be freed since it's from the rdata pool
2355  *
2356  * \param rdata The rdata
2357  * \param str The header to find
2358  *
2359  * \retval NULL on failure
2360  * \retval The header value on success
2361  */
2362 char *ast_sip_rdata_get_header_value(pjsip_rx_data *rdata, const pj_str_t str);
2363 
2364 /*!
2365  * \brief Set the outbound proxy for an outbound SIP message
2366  *
2367  * \param tdata The message to set the outbound proxy on
2368  * \param proxy SIP uri of the proxy
2369  * \retval 0 Success
2370  * \retval -1 Failure
2371  */
2372 int ast_sip_set_outbound_proxy(pjsip_tx_data *tdata, const char *proxy);
2373 
2374 /*!
2375  * \brief Add a header to an outbound SIP message
2376  *
2377  * \param tdata The message to add the header to
2378  * \param name The header name
2379  * \param value The header value
2380  * \retval 0 Success
2381  * \retval -1 Failure
2382  */
2383 int ast_sip_add_header(pjsip_tx_data *tdata, const char *name, const char *value);
2384 
2385 /*!
2386  * \brief Add a body to an outbound SIP message
2387  *
2388  * If this is called multiple times, the latest body will replace the current
2389  * body.
2390  *
2391  * \param tdata The message to add the body to
2392  * \param body The message body to add
2393  * \retval 0 Success
2394  * \retval -1 Failure
2395  */
2396 int ast_sip_add_body(pjsip_tx_data *tdata, const struct ast_sip_body *body);
2397 
2398 /*!
2399  * \brief Add a multipart body to an outbound SIP message
2400  *
2401  * This will treat each part of the input vector as part of a multipart body and
2402  * add each part to the SIP message.
2403  *
2404  * \param tdata The message to add the body to
2405  * \param bodies The parts of the body to add
2406  * \retval 0 Success
2407  * \retval -1 Failure
2408  */
2409 int ast_sip_add_body_multipart(pjsip_tx_data *tdata, const struct ast_sip_body *bodies[], int num_bodies);
2410 
2411 /*!
2412  * \brief Append body data to a SIP message
2413  *
2414  * This acts mostly the same as ast_sip_add_body, except that rather than replacing
2415  * a body if it currently exists, it appends data to an existing body.
2416  *
2417  * \param tdata The message to append the body to
2418  * \param body The string to append to the end of the current body
2419  * \retval 0 Success
2420  * \retval -1 Failure
2421  */
2422 int ast_sip_append_body(pjsip_tx_data *tdata, const char *body_text);
2423 
2424 /*!
2425  * \brief Copy a pj_str_t into a standard character buffer.
2426  *
2427  * pj_str_t is not NULL-terminated. Any place that expects a NULL-
2428  * terminated string needs to have the pj_str_t copied into a separate
2429  * buffer.
2430  *
2431  * This method copies the pj_str_t contents into the destination buffer
2432  * and NULL-terminates the buffer.
2433  *
2434  * \param dest The destination buffer
2435  * \param src The pj_str_t to copy
2436  * \param size The size of the destination buffer.
2437  */
2438 void ast_copy_pj_str(char *dest, const pj_str_t *src, size_t size);
2439 
2440 /*!
2441  * \brief Create and copy a pj_str_t into a standard character buffer.
2442  *
2443  * pj_str_t is not NULL-terminated. Any place that expects a NULL-
2444  * terminated string needs to have the pj_str_t copied into a separate
2445  * buffer.
2446  *
2447  * Copies the pj_str_t contents into a newly allocated buffer pointed to
2448  * by dest. NULL-terminates the buffer.
2449  *
2450  * \note Caller is responsible for freeing the allocated memory.
2451  *
2452  * \param dest [out] The destination buffer
2453  * \param src The pj_str_t to copy
2454  * \retval Number of characters copied or negative value on error
2455  */
2456 int ast_copy_pj_str2(char **dest, const pj_str_t *src);
2457 
2458 /*!
2459  * \brief Get the looked-up endpoint on an out-of dialog request or response
2460  *
2461  * The function may ONLY be called on out-of-dialog requests or responses. For
2462  * in-dialog requests and responses, it is required that the user of the dialog
2463  * has the looked-up endpoint stored locally.
2464  *
2465  * This function should never return NULL if the message is out-of-dialog. It will
2466  * always return NULL if the message is in-dialog.
2467  *
2468  * This function will increase the reference count of the returned endpoint by one.
2469  * Release your reference using the ao2_ref function when finished.
2470  *
2471  * \param rdata Out-of-dialog request or response
2472  * \return The looked up endpoint
2473  */
2474 struct ast_sip_endpoint *ast_pjsip_rdata_get_endpoint(pjsip_rx_data *rdata);
2475 
2476 /*!
2477  * \brief Add 'user=phone' parameter to URI if enabled and user is a phone number.
2478  *
2479  * \param endpoint The endpoint to use for configuration
2480  * \param pool The memory pool to allocate the parameter from
2481  * \param uri The URI to check for user and to add parameter to
2482  */
2483 void ast_sip_add_usereqphone(const struct ast_sip_endpoint *endpoint, pj_pool_t *pool, pjsip_uri *uri);
2484 
2485 /*!
2486  * \brief Retrieve any endpoints available to sorcery.
2487  *
2488  * \retval Endpoints available to sorcery, NULL if no endpoints found.
2489  */
2490 struct ao2_container *ast_sip_get_endpoints(void);
2491 
2492 /*!
2493  * \brief Retrieve the default outbound endpoint.
2494  *
2495  * \retval The default outbound endpoint, NULL if not found.
2496  */
2498 
2499 /*!
2500  * \brief Retrieve relevant SIP auth structures from sorcery
2501  *
2502  * \param auths Vector of sorcery IDs of auth credentials to retrieve
2503  * \param[out] out The retrieved auths are stored here
2504  */
2505 int ast_sip_retrieve_auths(const struct ast_sip_auth_vector *auths, struct ast_sip_auth **out);
2506 
2507 /*!
2508  * \brief Clean up retrieved auth structures from memory
2509  *
2510  * Call this function once you have completed operating on auths
2511  * retrieved from \ref ast_sip_retrieve_auths
2512  *
2513  * \param auths An array of auth object pointers to clean up
2514  * \param num_auths The number of auths in the array
2515  */
2516 void ast_sip_cleanup_auths(struct ast_sip_auth *auths[], size_t num_auths);
2517 
2518 /*!
2519  * \brief Retrieve relevant SIP auth structures from sorcery as a vector
2520  *
2521  * \param auth_ids Vector of sorcery IDs of auth credentials to retrieve
2522  * \param[out] auth_objects A pointer ast_sip_auth_objects_vector to hold the objects
2523  *
2524  * \retval 0 Success
2525  * \retval -1 Number of auth objects found is less than the number of names supplied.
2526  *
2527  * \WARNING The number of auth objects retrieved may be less than the
2528  * number of auth ids supplied if auth objects couldn't be found for
2529  * some of them.
2530  *
2531  * \NOTE Since the ref count on all auith objects returned has been
2532  * bumped, you must call ast_sip_cleanup_auth_objects_vector() to decrement
2533  * the ref count on all of the auth objects in the vector,
2534  * then call AST_VECTOR_FREE() on the vector itself.
2535  *
2536  */
2537 AST_VECTOR(ast_sip_auth_objects_vector, struct ast_sip_auth *);
2539  struct ast_sip_auth_objects_vector *auth_objects);
2540 
2541 /*!
2542  * \brief Clean up retrieved auth objects in vector
2543  *
2544  * Call this function once you have completed operating on auths
2545  * retrieved from \ref ast_sip_retrieve_auths_vector. All
2546  * auth objects will have their reference counts decremented and
2547  * the vector size will be reset to 0. You must still call
2548  * AST_VECTOR_FREE() on the vector itself.
2549  *
2550  * \param auth_objects A vector of auth structures to clean up
2551  */
2552 #define ast_sip_cleanup_auth_objects_vector(auth_objects) AST_VECTOR_RESET(auth_objects, ao2_cleanup)
2553 
2554 /*!
2555  * \brief Checks if the given content type matches type/subtype.
2556  *
2557  * Compares the pjsip_media_type with the passed type and subtype and
2558  * returns the result of that comparison. The media type parameters are
2559  * ignored.
2560  *
2561  * \param content_type The pjsip_media_type structure to compare
2562  * \param type The media type to compare
2563  * \param subtype The media subtype to compare
2564  * \retval 0 No match
2565  * \retval -1 Match
2566  */
2567 int ast_sip_is_content_type(pjsip_media_type *content_type, char *type, char *subtype);
2568 
2569 /*!
2570  * \brief Send a security event notification for when an invalid endpoint is requested
2571  *
2572  * \param name Name of the endpoint requested
2573  * \param rdata Received message
2574  */
2575 void ast_sip_report_invalid_endpoint(const char *name, pjsip_rx_data *rdata);
2576 
2577 /*!
2578  * \brief Send a security event notification for when an ACL check fails
2579  *
2580  * \param endpoint Pointer to the endpoint in use
2581  * \param rdata Received message
2582  * \param name Name of the ACL
2583  */
2584 void ast_sip_report_failed_acl(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, const char *name);
2585 
2586 /*!
2587  * \brief Send a security event notification for when a challenge response has failed
2588  *
2589  * \param endpoint Pointer to the endpoint in use
2590  * \param rdata Received message
2591  */
2592 void ast_sip_report_auth_failed_challenge_response(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2593 
2594 /*!
2595  * \brief Send a security event notification for when authentication succeeds
2596  *
2597  * \param endpoint Pointer to the endpoint in use
2598  * \param rdata Received message
2599  */
2600 void ast_sip_report_auth_success(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2601 
2602 /*!
2603  * \brief Send a security event notification for when an authentication challenge is sent
2604  *
2605  * \param endpoint Pointer to the endpoint in use
2606  * \param rdata Received message
2607  * \param tdata Sent message
2608  */
2609 void ast_sip_report_auth_challenge_sent(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pjsip_tx_data *tdata);
2610 
2611 /*!
2612  * \brief Send a security event notification for when a request is not supported
2613  *
2614  * \param endpoint Pointer to the endpoint in use
2615  * \param rdata Received message
2616  * \param req_type the type of request
2617  */
2618 void ast_sip_report_req_no_support(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata,
2619  const char* req_type);
2620 
2621 /*!
2622  * \brief Send a security event notification for when a memory limit is hit.
2623  *
2624  * \param endpoint Pointer to the endpoint in use
2625  * \param rdata Received message
2626  */
2627 void ast_sip_report_mem_limit(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
2628 
2629 int ast_sip_add_global_request_header(const char *name, const char *value, int replace);
2630 int ast_sip_add_global_response_header(const char *name, const char *value, int replace);
2631 
2632 /*!
2633  * \brief Retrieves the value associated with the given key.
2634  *
2635  * \param ht the hash table/dictionary to search
2636  * \param key the key to find
2637  *
2638  * \retval the value associated with the key, NULL otherwise.
2639  */
2640 void *ast_sip_dict_get(void *ht, const char *key);
2641 
2642 /*!
2643  * \brief Using the dictionary stored in mod_data array at a given id,
2644  * retrieve the value associated with the given key.
2645  *
2646  * \param mod_data a module data array
2647  * \param id the mod_data array index
2648  * \param key the key to find
2649  *
2650  * \retval the value associated with the key, NULL otherwise.
2651  */
2652 #define ast_sip_mod_data_get(mod_data, id, key) \
2653  ast_sip_dict_get(mod_data[id], key)
2654 
2655 /*!
2656  * \brief Set the value for the given key.
2657  *
2658  * Note - if the hash table does not exist one is created first, the key/value
2659  * pair is set, and the hash table returned.
2660  *
2661  * \param pool the pool to allocate memory in
2662  * \param ht the hash table/dictionary in which to store the key/value pair
2663  * \param key the key to associate a value with
2664  * \param val the value to associate with a key
2665  *
2666  * \retval the given, or newly created, hash table.
2667  */
2668 void *ast_sip_dict_set(pj_pool_t* pool, void *ht,
2669  const char *key, void *val);
2671 /*!
2672  * \brief Utilizing a mod_data array for a given id, set the value
2673  * associated with the given key.
2674  *
2675  * For a given structure's mod_data array set the element indexed by id to
2676  * be a dictionary containing the key/val pair.
2677  *
2678  * \param pool a memory allocation pool
2679  * \param mod_data a module data array
2680  * \param id the mod_data array index
2681  * \param key the key to find
2682  * \param val the value to associate with a key
2683  */
2684 #define ast_sip_mod_data_set(pool, mod_data, id, key, val) \
2685  mod_data[id] = ast_sip_dict_set(pool, mod_data[id], key, val)
2686 
2687 /*!
2688  * \brief For every contact on an AOR call the given 'on_contact' handler.
2689  *
2690  * \param aor the aor containing a list of contacts to iterate
2691  * \param on_contact callback on each contact on an AOR. The object
2692  * received by the callback will be a ast_sip_contact_wrapper structure.
2693  * \param arg user data passed to handler
2694  * \retval 0 Success, non-zero on failure
2695  */
2696 int ast_sip_for_each_contact(const struct ast_sip_aor *aor,
2697  ao2_callback_fn on_contact, void *arg);
2698 
2699 /*!
2700  * \brief Handler used to convert a contact to a string.
2701  *
2702  * \param object the ast_sip_aor_contact_pair containing a list of contacts to iterate and the contact
2703  * \param arg user data passed to handler
2704  * \param flags
2705  * \retval 0 Success, non-zero on failure
2706  */
2707 int ast_sip_contact_to_str(void *object, void *arg, int flags);
2708 
2709 /*!
2710  * \brief For every aor in the comma separated aors string call the
2711  * given 'on_aor' handler.
2712  *
2713  * \param aors a comma separated list of aors
2714  * \param on_aor callback for each aor
2715  * \param arg user data passed to handler
2716  * \retval 0 Success, non-zero on failure
2717  */
2718 int ast_sip_for_each_aor(const char *aors, ao2_callback_fn on_aor, void *arg);
2719 
2720 /*!
2721  * \brief For every auth in the array call the given 'on_auth' handler.
2722  *
2723  * \param array an array of auths
2724  * \param on_auth callback for each auth
2725  * \param arg user data passed to handler
2726  * \retval 0 Success, non-zero on failure
2727  */
2729  ao2_callback_fn on_auth, void *arg);
2730 
2731 /*!
2732  * \brief Converts the given auth type to a string
2733  *
2734  * \param type the auth type to convert
2735  * \retval a string representative of the auth type
2736  */
2738 
2739 /*!
2740  * \brief Converts an auths array to a string of comma separated values
2741  *
2742  * \param auths an auth array
2743  * \param buf the string buffer to write the object data
2744  * \retval 0 Success, non-zero on failure
2745  */
2746 int ast_sip_auths_to_str(const struct ast_sip_auth_vector *auths, char **buf);
2748 /*!
2749  * \brief AMI variable container
2750  */
2751 struct ast_sip_ami {
2752  /*! Manager session */
2753  struct mansession *s;
2754  /*! Manager message */
2755  const struct message *m;
2756  /*! Manager Action ID */
2757  const char *action_id;
2758  /*! user specified argument data */
2759  void *arg;
2760  /*! count of objects */
2761  int count;
2762 };
2764 /*!
2765  * \brief Creates a string to store AMI event data in.
2766  *
2767  * \param event the event to set
2768  * \param ami AMI session and message container
2769  * \retval an initialized ast_str or NULL on error.
2770  */
2771 struct ast_str *ast_sip_create_ami_event(const char *event,
2772  struct ast_sip_ami *ami);
2773 
2774 /*!
2775  * \brief An entity responsible formatting endpoint information.
2776  */
2778  /*!
2779  * \brief Callback used to format endpoint information over AMI.
2780  */
2781  int (*format_ami)(const struct ast_sip_endpoint *endpoint,
2782  struct ast_sip_ami *ami);
2784 };
2785 
2786 /*!
2787  * \brief Register an endpoint formatter.
2788  *
2789  * \param obj the formatter to register
2790  */
2792 
2793 /*!
2794  * \brief Unregister an endpoint formatter.
2795  *
2796  * \param obj the formatter to unregister
2797  */
2799 
2800 /*!
2801  * \brief Converts a sorcery object to a string of object properties.
2802  *
2803  * \param obj the sorcery object to convert
2804  * \param str the string buffer to write the object data
2805  * \retval 0 Success, non-zero on failure
2806  */
2807 int ast_sip_sorcery_object_to_ami(const void *obj, struct ast_str **buf);
2808 
2809 /*!
2810  * \brief Formats the endpoint and sends over AMI.
2811  *
2812  * \param endpoint the endpoint to format and send
2813  * \param endpoint ami AMI variable container
2814  * \param count the number of formatters operated on
2815  * \retval 0 Success, otherwise non-zero on error
2816  */
2817 int ast_sip_format_endpoint_ami(struct ast_sip_endpoint *endpoint,
2818  struct ast_sip_ami *ami, int *count);
2819 
2820 /*!
2821  * \brief Formats the contact and sends over AMI.
2822  *
2823  * \param obj a pointer an ast_sip_contact_wrapper structure
2824  * \param arg a pointer to an ast_sip_ami structure
2825  * \param flags ignored
2826  * \retval 0 Success, otherwise non-zero on error
2827  */
2828 int ast_sip_format_contact_ami(void *obj, void *arg, int flags);
2829 
2830 /*!
2831  * \brief Format auth details for AMI.
2832  *
2833  * \param auths an auth array
2834  * \param ami ami variable container
2835  * \retval 0 Success, non-zero on failure
2836  */
2837 int ast_sip_format_auths_ami(const struct ast_sip_auth_vector *auths,
2838  struct ast_sip_ami *ami);
2839 
2840 /*!
2841  * \brief Retrieve the endpoint snapshot for an endpoint
2842  *
2843  * \param endpoint The endpoint whose snapshot is to be retreieved.
2844  * \retval The endpoint snapshot
2845  */
2847  const struct ast_sip_endpoint *endpoint);
2848 
2849 /*!
2850  * \brief Retrieve the device state for an endpoint.
2851  *
2852  * \param endpoint The endpoint whose state is to be retrieved.
2853  * \retval The device state.
2854  */
2855 const char *ast_sip_get_device_state(const struct ast_sip_endpoint *endpoint);
2856 
2857 /*!
2858  * \brief For every channel snapshot on an endpoint snapshot call the given
2859  * 'on_channel_snapshot' handler.
2860  *
2861  * \param endpoint_snapshot snapshot of an endpoint
2862  * \param on_channel_snapshot callback for each channel snapshot
2863  * \param arg user data passed to handler
2864  * \retval 0 Success, non-zero on failure
2865  */
2866 int ast_sip_for_each_channel_snapshot(const struct ast_endpoint_snapshot *endpoint_snapshot,
2867  ao2_callback_fn on_channel_snapshot,
2868  void *arg);
2870 /*!
2871  * \brief For every channel snapshot on an endpoint all the given
2872  * 'on_channel_snapshot' handler.
2873  *
2874  * \param endpoint endpoint
2875  * \param on_channel_snapshot callback for each channel snapshot
2876  * \param arg user data passed to handler
2877  * \retval 0 Success, non-zero on failure
2878  */
2879 int ast_sip_for_each_channel(const struct ast_sip_endpoint *endpoint,
2880  ao2_callback_fn on_channel_snapshot,
2881  void *arg);
2882 
2884  /*! Top priority. Supplements with this priority are those that need to run before any others */
2886  /*! Channel creation priority.
2887  * chan_pjsip creates a channel at this priority. If your supplement depends on being run before
2888  * or after channel creation, then set your priority to be lower or higher than this value.
2889  */
2891  /*! Lowest priority. Supplements with this priority should be run after all other supplements */
2893 };
2894 
2895 /*!
2896  * \brief A supplement to SIP message processing
2897  *
2898  * These can be registered by any module in order to add
2899  * processing to incoming and outgoing SIP out of dialog
2900  * requests and responses
2901  */
2902 struct ast_sip_supplement {
2903  /*! Method on which to call the callbacks. If NULL, call on all methods */
2904  const char *method;
2905  /*! Priority for this supplement. Lower numbers are visited before higher numbers */
2907  /*!
2908  * \brief Called on incoming SIP request
2909  * This method can indicate a failure in processing in its return. If there
2910  * is a failure, it is required that this method sends a response to the request.
2911  * This method is always called from a SIP servant thread.
2912  *
2913  * \note
2914  * The following PJSIP methods will not work properly:
2915  * pjsip_rdata_get_dlg()
2916  * pjsip_rdata_get_tsx()
2917  * The reason is that the rdata passed into this function is a cloned rdata structure,
2918  * and its module data is not copied during the cloning operation.
2919  * If you need to get the dialog, you can get it via session->inv_session->dlg.
2920  *
2921  * \note
2922  * There is no guarantee that a channel will be present on the session when this is called.
2923  */
2924  int (*incoming_request)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
2925  /*!
2926  * \brief Called on an incoming SIP response
2927  * This method is always called from a SIP servant thread.
2928  *
2929  * \note
2930  * The following PJSIP methods will not work properly:
2931  * pjsip_rdata_get_dlg()
2932  * pjsip_rdata_get_tsx()
2933  * The reason is that the rdata passed into this function is a cloned rdata structure,
2934  * and its module data is not copied during the cloning operation.
2935  * If you need to get the dialog, you can get it via session->inv_session->dlg.
2936  *
2937  * \note
2938  * There is no guarantee that a channel will be present on the session when this is called.
2939  */
2940  void (*incoming_response)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
2941  /*!
2942  * \brief Called on an outgoing SIP request
2943  * This method is always called from a SIP servant thread.
2944  */
2945  void (*outgoing_request)(struct ast_sip_endpoint *endpoint, struct ast_sip_contact *contact, struct pjsip_tx_data *tdata);
2946  /*!
2947  * \brief Called on an outgoing SIP response
2948  * This method is always called from a SIP servant thread.
2949  */
2950  void (*outgoing_response)(struct ast_sip_endpoint *endpoint, struct ast_sip_contact *contact, struct pjsip_tx_data *tdata);
2951  /*! Next item in the list */
2953 };
2954 
2955 /*!
2956  * \brief Register a supplement to SIP out of dialog processing
2957  *
2958  * This allows for someone to insert themselves in the processing of out
2959  * of dialog SIP requests and responses. This, for example could allow for
2960  * a module to set channel data based on headers in an incoming message.
2961  * Similarly, a module could reject an incoming request if desired.
2962  *
2963  * \param supplement The supplement to register
2964  * \retval 0 Success
2965  * \retval -1 Failure
2966  */
2967 void ast_sip_register_supplement(struct ast_sip_supplement *supplement);
2968 
2969 /*!
2970  * \brief Unregister a an supplement to SIP out of dialog processing
2971  *
2972  * \param supplement The supplement to unregister
2973  */
2974 void ast_sip_unregister_supplement(struct ast_sip_supplement *supplement);
2975 
2976 /*!
2977  * \brief Retrieve the global MWI taskprocessor high water alert trigger level.
2978  *
2979  * \since 13.12.0
2980  *
2981  * \retval the system MWI taskprocessor high water alert trigger level
2982  */
2983 unsigned int ast_sip_get_mwi_tps_queue_high(void);
2984 
2985 /*!
2986  * \brief Retrieve the global MWI taskprocessor low water clear alert level.
2987  *
2988  * \since 13.12.0
2989  *
2990  * \retval the system MWI taskprocessor low water clear alert level
2991  */
2993 
2994 /*!
2995  * \brief Retrieve the global setting 'disable sending unsolicited mwi on startup'.
2996  * \since 13.12.0
2997  *
2998  * \retval non zero if disable.
2999  */
3001 
3002 /*!
3003  * \brief Retrieve the global setting 'use_callerid_contact'.
3004  * \since 13.24.0
3005  *
3006  * \retval non zero if CALLERID(num) is to be used as the default username in the contact
3007  */
3008 unsigned int ast_sip_get_use_callerid_contact(void);
3009 
3010 /*!
3011  * \brief Retrieve the global setting 'norefersub'.
3012  *
3013  * \retval non zero if norefersub is to be sent in "Supported" Headers
3014  */
3015 unsigned int ast_sip_get_norefersub(void);
3016 
3017 /*!
3018  * \brief Retrieve the global setting 'ignore_uri_user_options'.
3019  * \since 13.12.0
3020  *
3021  * \retval non zero if ignore the user field options.
3022  */
3023 unsigned int ast_sip_get_ignore_uri_user_options(void);
3024 
3025 /*!
3026  * \brief Retrieve the global setting 'send_contact_status_on_update_registration'.
3027  * \since 16.2.0
3028  *
3029  * \retval non zero if need to send AMI ContactStatus event when a contact is updated.
3030  */
3032 
3033 
3034 /*!
3035  * \brief Truncate the URI user field options string if enabled.
3036  * \since 13.12.0
3037  *
3038  * \param str URI user field string to truncate if enabled
3039  *
3040  * \details
3041  * We need to be able to handle URI's looking like
3042  * "sip:1235557890;phone-context=national@x.x.x.x;user=phone"
3043  *
3044  * Where the URI user field is:
3045  * "1235557890;phone-context=national"
3046  *
3047  * When truncated the string will become:
3048  * "1235557890"
3049  */
3050 #define AST_SIP_USER_OPTIONS_TRUNCATE_CHECK(str) \
3051  do { \
3052  char *__semi = strchr((str), ';'); \
3053  if (__semi && ast_sip_get_ignore_uri_user_options()) { \
3054  *__semi = '\0'; \
3055  } \
3056  } while (0)
3057 
3058 /*!
3059  * \brief Retrieve the system debug setting (yes|no|host).
3060  *
3061  * \note returned string needs to be de-allocated by caller.
3062  *
3063  * \retval the system debug setting.
3064  */
3065 char *ast_sip_get_debug(void);
3066 
3067 /*!
3068  * \brief Retrieve the global regcontext setting.
3069  *
3070  * \since 13.8.0
3071  *
3072  * \note returned string needs to be de-allocated by caller.
3073  *
3074  * \retval the global regcontext setting
3075  */
3076 char *ast_sip_get_regcontext(void);
3077 
3078 /*!
3079  * \brief Retrieve the global endpoint_identifier_order setting.
3080  *
3081  * Specifies the order by which endpoint identifiers should be regarded.
3082  *
3083  * \retval the global endpoint_identifier_order value
3084  */
3086 
3087 /*!
3088  * \brief Retrieve the default voicemail extension.
3089  * \since 13.9.0
3090  *
3091  * \note returned string needs to be de-allocated by caller.
3092  *
3093  * \retval the default voicemail extension
3094  */
3096 
3097 /*!
3098  * \brief Retrieve the global default realm.
3099  *
3100  * This is the value placed in outbound challenges' realm if there
3101  * is no better option (such as an auth-configured realm).
3102  *
3103  * \param[out] realm The default realm
3104  * \param size The buffer size of realm
3105  * \return nothing
3106  */
3107 void ast_sip_get_default_realm(char *realm, size_t size);
3108 
3109 /*!
3110  * \brief Retrieve the global default from user.
3111  *
3112  * This is the value placed in outbound requests' From header if there
3113  * is no better option (such as an endpoint-configured from_user or
3114  * caller ID number).
3115  *
3116  * \param[out] from_user The default from user
3117  * \param size The buffer size of from_user
3118  * \return nothing
3119  */
3120 void ast_sip_get_default_from_user(char *from_user, size_t size);
3121 
3122 /*!
3123  * \brief Retrieve the system keep alive interval setting.
3124  *
3125  * \retval the keep alive interval.
3126  */
3127 unsigned int ast_sip_get_keep_alive_interval(void);
3128 
3129 /*!
3130  * \brief Retrieve the system contact expiration check interval setting.
3131  *
3132  * \retval the contact expiration check interval.
3133  */
3135 
3136 /*!
3137  * \brief Retrieve the system setting 'disable multi domain'.
3138  * \since 13.9.0
3139  *
3140  * \retval non zero if disable multi domain.
3141  */
3142 unsigned int ast_sip_get_disable_multi_domain(void);
3143 
3144 /*!
3145  * \brief Retrieve the system max initial qualify time.
3146  *
3147  * \retval the maximum initial qualify time.
3148  */
3149 unsigned int ast_sip_get_max_initial_qualify_time(void);
3150 
3151 /*!
3152  * \brief translate ast_sip_contact_status_type to character string.
3153  *
3154  * \retval the character string equivalent.
3155  */
3156 
3157 const char *ast_sip_get_contact_status_label(const enum ast_sip_contact_status_type status);
3159 
3160 /*!
3161  * \brief Set a request to use the next value in the list of resolved addresses.
3162  *
3163  * \param tdata the tx data from the original request
3164  * \retval 0 No more addresses to try
3165  * \retval 1 The request was successfully re-intialized
3166  */
3167 int ast_sip_failover_request(pjsip_tx_data *tdata);
3168 
3169 /*!
3170  * \brief Retrieve the local host address in IP form
3171  *
3172  * \param af The address family to retrieve
3173  * \param addr A place to store the local host address
3174  *
3175  * \retval 0 success
3176  * \retval -1 failure
3177  *
3178  * \since 13.6.0
3179  */
3180 int ast_sip_get_host_ip(int af, pj_sockaddr *addr);
3181 
3182 /*!
3183  * \brief Retrieve the local host address in string form
3184  *
3185  * \param af The address family to retrieve
3186  *
3187  * \retval non-NULL success
3188  * \retval NULL failure
3189  *
3190  * \since 13.6.0
3191  *
3192  * \note An empty string may be returned if the address family is valid but no local address exists
3193  */
3194 const char *ast_sip_get_host_ip_string(int af);
3195 
3196 /*!
3197  * \brief Return the size of the SIP threadpool's task queue
3198  * \since 13.7.0
3199  */
3201 
3202 /*!
3203  * \brief Retrieve the SIP threadpool object
3204  */
3205 struct ast_threadpool *ast_sip_threadpool(void);
3206 
3207 /*!
3208  * \brief Retrieve transport state
3209  * \since 13.7.1
3210  *
3211  * @param transport_id
3212  * @returns transport_state
3213  *
3214  * \note ao2_cleanup(...) or ao2_ref(..., -1) must be called on the returned object
3215  */
3216 struct ast_sip_transport_state *ast_sip_get_transport_state(const char *transport_id);
3217 
3218 /*!
3219  * \brief Retrieves all transport states
3220  * \since 13.7.1
3221  *
3222  * @returns ao2_container
3223  *
3224  * \note ao2_cleanup(...) or ao2_ref(..., -1) must be called on the returned object
3225  */
3227 
3228 /*!
3229  * \brief Sets pjsip_tpselector from ast_sip_transport
3230  * \since 13.8.0
3231  *
3232  * \param transport The transport to be used
3233  * \param selector The selector to be populated
3234  * \retval 0 success
3235  * \retval -1 failure
3236  *
3237  * \note The transport selector must be unreffed using ast_sip_tpselector_unref
3238  */
3239 int ast_sip_set_tpselector_from_transport(const struct ast_sip_transport *transport, pjsip_tpselector *selector);
3240 
3241 /*!
3242  * \brief Sets pjsip_tpselector from ast_sip_transport
3243  * \since 13.8.0
3244  *
3245  * \param transport_name The name of the transport to be used
3246  * \param selector The selector to be populated
3247  * \retval 0 success
3248  * \retval -1 failure
3249  *
3250  * \note The transport selector must be unreffed using ast_sip_tpselector_unref
3251  */
3252 int ast_sip_set_tpselector_from_transport_name(const char *transport_name, pjsip_tpselector *selector);
3253 
3254 /*!
3255  * \brief Unreference a pjsip_tpselector
3256  * \since 17.0.0
3257  *
3258  * \param selector The selector to be unreffed
3259  */
3260 void ast_sip_tpselector_unref(pjsip_tpselector *selector);
3261 
3262 /*!
3263  * \brief Sets the PJSIP transport on a child transport
3264  * \since 17.0.0
3265  *
3266  * \param transport_name The name of the transport to be updated
3267  * \param transport The PJSIP transport
3268  * \retval 0 success
3269  * \retval -1 failure
3270  */
3271 int ast_sip_transport_state_set_transport(const char *transport_name, pjsip_transport *transport);
3272 
3273 /*!
3274  * \brief Sets the P-Preferred-Identity on a child transport
3275  * \since 17.0.0
3276  *
3277  * \param transport_name The name of the transport to be set on
3278  * \param identity The P-Preferred-Identity to use on requests on this transport
3279  * \retval 0 success
3280  * \retval -1 failure
3281  */
3282 int ast_sip_transport_state_set_preferred_identity(const char *transport_name, const char *identity);
3283 
3284 /*!
3285  * \brief Sets the service routes on a child transport
3286  * \since 17.0.0
3287  *
3288  * \param transport_name The name of the transport to be set on
3289  * \param service_routes A vector of service routes
3290  * \retval 0 success
3291  * \retval -1 failure
3292  *
3293  * \note This assumes ownership of the service routes in both success and failure scenarios
3294  */
3295 int ast_sip_transport_state_set_service_routes(const char *transport_name, struct ast_sip_service_route_vector *service_routes);
3296 
3297 /*!
3298  * \brief Apply the configuration for a transport to an outgoing message
3299  * \since 17.0.0
3300  *
3301  * \param transport_name The name of the transport to apply configuration from
3302  * \param tdata The SIP message
3303  */
3304 void ast_sip_message_apply_transport(const char *transport_name, pjsip_tx_data *tdata);
3305 
3306 /*!
3307  * \brief Allocate a vector of service routes
3308  * \since 17.0.0
3309  *
3310  * \retval non-NULL success
3311  * \retval NULL failure
3312  */
3313 struct ast_sip_service_route_vector *ast_sip_service_route_vector_alloc(void);
3314 
3315 /*!
3316  * \brief Destroy a vector of service routes
3317  * \since 17.0.0
3318  *
3319  * \param service_routes A vector of service routes
3320  */
3321 void ast_sip_service_route_vector_destroy(struct ast_sip_service_route_vector *service_routes);
3322 
3323 /*!
3324  * \brief Set name and number information on an identity header.
3325  *
3326  * \param pool Memory pool to use for string duplication
3327  * \param id_hdr A From, P-Asserted-Identity, or Remote-Party-ID header to modify
3328  * \param id The identity information to apply to the header
3329  */
3330 void ast_sip_modify_id_header(pj_pool_t *pool, pjsip_fromto_hdr *id_hdr,
3331  const struct ast_party_id *id);
3332 
3333 /*!
3334  * \brief Retrieve the unidentified request security event thresholds
3335  * \since 13.8.0
3336  *
3337  * \param count The maximum number of unidentified requests per source ip to accumulate before emitting a security event
3338  * \param period The period in seconds over which to accumulate unidentified requests
3339  * \param prune_interval The interval in seconds at which expired entries will be pruned
3340  */
3341 void ast_sip_get_unidentified_request_thresholds(unsigned int *count, unsigned int *period,
3342  unsigned int *prune_interval);
3343 
3344 /*!
3345  * \brief Get the transport name from an endpoint or request uri
3346  * \since 13.15.0
3347  *
3348  * \param endpoint
3349  * \param sip_uri
3350  * \param buf Buffer to receive transport name
3351  * \param buf_len Buffer length
3352  *
3353  * \retval 0 Success
3354  * \retval -1 Failure
3355  *
3356  * \note
3357  * If endpoint->transport is not NULL, it is returned in buf.
3358  * Otherwise if sip_uri has an 'x-ast-txp' parameter AND the sip_uri host is
3359  * an ip4 or ip6 address, its value is returned,
3360  */
3361 int ast_sip_get_transport_name(const struct ast_sip_endpoint *endpoint,
3362  pjsip_sip_uri *sip_uri, char *buf, size_t buf_len);
3363 
3364 /*!
3365  * \brief Sets pjsip_tpselector from an endpoint or uri
3366  * \since 13.15.0
3367  *
3368  * \param endpoint If endpoint->transport is set, it's used
3369  * \param sip_uri If sip_uri contains a x-ast-txp parameter, it's used
3370  * \param selector The selector to be populated
3371  *
3372  * \retval 0 success
3373  * \retval -1 failure
3374  */
3375 int ast_sip_set_tpselector_from_ep_or_uri(const struct ast_sip_endpoint *endpoint,
3376  pjsip_sip_uri *sip_uri, pjsip_tpselector *selector);
3377 
3378 /*!
3379  * \brief Set the transport on a dialog
3380  * \since 13.15.0
3381  *
3382  * \param endpoint
3383  * \param dlg
3384  * \param selector (optional)
3385  *
3386  * \note
3387  * This API calls ast_sip_get_transport_name(endpoint, dlg->target) and if the result is
3388  * non-NULL, calls pjsip_dlg_set_transport. If 'selector' is non-NULL, it is updated with
3389  * the selector used.
3390  *
3391  * \note
3392  * It is the responsibility of the caller to unref the passed in selector if one is provided.
3393  */
3394 int ast_sip_dlg_set_transport(const struct ast_sip_endpoint *endpoint, pjsip_dialog *dlg,
3395  pjsip_tpselector *selector);
3396 
3397 /*!
3398  * \brief Convert the DTMF mode enum value into a string
3399  * \since 13.18.0
3400  *
3401  * \param dtmf the dtmf mode
3402  * \param buf Buffer to receive dtmf mode string
3403  * \param buf_len Buffer length
3404  *
3405  * \retval 0 Success
3406  * \retval -1 Failure
3407  *
3408  */
3409 int ast_sip_dtmf_to_str(const enum ast_sip_dtmf_mode dtmf,
3410  char *buf, size_t buf_len);
3411 
3412 /*!
3413  * \brief Convert the DTMF mode name into an enum
3414  * \since 13.18.0
3415  *
3416  * \param dtmf_mode dtmf mode as a string
3417  *
3418  * \retval >= 0 The enum value
3419  * \retval -1 Failure
3420  *
3421  */
3422 int ast_sip_str_to_dtmf(const char *dtmf_mode);
3423 
3424 /*!
3425  * \brief Convert the call codec preference flags to a string
3426  * \since 18.0.0
3427  *
3428  * \param pref the call codec preference setting
3429  *
3430  * \returns a constant string with either the setting value or 'unknown'
3431  * \note Don't try to free the string!
3432  *
3433  */
3434 const char *ast_sip_call_codec_pref_to_str(struct ast_flags pref);
3435 
3436 /*!
3437  * \brief Convert a call codec preference string to preference flags
3438  * \since 18.0.0
3439  *
3440  * \param pref A pointer to an ast_flags structure to receive the preference flags
3441  * \param pref_str The call codec preference setting string
3442  * \param is_outgoing Is for outgoing calls?
3443  *
3444  * \retval 0 The string was parsed successfully
3445  * \retval -1 The string option was invalid
3446  */
3447 int ast_sip_call_codec_str_to_pref(struct ast_flags *pref, const char *pref_str, int is_outgoing);
3448 
3449 /*!
3450  * \brief Transport shutdown monitor callback.
3451  * \since 13.18.0
3452  *
3453  * \param data User data to know what to do when transport shuts down.
3454  *
3455  * \note The callback does not need to care that data is an ao2 object.
3456  *
3457  * \return Nothing
3458  */
3459 typedef void (*ast_transport_monitor_shutdown_cb)(void *data);
3460 
3461 /*!
3462  * \brief Transport shutdown monitor data matcher
3463  * \since 13.20.0
3464  *
3465  * \param a User data to compare.
3466  * \param b User data to compare.
3467  *
3468  * \retval 1 The data objects match
3469  * \retval 0 The data objects don't match
3470  */
3471 typedef int (*ast_transport_monitor_data_matcher)(void *a, void *b);
3472 
3474  /*! \brief Successfully registered the transport monitor */
3476  /*! \brief Replaced the already existing transport monitor with new one. */
3478  /*!
3479  * \brief Transport not found to monitor.
3480  * \note Transport is either already shutdown or is not reliable.
3481  */
3483  /*! \brief Error while registering transport monitor. */
3485 };
3486 
3487 /*!
3488  * \brief Register a reliable transport shutdown monitor callback.
3489  * \since 13.20.0
3490  *
3491  * \param transport Transport to monitor for shutdown.
3492  * \param cb Who to call when transport is shutdown.
3493  * \param ao2_data Data to pass with the callback.
3494  *
3495  * \note The data object passed will have its reference count automatically
3496  * incremented by this call and automatically decremented after the callback
3497  * runs or when the callback is unregistered.
3498  *
3499  * There is no checking for duplicate registrations.
3500  *
3501  * \return enum ast_transport_monitor_reg
3502  */
3504  ast_transport_monitor_shutdown_cb cb, void *ao2_data);
3505 
3506 /*!
3507  * \brief Register a reliable transport shutdown monitor callback replacing any duplicate.
3508  * \since 13.26.0
3509  * \since 16.3.0
3510  *
3511  * \param transport Transport to monitor for shutdown.
3512  * \param cb Who to call when transport is shutdown.
3513  * \param ao2_data Data to pass with the callback.
3514  * \param matches Matcher function that returns true if data matches a previously
3515  * registered data object
3516  *
3517  * \note The data object passed will have its reference count automatically
3518  * incremented by this call and automatically decremented after the callback
3519  * runs or when the callback is unregistered.
3520  *
3521  * This function checks for duplicates, and overwrites/replaces the old monitor
3522  * with the given one.
3523  *
3524  * \return enum ast_transport_monitor_reg
3525  */
3528 
3529 /*!
3530  * \brief Unregister a reliable transport shutdown monitor
3531  * \since 13.20.0
3532  *
3533  * \param transport Transport to monitor for shutdown.
3534  * \param cb The callback that was used for the original register.
3535  * \param data Data to pass to the matcher. May be NULL and does NOT need to be an ao2 object.
3536  * If NULL, all monitors with the provided callbck are unregistered.
3537  * \param matches Matcher function that returns true if data matches the previously
3538  * registered data object. If NULL, a simple pointer comparison is done.
3539  *
3540  * \note The data object passed into the original register will have its reference count
3541  * automatically decremeneted.
3542  *
3543  * \return Nothing
3544  */
3545 void ast_sip_transport_monitor_unregister(pjsip_transport *transport,
3547 
3548 /*!
3549  * \brief Unregister a transport shutdown monitor from all reliable transports
3550  * \since 13.20.0
3551  *
3552  * \param cb The callback that was used for the original register.
3553  * \param data Data to pass to the matcher. May be NULL and does NOT need to be an ao2 object.
3554  * If NULL, all monitors with the provided callbck are unregistered.
3555  * \param matches Matcher function that returns true if ao2_data matches the previously
3556  * registered data object. If NULL, a simple pointer comparison is done.
3557  *
3558  * \note The data object passed into the original register will have its reference count
3559  * automatically decremeneted.
3560  *
3561  * \return Nothing
3562  */
3564  void *data, ast_transport_monitor_data_matcher matches);
3565 
3566 /*! Transport state notification registration element. */
3568  /*! PJPROJECT transport state notification callback */
3569  pjsip_tp_state_callback cb;
3571 };
3572 
3573 /*!
3574  * \brief Register a transport state notification callback element.
3575  * \since 13.18.0
3576  *
3577  * \param element What we are registering.
3578  *
3579  * \return Nothing
3580  */
3582 
3583 /*!
3584  * \brief Unregister a transport state notification callback element.
3585  * \since 13.18.0
3586  *
3587  * \param element What we are unregistering.
3588  *
3589  * \return Nothing
3590  */
3592 
3593 #endif /* _RES_PJSIP_H */
enum ast_transport type
Definition: res_pjsip.h:101
int ast_sip_call_codec_str_to_pref(struct ast_flags *pref, const char *pref_str, int is_outgoing)
Convert a call codec preference string to preference flags.
Definition: res_pjsip.c:5557
unsigned long long ast_group_t
Definition: channel.h:214
Call pickup configuration options for endpoints.
Definition: res_pjsip.h:655
Information needed to identify an endpoint in a call.
Definition: channel.h:339
static char accountcode[AST_MAX_ACCOUNT_CODE]
Definition: chan_iax2.c:428
int authenticate_qualify
Definition: res_pjsip.h:309
int ast_sip_register_outbound_authenticator(struct ast_sip_outbound_authenticator *outbound_auth)
Register an outbound SIP authenticator.
Definition: res_pjsip.c:3389
Definition: test_heap.c:38
struct ast_ha * localnet
Definition: res_pjsip.h:124
void ast_sip_report_mem_limit(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Send a security event notification for when a memory limit is hit.
struct ast_dnsmgr_entry * external_address_refresher
Definition: res_pjsip.h:227
int ast_sip_auth_vector_init(struct ast_sip_auth_vector *vector, const char *auth_names)
Initialize an auth vector with the configured values.
long ast_sip_threadpool_queue_size(void)
Return the size of the SIP threadpool&#39;s task queue.
Definition: res_pjsip.c:5625
void ast_sip_add_usereqphone(const struct ast_sip_endpoint *endpoint, pj_pool_t *pool, pjsip_uri *uri)
Add &#39;user=phone&#39; parameter to URI if enabled and user is a phone number.
Definition: res_pjsip.c:3994
A contact&#39;s status.
Definition: res_pjsip.h:341
static const char name[]
Definition: format_mp3.c:68
ast_sip_scheduler_task_flags
Task flags for the res_pjsip scheduler.
Definition: res_pjsip.h:1767
static int incoming_request(struct ast_sip_session *session, pjsip_rx_data *rdata)
A SIP address of record.
Definition: res_pjsip.h:361
ast_sip_contact_filter
Contact retrieval filtering flags.
Definition: res_pjsip.h:1004
int ast_sip_for_each_aor(const char *aors, ao2_callback_fn on_aor, void *arg)
For every aor in the comma separated aors string call the given &#39;on_aor&#39; handler. ...
Definition: location.c:684
struct ao2_container * ast_sip_location_retrieve_aor_contacts_nolock(const struct ast_sip_aor *aor)
Retrieve all contacts currently available for an AOR without locking the AOR.
Definition: location.c:214
void ast_sip_report_auth_failed_challenge_response(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Send a security event notification for when a challenge response has failed.
An entity responsible formatting endpoint information.
Definition: res_pjsip.h:2763
The task is scheduled at multiples of interval.
Definition: res_pjsip.h:1817
char * ast_sip_get_regcontext(void)
Retrieve the global regcontext setting.
int ast_sip_register_authenticator(struct ast_sip_authenticator *auth)
Register a SIP authenticator.
Definition: res_pjsip.c:3338
Endpoint configuration options for INFO packages.
Definition: res_pjsip.h:681
struct ast_sip_contact_status * ast_sip_get_contact_status(const struct ast_sip_contact *contact)
Retrieve the current status for a contact.
ast_sip_session_media_encryption
Definition: res_pjsip.h:504
int ast_sip_requires_authentication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Determine if an incoming request requires authentication.
Definition: res_pjsip.c:3361
Definition: ast_expr2.c:325
const ast_string_field call_id
Definition: res_pjsip.h:303
static uint32_t keepalive
Definition: res_pktccops.c:162
const ast_string_field user_agent
Definition: res_pjsip.h:303
struct timeval last_start
int ast_sip_for_each_channel_snapshot(const struct ast_endpoint_snapshot *endpoint_snapshot, ao2_callback_fn on_channel_snapshot, void *arg)
For every channel snapshot on an endpoint snapshot call the given &#39;on_channel_snapshot&#39; handler...
char * address
Definition: f2c.h:59
int ast_sip_get_transport_name(const struct ast_sip_endpoint *endpoint, pjsip_sip_uri *sip_uri, char *buf, size_t buf_len)
Get the transport name from an endpoint or request uri.
Definition: res_pjsip.c:3762
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
Default filter flags.
Definition: res_pjsip.h:1006
int ast_sip_sched_task_cancel(struct ast_sip_sched_task *schtd)
Cancels the next invocation of a task.
void ast_sip_dialog_set_serializer(pjsip_dialog *dlg, struct ast_taskprocessor *serializer)
Set a serializer on a SIP dialog so requests and responses are automatically serialized.
ast_sip_check_auth_result
Possible returns from ast_sip_check_authentication.
Definition: res_pjsip.h:932
pjsip_dialog * ast_sip_create_dialog_uas(const struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pj_status_t *status)
General purpose method for creating a UAS dialog with an endpoint.
Definition: res_pjsip.c:4233
ast_transport
Definition: netsock2.h:59
Endpoint subscription configuration.
Definition: res_pjsip.h:602
void ast_sip_auth_vector_destroy(struct ast_sip_auth_vector *vector)
Free contents of an auth vector.
enum ast_transport_monitor_reg ast_sip_transport_monitor_register(pjsip_transport *transport, ast_transport_monitor_shutdown_cb cb, void *ao2_data)
Register a reliable transport shutdown monitor callback.
ast_transport_monitor_reg
Definition: res_pjsip.h:3459
const ast_string_field via_addr
Definition: res_pjsip.h:303
static int nat
Definition: chan_mgcp.c:171
int ast_sip_set_outbound_proxy(pjsip_tx_data *tdata, const char *proxy)
Set the outbound proxy for an outbound SIP message.
Definition: res_pjsip.c:5047
static struct stasis_rest_handlers mailboxes
REST handler for /api-docs/mailboxes.json.
struct ast_ha * localnet
Definition: res_pjsip.h:221
void * arg
Definition: res_pjsip.h:2745
AMI variable container.
Definition: res_pjsip.h:2737
void * ast_sip_dict_get(void *ht, const char *key)
Retrieves the value associated with the given key.
Definition: res_pjsip.c:5338
void ast_sip_transport_state_register(struct ast_sip_tpmgr_state_callback *element)
Register a transport state notification callback element.
Party identification options for endpoints.
Definition: res_pjsip.h:628
Structure for variables, used for configurations and for channel variables.
void ast_sip_dialog_set_endpoint(pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint)
Set an endpoint on a SIP dialog so in-dialog requests do not undergo endpoint lookup.
UDPTL support for T.38.
char * ast_sip_get_debug(void)
Retrieve the system debug setting (yes|no|host).
unsigned int ast_sip_get_norefersub(void)
Retrieve the global setting &#39;norefersub&#39;.
int ast_sip_transport_state_set_preferred_identity(const char *transport_name, const char *identity)
Sets the P-Preferred-Identity on a child transport.
ast_sip_call_codec_pref
Incoming/Outgoing call offer/answer joint codec preference.
Definition: res_pjsip.h:529
int ast_sip_for_each_channel(const struct ast_sip_endpoint *endpoint, ao2_callback_fn on_channel_snapshot, void *arg)
For every channel snapshot on an endpoint all the given &#39;on_channel_snapshot&#39; handler.
Full structure for sorcery.
Definition: sorcery.c:230
struct timeval when_queued
Definition: astman.c:222
Direct media options for SIP endpoints.
Definition: res_pjsip.h:729
const char * ast_sip_get_contact_short_status_label(const enum ast_sip_contact_status_type status)
Background DNS update manager.
void ast_sip_unregister_outbound_authenticator(struct ast_sip_outbound_authenticator *auth)
Unregister an outbound SIP authenticator.
Definition: res_pjsip.c:3401
unsigned int qualify_frequency
Definition: res_pjsip.h:307
int ast_sip_location_add_contact_nolock(struct ast_sip_aor *aor, const char *uri, struct timeval expiration_time, const char *path_info, const char *user_agent, const char *via_addr, int via_port, const char *call_id, struct ast_sip_endpoint *endpoint)
Add a new contact to an AOR without locking the AOR.
Definition: location.c:416
const char * ast_sip_get_device_state(const struct ast_sip_endpoint *endpoint)
Retrieve the device state for an endpoint.
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:337
struct ao2_container * ast_sip_location_retrieve_aor_contacts(const struct ast_sip_aor *aor)
Retrieve all contacts currently available for an AOR.
Definition: location.c:247
Wrapper for an ast_acl linked list.
Definition: acl.h:76
Replaced the already existing transport monitor with new one.
Definition: res_pjsip.h:3463
const char * ast_sip_get_contact_status_label(const enum ast_sip_contact_status_type status)
translate ast_sip_contact_status_type to character string.
void ast_sip_get_default_realm(char *realm, size_t size)
Retrieve the global default realm.
pj_sockaddr host
Definition: res_pjsip.h:199
void ast_copy_pj_str(char *dest, const pj_str_t *src, size_t size)
Copy a pj_str_t into a standard character buffer.
Definition: res_pjsip.c:5240
Endpoint abstractions.
Definition: dnsmgr.c:66
int ast_sip_str_to_dtmf(const char *dtmf_mode)
Convert the DTMF mode name into an enum.
Definition: res_pjsip.c:5513
const char * str
Definition: app_jack.c:147
void ast_sip_unregister_endpoint_formatter(struct ast_sip_endpoint_formatter *obj)
Unregister an endpoint formatter.
Definition: res_pjsip.c:3685
struct ast_sip_endpoint * ast_sip_default_outbound_endpoint(void)
Retrieve the default outbound endpoint.
int ast_sip_contact_to_str(void *object, void *arg, int flags)
Handler used to convert a contact to a string.
Definition: location.c:767
void * ast_sip_endpoint_alloc(const char *name)
Allocate a new SIP endpoint.
Endpoint configuration for SIP extensions.
Definition: res_pjsip.h:576
unsigned int cos
Definition: res_pjsip.h:243
Domain data structure.
Definition: sip.h:888
struct ast_threadpool * ast_sip_threadpool(void)
Retrieve the SIP threadpool object.
Definition: res_pjsip.c:5630
struct spandsp_fax_stats t38
struct ast_sip_transport_state * state
Definition: res_pjsip.h:239
int ast_sip_add_global_request_header(const char *name, const char *value, int replace)
int value
Definition: syslog.c:37
int ast_sip_add_body_multipart(pjsip_tx_data *tdata, const struct ast_sip_body *bodies[], int num_bodies)
Add a multipart body to an outbound SIP message.
Definition: res_pjsip.c:5098
int ast_sip_push_task_wait_servant(struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
Push a task to SIP servants and wait for it to complete.
Definition: res_pjsip.c:5204
int ast_sip_sched_task_get_times_by_name(const char *name, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end)
Gets the last start and end times of the task by name.
static int priority
struct ao2_container * ast_sip_location_retrieve_aor_contacts_nolock_filtered(const struct ast_sip_aor *aor, unsigned int flags)
Retrieve all contacts currently available for an AOR without locking the AOR and filter based on flag...
Definition: location.c:219
int ast_sip_dtmf_to_str(const enum ast_sip_dtmf_mode dtmf, char *buf, size_t buf_len)
Convert the DTMF mode enum value into a string.
Definition: res_pjsip.c:5484
Socket address structure.
Definition: netsock2.h:97
ast_endpoint_state
Valid states for an endpoint.
Definition: endpoints.h:51
int ast_sip_send_request(pjsip_tx_data *tdata, struct pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint, void *token, void(*callback)(void *token, pjsip_event *e))
General purpose method for sending a SIP request.
Definition: res_pjsip.c:5034
RTP configuration for SIP endpoints.
Definition: res_pjsip.h:689
int ast_sip_add_header(pjsip_tx_data *tdata, const char *name, const char *value)
Add a header to an outbound SIP message.
Definition: res_pjsip.c:5063
Media Stream API.
int ast_sip_persistent_endpoint_update_state(const char *endpoint_name, enum ast_endpoint_state state)
Change state of a persistent endpoint.
int(* ast_sip_dialog_outbound_auth_cb)(pjsip_dialog *dlg, pjsip_tx_data *tdata, void *user_data)
Callback called when an outbound request with authentication credentials is to be sent in dialog...
Definition: res_pjsip.h:1468
ast_sip_supplement_priority
Definition: res_pjsip.h:2869
int ast_sip_sched_is_task_running(struct ast_sip_sched_task *schtd)
Checks if the task is currently running.
ast_sip_contact_status_type
Status type for a contact.
Definition: res_pjsip.h:323
struct ast_endpoint_snapshot * ast_sip_get_endpoint_snapshot(const struct ast_sip_endpoint *endpoint)
Retrieve the endpoint snapshot for an endpoint.
const char * ast_sip_get_host_ip_string(int af)
Retrieve the local host address in string form.
Definition: res_pjsip.c:5473
int ast_sip_failover_request(pjsip_tx_data *tdata)
Set a request to use the next value in the list of resolved addresses.
Definition: res_pjsip.c:4871
struct ast_sip_endpoint * ast_pjsip_rdata_get_endpoint(pjsip_rx_data *rdata)
Get the looked-up endpoint on an out-of dialog request or response.
int ast_sip_create_response(const pjsip_rx_data *rdata, int st_code, struct ast_sip_contact *contact, pjsip_tx_data **p_tdata)
General purpose method for creating a SIP response.
Definition: res_pjsip.c:5448
struct ast_sip_endpoint * endpoint
Definition: res_pjsip.h:313
unsigned int ast_sip_get_mwi_tps_queue_high(void)
Retrieve the global MWI taskprocessor high water alert trigger level.
internal representation of ACL entries In principle user applications would have no need for this...
Definition: acl.h:51
struct ast_sockaddr external_media_address
Definition: res_pjsip.h:144
void ast_sip_unregister_authenticator(struct ast_sip_authenticator *auth)
Unregister a SIP authenticator.
Definition: res_pjsip.c:3350
int ast_sip_get_mwi_tps_queue_low(void)
Retrieve the global MWI taskprocessor low water clear alert level.
int ast_sip_retrieve_auths(const struct ast_sip_auth_vector *auths, struct ast_sip_auth **out)
Retrieve relevant SIP auth structures from sorcery.
struct ast_sip_sched_task * ast_sip_schedule_task(struct ast_taskprocessor *serializer, int interval, ast_sip_task sip_task, const char *name, void *task_data, enum ast_sip_scheduler_task_flags flags)
Schedule a task to run in the res_pjsip thread pool.
void ast_sip_register_endpoint_formatter(struct ast_sip_endpoint_formatter *obj)
Register an endpoint formatter.
Definition: res_pjsip.c:3679
int() ao2_callback_fn(void *obj, void *arg, int flags)
Type of a generic callback function.
Definition: astobj2.h:1230
void ast_sip_report_failed_acl(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, const char *name)
Send a security event notification for when an ACL check fails.
Structure for SIP nat hook information.
Definition: res_pjsip.h:271
void ast_sip_report_req_no_support(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, const char *req_type)
Send a security event notification for when a request is not supported.
struct ast_sip_contact * ast_sip_location_retrieve_first_aor_contact_filtered(const struct ast_sip_aor *aor, unsigned int flags)
Retrieve the first bound contact for an AOR and filter based on flags.
Definition: location.c:199
int ast_sip_register_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier)
Register a SIP endpoint identifier.
Definition: res_pjsip.c:3508
Structure for SIP transport information.
Definition: res_pjsip.h:87
char * ast_sip_rdata_get_header_value(pjsip_rx_data *rdata, const pj_str_t str)
Get a specific header value from rdata.
Definition: res_pjsip.c:3543
A wrapper for contact that adds the aor_id and a consistent contact id. Used by ast_sip_for_each_cont...
Definition: res_pjsip.h:396
General Asterisk PBX channel definitions.
int ast_sip_sched_task_get_next_run_by_name(const char *name)
Gets the number of milliseconds until the next invocation.
const char * ast_sip_call_codec_pref_to_str(struct ast_flags pref)
Convert the call codec preference flags to a string.
Definition: res_pjsip.c:5534
int ast_sip_auths_to_str(const struct ast_sip_auth_vector *auths, char **buf)
Converts an auths array to a string of comma separated values.
struct ast_sip_contact * ast_sip_location_create_contact(struct ast_sip_aor *aor, const char *uri, struct timeval expiration_time, const char *path_info, const char *user_agent, const char *via_addr, int via_port, const char *call_id, int prune_on_boot, struct ast_sip_endpoint *endpoint)
Create a new contact for an AOR without locking the AOR.
Definition: location.c:355
int ast_sip_add_body(pjsip_tx_data *tdata, const struct ast_sip_body *body)
Add a body to an outbound SIP message.
Definition: res_pjsip.c:5091
ast_t38_ec_modes
Definition: udptl.h:37
int ast_sip_format_endpoint_ami(struct ast_sip_endpoint *endpoint, struct ast_sip_ami *ami, int *count)
Formats the endpoint and sends over AMI.
Definition: res_pjsip.c:3699
struct pjsip_transport * transport
Transport itself.
Definition: res_pjsip.h:89
pjsip_tls_setting tls
Definition: res_pjsip.h:111
int ast_sip_push_task_wait_serializer(struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
Push a task to the serializer and wait for it to complete.
Definition: res_pjsip.c:5218
struct ao2_container * ast_sip_location_retrieve_contacts_from_aor_list(const char *aor_list)
Retrieve all contacts from a list of AORs.
Definition: location.c:335
static struct ao2_container * codecs
Registered codecs.
Definition: codec.c:48
int ast_sip_create_rdata(pjsip_rx_data *rdata, char *packet, const char *src_name, int src_port, char *transport_type, const char *local_name, int local_port)
General purpose method for creating an rdata structure using specific information.
Definition: res_pjsip.c:4323
struct ast_sip_endpoint * ast_sip_dialog_get_endpoint(pjsip_dialog *dlg)
Get the endpoint associated with this dialog.
static char mohsuggest[MAX_MUSICCLASS]
Definition: chan_iax2.c:430
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:299
ast_sip_direct_media_glare_mitigation
Definition: res_pjsip.h:491
int ast_copy_pj_str2(char **dest, const pj_str_t *src)
Create and copy a pj_str_t into a standard character buffer.
Definition: res_pjsip.c:5247
In case you didn&#39;t read that giant block of text above the mansession_session struct, the struct mansession is named this solely to keep the API the same in Asterisk. This structure really represents data that is different from Manager action to Manager action. The mansession_session pointer contained within points to session-specific data.
Definition: manager.c:1625
struct ast_sip_endpoint * ast_sip_identify_endpoint(pjsip_rx_data *rdata)
Determine the endpoint that has sent a SIP message.
Definition: res_pjsip.c:3528
int ast_sip_send_stateful_response(pjsip_rx_data *rdata, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint)
Send a stateful response to an out of dialog request.
Definition: res_pjsip.c:5420
unsigned int cos_audio
Definition: chan_mgcp.c:183
char * ast_sip_get_default_voicemail_extension(void)
Retrieve the default voicemail extension.
Successfully registered the transport monitor.
Definition: res_pjsip.h:3461
const char * method
Definition: res_pjsip.c:4335
static void challenge(const char *realm, pjsip_tx_data *tdata, const pjsip_rx_data *rdata, int is_stale)
astobj2 callback for adding digest challenges to responses
unsigned int ast_sip_get_mwi_disable_initial_unsolicited(void)
Retrieve the global setting &#39;disable sending unsolicited mwi on startup&#39;.
A set of macros to manage forward-linked lists.
static char language[MAX_LANGUAGE]
Definition: chan_alsa.c:121
struct ast_taskprocessor * ast_sip_create_serializer_group(const char *name, struct ast_serializer_shutdown_group *shutdown_group)
Create a new serializer for SIP tasks.
Definition: res_pjsip.c:5128
double qualify_timeout
Definition: res_pjsip.h:311
int ast_sip_create_request_with_auth(const struct ast_sip_auth_vector *auths, pjsip_rx_data *challenge, pjsip_tx_data *tdata, pjsip_tx_data **new_request)
Create a response to an authentication challenge.
Definition: res_pjsip.c:3412
static int default_expiration
Definition: pbx_dundi.c:199
int ast_sip_sched_task_get_times(struct ast_sip_sched_task *schtd, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end)
Gets the last start and end times of the task.
int ast_sip_sched_task_get_times_by_name2(const char *name, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end, int *interval, int *time_left, struct timeval *next_start)
Gets the queued, last start, last_end, time left, interval, next run by task name.
unsigned int ast_sip_get_disable_multi_domain(void)
Retrieve the system setting &#39;disable multi domain&#39;.
An entity with which Asterisk communicates.
Definition: res_pjsip.h:812
unsigned int ast_sip_get_max_initial_qualify_time(void)
Retrieve the system max initial qualify time.
unsigned int ast_sip_get_send_contact_status_on_update_registration(void)
Retrieve the global setting &#39;send_contact_status_on_update_registration&#39;.
unsigned int ast_sip_get_use_callerid_contact(void)
Retrieve the global setting &#39;use_callerid_contact&#39;.
int ast_sip_register_service(pjsip_module *module)
Register a SIP service in Asterisk.
Definition: res_pjsip.c:3315
int ast_sip_format_auths_ami(const struct ast_sip_auth_vector *auths, struct ast_sip_ami *ami)
Format auth details for AMI.
Definition: config_auth.c:195
Network socket handling.
struct ast_sip_contact * ast_sip_location_retrieve_contact_from_aor_list(const char *aor_list)
Retrieve the first bound contact from a list of AORs.
Definition: location.c:304
ast_sip_endpoint_identifier_type
Different methods by which incoming requests can be matched to endpoints.
Definition: res_pjsip.h:472
A snapshot of an endpoint&#39;s state.
struct ast_sip_service_route_vector * ast_sip_service_route_vector_alloc(void)
Allocate a vector of service routes.
int ast_sip_location_delete_contact(struct ast_sip_contact *contact)
Delete a contact.
Definition: location.c:450
void ast_sip_location_retrieve_contact_and_aor_from_list_filtered(const char *aor_list, unsigned int flags, struct ast_sip_aor **aor, struct ast_sip_contact **contact)
Retrieve the first bound contact AND the AOR chosen from a list of AORs and filter based on flags...
Definition: location.c:272
void ast_sip_transport_monitor_unregister(pjsip_transport *transport, ast_transport_monitor_shutdown_cb cb, void *data, ast_transport_monitor_data_matcher matches)
Unregister a reliable transport shutdown monitor.
int ast_sip_is_content_type(pjsip_media_type *content_type, char *type, char *subtype)
Checks if the given content type matches type/subtype.
Definition: res_pjsip.c:5259
struct ast_sip_aor * ast_sip_location_retrieve_aor(const char *aor_name)
Retrieve a named AOR.
Definition: location.c:147
int ast_sip_add_global_response_header(const char *name, const char *value, int replace)
struct ast_sip_auth * ast_sip_get_artificial_auth(void)
Retrieves a reference to the artificial auth.
Transport not found to monitor.
Definition: res_pjsip.h:3468
enum ast_transport_monitor_reg ast_sip_transport_monitor_register_replace(pjsip_transport *transport, ast_transport_monitor_shutdown_cb cb, void *ao2_data, ast_transport_monitor_data_matcher matches)
Register a reliable transport shutdown monitor callback replacing any duplicate.
ast_sip_session_redirect
Definition: res_pjsip.h:515
void ast_sip_register_supplement(struct ast_sip_supplement *supplement)
Register a supplement to SIP out of dialog processing.
Definition: res_pjsip.c:4511
struct ao2_container * ast_sip_get_transport_states(void)
Retrieves all transport states.
void ast_sip_location_prune_boot_contacts(void)
Prune the prune_on_boot contacts.
Definition: location.c:469
static void outgoing_request(struct ast_sip_session *session, pjsip_tx_data *tdata)
void ast_sip_get_default_from_user(char *from_user, size_t size)
Retrieve the global default from user.
void ast_sip_service_route_vector_destroy(struct ast_sip_service_route_vector *service_routes)
Destroy a vector of service routes.
int ast_sip_push_task_synchronous(struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
Push a task to SIP servants and wait for it to complete.
Definition: res_pjsip.c:5213
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
int ast_sip_sched_is_task_running_by_name(const char *name)
Checks if the task is currently running.
#define SORCERY_OBJECT(details)
Macro which must be used at the beginning of each sorcery capable object.
Definition: sorcery.h:356
int ast_sip_thread_is_servant(void)
Determine if the current thread is a SIP servant thread.
Definition: res_pjsip.c:5321
int ast_sip_push_task(struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
Pushes a task to SIP servants.
Definition: res_pjsip.c:5138
static int array(struct ast_channel *chan, const char *cmd, char *var, const char *value)
Media configuration for SIP endpoints.
Definition: res_pjsip.h:756
Transport to bind to.
Definition: res_pjsip.h:171
void ast_sip_report_invalid_endpoint(const char *name, pjsip_rx_data *rdata)
Send a security event notification for when an invalid endpoint is requested.
int ast_sip_sched_task_get_times2(struct ast_sip_sched_task *schtd, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end, int *interval, int *time_left, struct timeval *next_start)
Gets the queued, last start, last_end, time left, interval, next run.
def info(msg)
#define SIP_TLS_MAX_CIPHERS
Maximum number of ciphers supported for a TLS transport.
Definition: res_pjsip.h:77
unsigned int async_operations
Definition: res_pjsip.h:201
void ast_sip_unregister_supplement(struct ast_sip_supplement *supplement)
Unregister a an supplement to SIP out of dialog processing.
Definition: res_pjsip.c:4531
Contact associated with an address of record.
Definition: res_pjsip.h:281
int(* ast_transport_monitor_data_matcher)(void *a, void *b)
Transport shutdown monitor data matcher.
Definition: res_pjsip.h:3457
struct ast_taskprocessor * ast_sip_create_serializer(const char *name)
Create a new serializer for SIP tasks.
Definition: res_pjsip.c:5133
char * ast_sip_get_endpoint_identifier_order(void)
Retrieve the global endpoint_identifier_order setting.
ast_sip_session_refresh_method
Definition: res_pjsip.h:484
struct ast_sip_endpoint * ast_sip_get_artificial_endpoint(void)
Retrieves a reference to the artificial endpoint.
ast_sip_dtmf_mode
DTMF modes for SIP endpoints.
Definition: res_pjsip.h:408
userdata associated with baseline taskprocessor test
void ast_sip_add_date_header(pjsip_tx_data *tdata)
Adds a Date header to the tdata, formatted like: Date: Wed, 01 Jan 2021 14:53:01 GMT.
Definition: res_pjsip.c:3288
struct ast_taskprocessor * ast_sip_get_distributor_serializer(pjsip_rx_data *rdata)
Determine the distributor serializer for the SIP message.
int ast_sip_for_each_auth(const struct ast_sip_auth_vector *array, ao2_callback_fn on_auth, void *arg)
For every auth in the array call the given &#39;on_auth&#39; handler.
Definition: config_auth.c:135
void ast_sip_cleanup_auths(struct ast_sip_auth *auths[], size_t num_auths)
Clean up retrieved auth structures from memory.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
The next invocation of the task is at last finish + interval.
Definition: res_pjsip.h:1822
Definition: test_acl.c:111
void ast_sip_get_unidentified_request_thresholds(unsigned int *count, unsigned int *period, unsigned int *prune_interval)
Retrieve the unidentified request security event thresholds.
struct ast_sip_contact * ast_sip_location_retrieve_first_aor_contact(const struct ast_sip_aor *aor)
Retrieve the first bound contact for an AOR.
Definition: location.c:194
int ast_sip_sched_task_get_next_run(struct ast_sip_sched_task *schtd)
Gets the number of milliseconds until the next invocation.
struct ast_sip_transport_state * ast_sip_get_transport_state(const char *transport_id)
Retrieve transport state.
struct pjsip_tpfactory * factory
Transport factory.
Definition: res_pjsip.h:91
#define AST_MAX_CONTEXT
Definition: channel.h:136
int ast_sip_create_rdata_with_contact(pjsip_rx_data *rdata, char *packet, const char *src_name, int src_port, char *transport_type, const char *local_name, int local_port, const char *contact_uri)
General purpose method for creating an rdata structure using specific information.
Definition: res_pjsip.c:4271
struct timeval expiration_time
Definition: res_pjsip.h:305
Endpoint configuration for unsolicited MWI.
Definition: res_pjsip.h:586
pjsip_dialog * ast_sip_create_dialog_uas_locked(const struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pj_status_t *status)
General purpose method for creating a UAS dialog with an endpoint.
Definition: res_pjsip.c:4249
void ast_sip_message_apply_transport(const char *transport_name, pjsip_tx_data *tdata)
Apply the configuration for a transport to an outgoing message.
unsigned int ast_sip_get_contact_expiration_check_interval(void)
Retrieve the system contact expiration check interval setting.
void ast_sip_location_retrieve_contact_and_aor_from_list(const char *aor_list, struct ast_sip_aor **aor, struct ast_sip_contact **contact)
Retrieve the first bound contact AND the AOR chosen from a list of AORs.
Definition: location.c:266
Vector container support.
An entity responsible for identifying the source of a SIP message.
Definition: res_pjsip.h:993
int ast_sip_transport_state_set_transport(const char *transport_name, pjsip_transport *transport)
Sets the PJSIP transport on a child transport.
Structure used to handle boolean flags.
Definition: utils.h:199
int ast_sip_format_contact_ami(void *obj, void *arg, int flags)
Formats the contact and sends over AMI.
struct ast_str * ast_sip_create_ami_event(const char *event, struct ast_sip_ami *ami)
Creates a string to store AMI event data in.
int ast_sip_dlg_set_transport(const struct ast_sip_endpoint *endpoint, pjsip_dialog *dlg, pjsip_tpselector *selector)
Set the transport on a dialog.
Definition: res_pjsip.c:3791
The scheduled task&#39;s events are tracked in the debug log.
Definition: res_pjsip.h:1829
struct ast_sockaddr external_signaling_address
Definition: res_pjsip.h:134
#define AST_RWLIST_ENTRY
Definition: linkedlists.h:414
unsigned int external_signaling_port
Definition: res_pjsip.h:203
static int replace(struct ast_channel *chan, const char *cmd, char *data, struct ast_str **buf, ssize_t len)
Definition: func_strings.c:810
void ast_sip_modify_id_header(pj_pool_t *pool, pjsip_fromto_hdr *id_hdr, const struct ast_party_id *id)
Set name and number information on an identity header.
Definition: res_pjsip.c:5587
int ast_sip_get_host_ip(int af, pj_sockaddr *addr)
Retrieve the local host address in IP form.
Definition: res_pjsip.c:5460
struct timeval last_end
pjsip_endpoint * ast_sip_get_pjsip_endpoint(void)
Get a pointer to the PJSIP endpoint.
Definition: res_pjsip.c:3718
unsigned int tos_video
Definition: chan_skinny.c:198
void ast_sip_persistent_endpoint_publish_contact_state(const char *endpoint_name, const struct ast_sip_contact_status *contact_status)
Publish the change of state for a contact.
const ast_string_field aor
Definition: res_pjsip.h:303
unsigned int ast_sip_get_keep_alive_interval(void)
Retrieve the system keep alive interval setting.
An interchangeable way of handling digest authentication for SIP.
Definition: res_pjsip.h:950
A ast_taskprocessor structure is a singleton by name.
Definition: taskprocessor.c:69
FILE * out
Definition: utils/frame.c:33
const char * ast_sip_auth_type_to_str(enum ast_sip_auth_type type)
Converts the given auth type to a string.
Definition: config_auth.c:80
struct ast_sorcery * ast_sip_get_sorcery(void)
Get a pointer to the SIP sorcery structure.
int ast_sip_register_endpoint_identifier_with_name(struct ast_sip_endpoint_identifier *identifier, const char *name)
Register a SIP endpoint identifier with a name.
Definition: res_pjsip.c:3431
unsigned int tos_audio
Definition: chan_mgcp.c:181
void ast_sip_report_auth_challenge_sent(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pjsip_tx_data *tdata)
Send a security event notification for when an authentication challenge is sent.
A supplement to SIP message processing.
Definition: res_pjsip.h:2888
int ast_sip_dialog_setup_outbound_authentication(pjsip_dialog *dlg, const struct ast_sip_endpoint *endpoint, ast_sip_dialog_outbound_auth_cb cb, void *user_data)
Set up outbound authentication on a SIP dialog.
An opaque threadpool structure.
Definition: threadpool.c:36
int ast_sip_set_tpselector_from_transport(const struct ast_sip_transport *transport, pjsip_tpselector *selector)
Sets pjsip_tpselector from ast_sip_transport.
Definition: res_pjsip.c:3907
int ast_sip_set_tpselector_from_ep_or_uri(const struct ast_sip_endpoint *endpoint, pjsip_sip_uri *sip_uri, pjsip_tpselector *selector)
Sets pjsip_tpselector from an endpoint or uri.
Definition: res_pjsip.c:3975
int ast_sip_send_response(pjsip_response_addr *res_addr, pjsip_tx_data *tdata, struct ast_sip_endpoint *sip_endpoint)
Send a response to an out of dialog request.
Definition: res_pjsip.c:5407
unsigned int cos_video
Definition: chan_skinny.c:201
void ast_sip_unregister_service(pjsip_module *module)
Definition: res_pjsip.c:3331
void ast_sip_report_auth_success(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata)
Send a security event notification for when authentication succeeds.
int ast_sip_sorcery_object_to_ami(const void *obj, struct ast_str **buf)
Converts a sorcery object to a string of object properties.
void ast_sip_unregister_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier)
Unregister a SIP endpoint identifier.
Definition: res_pjsip.c:3513
enum ast_sip_check_auth_result ast_sip_check_authentication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata, pjsip_tx_data *tdata)
Method to determine authentication status of an incoming request.
Definition: res_pjsip.c:3377
void ast_sip_transport_state_unregister(struct ast_sip_tpmgr_state_callback *element)
Unregister a transport state notification callback element.
static struct test_val b
unsigned int tos
Definition: res_pjsip.h:241
struct ao2_container * ast_sip_location_retrieve_aor_contacts_filtered(const struct ast_sip_aor *aor, unsigned int flags)
Retrieve all contacts currently available for an AOR and filter based on flags.
Definition: location.c:252
pjsip_dialog * ast_sip_create_dialog_uac(const struct ast_sip_endpoint *endpoint, const char *aor_name, const char *request_user)
General purpose method for creating a UAC dialog with an endpoint.
Definition: res_pjsip.c:4028
static int rtcp_mux(struct ast_rtp *rtp, const unsigned char *packet)
struct ao2_container * ast_sip_get_endpoints(void)
Retrieve any endpoints available to sorcery.
int ast_sip_retrieve_auths_vector(const struct ast_sip_auth_vector *auth_ids, struct ast_sip_auth_objects_vector *auth_objects)
Return only reachable or unknown contacts.
Definition: res_pjsip.h:1009
struct ast_sip_service_route_vector * service_routes
Definition: res_pjsip.h:159
int ast_sip_append_body(pjsip_tx_data *tdata, const char *body_text)
Append body data to a SIP message.
Definition: res_pjsip.c:5114
Generic container type.
int ast_sip_location_update_contact(struct ast_sip_contact *contact)
Update a contact.
Definition: location.c:445
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:120
static int rewrite_contact(pjsip_rx_data *rdata, pjsip_dialog *dlg)
int ast_sip_location_add_contact(struct ast_sip_aor *aor, const char *uri, struct timeval expiration_time, const char *path_info, const char *user_agent, const char *via_addr, int via_port, const char *call_id, struct ast_sip_endpoint *endpoint)
Add a new contact to an AOR.
Definition: location.c:429
void ast_sip_tpselector_unref(pjsip_tpselector *selector)
Unreference a pjsip_tpselector.
Definition: res_pjsip.c:3987
int ast_sip_for_each_contact(const struct ast_sip_aor *aor, ao2_callback_fn on_contact, void *arg)
For every contact on an AOR call the given &#39;on_contact&#39; handler.
Definition: location.c:719
an interchangeable way of responding to authentication challenges
Definition: res_pjsip.h:975
int ast_sip_sched_task_get_name(struct ast_sip_sched_task *schtd, char *name, size_t maxlen)
Gets the task name.
NAT configuration options for endpoints.
Definition: res_pjsip.h:616
const ast_string_field aors
Definition: res_pjsip.h:821
ast_sip_auth_type
Methods of storing SIP digest authentication credentials.
Definition: res_pjsip.h:431
Error while registering transport monitor.
Definition: res_pjsip.h:3470
struct ast_dnsmgr_entry * external_media_address_refresher
Definition: res_pjsip.h:139
const ast_string_field uri
Definition: res_pjsip.h:303
Pluggable RTP Architecture.
struct ast_sip_contact * ast_sip_location_retrieve_contact(const char *contact_name)
Retrieve a named contact.
Definition: location.c:350
AST_VECTOR(ast_sip_service_route_vector, char *)
void ast_sip_transport_monitor_unregister_all(ast_transport_monitor_shutdown_cb cb, void *data, ast_transport_monitor_data_matcher matches)
Unregister a transport shutdown monitor from all reliable transports.
static struct ast_serializer_shutdown_group * shutdown_group
Shutdown group for options serializers.
Endpoint abstractions.
SIP body description.
Definition: res_pjsip.h:2027
pjsip_tls_setting tls
Definition: res_pjsip.h:209
int(* ast_sip_task)(void *user_data)
Definition: res_pjsip.h:1573
int ast_sip_send_out_of_dialog_request(pjsip_tx_data *tdata, struct ast_sip_endpoint *endpoint, int timeout, void *token, void(*callback)(void *token, pjsip_event *e))
General purpose method for sending an Out-Of-Dialog SIP request.
Definition: res_pjsip.c:4993
int ast_sip_transport_state_set_service_routes(const char *transport_name, struct ast_sip_service_route_vector *service_routes)
Sets the service routes on a child transport.
Session timers options.
Definition: res_pjsip.h:563
struct ast_dnsmgr_entry * external_signaling_address_refresher
Definition: res_pjsip.h:129
jack_status_t status
Definition: app_jack.c:146
unsigned int ast_sip_get_ignore_uri_user_options(void)
Retrieve the global setting &#39;ignore_uri_user_options&#39;.
DTLS configuration structure.
Definition: rtp_engine.h:554
int ast_sip_sched_task_cancel_by_name(const char *name)
Cancels the next invocation of a task by name.
int ast_sip_create_request(const char *method, struct pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint, const char *uri, struct ast_sip_contact *contact, pjsip_tx_data **tdata)
General purpose method for creating a SIP request.
Definition: res_pjsip.c:4490
Sorcery Data Access Layer API.
pj_ssl_cipher ciphers[SIP_TLS_MAX_CIPHERS]
Definition: res_pjsip.h:116
void(* ast_transport_monitor_shutdown_cb)(void *data)
Transport shutdown monitor callback.
Definition: res_pjsip.h:3445
void * ast_sip_dict_set(pj_pool_t *pool, void *ht, const char *key, void *val)
Set the value for the given key.
Definition: res_pjsip.c:5349
static int enabled
Definition: dnsmgr.c:91
Configuration for one-touch INFO recording.
Definition: res_pjsip.h:669
static struct test_val a
int ast_sip_set_tpselector_from_transport_name(const char *transport_name, pjsip_tpselector *selector)
Sets pjsip_tpselector from ast_sip_transport.
Definition: res_pjsip.c:3957