Group PJSUA_LIB_ACC

group PJSUA_LIB_ACC

PJSUA Accounts management.

PJSUA accounts provide identity (or identities) of the user who is currently using the application. In SIP terms, the identity is used as the From header in outgoing requests.

PJSUA-API supports creating and managing multiple accounts. The maximum number of accounts is limited by a compile time constant PJSUA_MAX_ACC.

Account may or may not have client registration associated with it. An account is also associated with route set and some authentication credentials, which are used when sending SIP request messages using the account. An account also has presence’s online status, which will be reported to remote peer when they subscribe to the account’s presence, or which is published to a presence server if presence publication is enabled for the account.

At least one account MUST be created in the application. If no user association is required, application can create a userless account by calling pjsua_acc_add_local(). A userless account identifies local endpoint instead of a particular user, and it correspond with a particular transport instance.

Also one account must be set as the default account, which is used as the account to use when PJSUA fails to match a request with any other accounts.

When sending outgoing SIP requests (such as making calls or sending instant messages), normally PJSUA requires the application to specify which account to use for the request. If no account is specified, PJSUA may be able to select the account by matching the destination domain name, and fall back to default account when no match is found.

Defines

PJSUA_MAX_ACC

Maximum accounts.

PJSUA_REG_INTERVAL

Default registration interval.

PJSUA_UNREG_TIMEOUT

Default maximum time to wait for account unregistration transactions to complete during library shutdown sequence.

Default: 4000 (4 seconds)

PJSUA_PUBLISH_EXPIRATION

Default PUBLISH expiration

PJSUA_DEFAULT_ACC_PRIORITY

Default account priority.

PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC

Maximum time to wait for unpublication transaction(s) to complete during shutdown process, before sending unregistration. The library tries to wait for the unpublication (un-PUBLISH) to complete before sending REGISTER request to unregister the account, during library shutdown process. If the value is set too short, it is possible that the unregistration is sent before unpublication completes, causing unpublication request to fail.

Default: 2000 (2 seconds)

PJSUA_REG_RETRY_INTERVAL

Default auto retry re-registration interval, in seconds. Set to 0 to disable this. Application can set the timer on per account basis by setting the pjsua_acc_config.reg_retry_interval field instead.

Default: 300 (5 minutes)

PJSUA_REG_AUTO_REG_REFRESH

When the registration is successfull, the auto registration refresh will be sent before it expires. Setting this to 0 will disable it. This is useful for app that uses Push Notification and doesn’t require auto registration refresh. App can periodically send refresh registration or send it before making a call.= See https://github.com/pjsip/pjproject/pull/2652 for more info.

Default: 1 (enabled)

PJSUA_CONTACT_REWRITE_METHOD

This macro specifies the default value for contact_rewrite_method field in pjsua_acc_config. It specifies how Contact update will be done with the registration, if allow_contact_rewrite is enabled in the account config. See pjsua_contact_rewrite_method for the options.

Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.

Default value: PJSUA_CONTACT_REWRITE_NO_UNREG(2) | PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE(4)

PJSUA_REG_USE_OUTBOUND_PROXY

Bit value used in pjsua_acc_config.reg_use_proxy field to indicate that the global outbound proxy list should be added to the REGISTER request.

PJSUA_REG_USE_ACC_PROXY

Bit value used in pjsua_acc_config.reg_use_proxy field to indicate that the account proxy list should be added to the REGISTER request.

PJSUA_CALL_HOLD_TYPE_DEFAULT

Specify the default call hold type to be used in pjsua_acc_config.

Default is PJSUA_CALL_HOLD_TYPE_RFC3264, and there’s no reason to change this except if you’re communicating with an old/non-standard peer.

Enums

enum pjsua_call_hold_type

This enumeration specifies how we should offer call hold request to remote peer. The default value is set by compile time constant PJSUA_CALL_HOLD_TYPE_DEFAULT, and application may control the setting on per-account basis by manipulating call_hold_type field in pjsua_acc_config.

Values:

enumerator PJSUA_CALL_HOLD_TYPE_RFC3264

This will follow RFC 3264 recommendation to use a=sendonly, a=recvonly, and a=inactive attribute as means to signal call hold status. This is the correct value to use.

enumerator PJSUA_CALL_HOLD_TYPE_RFC2543

This will use the old and deprecated method as specified in RFC 2543, and will offer c=0.0.0.0 in the SDP instead. Using this has many drawbacks such as inability to keep the media transport alive while the call is being put on hold, and should only be used if remote does not understand RFC 3264 style call hold offer.

enum pjsua_stun_use

This enumeration controls the use of STUN in the account.

Values:

enumerator PJSUA_STUN_USE_DEFAULT

Follow the default setting in the global pjsua_config.

enumerator PJSUA_STUN_USE_DISABLED

Disable STUN. If STUN is not enabled in the global pjsua_config, this setting has no effect.

