Contents
Configuring SIP Endpoint SDK for OS X
The following features are not supported for this pre-release:
- Video
- IPv6
- NAT, ICE, TURN, STUN
- SIP Cluster
- SIP Proxy
Using the Default Configuration File
You can find the default configuration file in the following location:
<installation folder>/Bin/SipEndpoint.config
This file contains XML configuration details that affect how your SIP Endpoint SDK application behaves. The initial settings are the same as those specified for use with the QuickStart application included with your SIP Endpoint SDK release.
Configuration settings are separated into two containers: the Basic Container holds the connectivity details that are required to connect to your SIP Server, while the Genesys Container holds a variety of configuration settings.
Basic Container
The first Container ("Basic") holds the basic connectivity details that are required to connect to your SIP Server. This container has at least one connection (Connectivity) element with the following attributes:
<Connectivity user="DN" server="SERVER:PORT" protocol="TRANSPORT"/>
Make the following changes and save the updated configuration file before using the SIP Endpoint SDK:
- user="DN" — Supply a valid DN for the user attribute.
- server="SERVER:PORT" — Replace SERVER with the host name where your SIP Server is deployed, and PORT with the SIP port of the SIP Server host. (The default SIP port value is 5060.)
- protocol="TRANSPORT" — Set the protocol attribute to reflect the protocol being used to communicate with SIP Server. Possible values are UDP, TCP, or TLS.
Genesys Container
The second Container ("Genesys") holds a number of configurable settings that are organized into domains and sections. These settings do not have to be changed, but can be customized to take full control over your SIP Endpoint SDK applications.
An overview of the settings in this container and the valid values for these settings is provided here:
| Domain | Section | Setting | Values | Description | |
|---|---|---|---|---|---|
policy
| |||||
endpoint
| |||||
| audio_qos | Number | The integer value representing the DSCP bits to set for RTP audio packets. The value should be 4 * Preferred DSCP value. | |||
| include_os_version_in_user_agent_header | Number | If set to 1, the user agent field includes the OS version the client is currently running on. Default: 1. | |||
| include_sdk_version_in_user_agent_header | Number | If set to 1, the user agent field includes the SDK version the client is currently running on. Default: 1. | |||
| ip_versions | IPv4 empty |
A value of IPv4 or an empty value means that the application selects an available local IPv4 address.
Default: IPv4. | |||
| public_address | String | Local IP address of the machine. This setting can be an explicit setting or a special value that the SDK uses to automatically obtain the public address.
Valid Values:
This setting may have one of the following special values:
Default Value: Empty string which is fully equivalent to the $auto value. If the value is specified as an explicit host name, the Contact header includes the host name for the recipient of SIP messages (SIP Server or SIP proxy) to resolve on their own. For all other cases, including $host, the resolved IP address is used for Contact. The value in SDP is always the IP address. | |||
| rtp_inactivity_timeout | Number | Timeout interval for RTP inactivity. Valid values are positive integers. A value of 0 means that this feature is not activated. A value 1 or higher indicates the inactivity timeout interval in seconds. Default: 30. Suggested values: 1 through 150. | |||
| rtp_port_min | Number | The integer value representing the minimum value for an RTP port range. Must be within the valid port range of 8000 to 65535. If the minimum value is not specified or set to an invalid value, the default value of (8000) is used for rtp_port_min. Setting the minimum to a value that is larger than the maximum is considered an error and will result in a failure to initialize the endpoint. | |||
| rtp_port_max | Number | The integer value representing the maximum value for an RTP port range. Must be within the valid port range of 8000 to 65535. If the maximum value is not specified or set to an invalid value, the default maximum 9000 is used for rtp_port_max. Setting the maximum to a value that is less than the minimum is considered an error and results in a failure to initialize the endpoint. | |||
| signaling_qos | Number | The integer value representing the DSCP bits to set for SIP packets. Integer value should be configured to 4 * Preferred DSCP value. | |||
| sip_port_min | Number | The integer value representing the minimum value for a SIP port range. Must be within the valid port range of 1 to 65535. If the minimum value is not specified or set to an invalid value, the default value of 5060 is used for sip_port_min. Setting the minimum to a value that is larger than the maximum is considered an error and will result in a failure to initialize the endpoint. | |||
| sip_port_max | Number | The integer value representing the maximum value for a SIP port range. Must be within the valid port range of 1 to 65535. If the maximum value is not specified or set to an invalid value, the default value of 5080 is used for sip_port_max. Setting the maximum to a value that is less than the minimum is considered an error and will result in a failure to initialize the endpoint. | |||
| sip_transaction_timeout | Number | SIP transaction timeout value in milliseconds. Valid values are 1 through 32000, with a default value of 4000. The recommended value is 4000. | |||
| vq_report_collector | See Producing RTCP Extended Reports | ||||
| vq_report_publish | See Producing RTCP Extended Reports | ||||
| answer_sdp_priority | config NULL Empty offer |
Valid values: config, NULL, or Empty—the endpoint selects the first codec from the codec configuration listed in both the codec configuration and the SDP offer. | |||
| sip_port_binding | 0 NULL Empty 1 |
Valid values: 0, NULL, or Empty—opens the SIP port to listen on any interface Default value: 0 | |||
session
| |||||
| agc_mode | 0
1 |
If set to 0, AGC (Automatic Gain Control) is disabled; if set to 1, it is enabled. Default: 1. Other values are reserved for future extensions. This configuration is applied at startup, after which time the agc_mode setting can be changed to 1 or 0 from the main sample application.
NOTE: It is not possible to apply different AGC settings for different channels in multi-channel scenarios. | |||
| auto_answer | 0 1 |
If set to 1, all incoming calls should be answered automatically. | |||
| auto_answer_delay | Number | Valid values: Number in milliseconds. Time in milliseconds to wait before auto-answering. The recommended and default value is 1500 milliseconds. | |||
| dtmf_method | Rfc2833
Info |
Method to send DTMF | |||
| echo_control | 0 1 |
Valid values: 0 or 1. If set to 1, echo control is enabled. | |||
| noise_suppression | 0 1 |
Valid values: 0 or 1. If set to 1, noise suppresion is enabled. | |||
| dtx_mode | 0 1 |
Valid values: 0 or 1. If set to 1, DTX is activated. | |||
| reject_session_when_headset_na | 0 1 |
Valid values: 0 or 1. If set to 1, the SDK should reject the incoming session if a USB headset is not available. | |||
| sip_code_when_headset_na | Number | Defaul Value: 480 If a valid SIP error code is supplied, the SDK rejects the incoming session with the specified SIP error code if a USB headset is not available. | |||
| vad_level | Number | Sets the degree of bandwidth reduction. Valid values: 0 – 3 — from 0 (conventional VAD) to 3 (aggressive high). | |||
| ringing_enabled | Number | Valid values: 0, 1, 2, or 3. 0 = event Ringing disabled | |||
| ringing_timeout | Number | Valid Values: Empty, 0, or a positive number Default Value: 0 | |||
| ringing_file | String | Valid values: Empty or the path to the ringing sound file. The path may be a file name in the current directory or the full path to the sound file. Default Value: ringing.wav kWavFormatPcm = 1, PCM, each sample of size bytes_per_sample
| |||
device
| |||||
| audio_in_device
For more information, see Audio Device Settings |
String | Microphone device name | |||
| audio_out_device | String | Speaker device name | |||
| capture_device | String | Capture device name | |||
| headset_name | String | The name of the headset model | |||
| use_headset | Number | Valid values: 0 or 1. If set to 0, the audio devices specified in audio_in_device and audio_out_device are used by the SDK. If set to 1, the SDK uses a headset as the preferred audio input and output device and the audio devices specified in audio_in_device and audio_out_device are ignored. | |||
codecs — See Working with Codec Priorities
| |||||
proxies
| |||||
proxy<n>
| |||||
| display_name | String | Proxy display name | |||
| domain | String | Valid Values: Any valid SIP domain Default Value: Empty string | |||
| password | String | Proxy password. Password configured for DN object. | |||
| reg_interval | Number | The period, in seconds, after which the endpoint starts a new registration cycle when a SIP proxy is down. Valid values are integers greater than or equal to 0. If the setting is empty or negative, the default value is 0, which means no new registration cycle is allowed. If the setting is greater than 0, a new registration cycle is allowed and will start after the period specified by regInterval. | |||
| reg_match_received_rport | Number | Valid Values: 0 or 1 Default Value: 0 | |||
| reg_timeout | Number | The period, in seconds, after which registration should expire. A new REGISTER request will be sent before expiration. Valid values are integers greater than or equal to 0. If the setting is 0, then registration is disabled, putting the endpoint in standalone mode. If the setting is empty/null, the default value of 1800 seconds is used. | |||
| mailbox | |||||
| password | String | Mailbox password | |||
| server | String | Proxy server address and port for this mailbox | |||
| timeout | Number | Subscription expiration timeout in seconds. If the setting is missing or set to 0, the SDK uses a default timeout of 1800 seconds (30 minutes). Valid Values: Any positive integer | |||
| transport | udp
tcp |
Transport protocol to use when communicating with server | |||
| user | String | Mailbox number this line subscribes to. | |||
system
| |||||
diagnostics
| |||||
| enable_logging | Number | Valid values: 0 or 1. Disable or enable logging. | |||
| log_file | String | Log file name, for example, SipEndpoint.log Valid values: Full path or relative path to the log file. | |||
| log_level | Number | Valid values: 0 – 4. Log levels: 0 = "Fatal"; 1 = "Error"; 2 = "Warning"; 3 = "Info"; 4 = "Debug". | |||
| log_options_provider | String | Valid values for webrtc = (warning, state, api, debug, info, error, critical). For example: gsip=2, webrtc=(error,critical) | |||
| log_options_endpoint | Number | Valid values: 0 – 4, same as log_level. | |||
| logger_type | external | If set to external, an external logger is used. | |||
security
| |||||
| cert_file | String | Full path pointing to the certificate file used as a client-side certificate for outgoing TLS connections and as a server-side certificate for incoming TLS connections. For example, /users/Desktop/certificate/hostname_cer.pem | |||
| tls_enabled | Number | If set to 1, connection with TLS transport will be registered. Default: 0. | |||
| use_srtp | String
disabled
optional |
Indicates whether to use SRTP | |||
| priv_key_file | String | Ful path to the endpoint private key file used for client-side authentication for outgoing TLS connections. For example, /users/Desktop/certificate/hostname_priv_key.pem | |||
| ca_list_file | String | Full path to the Certificat Authority's list file. For example, /users/Desktop/certificate/ca/ca_cert.pem | |||
Producing RTCP Extended Reports
You can use SIP Endpoint SDK to produce RTCP Extended Reports (RFC 3611) and publish them according to RFC 6035 at the end of each call, using a collector address of your choice.
Settings:
<domain name="policy">
<section name="endpoint">
...
<!--
Valid values for Voice Quality (VQ) report publish setting (vq_report_publish):
0--VQ report is not published
1--VQ report is published to the collector at the end of the call--
see the vq_report_collector setting information below
-->
<setting name="vq_report_publish" value="0"/>
<!--
Valid values for Voice Quality (VQ) report collector setting (vq_report_collector):
NULL or Empty--The VQ report is published to the proxy described in the
Connectivity section
FQDN or IP address along with port and transport--
collector@SipServer.genesyslab.com:5060;transport=udp
-->
<setting name="vq_report_collector" value="collector@SipServer.genesyslab.com:5060;transport=udp"/>
</section>Endpoint:
The vq_report_publish and vq_report_collector settings can be read from the Endpoint Policy by using the following methods:
GetEndpointPolicy(EndpointPolicyQuery.VqReportCollector);
GetEndpointPolicy(EndpointPolicyQuery.VqReportPublish);Working with Codec Priorities
Codecs are listed by name in the codecs domain of the configuration file. Codecs are listed by priority with codecs closer to the top of the list having higher priority. To disable a codec, comment out or remove the codec from the configuration file.
The value of setting payload_type is an integer. For codecs with dynamic payload type such as iSAC, iLBC, OPUS valid values are between 96 and 127.
Example
<domain name="codecs">
<section name="PCMU/8000">
<setting name="payload_type" value="0"/>
</section>
<section name="PCMA/8000">
<setting name="payload_type" value="8"/>
</section>
<section name="G722/16000">
<setting name="payload_type" value="9"/>
</section>
<section name="iLBC/8000">
<setting name="payload_type" value="102"/>
</section>
<section name="iSAC/32000">
<setting name="payload_type" value="104"/>
</section>
<section name="iSAC/16000">
<setting name="payload_type" value="103"/>
</section>
<section name="opus/48000/2">
<setting name="payload_type" value="120"/>
</section>
</domain>
Audio Device Settings
You can configure a headset and other audio input devices using the following parameters in the configuration file:
- headset_name
- audio_in_device
- audio_out_device
If the SDK cannot access any of the configured audio devices, the SDK uses the default system audio devices.
If use_headset is set to 1, the SDK searches for audio devices in this order:
Headset > Audio in device > Audio out device > System defaults
If use_headset is set to 0, the SDK skips the headset and uses this order:
Audio in device > Audio out device > System defaults
The procedure for audio device selection is applied on startup and every time any changes are made to device presence (such as when a new device is plugged in or an existing device is removed)
Auto-answer and Call Rejection
The auto-answer and call rejection features depend on the use_headset, auto_answer, and reject_session_when_headset_na configuration settings and whether or not audio devices are available. The following tables describe auto-answer and call rejection behavior:
Auto-answer and Call Rejection when use_headset=1
| Headset is Available
The SDK considers a headset available if the headset is found by name. Outgoing calls can be initiated. |
auto_answer=1 | Incoming calls are answered automatically:
|
| auto_answer=0 | Incoming calls are answered manually and the user explicitly selects whether or not video streams should be accepted (using the has_video parameter supplied in the gs_session_info argument) | |
| Headset is Not Available
The SDK decides that no headset is available if a headset was not found by name. An audio device is still assigned, if possible (that is, if any supported devices are present in the system), using the first available audio input and output devices or the system defaults. |
No auto-answer is possible in this sub-case, so the auto_answer setting is not used | reject_session_when_headset_na=1
|
reject_session_when_headset_na=0
|
Auto-answer and Call Rejection when use_headset=0
Audio devices are configured using the audio_in_device and audio_out_device settings. If no valid audio_in_device and audio_out_device devices are found, the SDK selects the system defaults. Outgoing calls can be initiated.
| Both microphone and speaker are available | auto_answer=1 | Incoming calls are answered automatically:
|
| auto_answer=0 | Incoming calls are answered manually and the user explicitly selects whether or not video streams should be accepted (using the has_video parameter supplied in the gs_session_info argument) | |
Either microphone or speaker is not available
|
No auto-answer is possible in this sub-case, so the auto_answer setting is not used | Auto-rejection is not applicable, so the reject_session_when_headset_na setting is not used |