Jump to: navigation, search
(Changing Endpoint Setting with Full SDK Restart)
Line 12: Line 12:
 
<div class="cloud-wrapper">
 
<div class="cloud-wrapper">
 
<div class="cloud-left">
 
<div class="cloud-left">
The following methods are defined in GSEndpoint protocol:
+
The following methods are defined in the GSEndpoint protocol:
 
<pre>
 
<pre>
  @protocol GSEndpoint <NSObject>
+
@protocol GSEndpoint <NSObject>
  /**
+
/**
  Get endpoint configuration setting
+
Get endpoint configuration setting
  @param key
+
@param key
  @returns string value of the requested key string
+
@returns string value of the requested key string
  @returns empty string if key-value pair does not exists
+
@returns empty string if key-value pair does not exists
  @returns empty string if key nill or empty
+
@returns empty string if key nill or empty
  */
+
*/
  - (NSString*) getConfigSettingForKey:(NSString*) key;
+
- (NSString*) getConfigSettingForKey:(NSString*) key;
  /**
+
/**
  Set endpoint configuration setting
+
Set endpoint configuration setting
  @param value
+
@param value
  @param key
+
@param key
  @returns result of the operation
+
@returns result of the operation
  */
+
*/
  - (GSResult) setConfigSettingValue:(NSString*) value forKey:(NSString*) key;
+
- (GSResult) setConfigSettingValue:(NSString*) value forKey:(NSString*) key;
 
</pre>
 
</pre>
 
</div>
 
</div>
Line 38: Line 38:
 
<div class="cloud-wrapper">
 
<div class="cloud-wrapper">
 
<div class="cloud-left">
 
<div class="cloud-left">
The following methods are defined in IExtendedService interface:
+
The following methods are defined in the IExtendedService interface:
 
<pre>
 
<pre>
  public interface class IExtendedService
+
public interface class IExtendedService
  {
+
{
    void SetConfigStringSetting(String^ key, String^ value);
+
void SetConfigStringSetting(String^ key, String^ value);
    String^ GetConfigStringSetting(String^ key);
+
String^ GetConfigStringSetting(String^ key);
  }
+
}
 
</pre>
 
</pre>
 
</div>
 
</div>
Line 51: Line 51:
  
 
==Detailed Description==
 
==Detailed Description==
The "key" value (for both configuration methods) should be in either one of these forms:
+
The "key" value (for both configuration methods) should be in either one of these two forms:
  
 
# for reference to Connectivity parameters in "Basic" container -- "name : N ", where
 
# for reference to Connectivity parameters in "Basic" container -- "name : N ", where
Line 96: Line 96:
 
and the following initialization code:
 
and the following initialization code:
 
<pre>
 
<pre>
  this.endpoint = SipEndpoint.EndpointFactory.CreateSipEndpoint();
+
this.endpoint = SipEndpoint.EndpointFactory.CreateSipEndpoint();
  this.extendedService = this.endpoint.Resolve("IExtendedService") as ExtendedService;
+
this.extendedService = this.endpoint.Resolve("IExtendedService") as ExtendedService;
  this.connectionManager = this.endpoint.Resolve("IConnectionManager") as ConnectionManager;
+
this.connectionManager = this.endpoint.Resolve("IConnectionManager") as ConnectionManager;
 
</pre>
 
</pre>
 
</div>
 
</div>
Line 110: Line 110:
 
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:
 
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:
 
<pre>
 
<pre>
  @property(nonatomic, retain)  
+
@property(nonatomic, retain)  
  id <GSEndpoint> ep;
+
id <GSEndpoint> ep;
 
</pre>
 
</pre>
 
and that property is initialized in the app implementation as following:
 
and that property is initialized in the app implementation as following:
 
<pre>
 
<pre>
  self.ep = [GSEndpointFactory initSipEndpoint:configData];
+
self.ep = [GSEndpointFactory initSipEndpoint:configData];
 
</pre>
 
</pre>
 
</div>
 
</div>
Line 132: Line 132:
 
<div class="cloud-left">
 
<div class="cloud-left">
 
<pre>
 
<pre>
  NSString *oldAA = [self.ep getConfigSettingForKey:         "policy.session.auto_answer"];
+
NSString *oldAA = [self.ep getConfigSettingForKey:"policy.session.auto_answer"];
  GSResult result = [self.ep setConfigSettingValue:"1" forKey:"policy.session.auto_answer"];
+
GSResult result = [self.ep setConfigSettingValue:"1" forKey:"policy.session.auto_answer"];
  if (result == GSResultOK)
+
if (result == GSResultOK)
      NSLog(@"Auto-answer changed from %@ to 1.",             oldAA);
+
NSLog(@"Auto-answer changed from %@ to 1.",oldAA);
  else NSLog(@"Error %d changing Auto-answer from %@.", result, oldAA);
+
else NSLog(@"Error %d changing Auto-answer from %@.", result, oldAA);
 
</pre>
 
</pre>
 
</div>
 
</div>
Line 146: Line 146:
 
<div class="cloud-left">
 
<div class="cloud-left">
 
<pre>
 
<pre>
  String oldAA   = this.extendedService.GetConfigStringSetting("policy.session.auto_answer");
+
String oldAA= this.extendedService.GetConfigStringSetting("policy.session.auto_answer");
  GsStatus result = this.extendedService.SetConfigStringSetting("policy.session.auto_answer", "1");
+
GsStatus result = this.extendedService.SetConfigStringSetting("policy.session.auto_answer", "1");
  if (result == GsStatusSuccess)  