enumerator PJSUA_STUN_RETRY_ON_FAILURE

Retry other STUN servers if the STUN server selected during startup (pjsua_init()) or after calling pjsua_update_stun_servers() is unavailable during runtime. This setting is valid only for account’s media STUN setting and if the call is using UDP media transport.

enum pjsua_upnp_use

This enumeration controls the use of UPnP in the account.

Values:

enumerator PJSUA_UPNP_USE_DEFAULT

Follow the default setting in the global pjsua_config.

enumerator PJSUA_UPNP_USE_DISABLED

Disable UPnP.

enum pjsua_ice_config_use

This enumeration controls the use of ICE settings in the account.

Values:

enumerator PJSUA_ICE_CONFIG_USE_DEFAULT

Use the default settings in the global pjsua_media_config.

enumerator PJSUA_ICE_CONFIG_USE_CUSTOM

Use the custom pjsua_ice_config setting in the account.

enum pjsua_turn_config_use

This enumeration controls the use of TURN settings in the account.

Values:

enumerator PJSUA_TURN_CONFIG_USE_DEFAULT

Use the default setting in the global pjsua_media_config.

enumerator PJSUA_TURN_CONFIG_USE_CUSTOM

Use the custom pjsua_turn_config setting in the account.

enum pjsua_ipv6_use

Specify how IPv6 transport should be used in account config. IP version preference only applies for outgoing direction, for incoming direction, we will check the corresponding message/offer and match it.

Values:

enumerator PJSUA_IPV6_DISABLED

IPv6 is not used.

enumerator PJSUA_IPV6_ENABLED

IPv6 is enabled.

enumerator PJSUA_IPV6_ENABLED_NO_PREFERENCE
enumerator PJSUA_IPV6_ENABLED_PREFER_IPV4

IPv6 is enabled, but IPv4 is preferable.

enumerator PJSUA_IPV6_ENABLED_PREFER_IPV6

IPv6 is enabled and preferable.

enumerator PJSUA_IPV6_ENABLED_USE_IPV6_ONLY

Only IPv6 is enabled, IPv4 will not be used.

enum pjsua_nat64_opt

Specify NAT64 options to be used in account config.

Values:

enumerator PJSUA_NAT64_DISABLED

NAT64 is not used.

enumerator PJSUA_NAT64_ENABLED

NAT64 is enabled.

Functions

void pjsua_ice_config_from_media_config(pj_pool_t *pool, pjsua_ice_config *dst, const pjsua_media_config *src)

Initialize ICE config from a media config. If the pool argument is NULL, a simple memcpy() will be used.

Parameters:

  • pool – Memory to duplicate strings.

  • dst – Destination config.

  • src – Source config.

void pjsua_ice_config_dup(pj_pool_t *pool, pjsua_ice_config *dst, const pjsua_ice_config *src)

Clone. If the pool argument is NULL, a simple memcpy() will be used.

Parameters:

  • pool – Memory to duplicate strings.

  • dst – Destination config.

  • src – Source config.

void pjsua_turn_config_from_media_config(pj_pool_t *pool, pjsua_turn_config *dst, const pjsua_media_config *src)

Initialize TURN config from a media config. If the pool argument is NULL, a simple memcpy() will be used.

Parameters:

  • pool – Memory to duplicate strings.

  • dst – Destination config.

  • src – Source config.

void pjsua_turn_config_dup(pj_pool_t *pool, pjsua_turn_config *dst, const pjsua_turn_config *src)

Clone. If the pool argument is NULL, a simple memcpy() will be used.

Parameters:

  • pool – Memory to duplicate strings.

  • dst – Destination config.

  • src – Source config.

void pjsua_srtp_opt_default(pjsua_srtp_opt *cfg)

Call this function to initialize SRTP config with default values.

Parameters:

cfg – The SRTP config to be initialized.

void pjsua_srtp_opt_dup(pj_pool_t *pool, pjsua_srtp_opt *dst, const pjsua_srtp_opt *src, pj_bool_t check_str)

Duplicate SRTP transport setting. If the pool argument is NULL, a simple memcpy() will be used.

Parameters:

  • pool – Memory to duplicate strings.

  • dst – Destination setting.

  • src – Source setting.

  • check_str – If set to TRUE, the function will check if strings are identical before copying. Identical strings will not be duplicated. If set to FALSE, all strings will be duplicated.

void pjsua_acc_config_default(pjsua_acc_config *cfg)

Call this function to initialize account config with default values.

Parameters:

cfg – The account config to be initialized.

void pjsua_acc_config_dup(pj_pool_t *pool, pjsua_acc_config *dst, const pjsua_acc_config *src)

Duplicate account config.

Parameters:

  • pool – Pool to be used for duplicating the config.

  • dst – Destination configuration.

  • src – Source configuration.

unsigned pjsua_acc_get_count(void)

Get number of current accounts.

Returns:

Current number of accounts.

