Documentation:SESDK:Developer:DynamicReconfiguration:9.0.0OSXDRAFT

Support for Dynamic Reconfiguration

Important

This feature was introduced as part of the 9.0.006.10 release.

This feature provides additional options to support regex matching and specify codec priorities.

This page describes the API and rules for dynamic reconfiguration of SIP Endpoint SDK from an application. Implementation provides two methods: one to get access to current configuration and another to change that configuration dynamically.

The following methods are defined in the GSEndpoint protocol:

@protocol GSEndpoint <NSObject>
/**
 Get endpoint configuration setting
 @param key
 @returns string value of the requested key string
 @returns empty string if key-value pair does not exists
 @returns empty string if key nill or empty
 */
- (NSString*) getConfigSettingForKey:(NSString*) key;
/**
 Set endpoint configuration setting
 @param value
 @param key
 @returns result of the operation
 */
- (GSResult) setConfigSettingValue:(NSString*) value forKey:(NSString*) key;

The following methods are defined in the IExtendedService interface:

public interface class IExtendedService
{
void SetConfigStringSetting(String^ key, String^ value);
String^ GetConfigStringSetting(String^ key);
}

Detailed Description

The "key" value (for both configuration methods) should be in either one of these two forms:

1. for reference to Connectivity parameters in "Basic" container -- "name : N ", where
   • name is attribute name, one of "user", "server", "protocol", "transport" (synonym for "protocol").
   • N refer to Connectivity line index, starting from 0, i.e. setting "user:0" refer to 'user' parameter in the first Connectivity line, and "user:1" refer to the second line.
2. for reference to all setting in "Genesys" container -- "domain . section .[subsection .]setting", where
   • domain is the XML domain element, must be one of "policy", "codecs", "proxies" or "system"
   • section and setting refer to corresponding XML schema elements
   • subsection is optional section name, as used currently for NAT options

Important

Historically SDK for .NET and OS X used different delimiters in option keys. For backward compatibility, in current SDK version, dot and colon in the "key" value may be used interchangeably.

When changes take effect

While any configuration setting may be changed at any time, not all changes take effect immediately. Particularly, for most cases:

• Connectivity parameters and settings in proxies domain take effect when connection is activated,
• settings in policy.endpoint section, and codecs and system domains take affect after Endpoint restart,
• settings in policy.session section take effect for the next session created,
• settings in policy.device section take effect next time device is going to be selected (TODO: what method to use to force that selection?)

Exceptions

• settings in policy.endpoint section that take effect for the next session (without Endpoint restart):
  • include_os_version_in_user_agent_header
  • include_sdk_version_in_user_agent_header
  • answer_sdp_priority
  • refer_to_proxy
  • vq_report_publish
  • vq_alarm_threshold
• setting policy.session.dtmf_method requires Endpoint restart, if changed to / from "rfc2833" value (since that change affect the enabled codec list)

Code Samples

Overview

Code samples in this section are written in assumption that application code uses class with 'endpoint' property:

 private SipEndpoint.IEndpoint endpoint;

and the following initialization code:

this.endpoint = SipEndpoint.EndpointFactory.CreateSipEndpoint();
this.extendedService = this.endpoint.Resolve("IExtendedService") as ExtendedService;
this.connectionManager = this.endpoint.Resolve("IConnectionManager") as ConnectionManager;

Overview

All code samples in this section are written in assumption that application code uses class with 'ep' property referring to GSEndpoint object. That is, it includes the following in the app header:

@property(nonatomic, retain) 
id <GSEndpoint> ep;

and that property is initialized in the app implementation as following:

self.ep = [GSEndpointFactory initSipEndpoint:configData];

Changing Session Policy Auto-answer

The case of changing settings that takes effect immediately is very simple. For example this is how to get current value and set policy auto-answer value to "1" (true).

Important

Any change will not affect any calls that are already ringing on the endpoint but will take effect from the next call onwards.

NSString *oldAA = [self.ep getConfigSettingForKey:"policy.session.auto_answer"];
GSResult result = [self.ep setConfigSettingValue:"1" forKey:"policy.session.auto_answer"];
if (result == GSResultOK)
 NSLog(@"Auto-answer changed from %@ to 1.",oldAA);
else NSLog(@"Error %d changing Auto-answer from %@.", result, oldAA);

String oldAA= this.extendedService.GetConfigStringSetting("policy.session.auto_answer");
GsStatus result = this.extendedService.SetConfigStringSetting("policy.session.auto_answer", "1");
if (result == GsStatusSuccess) 
 this.extendedService.LogPrint(4,"Auto-answer changed from " + oldAA +" to " + newAA);
else this.extendedService.LogPrint(4,"Error" + result + "changing Auto-answer to " + newAA);

Changing Connectivity Parameters

An example of how to re-connect to different SIP Server location - to do so, application should disable connection with certain "configId" or "connectionId", change server location and then enable connectionagain.

1. Getting a connection object may be done in two ways - either by "configId" (position in connections list of the current configuration, starting from 0 index):

   GSSipConnection *connection = [ [self.ep connectionManager] connectionByConfigId:configId];
   

   or by "connectionId" (an ID that is set into the "connectionId" property during enabling the connection):

   GSSipConnection *connection = 
   [ [self. ep connectionManager] connectionByConnectionId:connectionId] ;
   

2. Changing the server location to "new_server" for given connection:

   [connection disable]; // that operation cannot fail (always returns GSResultOK)
   NSString *key = [NSString stringWithFormat:@"server:%d", connection.configId];
   GSResult result = [self.ep setConfigSettingValue:new_server forKey:key];
   if (result == GSResultOK) result = [connection enable];
   if (result == GSResultOK)
   NSLog(@"Connection changed to %@.", new_server);
   else NSLog(@"Error %d changing connection.", result);
   

An example of how to re-connect to different SIP Server location - to do so, application should disable connection with certain "connectionId" (which is assigned by SDK after connection is enabled), change server location and then enable connection by "connectionConfigId" again.

this.connectionManager.DisableConnection(connectionId); // that operation cannot fail (always returns GsStatusSuccess)
String key = "server:" + connection.configId.ToString();
this.extendedService.SetConfigStringSetting(key, new_server);
this.connectionManager.EnableConnection(connectionConfigId);

Just in case if application ever needs to get "connectionId" for known "connectionConfId", the following method may be used:

 public int GetConnectionIdByConfigId(int connectionConfigId)
 {
 foreach (Connection conn in this.connectionManager.Connections)
 if (conn.ConfId == connectionConfigId) return conn.Id;
return -1; // negative result means "not found"
}

Changing Endpoint Setting with Full SDK Restart

[self.ep stop] // stop endpoint
[self.ep setConfigSettingValue:new_addr forKey:@"policy.endpoint.public_address"];
if ([self.ep configure]) { // re-start endpoint
self.ep.notificationDelegate = self;
self.ep.connectionManager.notificationDelegate = self;
self.ep.sessionManager.notificationDelegate = self;
self.ep.deviceManager.notificationDelegate = self;
[self.ep activate];
[self.ep.deviceManager configure];
self.connections = [self.ep.connectionManager allConnections];
}
else NSLog(@"Error restarting");

this.extendedService.StopCore(); // stop endpoint
this.extendedService.SetConfigStringSetting("policy.endpoint.public_address", new_addr);
this.extendedService.RestartCore();