Jump to: navigation, search
(→‎ringing_enabled)
(Update with the copy of version: 8.1.2OSX)
Line 1: Line 1:
−
=Configuring SIP Endpoint SDK for OS X=
+
=Configuring SIP Endpoint SDK for Apple OS=
  
−
{{NoteFormat|The following features are not supported:
 
  
−
* Video
+
__TOC__
−
* IPv6
+
The sample application that comes with the SIP Endpoint SDK for Apple OS distribution includes a property list (plist) that is used for configuring the application. This file is located at <tt>&lt;SIP Endpoint SDK Installation Folder&gt;/Sample/Src/Sip EP Sample.plist</tt>.
−
* NAT, ICE, TURN, STUN
 
−
* SIP Cluster
 
−
* SIP Proxy
 
−
}}
 
  
−
== Using the Default Configuration File ==
+
[[File: Important.png|middle]] '''Note:''' Genesys recommends that you use the sample application as the starting point for your development efforts.
−
You can find the default configuration file in the following location:<br>
 
−
&lt;installation folder&gt;/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.
+
If you are developing applications from scratch, you should:
−
 
+
# Create a copy of the plist from the sample application
−
Configuration settings are separated into two containers: the [[ConfiguringforAppleOS#Basic_Container|Basic Container]] holds the connectivity details that are required to connect to your SIP Server, while the [[ConfiguringforAppleOS#Genesys_Container|Genesys Container]] holds a variety of configuration settings.
+
# Name it appropriately
−
 
+
# Place it in your app's <tt>Src</tt> folder.
−
=== Basic Container ===
+
== SIP Endpoint Configuration Settings ==
−
 
+
You can customize the following settings in your SIP Endpoint SDK applications.
−
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:
+
{|
−
 
 
−
<pre><Connectivity user="DN" server="SERVER:PORT" protocol="TRANSPORT"/></pre>
 
−
 
 
−
<!--If you are using a configuration that supports [[DisasterRecovery|Disaster Recovery and Geo-Redundancy]], there may be multiple connection elements present with each specifying a separate possible connection. Refer to the [[DisasterRecovery#Configuration_Settings|configuration settings]] of that feature for details.-->
 
−
 
 
−
Make the following changes and save the updated configuration file before using the SIP Endpoint SDK:
 
−
* '''user="DN"''' &mdash; Supply a valid DN for the user attribute.
 
−
* '''server="SERVER:PORT"''' &mdash; 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"''' &mdash; 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:
 
−
 
 
−
{| class="wikitable" border="1"
 
−
! Domain
 
 
! Section
 
! Section
 
! Setting
 
! Setting
 +
! Values
 +
! Description
 +
|-
 +
| colspan=4 | '''GSDefaultConnectionPolicy'''
 
|-
 
|-
−
|colspan=3| [[ConfiguringforAppleOS#sdk_policy|'''policy''']]
+
| rowspan=1 |  
 +
| networkInterface
 +
| String
 +
| Name of the network interface
 
|-
 
|-
−
| rowspan=17|
+
| colspan=4 | '''GSDefaultDevicePolicy'''
−
|colspan=2| [[ConfiguringforAppleOS#sdk_endpoint|'''endpoint''']]
 
 
|-
 
|-
−
| rowspan=16 |  
+
| rowspan=3 |  
−
 
+
| audio_in_device
−
| [[ConfiguringforAppleOS#audio_qos|audio_qos]]
+
| String
 +
| Microphone device
 
|-
 
|-
−
| [[ConfiguringforAppleOS#include_os_version_in_user_agent_header|include_os_version_in_user_agent_header]]
+
| audio_out_device
 +
| String
 +
| Speaker device
 
|-
 
|-
−
| [[ConfiguringforAppleOS#include_sdk_version_in_user_agent_header|include_sdk_version_in_user_agent_header]]
+
| use_headset
 +
| Boolean
 +
| If set to YES, the SDK uses a headset as the preferred audio input and output device.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#ip_versions|ip_versions]]
+
| colspan=4 | '''GSDefaultEndpointPolicy'''
 
|-
 
|-
−
| [[ConfiguringforAppleOS#public_address|public_address]]
+
| rowspan=12 |  
 +
| audioQos
 +
| Number
 +
| The integer value representing the DSCP bits to set for RTP audio packets.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#rtp_inactivity_timeout|rtp_inactivity_timeout]]
+
| includeOSVersionInUserAgentHeader
 +
| Boolean
 +
| If set to YES, the user agent field includes the OS version the client is currently running on. Default: <tt>NO</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#rtp_port_min|rtp_port_min]]
+
| ip_version
 +
| IPv4
 +
IPv6<br>
 +
IPv4,IPv6<br>
 +
IPv6,IPv4<br>
 +
empty
 +
| A value of <tt>IPv4</tt> means that the application selects an available local IPv4 address; IPv6 addresses are ignored.
 +
A value of <tt>IPv6</tt>  means that the application selects an available local IPv6 address; IPv4 addresses are ignored.<br>
 +
A value of <tt>IPv4,IPv6</tt> or an empty value means that the application selects an IPv4 address if one exists. If not, an available IPv6 address are selected.<br>
 +
A value of <tt>IPv6,IPv4</tt> means that the application selects an IPv6 address if one exists. If not, an available IPv4 address are selected.<br>
 +
Default: <tt>IPv4,IPv6</tt>.<br>
 +
NOTE: This parameter has no effect if the <tt>public_address</tt> option specifies an explicit IP address.<br>
 +
NOTE: Although the IPv6 configuration options are available in the plist file for this product, they are not supported in the 8.1.2 Release of SIP Endpoint SDK for Apple OS.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#rtp_port_max|rtp_port_max]]
+
| public_address
 +
| String
 +
| Local IP address or Fully Qualified Domain Name (FQDN) of the machine.
 +
 
 +
NOTE: Although the IPv6 configuration options are available in the plist file for this product, they are not supported in the 8.1.2 Release of SIP Endpoint SDK for Apple OS.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#signaling_qos|signaling_qos]]
+
| rtpInactivityTimeout
 +
| Number
 +
| Timeout interval for RTP inactivity. Valid values are integers from <tt>0</tt> to <tt>150</tt>. A value of <tt>0</tt> or values greater than <tt>150</tt> mean that this feature is not activated. A value in the range of <tt>1</tt> to <tt>150</tt> indicates the inactivity timeout interval in seconds. Default: <tt>0</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#sip_port_min|sip_port_min]]
+
| rtpPortMin
 +
| Number
 +
| The integer value representing the minimum value for an RTP port range. Must be within the valid port range of <tt>9000</tt> to <tt>65535</tt>. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (<tt>9000</tt>) and maximum (minimum value + <tt>999</tt>) are used. 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.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#sip_port_max|sip_port_max]]
+
| rtpPortMax
 +
| Number
 +
| The integer value representing the maximum value for an RTP port range. Must be within the valid port range of <tt>9000</tt> to <tt>65535</tt>. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (<tt>9000</tt>) and maximum (minimum value + <tt>999</tt>) are used. 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.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#sip_transaction_timeout|sip_transaction_timeout]]
+
| secureSignalingQos
 +
| Number
 +
| The integer value representing the DSCP bits to set for TCP packets.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#vq_report_collector|vq_report_collector]]
+
| signalingQos
 +
| Number
 +
| The integer value representing the DSCP bits to set for SIP packets.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#vq_report_publish|vq_report_publish]]
+
| sipPortMin
 +
| Number
 +
| The integer value representing the minimum value for a SIP port range. Must be within the valid port range of <tt>1</tt> to <tt>65535</tt>. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (<tt>5060</tt>) and maximum (minimum value + <tt>6</tt>) are used. 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.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#answer_sdp_priority|answer_sdp_priority]]
+
| sipPortMax
 +
| Number
 +
| The integer value representing the maximum value for a SIP port range. Must be within the valid port range of <tt>1</tt> to <tt>65535</tt>. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (<tt>5060</tt>) and maximum (minimum value + <tt>6</tt>) are used. 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.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#sip_port_binding|sip_port_binding]]
+
| videoQos
 +
| Number
 +
| The integer value representing the DSCP bits to set for RTP Video packets.
 
|-
 
|-
−
| rowspan=14|
+
| colspan=4 | '''GSDefaultSessionPolicy'''
−
|colspan=2| [[ConfiguringforAppleOS#sdk_session|'''session''']]
 
 
|-
 
|-
−
| rowspan=13 |  
+
| rowspan=6 |  
 +
| 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 <tt>agc_mode</tt> setting can be changed to <tt>1</tt> or <tt>0</tt> from the main sample application.
  
−
| [[ConfiguringforAppleOS#agc_mode|agc_mode]]
+
NOTE: It is not possible to apply different AGC settings for different channels in multi-channel scenarios.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#auto_answer|auto_answer]]
+
| auto_accept_video
 +
| Boolean
 +
| If set to YES, all incoming video should be accepted automatically.
 +
 
 +
NOTE: The video mode window will not be opened if <tt>auto_accept_video</tt> and <tt>auto_answer</tt> are both set to <tt>0</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#auto_answer_delay|auto_answer_delay]]
+
| auto_answer
 +
| Boolean
 +
| If set to YES, all incoming calls should be answered automatically.
 +
 
 +
NOTE: The video mode window will not be opened if <tt>auto_accept_video</tt> and <tt>auto_answer</tt> are both set to <tt>0</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#dtmf_method|dtmf_method]]
+
| dtmf_method
 +
| Rfc2833
 +
Info<br>
 +
InbandRtp
 +
| Method to send DTMF
 
|-
 
|-
−
| [[ConfiguringforAppleOS#echo_control|echo_control]]
+
| reject_session_when_headset_na
 +
| Boolean
 +
| If set to YES, the SDK should reject the incoming session if a USB headset is not available.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#noise_suppression|noise_suppression]]
+
| sip_code_when_headset_na
 +
| Number
 +
| 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.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#dtx_mode|dtx_mode]]
+
| colspan=4 | '''basic: account connection details'''
 
|-
 
|-
−
| [[ConfiguringforAppleOS#reject_session_when_headset_na|reject_session_when_headset_na]]
+
| rowspan=9 |  
 +
| regInterval
 +
| 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 <tt>0</tt>. If the setting is empty or negative, the default value is <tt>0</tt>, which means no new registration cycle is allowed. If the setting is greater than <tt>0</tt>, a new registration cycle is allowed and will start after the period specified by <tt>regInterval</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#sip_code_when_headset_na|sip_code_when_headset_na]]
+
| registrationTimeout
 +
| Number
 +
| The period, in seconds, after which registration should expire. A new <tt>REGISTER</tt> request will be sent before expiration. Valid values are integers greater than or equal to <tt>0</tt>. If the setting is empty or negative, the default value is 1800 seconds. If the setting is <tt>0</tt>, registration is disabled, putting the endpoint in standalone mode.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#vad_level|vad_level]]
+
| transport
 +
| udp
 +
tcp<br>
 +
tls
 +
| The transport protocol to use when communicating with server
 
|-
 
|-
−
| [[ConfiguringforAppleOS#ringing_enabled|ringing_enabled]]
+
| server
 +
| String
 +
| The server address and port
 
|-
 
|-
−
| [[ConfiguringforAppleOS#ringing_timeout|ringing_timeout]]
+
| stun_server
 +
| String
 +
| STUN server address (with optional port). An empty or null value indicates this feature is not being used.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#ringing_file|ringing_file]]
+
| turn_password
 +
| Number
 +
| Password for TURN authentication
 
|-
 
|-
−
| rowspan=6 |
+
| turn_server
−
|colspan=2| [[ConfiguringforAppleOS#sdk_device|'''device''']]
+
| String
 +
| TURN server address (with optional port). An empty or null value indicates this feature is not being used.
 
|-
 
|-
−
| rowspan=5 |
+
| turn_userName
−
 
+
| String
−
| [[ConfiguringforAppleOS#audio_in_device|audio_in_device]]
+
| User ID for TURN authorization
−
 
 
−
For more information, see [[ConfiguringforAppleOS#Audio_Device_Settings|Audio Device Settings]]
 
 
|-
 
|-
−
| [[ConfiguringforAppleOS#audio_out_device|audio_out_device]]
+
| user
 +
| String
 +
| User ID for this connection
 
|-
 
|-
−
| [[ConfiguringforAppleOS#capture_device|capture_device]]
+
| colspan=4 | '''basic: account mailbox details'''
 
|-
 
|-
−
| [[ConfiguringforAppleOS#headset_name|headset_name]]
+
| rowspan=4 |  
 +
| server
 +
| String
 +
| Proxy server address and port for this mailbox
 
|-
 
|-
−
| [[ConfiguringforAppleOS#use_headset|use_headset]]
+
| timeout
 +
| Number
 +
| Registration timeout interval
 
|-
 
|-
−
|colspan=3| '''codecs'''&mdash;See [[ConfiguringforAppleOS#Working_with_Codec_Priorities|Working with Codec Priorities]]
+
| transport
 +
| udp
 +
tcp<br>
 +
tls
 +
| Transport protocol to use when communicating with server
 
|-
 
|-
−
|colspan=3| [[ConfiguringforAppleOS#sdk_proxies|'''proxies''']]
+
| user
 +
| String
 +
| User ID for this mailbox
 
|-
 
|-
−
| rowspan=13 |
+
| colspan=4 | '''codecs: priority'''
−
|colspan=2| [[ConfiguringforAppleOS#sdk_proxy|'''proxy''<n>''']]
 
 
|-
 
|-
−
| rowspan=12 |  
+
| rowspan=1 |  
−
 
+
| ''&lt;Codec Name&gt;''
−
| [[ConfiguringforAppleOS#display_name|display_name]]
+
| Number
 +
| Codec priority in SDP. A higher number means the codec has preference in codec negotiation.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#domain|domain]]
+
| colspan=4 | '''diagnostics'''
 
|-
 
|-
−
| [[ConfiguringforAppleOS#password|password]]
+
| rowspan=5 |  
 +
| enable_logging
 +
| Boolean
 +
| Enable or disable logging
 
|-
 
|-
−
| [[ConfiguringforAppleOS#reg_interval|reg_interval]]
+
| log_file
 +
| String
 +
| Log file name, for example, <tt>SipEndpoint.log</tt>
 
|-
 
|-
−
| [[ConfiguringforAppleOS#reg_match_received_rport|reg_match_received_rport]]
+
| log_level
 +
| debug
 +
info<br>
 +
warn<br>
 +
error<br>
 +
fatal
 +
| Log levels
 
|-
 
|-
−
| [[ConfiguringforAppleOS#reg_timeout|reg_timeout]]
+
| Log_option_provider
 +
| #/Empty
 +
gsip=3,webrtc=(state,warning)
 +
| If set to <tt>#/Empty</tt>, log messages will not include webrtc messages.
 +
If set to <tt>gsip=3,webrtc=(state,warning)</tt> and the level is set to <tt>info</tt>, log messages will include webrtc messages.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#sdk_mailbox| '''mailbox''']]
+
| logger_type
 +
| file
 +
default
 +
| If set to <tt>file</tt>, the log data will be printed to the file specified by the <tt>log_file</tt> parameter.
 +
If set to <tt>default</tt>, the log data will be printed to the console.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#password|password]]
 
 
|-
 
|-
−
| [[ConfiguringforAppleOS#server|server]]
+
| colspan=4 | '''security'''
 
|-
 
|-
−
| [[ConfiguringforAppleOS#timeout|timeout]]
+
| rowspan=13 |  
−
|-
+
| ca_list_file
−
| [[ConfiguringforAppleOS#transport|transport]]
+
| String
−
|-
+
| Certificate of Authority (CA) list file
−
| [[ConfiguringforAppleOS#user|user]]
 
−
|-
 
−
|colspan=3| [[ConfiguringforAppleOS#sdk_system|'''system''']]
 
 
|-
 
|-
−
| rowspan=7 |
+
| cert_file
−
|colspan=4| [[ConfiguringforAppleOS#sdk_diagnostics|'''diagnostics''']]
+
| String
 +
| Public endpoint certificate file, which is used as client-side certificate for outgoing TLS connection and server-side certificate for incoming TLS connection
 
|-
 
|-
−
| rowspan=6 |  
+
| method
−
 
+
| unspecified
−
| [[ConfiguringforAppleOS#enable_logging|enable_logging]]
+
tlsv1<br>
 +
sslv2<br>
 +
sslv3<br>
 +
sslv23
 +
| Security method
 
|-
 
|-
−
| [[ConfiguringforAppleOS#log_file|log_file]]
+
| password
 +
| String
 +
| Password to open private key
 
|-
 
|-
−
| [[ConfiguringforAppleOS#log_level|log_level]]
+
| privkey_file
 +
| String
 +
| Path to the optional private key file of the endpoint certificate to be used. Example: <tt>/usr/local/ssl/certs/example_priv_key.pem</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#log_options_provider|log_options_provider]]
+
| require_client_cert
 +
| Boolean
 +
| Indicates whether a client certificate is required. Default: <tt>NO</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#log_options_endpoint|log_options_endpoint]]
+
| server_name
 +
| String
 +
| Server name. Default: empty.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#logger_type|logger_type]]
+
| srtp_secure_signaling
 +
| no
 +
yes<br>
 +
sips
 +
| Indicates whether SRTP secure signaling is to be used
 
|-
 
|-
−
| rowspan=6 |
+
| timeout
−
|colspan=4| [[ConfiguringforAppleOS#sdk_security|'''security''']]
+
| Number
 +
| Timeout interval. Default: <tt>0</tt>.
 
|-
 
|-
−
| rowspan=5 |  
+
| tls_enabled
−
 
+
| Boolean
−
| [[ConfiguringforAppleOS#cert_file|cert_file]]
+
| If set to <tt>YES</tt>, connection with TLS transport will be registered. Default: <tt>NO</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#tls_enabled|tls_enabled]]
+
| use_srtp
 +
| disabled
 +
optional<br>
 +
mandatory
 +
| Indicates whether to use SRTP
 
|-
 
|-
−
| [[ConfiguringforAppleOS#use_srtp|use_srtp]]
+
| verify_client
 +
| Boolean
 +
| Indicates whether clients must be verified. Default: <tt>NO</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#priv_key_file|priv_key_file]]
+
| verify_server
 +
| Boolean
 +
| Indicates whether servers must be verified. Default: <tt>NO</tt>.
 
|-
 
|-
−
| [[ConfiguringforAppleOS#ca_list_file|ca_list_file]]
 
 
|}
 
|}
 +
== Specifying Behavior When A USB headset Is Not Available ==
 +
The following behaviors can now be specified when a SIP Endpoint user does not have a working USB headset:
 +
* Whether SIP Endpoint should automatically reject an incoming call
 +
* The SIP error code to be sent to the inviting party
 +
Support for this feature involves several configuration settings:
 +
* endpoint:GSDefaultDevicePolicy:use_headset
 +
* endpoint:GSDefaultSessionPolicy:reject_session_when_headset_na
 +
* endpoint:GSDefaultSessionPolicy:sip_code_when_headset_na
 +
Information about these settings is available in the table of [[ConfiguringforAppleOS#SIP_Endpoint_Configuration_Settings|SIP Endpoint Configuration Settings]] that appears elsewhere on this page.
  
−
==<tt>policy</tt> Domain==
+
You can tell whether SIP Endpoint has been instructed to use a USB headset by using the following method of <tt>GSDevicePolicyDelegate</tt>:
−
<span id="sdk_policy"></span>
+
- (BOOL) useHeadset;
−
 
 
−
===<tt>endpoint</tt> Section===
 
−
<span id="sdk_endpoint"></span>
 
−
 
 
−
 
 
−
====audio_qos====
 
−
{{AnchorDiv|audio_qos}}
 
−
Valid Values: Number<br/>
 
−
 
 
−
The integer value representing the DSCP bits to set for RTP audio packets. The value should be <tt>4 * Preferred DSCP value</tt>.
 
−
 
 
−
 
 
−
====include_os_version_in_user_agent_header====
 
−
{{AnchorDiv|include_os_version_in_user_agent_header}}
 
−
Valid Values: <tt>0</tt> or <tt>1</tt><br/>
 
−
Default Value: <tt>1</tt>
 
−
 
 
−
If set to 1, the user agent field includes the OS version the client is currently running on.
 
−
 
 
−
 
 
−
====include_sdk_version_in_user_agent_header====
 
−
{{AnchorDiv|include_sdk_version_in_user_agent_header}}
 
−
Valid Values: <tt>0</tt> or <tt>1</tt><br/>
 
−
Defaule Value: <tt>1</tt>
 
−
 
 
−
If set to 1, the user agent field includes the SDK version the client is currently running on.
 
−
 
 
−
 
 
−
====ip_versions====
 
−
{{AnchorDiv|ip_versions}}
 
−
Valid Values: IPv4, empty
 
−
Default Value: <tt>IPv4</tt>.<br>
 
−
 
 
−
A value of <tt>IPv4</tt> or an empty value means that the application selects an available local IPv4 address.
 
−
 
 
−
NOTE: This parameter has no effect if the <tt>public_address</tt> option specifies an explicit IP address.
 
−
 
 
−
 
 
−
====public_address====
 
−
{{AnchorDiv|public_address}}
 
−
Valid Values: See description below.<br/>
 
−
 
 
−
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:'''<br>
 
−
This setting may have one of the following explicit values:
 
−
 
 
−
*An IP address. For example, <tt>192.168.16.123</tt> for IPv4.
 
−
*A bare host name, for example, <tt>epsipmac2</tt>.
 
−
 
 
−
This setting may have one of the following special values:
 
−
 
 
−
*<tt>$auto</tt>—The SDK selects the first valid IP address on the first network adapter that is active (status=up) and has the default gateway configured. IP family preference is specified by the '''policy.endpoint.ip_versions''' setting.
 
−
*<tt>$ipv4</tt><!-- or <tt>$ipv6</tt>-->—Same behavior as the <tt>$auto</tt> setting but the SDK restricts the address to a particular IP family.
 
−
*<tt>$host</tt>—The SDK retrieves the standard host name for the local computer using the <tt>gethostname</tt> system function.
 
−
*An adapter name or part of an adapter name prefixed with <tt>$</tt>. For example, <tt>en0</tt> or <tt>en1</tt>. The specified name must be different from the special values <tt>$auto</tt>, <tt>$ipv4</tt>, and <tt>$host</tt>.
 
−
 
 
−
'''Default Value:''' Empty string which is fully equivalent to the <tt>$auto</tt> value.<br>
 
−
 
 
−
If the value is specified as an explicit host name, the <tt>Contact</tt> 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 <tt>$host</tt>, the resolved IP address is used for <tt>Contact</tt>. The value in SDP is always the IP address.
 
−
 
 
−
 
 
−
====rtp_inactivity_timeout====
 
−
{{AnchorDiv|rtp_inactivity_timeout}}
 
−
Valid Values: Integer between <tt>5</tt> and <tt>150</tt><br/>
 
−
Default Value: <tt>150</tt><br/>
 
−
Suggested Value: <tt>30</tt>
 
−
 
 
−
Timeout interval in seconds for RTP inactivity.
 
−
 
 
−
====rtp_port_min====
 
−
{{AnchorDiv|rtp_port_min}}
 
−
Valid Values: Number<br/>
 
−
Default Value: <tt>8000</tt>
 
−
 
 
−
The integer value representing the minimum value for an RTP port range. Must be within the valid port range of <tt>8000</tt> to <tt>65535</tt>. If the minimum value is not specified or set to an invalid value, the default value of <tt>8000</tt> is used for <tt>rtp_port_min</tt>. 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====
 
−
{{AnchorDiv|rtp_port_max}}
 
−
Valid Values: Number<br/>
 
−
Default Value: <tt>9000</tt>
 
−
 
 
−
The integer value representing the maximum value for an RTP port range. Must be within the valid port range of <tt>8000</tt> to <tt>65535</tt>. If the maximum value is not specified or set to an invalid value, the default maximum <tt>9000</tt> is used for <tt>rtp_port_max</tt>. 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====
 
−
{{AnchorDiv|signaling_qos}}
 
−
Valid Values: Number<br/>
 
−
 
 
−
The integer value representing the DSCP bits to set for SIP packets. Integer value should be configured to <tt>4 * Preferred DSCP value</tt>.
 
−
 
 
−
 
 
−
====sip_port_min====
 
−
{{AnchorDiv|sip_port_min}}
 
−
Valid Values: Number between <tt>1</tt> and <tt>65535</tt><br/>
 
−
Default Value: <tt>5060</tt>
 
−
 
 
−
The integer value representing the minimum value for a SIP port range. Must be within the valid port range of <tt>1</tt> to <tt>65535</tt>. If the minimum value is not specified or set to an invalid value, the default value of <tt>5060</tt> is used for <tt>sip_port_min</tt>. 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====
 
−
{{AnchorDiv|sip_port_max}}
 
−
Valid Values: Number between <tt>1</tt> and <tt>65535</tt><br/>
 
−
Default Value: <tt>5080</tt>
 
−
 
 
−
The integer value representing the maximum value for a SIP port range. Must be within the valid port range of <tt>1</tt> to <tt>65535</tt>. If the maximum value is not specified or set to an invalid value, the default value of <tt>5080</tt> is used for <tt>sip_port_max</tt>. 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====
 
−
{{AnchorDiv|sip_transaction_timeout}}
 
−
Valid Values: Number between <tt>1</tt> and <tt>32000</tt><br/>
 
−
Default Value: <tt>4000</tt>
 
−
 
 
−
SIP transaction timeout value in milliseconds. Valid values are <tt>1</tt> through <tt>32000</tt>, with a default value of <tt>4000</tt>. The recommended value is <tt>4000</tt>.
 
−
 
 
−
 
 
−
====vq_report_collector====
 
−
{{AnchorDiv|vq_report_collector}}
 
−
 
 
−
See [[ConfiguringforAppleOS#Producing_RTCP_Extended_Reports|Producing RTCP Extended Reports]]
 
−
 
 
−
 
 
−
====vq_report_publish====
 
−
{{AnchorDiv|vq_report_publish}}
 
−
 
 
−
See [[ConfiguringforAppleOS#Producing_RTCP_Extended_Reports|Producing RTCP Extended Reports]]
 
−
 
 
−
 
 
−
====answer_sdp_priority====
 
−
{{AnchorDiv|answer_sdp_priority}}
 
−
Valid Values: <tt>config</tt> or <tt>offer</tt><br/>
 
−
Default value: <tt>config</tt>
 
  
−
* <tt>config</tt>—The endpoint selects the first codec from the codec configuration listed in both the codec configuration and the SDP offer.
+
To determine whether SIP Endpoint will reject an incoming session when a USB headset is not available or to determine which SIP error code is sent if a USB headset is not available, use the following methods of <tt>GSSessionPolicyDelegate</tt>:
−
* <tt>offer</tt>—the endpoint selects the first codec in the SDP offer listed in both the codec configuration and the SDP offer.
+
- (BOOL) rejectWhenHeadsetNa:(id<GSSession>) session;
 +
- (NSString*) sipCodeWhenHeadsetNa:(id<GSSession>) session;
  
−
====sip_port_binding====
+
== Configuring Message Waiting Indicator (MWI) Support ==
−
{{AnchorDiv|sip_port_binding}}
+
A Message Waiting Indicator (MWI) is usually an audio or visual signal that a voicemail or other type of message is waiting. SIP Endpoint SDK's MWI support involves several configuration settings:
−
Valid Values: <tt>0</tt> or <tt>1</tt><br/>
+
* endpoint:basic:mailbox:user
−
Default Value: <tt>0</tt>
+
* endpoint:basic:mailbox:server
−
 
+
* endpoint:basic:mailbox:transport
−
*<tt>0</tt>—opens the SIP port to listen on any interface<br>
+
* endpoint:basic:mailbox:timeout
−
*<tt>1</tt>—the SIP port binds to the interface specified by the <tt>public_address</tt> setting and listens only on this IP address.
+
Information about these settings is available in the table of [[ConfiguringforAppleOS#SIP_Endpoint_Configuration_Settings|SIP Endpoint Configuration Settings]] that appears elsewhere on this page.
−
 
+
You can use these settings to have SIP Server notify your application when new messages have been received by the subscribing mailbox. <tt>GSMessageWaitingIndicationService</tt> provides the following methods to control mailbox notification subscriptions:
−
===<tt>session</tt> Section===
+
-(GSResult) subscribeForMailbox:(GSMessageWaitingIndicationSubscription*) subscription;
−
{{AnchorDiv|sdk_session}}
+
-(GSResult) unsubscribeForMailbox:(GSMessageWaitingIndicationSubscription*) subscription;
−
 
+
Notifications are provided by <tt>GSMessageWaitingIndicationNotificationDelegate</tt>.
−
 
+
Access to the MWI summary is provided by the following method:
−
====agc_mode====
+
- (void) state:(GSMessageWaitingIndicationState*)  
−
{{AnchorDiv|agc_mode}}
+
          state forSubscription:(GSMessageWaitingIndicationSubscription*) subscription
−
Valid Values: <tt>0</tt> or <tt>1</tt><br/>
+
These notifications encapsulate the following information:
−
 
+
subscription = theSubscription;
−
 
+
messagesWaiting = theMessagesWaiting;
−
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 <tt>agc_mode</tt> setting can be changed to <tt>1</tt> or <tt>0</tt> from the main sample application.
+
messageSummary = theMessageSummary;
−
NOTE: It is not possible to apply different AGC settings for different channels in multi-channel scenarios.
 
−
 
 
−
 
 
−
====auto_answer====
 
−
{{AnchorDiv|auto_answer}}
 
−
Valid Values: <tt>0</tt> or <tt>1</tt><br/>
 
−
 
 
−
 
 
−
If set to 1, all incoming calls should be answered automatically.
 
−
 
 
−
 
 
−
====auto_answer_delay====
 
−
{{AnchorDiv|auto_answer_delay}}
 
−
Valid Values: Number in milliseconds<br/>
 
−
 
 
−
Time in milliseconds to wait before auto-answering. The recommended and default value is <tt>1500</tt> milliseconds.
 
−
 
 
−
 
 
−
====dtmf_method====
 
−
{{AnchorDiv|dtmf_method}}
 
−
Valid Values: <tt>Rfc2833</tt>, <tt>Info</tt>, or <tt>InbandRtp</tt>
 
−
 
 
−
Method to send DTMF
 
−
 
 
−
 
 
−
====echo_control====
 
−
{{AnchorDiv|echo_control}}
 
−
Valid Values: <tt>0</tt> or <tt>1</tt><br/>
 
−
 
 
−
If set to 1, echo control is enabled.
 
−
 
 
−
 
 
−
====noise_suppression====
 
−
{{AnchorDiv|noise_suppression}}
 
−
Valid Values: <tt>0</tt> or <tt>1</tt><br/>
 
−
 
 
−
If set to 1, noise suppresion is enabled.
 
−
 
 
−
 
 
−
====dtx_mode====
 
−
{{AnchorDiv|dtx_mode}}
 
−
Valid Values: <tt>0</tt> or <tt>1</tt><br/>
 
−
 
 
−
If set to 1, DTX is activated.
 
−
 
 
−
 
 
−
====reject_session_when_headset_na====
 
−
{{AnchorDiv|reject_session_when_headset_na}}
 
−
Valid Values:<tt>0</tt> or <tt>1</tt><br/>
 
−
 
 
−
If set to 1, the SDK should reject the incoming session if a USB headset is not available.
 
−
 
 
−
 
 
−
====sip_code_when_headset_na====
 
−
{{AnchorDiv|sip_code_when_headset_na}}
 
−
Valid Values: Number<br/>
 
−
 
 
−
Defaul Value: <tt>480</tt><br>
 
−
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====
 
−
{{AnchorDiv|vad_level}}
 
−
Valid values: 0&ndash;3,from 0 (conventional VAD) to 3 (aggressive high)
 
−
 
 
−
Sets the degree of bandwidth reduction.
 
−
 
 
−
 
 
−
====ringing_enabled====
 
−
{{AnchorDiv|ringing_enabled}}
 
−
Valid values: 0, 1, 2, 3, 4, or 5.<br/>
 
−
Default Value: 3<br/>
 
−
 
 
−
* 0&mdash;event Ringing disabled
 
−
* 1&mdash;event Ringing enabled
 
−
* 2&mdash;play ringtone internally (event Ringing disabled)
 
−
* 3&mdash;play ringtone internally and enable event Ringing.
 
−
* 4&mdash;play ringtone through separate "ringer" device
 
−
* 5&mdash;play ringtone through "ringer" device and enable event Ringing
 
−
 
 
−
====ringing_timeout====
 
−
{{AnchorDiv|ringing_timeout}}
 
−
Valid Values: Empty, 0, or a positive number<br>
 
−
Default Value: 0<br>
 
−
 
 
−
 
 
−
Specifies the duration, in seconds, of the ringing tone. If set to <tt>0</tt> or if the value is empty, the ringing time is unlimited.
 
−
 
 
−
 
 
−
====ringing_file====
 
−
{{AnchorDiv|ringing_file}}
 
−
Valid Values: Empty string or string to 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.<br>
 
−
Default Value: <tt>ringing.wav</tt><br>
 
−
 
 
−
 
 
−
Specifies the audio file that is played when the ringing tone is enabled with the <tt>ringing_enabled</tt> option.<br>
 
−
Note that WebRTC does not support MP3 playback. The ringtone file for built-in ringing should be a RIFF (little-endian) WAVE file using one of the following formats:<br>
 
−
 
 
−
kWavFormatPcm  = 1, PCM, each sample of size bytes_per_sample<br>
 
−
kWavFormatALaw  = 6, 8-bit ITU-T G.711 A-law<br>
 
−
kWavFormatMuLaw = 7, 8-bit ITU-T G.711 mu-law<br>
 
−
 
 
−
 
 
−
Uncompressed PCM audio must be 16 bit mono or stereo and have a frequency of 8, 16, or 32 KHZ.
 
−
 
 
−
===<tt>device</tt> Section===
 
−
{{AnchorDiv|sdk_device}}
 
−
 
 
−
====audio_in_device====
 
−
{{AnchorDiv|audio_in_device}}
 
−
Valid Values: String<br/>
 
−
 
 
−
Microphone device name. For more information, see [[ConfiguringforAppleOS#Audio_Device_Settings|Audio Device Settings]]
 
−
 
 
−
 
 
−
====audio_out_device====
 
−
{{AnchorDiv|audio_out_device}}
 
−
Valid Values: String<br/>
 
−
 
 
−
Speaker device name
 
−
 
 
−
 
 
−
====capture_device====
 
−
{{AnchorDiv|capture_device}}
 
−
Valid Values: String<br/>
 
−
 
 
−
Capture device name.
 
−
 
 
−
 
 
−
====headset_name====
 
−
{{AnchorDiv|headset_name}}
 
−
Valid Values: String<br/>
 
−
 
 
−
The name of the headset model.
 
−
 
 
−
 
 
−
====use_headset====
 
−
{{AnchorDiv|use_headset}}
 
−
Valid values: <tt>0</tt> or <tt>1</tt>
 
−
 
 
−
If set to <tt>0</tt>, the audio devices specified in <tt>audio_in_device</tt> and <tt>audio_out_device</tt> 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 <tt>audio_in_device</tt> and <tt>audio_out_device</tt> are ignored.
 
−
 
 
−
===<tt>codecs</tt> Section===
 
−
{{AnchorDiv|sdk_codec}}
 
−
 
 
−
See [[ConfiguringforAppleOS#Working_with_Codec_Priorities|Working with Codec Priorities]].
 
−
 
 
−
==<tt>proxies</tt> Domain==
 
−
<span id="sdk_proxies"></span>
 
−
 
 
−
===<tt>proxy <n></tt> Section===
 
−
<span id="sdk_proxy"></span>
 
−
 
 
−
 
 
−
====display_name====
 
−
{{AnchorDiv|display_name}}
 
−
Valid Values: String<br/>
 
−
 
 
−
Proxy display name
 
−
 
 
−
 
 
−
====domain====
 
−
{{AnchorDiv|domain}}
 
−
Valid Values: String containing any valid SIP domain<br/>
 
−
Default Value: Empty string<br/><br/>
 
−
 
 
−
A SIP domain is an application layer configuration defining the management domain of a SIP proxy. The configured value should include <tt>hostport</tt> and may include <tt>uri-parameters</tt> as defined by RFC 3261. The scheme, <tt>userinfo</tt>, and <tt>transport</tt> URI parameters are included automatically.<br/><br/>
 
−
If set to an empty string, SIP Endpoint SDK uses the parameters from the <tt>Connectivity</tt> section to construct the SIP domain value as it did in previous versions.
 
−
 
 
−
 
 
−
====password====
 
−
{{AnchorDiv|password}}
 
−
Valid Values: String<br/>
 
−
 
 
−
Proxy password. Password configured for DN object.
 
−
 
 
−
 
 
−
====reg_interval====
 
−
{{AnchorDiv|reg_interval}}
 
−
Valid Values: Integers greater than or equal to <tt>0</tt><br/>
 
−
Default Value: <tt>0</tt>
 
−
 
 
−
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 <tt>0</tt>. If the setting is empty or negative, the default value is <tt>0</tt>, which means no new registration cycle is allowed. If the setting is greater than <tt>0</tt>, a new registration cycle is allowed and will start after the period specified by <tt>regInterval</tt>.
 
−
 
 
−
 
 
−
====reg_match_received_rport====
 
−
{{AnchorDiv|reg_match_received_rport}}
 
−
Valid Values: <tt>0</tt> or <tt>1</tt><br>
 
−
Default Value: <tt>0</tt><br>
 
−
 
 
−
This setting controls whether or not SIP Endpoint SDK should re-register itself when receiving a mismatched IP address in the <tt>received</tt> parameter of a <tt>REGISTER</tt> response. This helps resolve the case where SIP Endpoint SDK for OS X has multiple network interfaces and obtains the wrong local IP address. A value of 0 (default) disables this feature and a value of 1 enables re-registration.
 
−
 
 
−
 
 
−
====reg_timeout====
 
−
{{AnchorDiv|reg_timeout}}
 
−
Valid Values: Number<br/>
 
−
 
 
−
The period, in seconds, after which registration should expire. A new <tt>REGISTER</tt> request will be sent before expiration. Valid values are integers greater than or equal to <tt>0</tt>. If the setting is <tt>0</tt>, then registration is disabled, putting the endpoint in standalone mode. If the setting is <tt>empty</tt>/<tt>null</tt>, the default value of <tt>1800</tt> seconds is used.
 
−
 
 
−
 
 
−
===<tt>mailbox</tt> Section===
 
−
<span id="sdk_mailbox"></span>
 
−
{{NoteFormat|The '''mailbox''' section is a sub-section of the '''proxy<n>''' section.}}
 
−
 
 
−
====password====
 
−
{{AnchorDiv|password}}
 
−
Valid Values: String
 
−
 
 
−
Mailbox password
 
−
 
 
−
 
 
−
====server====
 
−
{{AnchorDiv|server}}
 
−
Valid Values: String
 
−
 
 
−
Proxy server address and port for this mailbox
 
−
 
 
−
 
 
−
====timeout====
 
−
{{AnchorDiv|timeout}}
 
−
Valid Values: Any positive integer<br/>
 
−
Default Value: <tt>1800</tt> seconds (30 minutes)
 
−
 
 
−
Subscription expiration timeout in seconds. If the setting is missing or set to <tt>0</tt>, the SDK uses a default timeout of 1800 seconds (30 minutes).<br/>
 
−
 
 
−
 
 
−
====transport====
 
−
{{AnchorDiv|transport}}
 
−
Valid Values: <tt>udp</tt>, <tt>tcp</tt>, or <tt>tls</tt>
 
−
 
 
−
Transport protocol to use when communicating with server
 
−
 
 
−
 
 
−
====user====
 
−
{{AnchorDiv|user}}
 
−
Valid Values: String
 
−
 
 
−
Mailbox number this line subscribes to.
 
−
 
 
−
==<tt>system</tt> Domain==
 
−
<span id="sdk_system"></span>
 
−
 
 
−
===<tt>diagnostics</tt> Section===
 
−
<span id="sdk_diagnostics"></span>
 
−
 
 
−
 
 
−
====enable_logging====
 
−
{{AnchorDiv|enable_logging}}
 
−
Valid Values: <tt>0</tt> or <tt>1</tt><br/>
 
−
 
 
−
Valid values of <tt>0</tt> or <tt>1</tt> disable or enable logging.
 
−
 
 
−
 
 
−
====log_file====
 
−
{{AnchorDiv|log_file}}
 
−
Valid values: String containing full path or relative path to the log file.<br/>
 
−
 
 
−
Log file name, for example, <tt>SipEndpoint.log</tt>
 
−
 
 
−
 
 
−
====log_level====
 
−
{{AnchorDiv|log_level}}
 
−
Valid Values: Number, <tt>0</tt>&ndash;<tt>4</tt><br/>
 
−
 
 
−
Valid values correspond to log levels:
 
−
 
 
−
* 0 = "Fatal"
 
−
* 1 = "Error"
 
−
* 2 = "Warning"
 
−
* 3 = "Info"
 
−
* 4 = "Debug".
 
−
 
 
−
 
 
−
====log_options_provider====
 
−
{{AnchorDiv|log_options_provider}}
 
−
Valid Values: String<br/>
 
−
 
 
−
Valid values for webrtc are <tt>(warning, state, api, debug, info, error, critical)</tt>. For example: <tt>gsip=2, webrtc=(error,critical)</tt>
 
−
 
 
−
 
 
−
====log_options_endpoint====
 
−
{{AnchorDiv|log_options_endpoint}}
 
−
Valid Values: Number, <tt>0</tt> &ndash; <tt>4</tt><br/>
 
−
 
 
−
Valid values are log levels, same as <tt>log_level</tt>
 
−
 
 
−
A value of <tt>10</tt> = Logging disabled.
 
−
 
 
−
 
 
−
====logger_type====
 
−
{{AnchorDiv|logger_type}}
 
−
Valid Values: <tt>external</tt><br/>
 
−
 
 
−
If set to <tt>external</tt>, an external logger is used.
 
−
 
 
−
===<tt>security</tt> Section===
 
−
{{AnchorDiv|sdk_security}}
 
−
 
 
−
 
 
−
====cert_file====
 
−
{{AnchorDiv|cert_file}}
 
−
Valid Values: String<br/>
 
−
 
 
−
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, <tt>/users/Desktop/certificate/hostname_cer.pem</tt>
 
−
 
 
−
 
 
−
====tls_enabled====
 
−
{{AnchorDiv|tls_enabled}}
 
−
Valid Values: Number<br/>
 
−
Default Value: <tt>0</tt>
 
−
 
 
−
If set to <tt>1</tt>, connection with TLS transport will be registered.
 
−
 
 
−
 
 
−
====use_srtp====
 
−
{{AnchorDiv|use_srtp}}
 
−
Valid Values: <tt>optional</tt>, <tt>allowed</tt>, <tt>disabled</tt>, <tt>off</tt>, <tt>elective</tt>, <tt>both</tt>, <tt>enabled</tt>, <tt>force</tt>, <tt>mandatory</tt>
 
−
 
 
−
Indicates whether to use SRTP:
 
−
 
 
−
* <tt>optional</tt> or <tt>allowed</tt>—do not send secure offers, but accept them
 
−
* <tt>disabled</tt> or <tt>off</tt>—do not send secure offers and reject incoming secure offers
 
−
* <tt>elective</tt> or <tt>both</tt>—send both secure and non-secure offers and accept either
 
−
* <tt>enabled</tt>—send secure offers, accept both secure and non-secure offers
 
−
* <tt>force</tt> or <tt>mandatory</tt>—send secure offers, reject incoming non-secure offers
 
−
 
 
−
====priv_key_file====
 
−
{{AnchorDiv|priv_key_file}}
 
−
Valid Values: String<br/>
 
−
 
 
−
Ful path to the <b>endpoint private key</b> file used for client-side authentication for outgoing TLS connections. For example, <tt>/users/Desktop/certificate/hostname_priv_key.pem</tt>
 
−
 
 
−
 
 
−
====ca_list_file====
 
−
{{AnchorDiv|ca_list_file}}
 
−
Valid Values: String<br/>
 
−
 
 
−
Full path to the <b>Certificat Authority's list file</b>. For example, <tt>/users/Desktop/certificate/ca/ca_cert.pem</tt>
 
−
 
 
−
== Producing RTCP Extended Reports ==
 
−
You can use SIP Endpoint SDK to produce RTCP Extended Reports (<span class="plainlinks">[http://tools.ietf.org/html/rfc3611 RFC 3611]</span>) and publish them according to <span class="plainlinks">[http://tools.ietf.org/html/rfc6035 RFC 6035]</span> at the end of each call, using a collector address of your choice.
 
−
 
 
−
{{NoteFormat|The publish message is sent to the specified collector address only if the <tt>vq_report_collector</tt> parameter is configured with the <tt><nowiki> user@server:port;transport=udp</nowiki></tt> format. For example, <tt><nowiki>collector@127.0.0.1:5160;transport=udp</nowiki></tt>.}}
 
−
 
 
−
'''Settings:'''
 
−
 
 
−
<source lang="xml">
 
−
<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>
 
−
</source>
 
−
 
 
−
'''Endpoint:'''
 
−
 
 
−
The <tt>vq_report_publish</tt> and <tt>vq_report_collector</tt> settings can be read from the Endpoint Policy by using the following methods:
 
−
 
 
−
<source lang="csharp">
 
−
GetEndpointPolicy(EndpointPolicyQuery.VqReportCollector);
 
−
GetEndpointPolicy(EndpointPolicyQuery.VqReportPublish);
 
−
</source>
 
−
 
 
−
== Working with Codec Priorities ==
 
−
Codecs are listed by name in the <tt>codecs</tt> 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 <tt>payload_type</tt> is an integer. For codecs with dynamic payload type such as iSAC, iLBC, OPUS valid values are between <tt>96</tt> and <tt>127</tt>.
 
−
 
 
−
==== Example ====
 
−
 
 
−
<source lang="xml">
 
−
<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>
 
−
 
 
−
</source>
 
−
 
 
−
<!--{{NoteFormat|For information on which codecs are supported by SIP Endpoint SDK for .NET, see the list of [[Documentation:SESN:Overview:Welcome:8.5.2OSX#Supported_Codecs|Supported Codecs]] in the SIP Endpoint SDK Overview.|2}}-->
 
−
 
 
−
==Audio Device Settings==
 
−
 
 
−
You can configure a headset and other audio input devices using the following parameters in the configuration file:
 
−
 
 
−
* <tt>use_headset</tt>
 
−
* <tt>headset_name</tt>
 
−
* <tt>audio_in_device</tt>
 
−
* <tt>audio_out_device</tt>
 
−
 
 
−
 
 
−
If the SDK cannot access any of the configured audio devices, the SDK uses the default system audio devices.
 
−
 
 
−
If <tt>use_headset</tt> is set to <tt>1</tt>, the SDK searches for a headset with configured <tt>headset_name</tt>. If the SDK does not find the headset, it uses the system defaults.
 
−
 
 
−
If <tt>use_headset</tt> is set to <tt>0</tt>, the SDK skips the search for a headset and searches for audio in and audio out devices with names configured by <tt>audio_in_device</tt> and <tt>audio_out_device</tt>. If the devices are not found, the SDK uses the 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 <tt>use_headset</tt>, <tt>auto_answer</tt>, and <tt>reject_session_when_headset_na</tt> 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 ====
 
−
 
 
−
{|
 
−
|-
 
−
| rowspan="2"| <u>''Headset is Available''</u>
 
−
 
 
−
The SDK considers a headset available if the headset is found by name.
 
−
 
 
−
Outgoing calls can be initiated.
 
−
| <tt>auto_answer=1</tt>
 
−
| Incoming calls are answered automatically:
 
−
* As audio if <tt>auto_accept_video=0</tt>
 
−
* As audio with video if the call has video and <tt>auto_accept_video=1</tt>
 
−
|-
 
−
| <tt>auto_answer=0</tt>
 
−
| Incoming calls are answered manually and the user explicitly selects whether or not video streams should be accepted (using the <tt>has_video</tt> parameter supplied in the <tt>gs_session_info</tt> argument)
 
−
|-
 
−
| rowspan="2"| <u>''Headset is Not Available''</u>
 
−
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.
 
−
| rowspan="2"| No auto-answer is possible in this sub-case, so the <tt>auto_answer</tt> setting is not used
 
−
| <tt>reject_session_when_headset_na=1</tt>
 
−
* Incoming calls are automatically rejected
 
−
* Outgoing calls are blocked
 
−
|-
 
−
| <tt>reject_session_when_headset_na=0</tt>
 
−
* Incoming calls can be answered manually&mdash;it is assumed that the agent will plug the headset in (or use an available non-headset device, if applicable) before answering the call
 
−
* Outgoing calls can be initiated&mdash;it is the agent's responsibility to ensure that the appropriate audio devices are available before the call is answered by the remote side
 
−
|-
 
−
|}
 
−
 
 
−
==== Auto-answer and Call Rejection when use_headset=0 ====
 
−
Audio devices are configured using the <tt>audio_in_device</tt> and <tt>audio_out_device</tt> settings. If no valid <tt>audio_in_device</tt> and <tt>audio_out_device</tt> devices are found, the SDK selects the system defaults. Outgoing calls can be initiated.
 
−
 
 
−
{|
 
−
|-
 
−
| rowspan="2"| <u>''Both microphone and speaker are available''</u>
 
−
| <tt>auto_answer=1</tt>
 
−
| Incoming calls are answered automatically:
 
−
* As audio if <tt>auto_accept_video=0</tt>
 
−
* As audio with video if the call has video and <tt>auto_accept_video=1</tt>
 
−
|-
 
−
| <tt>auto_answer=0</tt>
 
−
| Incoming calls are answered manually and the user explicitly selects whether or not video streams should be accepted (using the <tt>has_video</tt> parameter supplied in the <tt>gs_session_info</tt> argument)
 
−
|-
 
−
| <u>''Either microphone or speaker is not available''</u>
 
−
* Incoming calls can be answered manually&mdash;it is assumed that the agent will plug in the headset (or use an available non-headset device, if applicable) before answering the call
 
−
* Outgoing calls can be initiated&mdash;it is the agent's responsibility to ensure that the appropriate audio devices are available before the call is answered by the remote side
 
−
| No auto-answer is possible in this sub-case, so the <tt>auto_answer</tt> setting is not used
 
−
| Auto-rejection is not applicable, so the  <tt>reject_session_when_headset_na</tt> setting is not used
 
−
|-
 
−
|}
 
 
[[Category:SIP Endpoint SDK]]
 
[[Category:SIP Endpoint SDK]]
 
[[Category:SIP Endpoint SDK Developer's Guide]]
 
[[Category:SIP Endpoint SDK Developer's Guide]]
 
[[Category:V:SESDK:9.0.0OSXDRAFT]]
 
[[Category:V:SESDK:9.0.0OSXDRAFT]]

Revision as of 05:32, July 25, 2017

Configuring SIP Endpoint SDK for Apple OS

The sample application that comes with the SIP Endpoint SDK for Apple OS distribution includes a property list (plist) that is used for configuring the application. This file is located at <SIP Endpoint SDK Installation Folder>/Sample/Src/Sip EP Sample.plist.

Important.png Note: Genesys recommends that you use the sample application as the starting point for your development efforts.

If you are developing applications from scratch, you should:

  1. Create a copy of the plist from the sample application
  2. Name it appropriately
  3. Place it in your app's Src folder.

SIP Endpoint Configuration Settings

You can customize the following settings in your SIP Endpoint SDK applications.

Section Setting Values Description
GSDefaultConnectionPolicy
networkInterface String Name of the network interface
GSDefaultDevicePolicy
audio_in_device String Microphone device
audio_out_device String Speaker device
use_headset Boolean If set to YES, the SDK uses a headset as the preferred audio input and output device.
GSDefaultEndpointPolicy
audioQos Number The integer value representing the DSCP bits to set for RTP audio packets.
includeOSVersionInUserAgentHeader Boolean If set to YES, the user agent field includes the OS version the client is currently running on. Default: NO.
ip_version IPv4

IPv6
IPv4,IPv6
IPv6,IPv4
empty

A value of IPv4 means that the application selects an available local IPv4 address; IPv6 addresses are ignored.

A value of IPv6 means that the application selects an available local IPv6 address; IPv4 addresses are ignored.
A value of IPv4,IPv6 or an empty value means that the application selects an IPv4 address if one exists. If not, an available IPv6 address are selected.
A value of IPv6,IPv4 means that the application selects an IPv6 address if one exists. If not, an available IPv4 address are selected.
Default: IPv4,IPv6.
NOTE: This parameter has no effect if the public_address option specifies an explicit IP address.
NOTE: Although the IPv6 configuration options are available in the plist file for this product, they are not supported in the 8.1.2 Release of SIP Endpoint SDK for Apple OS.

public_address String Local IP address or Fully Qualified Domain Name (FQDN) of the machine.

NOTE: Although the IPv6 configuration options are available in the plist file for this product, they are not supported in the 8.1.2 Release of SIP Endpoint SDK for Apple OS.

rtpInactivityTimeout Number Timeout interval for RTP inactivity. Valid values are integers from 0 to 150. A value of 0 or values greater than 150 mean that this feature is not activated. A value in the range of 1 to 150 indicates the inactivity timeout interval in seconds. Default: 0.
rtpPortMin Number The integer value representing the minimum value for an RTP port range. Must be within the valid port range of 9000 to 65535. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (9000) and maximum (minimum value + 999) are used. 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.
rtpPortMax Number The integer value representing the maximum value for an RTP port range. Must be within the valid port range of 9000 to 65535. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (9000) and maximum (minimum value + 999) are used. 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.
secureSignalingQos Number The integer value representing the DSCP bits to set for TCP packets.
signalingQos Number The integer value representing the DSCP bits to set for SIP packets.
sipPortMin 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 and maximum values are not specified or are set to an invalid value, the default minimum (5060) and maximum (minimum value + 6) are used. 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.
sipPortMax 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 minimum and maximum values are not specified or are set to an invalid value, the default minimum (5060) and maximum (minimum value + 6) are used. 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.
videoQos Number The integer value representing the DSCP bits to set for RTP Video packets.
GSDefaultSessionPolicy
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_accept_video Boolean If set to YES, all incoming video should be accepted automatically.

NOTE: The video mode window will not be opened if auto_accept_video and auto_answer are both set to 0.

auto_answer Boolean If set to YES, all incoming calls should be answered automatically.

NOTE: The video mode window will not be opened if auto_accept_video and auto_answer are both set to 0.

dtmf_method Rfc2833

Info
InbandRtp

Method to send DTMF
reject_session_when_headset_na Boolean If set to YES, the SDK should reject the incoming session if a USB headset is not available.
sip_code_when_headset_na Number 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.
basic: account connection details
regInterval 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.
registrationTimeout 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 empty or negative, the default value is 1800 seconds. If the setting is 0, registration is disabled, putting the endpoint in standalone mode.
transport udp

tcp
tls

The transport protocol to use when communicating with server
server String The server address and port
stun_server String STUN server address (with optional port). An empty or null value indicates this feature is not being used.
turn_password Number Password for TURN authentication
turn_server String TURN server address (with optional port). An empty or null value indicates this feature is not being used.
turn_userName String User ID for TURN authorization
user String User ID for this connection
basic: account mailbox details
server String Proxy server address and port for this mailbox
timeout Number Registration timeout interval
transport udp

tcp
tls

Transport protocol to use when communicating with server
user String User ID for this mailbox
codecs: priority
<Codec Name> Number Codec priority in SDP. A higher number means the codec has preference in codec negotiation.
diagnostics
enable_logging Boolean Enable or disable logging
log_file String Log file name, for example, SipEndpoint.log
log_level debug

info
warn
error
fatal

Log levels
Log_option_provider #/Empty

gsip=3,webrtc=(state,warning)

If set to #/Empty, log messages will not include webrtc messages.

If set to gsip=3,webrtc=(state,warning) and the level is set to info, log messages will include webrtc messages.

logger_type file

default

If set to file, the log data will be printed to the file specified by the log_file parameter.

If set to default, the log data will be printed to the console.

security
ca_list_file String Certificate of Authority (CA) list file
cert_file String Public endpoint certificate file, which is used as client-side certificate for outgoing TLS connection and server-side certificate for incoming TLS connection
method unspecified

tlsv1
sslv2
sslv3
sslv23

Security method
password String Password to open private key
privkey_file String Path to the optional private key file of the endpoint certificate to be used. Example: /usr/local/ssl/certs/example_priv_key.pem.
require_client_cert Boolean Indicates whether a client certificate is required. Default: NO.
server_name String Server name. Default: empty.
srtp_secure_signaling no

yes
sips

Indicates whether SRTP secure signaling is to be used
timeout Number Timeout interval. Default: 0.
tls_enabled Boolean If set to YES, connection with TLS transport will be registered. Default: NO.
use_srtp disabled

optional
mandatory

Indicates whether to use SRTP
verify_client Boolean Indicates whether clients must be verified. Default: NO.
verify_server Boolean Indicates whether servers must be verified. Default: NO.

Specifying Behavior When A USB headset Is Not Available

The following behaviors can now be specified when a SIP Endpoint user does not have a working USB headset:

  • Whether SIP Endpoint should automatically reject an incoming call
  • The SIP error code to be sent to the inviting party

Support for this feature involves several configuration settings:

  • endpoint:GSDefaultDevicePolicy:use_headset
  • endpoint:GSDefaultSessionPolicy:reject_session_when_headset_na
  • endpoint:GSDefaultSessionPolicy:sip_code_when_headset_na

Information about these settings is available in the table of SIP Endpoint Configuration Settings that appears elsewhere on this page.

You can tell whether SIP Endpoint has been instructed to use a USB headset by using the following method of GSDevicePolicyDelegate: 

- (BOOL) useHeadset;

To determine whether SIP Endpoint will reject an incoming session when a USB headset is not available or to determine which SIP error code is sent if a USB headset is not available, use the following methods of GSSessionPolicyDelegate: 

- (BOOL) rejectWhenHeadsetNa:(id<GSSession>) session;
- (NSString*) sipCodeWhenHeadsetNa:(id<GSSession>) session;

Configuring Message Waiting Indicator (MWI) Support

A Message Waiting Indicator (MWI) is usually an audio or visual signal that a voicemail or other type of message is waiting. SIP Endpoint SDK's MWI support involves several configuration settings:

  • endpoint:basic:mailbox:user
  • endpoint:basic:mailbox:server
  • endpoint:basic:mailbox:transport
  • endpoint:basic:mailbox:timeout

Information about these settings is available in the table of SIP Endpoint Configuration Settings that appears elsewhere on this page. You can use these settings to have SIP Server notify your application when new messages have been received by the subscribing mailbox. GSMessageWaitingIndicationService provides the following methods to control mailbox notification subscriptions: 

-(GSResult) subscribeForMailbox:(GSMessageWaitingIndicationSubscription*) subscription;
-(GSResult) unsubscribeForMailbox:(GSMessageWaitingIndicationSubscription*) subscription;

Notifications are provided by GSMessageWaitingIndicationNotificationDelegate. Access to the MWI summary is provided by the following method: 

- (void) state:(GSMessageWaitingIndicationState*) 
         state forSubscription:(GSMessageWaitingIndicationSubscription*) subscription

These notifications encapsulate the following information: 

subscription = theSubscription;
messagesWaiting = theMessagesWaiting;
messageSummary = theMessageSummary;
Comments or questions about this documentation? Contact us for support!