pj_bool_t pjsua_acc_is_valid(pjsua_acc_id acc_id)

Check if the specified account ID is valid.

Parameters:

acc_id – Account ID to check.

Returns:

Non-zero if account ID is valid.

pj_status_t pjsua_acc_set_default(pjsua_acc_id acc_id)

Set default account to be used when incoming and outgoing requests doesn’t match any accounts.

Parameters:

acc_id – The account ID to be used as default.

Returns:

PJ_SUCCESS on success.

pjsua_acc_id pjsua_acc_get_default(void)

Get default account to be used when receiving incoming requests (calls), when the destination of the incoming call doesn’t match any other accounts.

Returns:

The default account ID, or PJSUA_INVALID_ID if no default account is configured.

pj_status_t pjsua_acc_add(const pjsua_acc_config *acc_cfg, pj_bool_t is_default, pjsua_acc_id *p_acc_id)

Add a new account to pjsua. PJSUA must have been initialized (with pjsua_init()) before calling this function. If registration is configured for this account, this function would also start the SIP registration session with the SIP registrar server. This SIP registration session will be maintained internally by the library, and application doesn’t need to do anything to maintain the registration session.

Parameters:

  • acc_cfg – Account configuration.

  • is_default – If non-zero, this account will be set as the default account. The default account will be used when sending outgoing requests (e.g. making call) when no account is specified, and when receiving incoming requests when the request does not match any accounts. It is recommended that default account is set to local/LAN account.

  • p_acc_id – Pointer to receive account ID of the new account.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_acc_add_local(pjsua_transport_id tid, pj_bool_t is_default, pjsua_acc_id *p_acc_id)

Add a local account. A local account is used to identify local endpoint instead of a specific user, and for this reason, a transport ID is needed to obtain the local address information.

Parameters:

  • tid – Transport ID to generate account address.

  • is_default – If non-zero, this account will be set as the default account. The default account will be used when sending outgoing requests (e.g. making call) when no account is specified, and when receiving incoming requests when the request does not match any accounts. It is recommended that default account is set to local/LAN account.

  • p_acc_id – Pointer to receive account ID of the new account.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_acc_set_user_data(pjsua_acc_id acc_id, void *user_data)

Set arbitrary data to be associated with the account.

Parameters:

  • acc_id – The account ID.

  • user_data – User/application data.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

void *pjsua_acc_get_user_data(pjsua_acc_id acc_id)

Retrieve arbitrary data associated with the account.

Parameters:

acc_id – The account ID.

Returns:

The user data. In the case where the account ID is not valid, NULL is returned.

pj_status_t pjsua_acc_del(pjsua_acc_id acc_id)

Delete an account. This will unregister the account from the SIP server, if necessary, and terminate server side presence subscriptions associated with this account.

Parameters:

acc_id – Id of the account to be deleted.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_acc_get_config(pjsua_acc_id acc_id, pj_pool_t *pool, pjsua_acc_config *acc_cfg)

Get current config for the account. This will copy current account setting to the specified parameter. Note that all pointers in the settings will point to the original settings in the account and application must not modify the values in any way. Application must also take care that these data is only valid until the account is destroyed.

Parameters:

  • acc_id – The account ID.

  • pool – Pool to duplicate the config.

  • acc_cfg – Structure to receive the settings.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_acc_modify(pjsua_acc_id acc_id, const pjsua_acc_config *acc_cfg)

Modify account configuration setting. This function may trigger unregistration (of old account setting) and re-registration (of the new account setting), e.g: changing account ID, credential, registar, or proxy setting.

Note:

  • when the new config triggers unregistration, the pjsua callback on_reg_state()/on_reg_state2() for the unregistration will not be called and any failure in the unregistration will be ignored, so if application needs to be sure about the unregistration status, it should unregister manually and wait for the callback before calling this function

  • when the new config triggers re-registration and the re-registration fails, the account setting will not be reverted back to the old setting and the account will be in unregistered state.

Parameters:

  • acc_id – Id of the account to be modified.

  • acc_cfg – New account configuration.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_acc_set_online_status(pjsua_acc_id acc_id, pj_bool_t is_online)

Modify account’s presence status to be advertised to remote/presence subscribers. This would trigger the sending of outgoing NOTIFY request if there are server side presence subscription for this account, and/or outgoing PUBLISH if presence publication is enabled for this account.

See also

pjsua_acc_set_online_status2()

Parameters:

  • acc_id – The account ID.

  • is_online – True of false.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_acc_set_online_status2(pjsua_acc_id acc_id, pj_bool_t is_online, const pjrpid_element *pr)

Modify account’s presence status to be advertised to remote/presence subscribers. This would trigger the sending of outgoing NOTIFY request if there are server side presence subscription for this account, and/or outgoing PUBLISH if presence publication is enabled for this account.

See also

pjsua_acc_set_online_status()

