PJSIP Configurations/Settings
[Base Types]

---

Detailed Description

Data Structures
struct	pjsip_cfg_t
Defines
#define	PJSIP_MAX_TSX_COUNT   (1024-1)
#define	PJSIP_MAX_DIALOG_COUNT   (512-1)
#define	PJSIP_MAX_TRANSPORTS   (PJ_IOQUEUE_MAX_HANDLES)
#define	PJSIP_TPMGR_HTABLE_SIZE   31
#define	PJSIP_MAX_URL_SIZE   256
#define	PJSIP_MAX_MODULE   16
#define	PJSIP_MAX_PKT_LEN   2000
#define	PJSIP_ENCODE_SHORT_HNAME   0
#define	PJSIP_INCLUDE_ALLOW_HDR_IN_DLG   1
#define	PJSIP_SAFE_MODULE   1
#define	PJSIP_CHECK_VIA_SENT_BY   1
#define	PJSIP_UNESCAPE_IN_PLACE   0
#define	PJSIP_MAX_NET_EVENTS   1
#define	PJSIP_MAX_TIMED_OUT_ENTRIES   10
#define	PJSIP_TRANSPORT_IDLE_TIME   600
#define	PJSIP_MAX_TRANSPORT_USAGE   ((unsigned)-1)
#define	PJSIP_TCP_TRANSPORT_BACKLOG   5
#define	PJSIP_TCP_KEEP_ALIVE_INTERVAL   90
#define	PJSIP_TCP_KEEP_ALIVE_DATA   { "\r\n", 2 }
#define	PJSIP_TLS_KEEP_ALIVE_INTERVAL   90
#define	PJSIP_TLS_KEEP_ALIVE_DATA   { "\r\n", 2 }
#define	PJSIP_HAS_RESOLVER   1
#define	PJSIP_MAX_RESOLVED_ADDRESSES   8
#define	PJSIP_HAS_TLS_TRANSPORT   0
#define	PJSIP_TLS_TRANSPORT_BACKLOG   5
#define	PJSIP_MAX_TIMER_COUNT
#define	PJSIP_POOL_LEN_ENDPT   (4000)
#define	PJSIP_POOL_INC_ENDPT   (4000)
#define	PJSIP_POOL_RDATA_LEN   4000
#define	PJSIP_POOL_RDATA_INC   4000
#define	PJSIP_POOL_LEN_TRANSPORT   512
#define	PJSIP_POOL_INC_TRANSPORT   512
#define	PJSIP_POOL_LEN_TDATA   4000
#define	PJSIP_POOL_INC_TDATA   4000
#define	PJSIP_POOL_LEN_UA   512
#define	PJSIP_POOL_INC_UA   512
#define	PJSIP_MAX_FORWARDS_VALUE   70
#define	PJSIP_RFC3261_BRANCH_ID   "z9hG4bK"
#define	PJSIP_RFC3261_BRANCH_LEN   7
#define	PJSIP_POOL_TSX_LAYER_LEN   512
#define	PJSIP_POOL_TSX_LAYER_INC   512
#define	PJSIP_POOL_TSX_LEN   1536
#define	PJSIP_POOL_TSX_INC   256
#define	PJSIP_MAX_TSX_KEY_LEN   (PJSIP_MAX_URL_SIZE*2)
#define	PJSIP_POOL_LEN_USER_AGENT   1024
#define	PJSIP_POOL_INC_USER_AGENT   1024
#define	PJSIP_MAX_CALL_ID_LEN   pj_GUID_STRING_LENGTH()
#define	PJSIP_MAX_TAG_LEN   pj_GUID_STRING_LENGTH()
#define	PJSIP_MAX_BRANCH_LEN   (PJSIP_RFC3261_BRANCH_LEN + pj_GUID_STRING_LENGTH() + 2)
#define	PJSIP_MAX_HNAME_LEN   64
#define	PJSIP_POOL_LEN_DIALOG   1200
#define	PJSIP_POOL_INC_DIALOG   512
#define	PJSIP_MAX_HEADER_TYPES   64
#define	PJSIP_MAX_URI_TYPES   4
#define	PJSIP_T1_TIMEOUT   500
#define	PJSIP_T2_TIMEOUT   4000
#define	PJSIP_T4_TIMEOUT   5000
#define	PJSIP_TD_TIMEOUT   32000
#define	PJSIP_AUTH_HEADER_CACHING   0
#define	PJSIP_AUTH_AUTO_SEND_NEXT   0
#define	PJSIP_AUTH_QOP_SUPPORT   1
#define	PJSIP_MAX_STALE_COUNT   3
#define	PJSIP_HAS_DIGEST_AKA_AUTH   0
#define	PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH   5
#define	PJSIP_REGISTER_CLIENT_CHECK_CONTACT   1
#define	PJSIP_REGISTER_CLIENT_ADD_XUID_PARAM   0
Functions
pjsip_cfg_t *	pjsip_cfg (void)
Variables
pjsip_cfg_t	pjsip_sip_cfg_var

