Jump to: navigation, search

Configuring SIP Endpoint SDK for .NET

Basic Configuration Settings

You may want to configure RTP port ranges, QoS bits, diagnostics, and endpoint DNs in your application. The following sections contain information that may be helpful in doing that.

Most configuration settings described on this page can be found and changed in the SipEndpoint.config file that is included with your SIP Endpoint SDK installation. For more information about this file, see Default SipEndpoint.config Settings.

RTP Port Ranges

It can sometimes be useful to limit the RTP port range used by your SIP Endpoint for sending and receiving media. In order to accomplish this, the SIP Endpoint SDK has settings that are read from the configuration file when the endpoint is initializing.

The SIP Endpoint uses RTP ports from this range for all media sessions until the next restart. This means that the RTP port range cannot be changed while the endpoint is running.

The port range is configured by specifying the minimum and maximum number of RTP ports to use, using the following settings in the SipEndpoint.config file:

  • port_range_enable — Forces the application to use transport ports within a specific range (as specified by port_range_min and port_range_max).
  • port_range_min — The lowest port number. This parameter must have a value that is less than the value of the maximum port range parameter. The smallest allowable value is 10.
  • port_range_max — The highest port number. This parameter must have a value that is greater than the value of the minimum port range parameter. The largest allowable value is 65535.

Information.png Note: If the port range is set to an incorrect value (if the maximum value is less than the minimum value, or if values that are out of range or uncountable are used for example) then the default port range values of 1025 to 65535 are used instead.

QoS Bits

You can mark RTP packets by setting the QoS (TOS) bits so that network routers can prioritize them. This can make a big difference in the quality of your voice transmissions. When the SIP Endpoint is initializing, it gets information on QoS (TOS) bit settings from the SipEndpoint.config file. This information cannot be changed while the endpoint is running.

The system:qos:audio setting allows you to specify a string value that properly marks your RTP packets, and the type of QoS supported for audio. For example, you could specify the type of QOS with a value such as "tos 22". If QOS is not supported for audio, leave this setting empty.

Diagnostics

In order to diagnose production issues, it is important to have access to diagnostic information that relates to your SIP endpoint and its environment. Because of this, the SIP Endpoint SDK provides logging of the following CounterPath subsystems:

  • Audio — Audio-related logging, including audio devices
  • DNS — DNS resolution
  • Jitter
  • Resip — ReSIProcate logging, including SIP signaling and transport

The logging level is configurable via the log_level setting and can be set to:

  • None
  • Critical
  • Error
  • Warning
  • Info
  • Debug
  • MaxDetails

For SIP Endpoint logging, the endpoint supports the standard ILogger Platform SDK logging interface and the Platform SDK logging library.

For troubleshooting purposes, Genesys recommends running a network tracer such as PCap Trace from the command line with predefined settings including filters and output file. A file with a recorded trace can be read by PCap Trace.

Important.png Note: There is not a one-to-one mapping between calls in the softphone and calls in the SIP Endpoint. The SIP Endpoint logs will not contain the ConnectionID that is used by the softphone for call identification.

Endpoint DNs

The following fields of DN objects can be configured:

  • Number — Contains a numeric-only DN number. This number can be used to dial from a phone to reach this DN directly. The "@" character and domain names are not allowed. This number constitutes the username part of the endpoint's Address of Record (AOR).
  • Type — Should be set to "Extension".
  • Annex TServer/refer-enabled — Valid values are "true" or "false":
    • "true" indicates that REFER can be used to make a call or a transfer. (This value is supported by the SIP Endpoint SDK starting in release 8.0.000.11.)
    • "false" indicates that REFER is disabled for the above usage.
  • Annex TServer/sip-cti-control — Valid values are "talk", "hold", "dtmf", or "beep":
    • "talk" and "hold" are used to support the talk and hold BroadSoft extensions.
    • "dtmf" is used to support the sending of DTMF tones during third-party call control of an active call.
    • "beep" is used to provide a periodical beep tone in an active call. Start and stop of the beeping is controlled by third-party call control.


Advanced Settings and Configuration Options

The default configuration file does not contain all settings that may be used with the SIP Endpoint SDK; additional settings can be added to change certain behaviors. Some of these additional settings are discussed below.

Controlling Volume Levels

When using some devices, it can appear that changes made to the volume levels are not saved. This typically occurs because the device being used doesn't allow changes to the sound levels for that device.

In other cases it can appear that sound levels are being adjusted correctly, but no change (and possibly no sound) can be heard. This is often because the changes made were applied to Wave volume, but the actual volume level being used or returned by the getVolume() function is limited by the master volume setting.

To correct these behaviors, change the allow_master_volume_change setting to 1, enabling your application to adjust the master volume levels instead of limiting it to individual devices or Wave volume levels. 

<domain name="video">
...
    <section name="mixer">
    ...
        <setting name="allow_master_volume_change" value="1"/>
    </section>
</domain>


Working with Codec Priorities

Each section describing an available codec contains the following key settings:

Setting Name Allowable Values Description
enabled 1 = true

0 = false

When set to 1, the SIP Endpoint SDK is able to use the specified codec.
priority Numeric value of 1 or higher Specifies the numeric priority of the codec, used to create a prioritized list of codecs that the SIP Endpoint SDK will advertise in the INVITE or 200 OK Session Description Protocol (SDP) as its preferred codecs for incoming audio or video - that is, the audio/video the other party should send.