Parameters:

  • acc_id – The account ID.

  • is_online – True of false.

  • pr – Extended information in subset of RPID format which allows setting custom presence text.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_acc_set_registration(pjsua_acc_id acc_id, pj_bool_t renew)

Update registration or perform unregistration. If registration is configured for this account, then initial SIP REGISTER will be sent when the account is added with pjsua_acc_add(). Application normally only need to call this function if it wants to manually update the registration or to unregister from the server.

Parameters:

  • acc_id – The account ID.

  • renew – If renew argument is zero, this will start unregistration process.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_acc_get_info(pjsua_acc_id acc_id, pjsua_acc_info *info)

Get information about the specified account.

Parameters:

  • acc_id – Account identification.

  • info – Pointer to receive account information.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_enum_accs(pjsua_acc_id ids[], unsigned *count)

Enumerate all account currently active in the library. This will fill the array with the account Ids, and application can then query the account information for each id with pjsua_acc_get_info().

See also

pjsua_acc_enum_info().

Parameters:

  • ids – Array of account IDs to be initialized.

  • count – In input, specifies the maximum number of elements. On return, it contains the actual number of elements.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_acc_enum_info(pjsua_acc_info info[], unsigned *count)

Enumerate account informations.

Parameters:

  • info – Array of account infos to be initialized.

  • count – In input, specifies the maximum number of elements. On return, it contains the actual number of elements.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pjsua_acc_id pjsua_acc_find_for_outgoing(const pj_str_t *url)

This is an internal function to find the most appropriate account to used to reach to the specified URL.

Parameters:

url – The remote URL to reach.

Returns:

Account id.

pjsua_acc_id pjsua_acc_find_for_incoming(pjsip_rx_data *rdata)

This is an internal function to find the most appropriate account to be used to handle incoming calls.

Parameters:

rdata – The incoming request message.

Returns:

Account id.

pj_status_t pjsua_acc_create_request(pjsua_acc_id acc_id, const pjsip_method *method, const pj_str_t *target, pjsip_tx_data **p_tdata)

Create arbitrary requests using the account. Application should only use this function to create auxiliary requests outside dialog, such as OPTIONS, and use the call or presence API to create dialog related requests.

Parameters:

  • acc_id – The account ID.

  • method – The SIP method of the request.

  • target – Target URI.

  • p_tdata – Pointer to receive the request.

Returns:

PJ_SUCCESS or the error code.

pj_status_t pjsua_acc_create_uac_contact(pj_pool_t *pool, pj_str_t *contact, pjsua_acc_id acc_id, const pj_str_t *uri)

Create a suitable Contact header value, based on the specified target URI for the specified account.

Parameters:

  • pool – Pool to allocate memory for the string.

  • contact – The string where the Contact will be stored.

  • acc_id – Account ID.

  • uri – Destination URI of the request.

Returns:

PJ_SUCCESS on success, other on error.

pj_status_t pjsua_acc_create_uas_contact(pj_pool_t *pool, pj_str_t *contact, pjsua_acc_id acc_id, pjsip_rx_data *rdata)

Create a suitable Contact header value, based on the information in the incoming request.

Parameters:

  • pool – Pool to allocate memory for the string.

  • contact – The string where the Contact will be stored.

  • acc_id – Account ID.

  • rdata – Incoming request.

Returns:

PJ_SUCCESS on success, other on error.

pj_status_t pjsua_acc_set_transport(pjsua_acc_id acc_id, pjsua_transport_id tp_id)

Lock/bind this account to a specific transport/listener. Normally application shouldn’t need to do this, as transports will be selected automatically by the stack according to the destination.

When account is locked/bound to a specific transport, all outgoing requests from this account will use the specified transport (this includes SIP registration, dialog (call and event subscription), and out-of-dialog requests such as MESSAGE).

Note that transport_id may be specified in pjsua_acc_config too.

Parameters:

  • acc_id – The account ID.

  • tp_id – The transport ID.

Returns:

PJ_SUCCESS on success.

struct pjsua_ice_config
#include <pjsua.h>

ICE setting. This setting is used in the pjsua_acc_config.

Public Members

pj_bool_t enable_ice

Enable ICE.

int ice_max_host_cands

Set the maximum number of host candidates.

Default: -1 (maximum not set)

pj_ice_sess_options ice_opt

ICE session options.

pj_bool_t ice_no_rtcp

Disable RTCP component.

Default: no

pj_bool_t ice_always_update

Send re-INVITE/UPDATE every after ICE connectivity check regardless the default ICE transport address is changed or not. When this is set to PJ_FALSE, re-INVITE/UPDATE will be sent only when the default ICE transport address is changed.

Default: yes

struct pjsua_turn_config
#include <pjsua.h>

TURN setting. This setting is used in the pjsua_acc_config.

Public Members

pj_bool_t enable_turn

Enable TURN candidate in ICE.

pj_str_t turn_server

Specify TURN domain name or host name, in in “DOMAIN:PORT” or “HOST:PORT” format.