---

Define Documentation

#define PJSIP_MAX_TSX_COUNT   (1024-1)

Specify maximum transaction count in transaction hash table. For efficiency, the value should be 2^n-1 since it will be rounded up to 2^n.

Default value is 1023

#define PJSIP_MAX_DIALOG_COUNT   (512-1)

Specify maximum number of dialogs in the dialog hash table. For efficiency, the value should be 2^n-1 since it will be rounded up to 2^n.

Default value is 511.

#define PJSIP_MAX_TRANSPORTS   (PJ_IOQUEUE_MAX_HANDLES)

Specify maximum number of transports. Default value is equal to maximum number of handles in ioqueue. See also PJSIP_TPMGR_HTABLE_SIZE.

#define PJSIP_TPMGR_HTABLE_SIZE   31

Transport manager hash table size (must be 2^n-1). See also PJSIP_MAX_TRANSPORTS

#define PJSIP_MAX_URL_SIZE   256

Specify maximum URL size. This constant is used mainly when printing the URL for logging purpose only.

#define PJSIP_MAX_MODULE   16

Specify maximum number of modules. This mainly affects the size of mod_data array in various components.

#define PJSIP_MAX_PKT_LEN   2000

Maximum packet length. We set it more than MTU since a SIP PDU containing presence information can be quite large (>1500).

#define PJSIP_ENCODE_SHORT_HNAME   0

Encode SIP headers in their short forms to reduce size. By default, SIP headers in outgoing messages will be encoded in their full names. If this option is enabled, then SIP headers for outgoing messages will be encoded in their short forms, to reduce message size. Note that this does not affect the ability of PJSIP to parse incoming SIP messages, as the parser always supports parsing both the long and short version of the headers.

Note that there is also an undocumented variable defined in sip_msg.c to control whether compact form should be used for encoding SIP headers. The default value of this variable is PJSIP_ENCODE_SHORT_HNAME. To change PJSIP behavior during run-time, application can use the following construct:

   extern pj_bool_t pjsip_use_compact_form;
 
   // enable compact form
   pjsip_use_compact_form = PJ_TRUE;
 

Default is 0 (no)

#define PJSIP_INCLUDE_ALLOW_HDR_IN_DLG   1

Send Allow header in dialog establishing requests? RFC 3261 Allow header SHOULD be included in dialog establishing requests to inform remote agent about which SIP requests are allowed within dialog.

Note that there is also an undocumented variable defined in sip_dialog.c to control whether Allow header should be included. The default value of this variable is PJSIP_INCLUDE_ALLOW_HDR_IN_DLG. To change PJSIP behavior during run-time, application can use the following construct:

   extern pj_bool_t pjsip_include_allow_hdr_in_dlg;
 
   // do not transmit Allow header
   pjsip_include_allow_hdr_in_dlg = PJ_FALSE;
 

Default is 1 (Yes)

#define PJSIP_SAFE_MODULE   1

Allow SIP modules removal or insertions during operation? If yes, then locking will be employed when endpoint need to access module.

#define PJSIP_CHECK_VIA_SENT_BY   1

Perform Via sent-by checking as specified in RFC 3261 Section 18.1.2, which says that UAC MUST silently discard responses with Via sent-by containing values that the UAC doesn't recognize as its transport address.

In PJSIP, this will cause response to be discarded and a message is written to the log, saying something like: "Dropping response Response msg 200/INVITE/cseq=608594373 (rdata00A99EF4) from 1.2.3.4:5060 because sent-by is mismatch"

The default behavior is yes, but when the UA supports IP address change for the SIP transport, it will need to turn this checking off since when the transport address is changed between request is sent and response is received, the response will be discarded since its Via sent-by now contains address that is different than the transport address.

