< Back to Package Overview
Initializing the SDK
This article discusses how to initialize, reinitialize, and shutdown the Avaya Client SDK Communications Package for Windows within your application.
Creating and configuring a Client
The central class of the Avaya Client SDK is Client. Each application using the Client SDK will have its own instance of Client and will maintain a reference to this object in order to create a User and access features within the SDK.
Configuring a Client
As part of the process to create your client instance, you must create a ClientConfiguration object that defines your application. There are two ways to create ClientConfiguration object.
-
By initializing the configuration details with the attribute Data Directory.
ClientConfiguration clientConfiguration = new ClientConfiguration("d:\avayaclientservices"); //The directory to store persistent data
The Client SDK uses the default values for the Product Name, Product Version, Platform, Build number, OS version and Vendor for constructing the User-Agent string. The default values are set based on the Application's build properties and platform.
You can get the User-Agent name generated by the Client SDK by using the API UserAgentName.
String userAgentName = clientConfiguration.UserAgentName;
You can always override the default values for all the configuration details
clientConfiguration.ProductName = "TestApplication";
-
By initializing the configuration details with the attributes like Data directory, Product name, Product version, Platform, OS version, Build number and Vendor name. The attributes you define within ClientConfiguration will be used to identify your application in the network.
ClientConfiguration clientConfiguration = new ClientConfiguration
("d:\avayaclientservices","TestApplication", "Avaya",
"Windows", platformVersion, "1", "Avaya");
Also, you can always set the custom User-Agent string by using setUserAgentName(). Note that, setting the custom User-Agent might not enable all the server capabilities as the format of the User-Agent string is server-specific.
clientConfiguration.UserAgentName = "TestApplication";
Note:
- Once the User-Agent string is set explicitly using API UserAgentName, changing any of the attributes of ClientConfiguration instance like ProductName will not be reflected on the User-Agent string.
- Since there are few server-specific requirements for the format of the User-Agent string, we recommend you to use the first API and let the Client SDK construct the User-Agent string by using the default values to enable complete server capabilities.
Set a user agent unique instance id defined in RFC 5626. Generate unique value once (e.g. UUID [RFC4122]) and then save this in persistent storage for all future use.
string userAgentInstanceId;
if (persistentStorage.UserAgentInstanceId.Length > 0) {
userAgentInstanceId = persistentStorage.UserAgentInstanceId;
}
else {
userAgentInstanceId = Guid.NewGuid().ToString();
persistentStorage.UserAgentInstanceId = userAgentInstanceId;
}
clientConfiguration.UserAgentInstanceId = userAgentInstanceId;
Next, create a client event handler instance. This handler will be used to handle events that occur during the lifecycle of your client, such as the shutdown event.
class ApplicationClientDelegate
{
void client_UserCreated(object sender, UserEventArgs e)
{
// Called to report the specified user has
// been created successfully
// Add code here to handle user created
}
void client_UserRemoved(object sender, UserEventArgs e)
{
// Called to report the specified user has
// been removed
// Add code here to handle user removed
}
void client_ShutdownCompleted(object sender, EventArgs e)
{
// Called to report Client shutdown has been completed
// Add code here to handle shutdown of the Client
}
};
Creation of the Client object
After you instantiate and set up required configuration object and event handlers, you are now ready to create the Client object.
Pass ClientConfiguration object to Client constructor. Once Client is created, set event handlers.
ApplicationClientDelegate clientDelegate = new ApplicationClientDelegate();
Client client = new Client(clientConfiguration);
client.UserCreated += new EventHandler
(clientDelegate.client_UserCreated);
client.UserRemoved += new EventHandler
(clientDelegate.client_UserRemoved);
client.ShutdownCompleted += new EventHandler
(clientDelegate.client_ShutdownCompleted);
By default, Client operates an event loop on the main thread. To handle callbacks from the client on the application thread (typically the UI thread), the client delivers callbacks via a Looper. If you must change this behavior, you can specify your own Looper using the Client constructor.
Creating a User
A User object defines all of the capabilities available to the end user of your application. Creating a User is very similar to creating a Client.
Configuring a User
First, create a UserConfiguration object:
UserConfiguration userConfiguration = new UserConfiguration();
You can use the LocalCallLogFilePath property of the UserConfiguration object to specify path to the call log file.
string callLogFilePath = Path.Combine(CallLogDirectoryPath, "CallLog.xml");
userConfiguration.LocalCallLogFilePath = callLogFilePath;
The UserConfiguration object will be used to define the services that will be available to end users of your application. Each service is configured individually; its configuration is stored in a dedicated object, referenced from the UserConfiguration object.
Service configuration starts with obtaining a reference to the desired service configuration from UserConfiguration. Once you have completed the configuration for the service, or re-configuration of the service, save the configuration back to the UserConfiguration object.
Note: More information on service configuration can be found in the article Configuring the SDK.
Example: Configuring the Call Service for SIP
Start by obtaining any existing service configuration (memory for SipUserConfiguration is allocated during creating User):
SipUserConfiguration sipConfiguration =
userConfiguration.SipUserConfiguration;
Enable the service:
sipConfiguration.Enabled = true;
Configure the SIP parameters supplied by your administrator:
sipConfiguration.UserId = ""; // Provided by your administrator
sipConfiguration.Domain = ""; // Provided by your administrator
Next, you must configure the connection parameters for the SIP server. This will take the form of one or more server configurations represented as SignalingServer objects encapsulated in a single ConnectionPolicy object:
SignalingServer signalingServer = new SignalingServer(TLS,
"", // Provided by your administrator
, // Provided by your administrator
AUTOMATIC); // Allow the Client SDK to manage failback
sipConfiguration.ConnectionPolicy = new ConnectionPolicy(signalingServer);
To successfully register to the SIP server a password corresponding to the username will be required. The password required for the SIP service is not defined as part of the service configuration. Passwords are requested by and communicated to the Client SDK using the ICredentialProvider interface:
sipConfiguration.CredentialProvider = this;
And finally save your configuration back to your user object:
userConfiguration.SipUserConfiguration = sipConfiguration;
Note: More information on how to manage passwords using the ICredentialProvider can be found in the article Working with Credentials.
Creation of the User object
After you instantiate and set up any required configuration objects, you are now ready to create the User.
Creating a user is an asynchronous operation. The result of this operation is delivered through Client.CreateUserCompletionHandler. The example below shows a pattern you will see used commonly throughout the Client SDK. Many SDK functions result in network activity and these operations are performed asynchronously, with the results being provided via a completion handler on the main thread (or the thread associated with the "Looper" optionally specified during Client creation).
m_Client.CreateUser(config, (user, error) =>
{
if (error != null)
{
WriteToLogFile(string.Format("User creation error {0}", error));
return;
}
Console.WriteLine("User created.");
m_User = user;
// Add event handlers to user object to handle all user related events
m_User.AllRegistrationsSuccessful += AllRegistrationsSuccessful;
m_User.AllRegistrationsFailed += AllRegistrationsFailed;
...
m_User.Start();
});
If the user is successfully created, the error object is not null. At this point you can register event handlers for any Client SDK services that you wish to observe events for, and then call the Start() method of your User to start all services.
The Start() method triggers the network activity required to register with any services configured. Once a successful connection has been established to the infrastructure, API's dependent on infrastructure services will be accessible through the User service.
Reinitializing a Service
To reinitialize a User object to apply new configuration settings you must perform the following steps:
- Remove the current User from the Client
- Apply configuration changes
- Restart the User
To remove a User from the Client use the RemoveUser() method. The RemoveUser() method supports both graceful and ungraceful invocation.
client.RemoveUser(user, true);
For more information on the differences between graceful and ungraceful invocation please refer to the section Shutdown the Client.
To confirm that the user has been removed the calling application will receive notification via the client_UserRemoved() callback on the event handlers implementation object.
Applying the new configuration and starting the user follows the same process as described in the section Creating a User.
Note: Removing the User will stop all services configured for the User. Support to reconfigure services individually is a feature planned for a future release.
Shutdown the Client
The Client shutdown() method can be called in one of two ways:
- Graceful Shutdown
- Ungraceful Shutdown
When a graceful shutdown is invoked:
client.Shutdown(true);
Client SDK attempts to unregister with each infrastructure service.
Client SDK waits until confirmation is provided by each infrastructure service. Once confirmation from all infrastructure services is received, the shutdown and cleanup of internal resources will be done. The graceful shutdown operation is dependent on a network response from one or more infrastructure services. When errors occur this process may take as long as the network timeout on each infrastructure connection to complete.
When an ungraceful shutdown is invoked:
client.Shutdown(false)
All network connections are immediately terminated, User objects controlled by the Client object are removed, and internal resources are immediately released.
When shutdown is complete and all resources are released the client_ShutdownCompleted() event is raised. Provide the event handlers implementation object to notify the calling application that the process has completed.