pj_turn_tp_type turn_conn_type

Specify the connection type to be used to the TURN server. Valid values are PJ_TURN_TP_UDP, PJ_TURN_TP_TCP or PJ_TURN_TP_TLS.

Default: PJ_TURN_TP_UDP

pj_stun_auth_cred turn_auth_cred

Specify the credential to authenticate with the TURN server.

pj_turn_sock_tls_cfg turn_tls_setting

This specifies TLS settings for TURN TLS. It’s only applicable when TLS is used to connect to the TURN server.

struct pjsua_acc_config
#include <pjsua.h>

This structure describes account configuration to be specified when adding a new account with pjsua_acc_add(). Application MUST initialize this structure first by calling pjsua_acc_config_default().

Public Members

void *user_data

Arbitrary user data to be associated with the newly created account. Application may set this later with pjsua_acc_set_user_data() and retrieve it with pjsua_acc_get_user_data().

int priority

Account priority, which is used to control the order of matching incoming/outgoing requests. The higher the number means the higher the priority is, and the account will be matched first.

pj_str_t id

The full SIP URL for the account. The value can take name address or URL format, and will look something like “sip:account@serviceprovider” or “"Display Name” <sip:account@provider>”.

This field is mandatory.

pj_str_t reg_uri

This is the URL to be put in the request URI for the registration, and will look something like “sip:serviceprovider”.

This field should be specified if registration is desired. If the value is empty, no account registration will be performed.

pjsip_hdr reg_hdr_list

The optional custom SIP headers to be put in the registration request.

pj_str_t reg_contact_params

Additional parameters that will be appended in the Contact header for this account. This will only affect REGISTER requests and will be appended after contact_params;

The parameters should be preceeded by semicolon, and all strings must be properly escaped. Example: “;my-param=X;another-param=Hi%20there”

pj_str_t reg_contact_uri_params

Additional URI parameters that will be appended in the Contact URI for this account. This will only affect REGISTER requests and will be appended after contact_uri_params;

The parameters should be preceeded by semicolon, and all strings must be properly escaped. Example: “;my-param=X;another-param=Hi%20there”

pjsip_hdr sub_hdr_list

The optional custom SIP headers to be put in the presence subscription request.

pj_bool_t mwi_enabled

Subscribe to message waiting indication events (RFC 3842).

See also enable_unsolicited_mwi field on pjsua_config.

Default: no

unsigned mwi_expires

Specify the default expiration time for Message Waiting Indication (RFC 3842) event subscription. This must not be zero.

Default: PJSIP_MWI_DEFAULT_EXPIRES

pj_bool_t publish_enabled

If this flag is set, the presence information of this account will be PUBLISH-ed to the server where the account belongs.

Default: PJ_FALSE

pjsip_publishc_opt publish_opt

Event publication options.

unsigned unpublish_max_wait_time_msec

Maximum time to wait for unpublication transaction(s) to complete during shutdown process, before sending unregistration. The library tries to wait for the unpublication (un-PUBLISH) to complete before sending REGISTER request to unregister the account, during library shutdown process. If the value is set too short, it is possible that the unregistration is sent before unpublication completes, causing unpublication request to fail.

Default: PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC

pjsip_auth_clt_pref auth_pref

Authentication preference.

pj_str_t pidf_tuple_id

Optional PIDF tuple ID for outgoing PUBLISH and NOTIFY. If this value is not specified, a random string will be used.

pj_str_t force_contact

Optional URI to be put as Contact for this account. It is recommended that this field is left empty, so that the value will be calculated automatically based on the transport address.

pj_str_t contact_params

Additional parameters that will be appended in the Contact header for this account. This will affect the Contact header in all SIP messages sent on behalf of this account, including but not limited to REGISTER, INVITE, and SUBCRIBE requests or responses.

The parameters should be preceeded by semicolon, and all strings must be properly escaped. Example: “;my-param=X;another-param=Hi%20there”

pj_str_t contact_uri_params

Additional URI parameters that will be appended in the Contact URI for this account. This will affect the Contact URI in all SIP messages sent on behalf of this account, including but not limited to REGISTER, INVITE, and SUBCRIBE requests or responses.

The parameters should be preceeded by semicolon, and all strings must be properly escaped. Example: “;my-param=X;another-param=Hi%20there”

pjsua_100rel_use require_100rel

Specify how support for reliable provisional response (100rel/ PRACK) should be used for all sessions in this account. See the documentation of pjsua_100rel_use enumeration for more info.

Default: The default value is taken from the value of require_100rel in pjsua_config.

pjsua_sip_timer_use use_timer

Specify the usage of Session Timers for all sessions. See the pjsua_sip_timer_use for possible values.

Default: PJSUA_SIP_TIMER_OPTIONAL

pjsip_timer_setting timer_setting

Specify Session Timer settings, see pjsip_timer_setting.

unsigned proxy_cnt