#define PJSIP_UNESCAPE_IN_PLACE   0

If non-zero, SIP parser will unescape the escape characters ('') in the original message, which means that it will modify the original message. Otherwise the parser will create a copy of the string and store the unescaped string to the new location.

Unescaping in-place is faster, but less elegant (and it may break certain applications). So normally it's disabled, unless when benchmarking (to show off big performance).

Default: 0

#define PJSIP_MAX_NET_EVENTS   1

This macro controls maximum numbers of ioqueue events to be processed in a single pjsip_endpt_handle_events() poll. When PJSIP detects that there are probably more events available from the network and total events so far is less than this value, PJSIP will call pj_ioqueue_poll() again to get more events.

Value 1 works best for ioqueue with select() back-end, while for IOCP it is probably best to set this value equal to PJSIP_MAX_TIMED_OUT_ENTRIES since IOCP only processes one event at a time.

Default: 1

#define PJSIP_MAX_TIMED_OUT_ENTRIES   10

Max entries to process in timer heap per poll.

Default: 10

#define PJSIP_TRANSPORT_IDLE_TIME   600

Idle timeout interval to be applied to transports with no usage before the transport is destroyed. Value is in seconds.

Default: 600

#define PJSIP_MAX_TRANSPORT_USAGE   ((unsigned)-1)

Maximum number of usages for a transport before a new transport is created. This only applies for ephemeral transports such as TCP.

Currently this is not used.

Default: -1

#define PJSIP_TCP_TRANSPORT_BACKLOG   5

The TCP incoming connection backlog number to be set in accept().

Default: 5

See also:

PJSIP_TLS_TRANSPORT_BACKLOG

#define PJSIP_TCP_KEEP_ALIVE_INTERVAL   90

Set the interval to send keep-alive packet for TCP transports. If the value is zero, keep-alive will be disabled for TCP.

Default: 90 (seconds)

See also:

PJSIP_TCP_KEEP_ALIVE_DATA

#define PJSIP_TCP_KEEP_ALIVE_DATA   { "\r\n", 2 }

Set the payload of the TCP keep-alive packet.

Default: CRLF

#define PJSIP_TLS_KEEP_ALIVE_INTERVAL   90

Set the interval to send keep-alive packet for TLS transports. If the value is zero, keep-alive will be disabled for TLS.

Default: 90 (seconds)

See also:

PJSIP_TLS_KEEP_ALIVE_DATA

#define PJSIP_TLS_KEEP_ALIVE_DATA   { "\r\n", 2 }

Set the payload of the TLS keep-alive packet.

Default: CRLF

#define PJSIP_HAS_RESOLVER   1

This macro specifies whether full DNS resolution should be used. When enabled, pjsip_resolve() will perform asynchronous DNS SRV and A (or AAAA, when IPv6 is supported) resolution to resolve the SIP domain.

Note that even when this setting is enabled, asynchronous DNS resolution will only be done when application calls pjsip_endpt_create_resolver(), configure the nameservers with pj_dns_resolver_set_ns(), and configure the SIP endpoint's DNS resolver with pjsip_endpt_set_resolver(). If these steps are not followed, the domain will be resolved with normal pj_gethostbyname() function.

Turning off this setting will save the footprint by about 16KB, since it should also exclude dns.o and resolve.o from PJLIB-UTIL.

Default: 1 (enabled)

See also:

PJSIP_MAX_RESOLVED_ADDRESSES

#define PJSIP_MAX_RESOLVED_ADDRESSES   8

Maximum number of addresses returned by the resolver. The number here will slightly affect stack usage, since each entry will occupy about 32 bytes of stack memory.

Default: 8

See also:

PJSIP_HAS_RESOLVER

#define PJSIP_HAS_TLS_TRANSPORT   0

Enable TLS SIP transport support. For most systems this means that OpenSSL must be installed.

Default: 0 (for now)

#define PJSIP_TLS_TRANSPORT_BACKLOG   5

The TLS pending incoming connection backlog number to be set in accept().

Default: 5

See also:

PJSIP_TCP_TRANSPORT_BACKLOG

#define PJSIP_MAX_TIMER_COUNT

Value:

(2*pjsip_cfg()->tsx.max_count + \
                                         2*PJSIP_MAX_DIALOG_COUNT)

#define PJSIP_POOL_LEN_ENDPT   (4000)

Initial memory block for the endpoint.

#define PJSIP_POOL_INC_ENDPT   (4000)