A lower number has a higher priority, therefore 1 is the highest priortity.

For example, assume that you have the following priorities set in your SIP Endpoint SDK configuration: 

<domain name="codecs">
    ...
    <section name="g711a">
        <setting name="enabled" value="1" />
        <setting name="priority" value="2.000000" />
    </section>
    ...
    <section name="g729">
        <setting name="enabled" value="0" />
        <setting name="priority" value="1.000000" />
    </section>
    ...
</domain>

By default, a codec with higher priority (g729 in this example) is typically used for communication. However, there are some cases where codec selection relies on other factors such as network condition to determine which codec is used.

Forcing Codec Priority

In the priority example above, the RTP stream could be transmitted with G711 under some conditions even though the INVITE messages are sent with G729. To ensure that the codec you have given the highest priority is always used, update your SipEndpoint.config file to include the honor_first_codec setting:

  • Setting the value to 1 instructs the SIP Endpoint SDK to respect the other party's prefered codec as advertised in the received SDP.
  • Setting the value to 0 instructs the SIP Endpoint SDK to ignore the other party’s prefered codec as advertised in the received SDP. In this case, audio and video are sent using the best available codec based on the other party's capability, the available bandwidth, and network conditions.

An snippet including the honor_first_codec setting is provided below: 

<domain name="system">
  ...
  <section name="network">    
    <setting name="honor_first_codec" value="1"/>
  </section>
  ...
</domain>

G.729 Annex B Support

In addition to the existing support for the G.729 voice codec with a setting of annexb=yes, SIP Endpoint SDK for .NET now supports the G.729 voice codec with an option of annexb=no.

To configure this setting in the SipEndpoint.config file, add the vad_enabled setting to the G.729 section with a value of either 1 (annexb=yes) or 0 (annexb=no), as shown below: 

<domain name="codecs">
  ...
  <section name="g729">
     <setting name="enabled" value="1"/> 
     <setting name="vad_enabled" value="1"/>
  </section>
  ...
</domain>

Headset Connectivity Notification

The SIP Endpoint SDK only supports headset monitoring when the device is explicitly defined in the SipEndpoint.config file as shown below: 

<domain name="genesyslab">
...
    <section name="device">
    ...
        <setting name="use_headset" value="1"/>
        <setting name="headset_name" value="DEVICE NAME"/>
    </section>
</domain>

In this case, headset connectivity is fully supported and the application can receive events indicating that the device has been plugged or unplugged.

It is also possible to use your application to select audio devices automatically by using the SIP Endpoint SDK API to look for IN and OUT devices. Using the GetAllSystemAudioInDevices() and GetAllSystemAudioutDevices() methods allows you to check for attached devices, which can then be used to update the following settings before initializing the SIP Endpoint SDK. 

<domain name="genesyslab">
...
    <section name="device">
    ...
        <setting name="manual_audio_devices_configure" value="1"/>
        <setting name="audio_in_device" value="InDevice"/>
        <setting name="audio_out_device" value="OutDevice"/>
    </section>
</domain>

However, the plugged or unplugged states are not monitored for the selected device in this case.

If no devices are defined in the SipEndpoint.config file then the SIP Endpoint SDK uses a default procedure to determine what device is attached, and will not monitor for plugged/unplugged states.

SIP Messaging and Media Encryption

SIP Endpoint SDK has settings that allow you to encrypt SIP messaging and the media channel. The SIP messaging can be encrypted using TLS, while the media channel can be encrypted using SRTP. The following diagram shows the SIP Endpoint SDK architecture with these features enabled.


SIP Endpoint SDK TLS-SRTP Architecture.png

Figure 1: SIP Endpoint SDK Architecture with TLS and SRTP Enabled


To enable TLS support, set the protocol to tls, as shown here. The outgoing SIP messaging will be encrypted: 

<Container name ="Basic">
  <Connectivity user ="DN" server="SipServerHost:Port" protocol="tls"/>
</Container>

To encode the media channel, set media_encrypted to 1, as shown here: 

<domain name="proxies">
  <section name="proxyN">
    <setting name="media_encrypted" value="1"/>
  </section>
</domain>

The media_encrypted setting can be set to 1 (true) or 0 (false), with the following meanings:

Value Description
1 SIP Endpoint can make and accept only media encrypted calls;
0 Media encrypted calls are not allowed for the SIP Endpoint.

Digest Authentication Support

SIP Endpoint SDK supports the RFC2617-style digest authentication that is currently used by SIP Server. This authentication is triggered by using the following DN configuration options: password and authenticate-requests. If these options are configured for a specific DN, then SIP Server enforces the authentication mechanism for that DN.

During registration, the SIP Endpoint receives a 401 Unauthorized SIP challenge message request from SIP Server. The SIP Endpoint should then provide the encrypted password, along with the Digest username, in the next REGISTER message.

At this point, SIP Server compares the received password to the password associated with the DN object defined in Config Server. If the passwords match, then the SIP Endpoint can be registered and may proceed to access the call functionality provided by SIP Server.

SIP Endpoint SDK provides the following method to set the password for a particular connection ID. This method has been added to the IExtendedService interface in the Genesyslab.Sip.Endpoint.Provider.CP namespace: 

void SetPassword(int connectionId, String^ password);
This page was last edited on July 26, 2016, at 22:15.
Comments or questions about this documentation? Contact us for support!