Number of proxies in the proxy array below.

pj_str_t proxy[8]

Optional URI of the proxies to be visited for all outgoing requests that are using this account (REGISTER, INVITE, etc). Application need to specify these proxies if the service provider requires that requests destined towards its network should go through certain proxies first (for example, border controllers).

These proxies will be put in the route set for this account, with maintaining the orders (the first proxy in the array will be visited first). If global outbound proxies are configured in pjsua_config, then these account proxies will be placed after the global outbound proxies in the routeset.

unsigned lock_codec

If remote sends SDP answer containing more than one format or codec in the media line, send re-INVITE or UPDATE with just one codec to lock which codec to use.

Default: 1 (Yes). Set to zero to disable.

unsigned reg_timeout

Optional interval for registration, in seconds. If the value is zero, default interval will be used (PJSUA_REG_INTERVAL, 300 seconds).

unsigned reg_delay_before_refresh

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

Default: PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH, 5 seconds

unsigned unreg_timeout

Specify the maximum time to wait for unregistration requests to complete during library shutdown sequence.

Default: PJSUA_UNREG_TIMEOUT

unsigned cred_count

Number of credentials in the credential array.

pjsip_cred_info cred_info[8]

Array of credentials. If registration is desired, normally there should be at least one credential specified, to successfully authenticate against the service provider. More credentials can be specified, for example when the requests are expected to be challenged by the proxies in the route set.

pjsua_transport_id transport_id

Optionally bind this account to specific transport. This normally is not a good idea, as account should be able to send requests using any available transports according to the destination. But some application may want to have explicit control over the transport to use, so in that case it can set this field.

Default: -1 (PJSUA_INVALID_ID)

See also

pjsua_acc_set_transport()

pj_bool_t allow_contact_rewrite

This option is used to update the transport address and the Contact header of REGISTER request. When this option is enabled, the library will keep track of the public IP address from the response of REGISTER request. Once it detects that the address has changed, it will unregister current Contact, update the Contact with transport address learned from Via header, and register a new Contact to the registrar. This will also update the public name of UDP transport if STUN is configured.

Possible values:

  • 0 (disabled).

  • 1 (enabled). Update except if both Contact and server’s IP address are public but response contains private IP.

  • 2 (enabled). Update without exception.

See also contact_rewrite_method field.

Default: 1

int contact_rewrite_method

Specify how Contact update will be done with the registration, if allow_contact_rewrite is enabled. The value is bitmask combination of pjsua_contact_rewrite_method. See also pjsua_contact_rewrite_method.

Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.

Default value: PJSUA_CONTACT_REWRITE_METHOD (PJSUA_CONTACT_REWRITE_NO_UNREG | PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE)

pj_bool_t contact_use_src_port

Specify if source TCP port should be used as the initial Contact address if TCP/TLS transport is used. Note that this feature will be automatically turned off when nameserver is configured because it may yield different destination address due to DNS SRV resolution. Also some platforms are unable to report the local address of the TCP socket when it is still connecting. In these cases, this feature will also be turned off.

Default: PJ_TRUE (yes).

pj_bool_t allow_via_rewrite

This option is used to overwrite the “sent-by” field of the Via header for outgoing messages with the same interface address as the one in the REGISTER request, as long as the request uses the same transport instance as the previous REGISTER request.

Default: 1 (yes)

pj_bool_t allow_sdp_nat_rewrite

This option controls whether the IP address in SDP should be replaced with the IP address found in Via header of the REGISTER response, ONLY when STUN and ICE are not used. If the value is FALSE (the original behavior), then the local IP address will be used. If TRUE, and when STUN and ICE are disabled, then the IP address found in registration response will be used.

Default: PJ_FALSE (no)

unsigned use_rfc5626

Control the use of SIP outbound feature. SIP outbound is described in RFC 5626 to enable proxies or registrar to send inbound requests back to UA using the same connection initiated by the UA for its registration. This feature is highly useful in NAT-ed deployemtns, hence it is enabled by default.

Note: currently SIP outbound can only be used with TCP and TLS transports. If UDP is used for the registration, the SIP outbound feature will be silently ignored for the account.

Default: PJ_TRUE

pj_str_t rfc5626_instance_id

Specify SIP outbound (RFC 5626) instance ID to be used by this application. If empty, an instance ID will be generated based on the hostname of this agent. If application specifies this parameter, the value will look like “<urn:uuid:00000000-0000-1000-8000-AABBCCDDEEFF>” without the doublequote.

Default: empty

pj_str_t rfc5626_reg_id

Specify SIP outbound (RFC 5626) registration ID. The default value is empty, which would cause the library to automatically generate a suitable value.

Default: empty

unsigned ka_interval

Set the interval for periodic keep-alive transmission for this account. If this value is zero, keep-alive will be disabled for this account. The keep-alive transmission will be sent to the registrar’s address, after successful registration.

Default: 15 (seconds)