Memory increment for endpoint.

#define PJSIP_POOL_RDATA_LEN   4000

Initial memory block for rdata.

#define PJSIP_POOL_RDATA_INC   4000

Memory increment for rdata.

#define PJSIP_POOL_LEN_TDATA   4000

Initial memory block size for tdata.

#define PJSIP_POOL_INC_TDATA   4000

Memory increment for tdata.

#define PJSIP_POOL_LEN_UA   512

Initial memory size for UA layer

#define PJSIP_POOL_INC_UA   512

Memory increment for UA layer.

#define PJSIP_POOL_TSX_LAYER_LEN   512

Initial memory size for transaction layer. The bulk of pool usage for transaction layer will be used to create the hash table, so setting this value too high will not help too much with reducing fragmentation and the memory will most likely be wasted.

#define PJSIP_POOL_TSX_LAYER_INC   512

Memory increment for transaction layer. The bulk of pool usage for transaction layer will be used to create the hash table, so setting this value too high will not help too much with reducing fragmentation and the memory will most likely be wasted.

#define PJSIP_POOL_TSX_LEN   1536

Initial memory size for a SIP transaction object.

#define PJSIP_POOL_TSX_INC   256

Memory increment for transaction object.

#define PJSIP_T1_TIMEOUT   500

Transaction T1 timeout value.

#define PJSIP_T2_TIMEOUT   4000

Transaction T2 timeout value.

#define PJSIP_T4_TIMEOUT   5000

Transaction completed timer for non-INVITE

#define PJSIP_TD_TIMEOUT   32000

Transaction completed timer for INVITE

#define PJSIP_AUTH_HEADER_CACHING   0

If this flag is set, the stack will keep the Authorization/Proxy-Authorization headers that are sent in a cache. Future requests with the same realm and the same method will use the headers in the cache (as long as no qop is required by server).

Turning on this flag will make authorization process goes faster, but will grow the memory usage undefinitely until the dialog/registration session is terminated.

Default: 0

#define PJSIP_AUTH_AUTO_SEND_NEXT   0

If this flag is set, the stack will proactively send Authorization/Proxy- Authorization header for next requests. If next request has the same method with any of previous requests, then the last header which is saved in the cache will be used (if PJSIP_AUTH_CACHING is set). Otherwise a fresh header will be recalculated. If a particular server has requested qop, then a fresh header will always be calculated.

If this flag is NOT set, then the stack will only send Authorization/Proxy- Authorization headers when it receives 401/407 response from server.

Turning ON this flag will grow memory usage of a dialog/registration pool indefinitely until it is terminated, because the stack needs to keep the last WWW-Authenticate/Proxy-Authenticate challenge.

Default: 0

#define PJSIP_AUTH_QOP_SUPPORT   1

Support qop="auth" directive. This option also requires client to cache the last challenge offered by server.

Default: 1

#define PJSIP_MAX_STALE_COUNT   3

Maximum number of stale retries when server keeps rejecting our request with stale=true.

Default: 3

#define PJSIP_HAS_DIGEST_AKA_AUTH   0

Specify support for IMS/3GPP digest AKA authentication version 1 and 2 (AKAv1-MD5 and AKAv2-MD5 respectively).

Default: 0 (for now)

#define PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH   5

Specify the number of seconds to refresh the client registration before the registration expires.

Default: 5 seconds

#define PJSIP_REGISTER_CLIENT_CHECK_CONTACT   1

Specify whether client registration should check for its registered contact in Contact header of successful REGISTE response to determine whether registration has been successful. This setting may be disabled if non-compliant registrar is unable to return correct Contact header.

This setting can be changed in run-time by settting regc.check_contact field of pjsip_cfg().

Default is 1

#define PJSIP_REGISTER_CLIENT_ADD_XUID_PARAM   0

Specify whether client registration should add "x-uid" extension parameter in all Contact URIs that it registers to assist the matching of Contact URIs in the 200/OK REGISTER response, in case the registrar is unable to return exact Contact URI in the 200/OK response.

This setting can be changed in run-time by setting regc.add_xuid_param field of pjsip_cfg().

Default is 0.

---

Function Documentation

pjsip_cfg_t* pjsip_cfg

(

void

)

Get pjsip configuration instance. Application may modify the settings before creating the SIP endpoint and modules.

Returns:

Configuration instance.

References PJ_INLINE.