+
if (result == GsStatusSuccess)  
      this.extendedService.LogPrint(4,"Auto-answer changed from " + oldAA + " to " + newAA);
+
this.extendedService.LogPrint(4,"Auto-answer changed from " + oldAA +" to " + newAA);
  else this.extendedService.LogPrint(4,"Error" + result + "changing Auto-answer to " + newAA);
+
else this.extendedService.LogPrint(4,"Error" + result + "changing Auto-answer to " + newAA);
 
</pre>
 
</pre>
 
</div>
 
</div>
Line 165: Line 165:
 
<div class="cloud-left">
 
<div class="cloud-left">
  
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 connection  again.
+
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.
 
<ol>
 
<ol>
 
<li> 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):
 
<li> 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):
<pre>GSSipConnection *connection = [[self.ep connectionManager] connectionByConfigId:configId];</pre>
+
<pre>GSSipConnection *connection = [ [self.ep connectionManager] connectionByConfigId:configId];
 +
</pre>
 
or by "connectionId" (an ID that is set into the "connectionId" property during enabling the connection):
 
or by "connectionId" (an ID that is set into the "connectionId" property during enabling the connection):
 
<pre>
 
<pre>
 
GSSipConnection *connection =  
 
GSSipConnection *connection =  
[[self. ep connectionManager] connectionByConnectionId:connectionId] ;
+
[ [self. ep connectionManager] connectionByConnectionId:connectionId] ;
 
</pre>
 
</pre>
 
</li>
 
</li>
Line 182: Line 183:
 
if (result == GSResultOK) result = [connection enable];
 
if (result == GSResultOK) result = [connection enable];
 
if (result == GSResultOK)
 
if (result == GSResultOK)
    NSLog(@"Connection changed to %@.", new_server);
+
NSLog(@"Connection changed to %@.", new_server);
 
else NSLog(@"Error %d changing connection.", result);
 
else NSLog(@"Error %d changing connection.", result);
 
</pre></li>
 
</pre></li>
Line 195: Line 196:
  
 
<pre>this.connectionManager.DisableConnection(connectionId); // that operation cannot fail (always returns GsStatusSuccess)
 
<pre>this.connectionManager.DisableConnection(connectionId); // that operation cannot fail (always returns GsStatusSuccess)
  String key = "server:" + connection.configId.ToString();
+
String key = "server:" + connection.configId.ToString();
  this.extendedService.SetConfigStringSetting(key, new_server);
+
this.extendedService.SetConfigStringSetting(key, new_server);
  this.connectionManager.EnableConnection(connectionConfigId);
+
this.connectionManager.EnableConnection(connectionConfigId);
 
</pre>
 
</pre>
 
Just in case if application ever needs to get "connectionId" for known "connectionConfId", the following method may be used:
 
Just in case if application ever needs to get "connectionId" for known "connectionConfId", the following method may be used:
 
<pre>
 
<pre>
  public int GetConnectionIdByConfigId(int connectionConfigId)
+
public int GetConnectionIdByConfigId(int connectionConfigId)
  {
+
{
    foreach (Connection conn in this.connectionManager.Connections)
+
foreach (Connection conn in this.connectionManager.Connections)
      if (conn.ConfId == connectionConfigId) return conn.Id;
+
if (conn.ConfId == connectionConfigId) return conn.Id;
    return -1; // negative result means "not found"
+
return -1; // negative result means "not found"
  }
+
}
 
</pre>
 
</pre>
 
</div>
 
</div>
Line 222: Line 223:
 
<pre>
 
<pre>
 
[self.ep stop] // stop endpoint
 
[self.ep stop] // stop endpoint
  [self.ep setConfigSettingValue:new_addr forKey:@"policy.endpoint.public_address"];
+
[self.ep setConfigSettingValue:new_addr forKey:@"policy.endpoint.public_address"];
  if ([self.ep configure]) { // re-start endpoint
+
if ([self.ep configure]) { // re-start endpoint
    self.ep.notificationDelegate = self;
+
self.ep.notificationDelegate = self;
    self.ep.connectionManager.notificationDelegate = self;
+
self.ep.connectionManager.notificationDelegate = self;
    self.ep.sessionManager.notificationDelegate = self;
+
self.ep.sessionManager.notificationDelegate = self;
    self.ep.deviceManager.notificationDelegate = self;
+
self.ep.deviceManager.notificationDelegate = self;
    [self.ep activate];
+
[self.ep activate];
    [self.ep.deviceManager configure];
+
[self.ep.deviceManager configure];
    self.connections = [self.ep.connectionManager allConnections];
+
self.connections = [self.ep.connectionManager allConnections];
  }
+
}
  else NSLog(@"Error restarting");
+
else NSLog(@"Error restarting");
 
</pre>
 
</pre>
 
</div>
 
</div>
Line 242: Line 243:
 
<div class="cloud-left">
 
<div class="cloud-left">
 
<pre>
 
<pre>
  this.extendedService.StopCore(); // stop endpoint
+
this.extendedService.StopCore(); // stop endpoint
  this.extendedService.SetConfigStringSetting("policy.endpoint.public_address", new_addr);
+
this.extendedService.SetConfigStringSetting("policy.endpoint.public_address", new_addr);
  this.extendedService.RestartCore();
+
this.extendedService.RestartCore();
 
</pre>
 
</pre>
 
</div>
 
</div>

Revision as of 05:32, December 7, 2018

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();

Comments or questions about this documentation? Contact us for support!