pj_str_t ka_data

Specify the data to be transmitted as keep-alive packets.

Default: CR-LF

pj_bool_t vid_in_auto_show

Specify whether incoming video should be shown to screen by default. This applies to incoming call (INVITE), incoming re-INVITE, and incoming UPDATE requests.

Regardless of this setting, application can detect incoming video by implementing on_call_media_state() callback and enumerating the media stream(s) with pjsua_call_get_info(). Once incoming video is recognised, application may retrieve the window associated with the incoming video and show or hide it with pjsua_vid_win_set_show().

Default: PJ_FALSE

pj_bool_t vid_out_auto_transmit

Specify whether outgoing video should be activated by default when making outgoing calls and/or when incoming video is detected. This applies to incoming and outgoing calls, incoming re-INVITE, and incoming UPDATE. If the setting is non-zero, outgoing video transmission will be started as soon as response to these requests is sent (or received).

Regardless of the value of this setting, application can start and stop outgoing video transmission with pjsua_call_set_vid_strm().

Default: PJ_FALSE

unsigned vid_wnd_flags

Specify video window’s flags. The value is a bitmask combination of pjmedia_vid_dev_wnd_flag.

Default: 0

pjmedia_vid_dev_index vid_cap_dev

Specify the default capture device to be used by this account. If vid_out_auto_transmit is enabled, this device will be used for capturing video.

Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV

pjmedia_vid_dev_index vid_rend_dev

Specify the default rendering device to be used by this account.

Default: PJMEDIA_VID_DEFAULT_RENDER_DEV

pjmedia_vid_stream_rc_config vid_stream_rc_cfg

Specify the send rate control for video stream.

Default: see pjmedia_vid_stream_rc_config

pjmedia_vid_stream_sk_config vid_stream_sk_cfg

Specify the send keyframe config for video stream.

Default: see pjmedia_vid_stream_sk_config

pjsua_transport_config rtp_cfg

Media transport config.

For port and port_range settings, RTCP port is selected as RTP port+1. Example: port=5000, port_range=4

  • Available ports: 5000, 5002, 5004 (Media/RTP transport) 5001, 5003, 5005 (Media/RTCP transport)

pjsua_nat64_opt nat64_opt

Specify NAT64 options.

Default: PJSUA_NAT64_DISABLED

pjsua_ipv6_use ipv6_sip_use

Specify whether IPv6 should be used for SIP signalling.

Default: PJSUA_IPV6_ENABLED_NO_PREFERENCE (IP version used will be based on the address resolution returned by OS/resolver)

pjsua_ipv6_use ipv6_media_use

Specify whether IPv6 should be used on media.

Default: PJSUA_IPV6_ENABLED_PREFER_IPV4 (Dual stack media, capable to use IPv4/IPv6. Outgoing offer will prefer to use IPv4)

pjsua_stun_use sip_stun_use

Control the use of STUN for the SIP signaling.

Default: PJSUA_STUN_USE_DEFAULT

pjsua_stun_use media_stun_use

Control the use of STUN for the media transports.

Default: PJSUA_STUN_RETRY_ON_FAILURE

pjsua_upnp_use sip_upnp_use

Control the use of UPnP for the SIP signaling.

Default: PJSUA_UPNP_USE_DEFAULT

pjsua_upnp_use media_upnp_use

Control the use of UPnP for the media transports.

Default: PJSUA_UPNP_USE_DEFAULT

pj_bool_t use_loop_med_tp

Use loopback media transport. This may be useful if application doesn’t want PJSIP to create real media transports/sockets, such as when using third party media.

Default: PJ_FALSE

pj_bool_t enable_loopback

Enable local loopback when loop_med_tp_use is set to PJ_TRUE. If enabled, packets sent to the transport will be sent back to the streams attached to the transport.

Default: PJ_FALSE

pjsua_ice_config_use ice_cfg_use

Control the use of ICE in the account. By default, the settings in the pjsua_media_config will be used.

Default: PJSUA_ICE_CONFIG_USE_DEFAULT

pjsua_ice_config ice_cfg

The custom ICE setting for this account. This setting will only be used if ice_cfg_use is set to PJSUA_ICE_CONFIG_USE_CUSTOM

pjsua_turn_config_use turn_cfg_use

Control the use of TURN in the account. By default, the settings in the pjsua_media_config will be used

Default: PJSUA_TURN_CONFIG_USE_DEFAULT

pjsua_turn_config turn_cfg

The custom TURN setting for this account. This setting will only be used if turn_cfg_use is set to PJSUA_TURN_CONFIG_USE_CUSTOM

pjmedia_srtp_use use_srtp

Specify whether secure media transport should be used for this account. Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and PJMEDIA_SRTP_MANDATORY.

Default: PJSUA_DEFAULT_USE_SRTP

int srtp_secure_signaling

Specify whether SRTP requires secure signaling to be used. This option is only used when use_srtp option above is non-zero.

Valid values are: 0: SRTP does not require secure signaling 1: SRTP requires secure transport such as TLS 2: SRTP requires secure end-to-end transport (SIPS)

Default: PJSUA_DEFAULT_SRTP_SECURE_SIGNALING

pj_bool_t srtp_optional_dup_offer

This setting has been deprecated and will be ignored.

pjsua_srtp_opt srtp_opt

Specify SRTP transport setting. Application can initialize it with default values using pjsua_srtp_opt_default().

unsigned reg_retry_interval

Specify interval of auto registration retry upon registration failure, in seconds. Set to 0 to disable auto re-registration. Note that registration will only be automatically retried for temporal failures considered to be recoverable in relatively short term, such as: 408 (Request Timeout), 480 (Temporarily Unavailable), 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), 504 (Server Timeout), 6xx (global failure), and failure caused by transport problem. For registration retry caused by transport failure, the first retry will be done after reg_first_retry_interval seconds instead. Note that the interval will be randomized slightly by some seconds (specified in reg_retry_random_interval) to avoid all clients re-registering at the same time.

See also reg_first_retry_interval setting.

Default: PJSUA_REG_RETRY_INTERVAL

unsigned reg_first_retry_interval

This specifies the interval for the first registration retry. The registration retry is explained in reg_retry_interval. Note that the value here will also be randomized by some seconds (specified in reg_retry_random_interval) to avoid all clients re-registering at the same time.

Default: 0

unsigned reg_retry_random_interval

This specifies maximum randomized value to be added/substracted to/from the registration retry interval specified in reg_retry_interval and reg_first_retry_interval, in second. This is useful to avoid all clients re-registering at the same time. For example, if the registration retry interval is set to 100 seconds and this is set to 10 seconds, the actual registration retry interval will be in the range of 90 to 110 seconds.

Default: 10

pj_bool_t drop_calls_on_reg_fail

Specify whether calls of the configured account should be dropped after registration failure and an attempt of re-registration has also failed.

Default: PJ_FALSE (disabled)

unsigned reg_use_proxy

Specify how the registration uses the outbound and account proxy settings. This controls if and what Route headers will appear in the REGISTER request of this account. The value is bitmask combination of PJSUA_REG_USE_OUTBOUND_PROXY and PJSUA_REG_USE_ACC_PROXY bits. If the value is set to 0, the REGISTER request will not use any proxy (i.e. it will not have any Route headers).

Default: 3 (PJSUA_REG_USE_OUTBOUND_PROXY | PJSUA_REG_USE_ACC_PROXY)

pjsua_call_hold_type call_hold_type

Specify how to offer call hold to remote peer. Please see the documentation on pjsua_call_hold_type for more info.

Default: PJSUA_CALL_HOLD_TYPE_DEFAULT

pj_bool_t register_on_acc_add

Specify whether the account should register as soon as it is added to the UA. Application can set this to PJ_FALSE and control the registration manually with pjsua_acc_set_registration().

Default: PJ_TRUE

pj_bool_t disable_reg_on_modify

Specify whether account modification with pjsua_acc_modify() should automatically update registration if necessary, for example if account credentials change.

Disable this when immediate registration is not desirable, such as during IP address change.

Default: PJ_FALSE.

pjsua_ip_change_acc_cfg ip_change_cfg

Specify account configuration specific to IP address change used when calling pjsua_handle_ip_change().

pj_bool_t enable_rtcp_mux

Enable RTP and RTCP multiplexing.

pjmedia_rtcp_fb_setting rtcp_fb_cfg

RTCP Feedback configuration.

pj_bool_t enable_rtcp_xr

Enable RTCP Extended Report (RTCP XR).

Default: PJMEDIA_STREAM_ENABLE_XR

struct pjsua_acc_info
#include <pjsua.h>

Account info. Application can query account info by calling pjsua_acc_get_info().

Public Members

pjsua_acc_id id

The account ID.

pj_bool_t is_default

Flag to indicate whether this is the default account.

pj_str_t acc_uri

Account URI

pj_bool_t has_registration

Flag to tell whether this account has registration setting (reg_uri is not empty).

unsigned expires

An up to date expiration interval for account registration session, PJSIP_EXPIRES_NOT_SPECIFIED if the account doesn’t have reg session.

pjsip_status_code status

Last registration status code. If status code is zero, the account is currently not registered. Any other value indicates the SIP status code of the registration.

pj_status_t reg_last_err

Last registration error code. When the status field contains a SIP status code that indicates a registration failure, last registration error code contains the error code that causes the failure. In any other case, its value is zero.

pj_str_t status_text

String describing the registration status.

pj_bool_t online_status

Presence online status for this account.

pj_str_t online_status_text

Presence online status text.

pjrpid_element rpid

Extended RPID online status information.

char buf_[PJ_ERR_MSG_SIZE]

Buffer that is used internally to store the status text.