Code Listing: Programming Sign-in Function
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
In the following example from a Microsoft Windows form-based client application, a user is permitted to sign in to a specified Microsoft Office Communications Server using specified server signaling settings. The example implements code from Creating and Initializing a Platform Object, Create a Principal Endpoint, Configure Server Signaling Settings, and Enable an Endpoint.
public class ClientPlatformManager : _IUccPlatformEvents,
_IUccEndpointEvents,
_IUccSignalingChannelEvents,
{
// Declare platform and endpoint interface instances.
internal UccPlatform apiPlatform;
internal IUccEndpoint apiEndpoint;
internal IUccPublicationManager myPubManager;
internal IUccSessionManager mySessionManager;
internal IUccConferenceManager myConferenceMgr;
internal IUccSessionManager mySessionManager;
internal IUccEndpoint _telEndpoint;
// Enumerator for servers collection returned in OnFindServer callback.
IEnumerator servers = null;
/// <summary>
/// Public method called to sign a local user in to an instance of
/// Office Communications Server
/// </summary>
public void SignIn()
{
// Create client platform singleton ctxt);.
apiPlatform = new UccPlatformClass();
// Advise for platform events.
UCC_Advise<_IUccPlatformEvents>(
this.apiPlatform,
this);
UccContext ctxt = new UccContextClass();
ctxt.AddNamedProperty("Platform Name", "sampleUCCPClient");
apiPlatform.Initialize("MyUccpClient", ctxt)
// Create the SIP endpoint and advise for endpoint events.
apiEndpoint = apiPlatform.CreateEndpoint(
UCC_ENDPOINT_TYPE.UCCET_PRINCIPAL_SERVER_BASED,
_meUri,
null,
null);
// Advise for endpoint events.
UCC_Advise<_IUccEndpointEvents>(
this.apiEntpoint,
this);
// Query Interface (QI)IUccServerSignalingSettings from endpoint
// and configure server settings.
IUccServerSignalingSettings serverSignalingSettings = apiEndpoint as IUccServerSignalingSettings;
if (serverSignalingSettings != null)
{
// Advise for server signaling settings events.
UCC_Advise<_IUccServerSignalingSettingsEvents>(
this.apiEndpoint,
this);
serverSignalingSettings.FindServer("contoso.com", null);
}
}
void _IUccServerSignalingSettingsEvents.OnFindServer(
IUccEndpoint pEventSource,
UccFindServerEvent pFindServerEventData)
{
IUccServerSignalingSettings serverSignalingSettings = pEventSource as IUccServerSignalingSettings;
if (pFindServerEventData.IsComplete)
{
if (pFindServerEventData.SignalingServers.Count > 0)
{
// Instantiate declared IEnumerator with collection of servers.
this.servers = pFindServerEventData.SignalingServers.GetEnumerator();
// Iterate on collection and set Server property to first server in collection.
foreach (IUccSignalingServer ss in pFindServerEventData.SignalingServers)
{
serverSignalingSettings.Server = ss;
break;
}
// Enable the endpoint to sign in.
pEventSource.Enable(null);
}
else
{
MessageBox.Show("An Office Communications Server instance was not found. Sign in will end","Sign In Error");
}
}
}
/// <summary>
/// Endpoint disable event handler unadvises for endpoint advisement,
/// de-references IUccEndpoint instance, and shuts down platform
/// </summary>
/// <param name="pEventSource">disabled endpoint instance</param>
/// <param name="pEventData">operation progress event</param>
void _IUccEndpointEvents.OnDisable(
IUccEndpoint pEventSource,
IUccOperationProgressEvent pEventData
)
{
try
{
string eURI = pEventSource.Uri.Value;
if (pEventData.IsComplete && pEventData.StatusCode >=0)
{
UCC_Unadvise<_IUccEndpointEvents>(pEventSource, this);
if (this._telEndpoint != null)
{
UCC_Unadvise<_IUccEndpointEvents>(this._telEndpoint, this);
}
// Sign out completed.
pEventSource = null;
// Shut down the platform.
if (this.apiPlatform!= null)
{
this.apiPlatform.Shutdown(null);
this._platformInitialized = false;
}
}
}
catch (COMException e)
{
MessageBox.Show(
"On Endpoint Disable: COM Exception. " +
e.Message);
}
}
void _IUccEndpointEvents.OnEnable(
IUccEndpoint pEventSource,
IUccOperationProgressEvent pEventData)
{
try
{
if (pEventData.IsComplete )
{
if (pEventData.StatusCode >= 0)
{
// Sign in succeeded. Proceed with subscription and publication.
// Get subscription manager role from endpoint.
this.mySubscriptionMgr = pEventSource as IUccSubscriptionManager;
// Get publication manager role from endpoint.
this.myPubManager = pEventSource as IUccPublicationManager;
// Advise publication manager instance of this class as endpoint sink.
UCC_Advise<_IUccPublicationManagerEvents>(this.myPubManager, this);
// Get Media Endpoint Settings object from active endpoint.
IUccMediaEndpointSettings _mediaEndpointSettings = pEventSource as IUccMediaEndpointSettings;
// Create a session manager object to handle session related functionality and events.
this.mySessionManager = pEventSource as IUccSessionManager;
// Advise session manager instance of this class as endpoint sink.
UCC_Advise<_IUccSessionManagerEvents>(this.mySessionManager, this);
//Get conference manager role from endpoint.
this._confManager = _endpoint as IUccConferenceManager;
UCC_Advise<_IUccConferenceManagerSessionEvents>(
_confManagerSession,
this);
//
// The OnEnable callback is the best place to trigger application logic that creates self-subscriptions
// for the local user's contact list and server configuration. The client should publish the user's presence
// status at this time too.
//
// Self-subscription requires many steps and is best handled by a helper method called from OnEnable.
// Publication should be handled by a separate helper function called from OnEnable.
// Both of these helper methods use the role specific interfaces obtained in OnEnable.
//
}
else
{
//
// Sign in failed.
// The current server in the server collection returned with OnFindServers
// did not accept the endpoint registration (Enable). The next server in the collection
// is tried.
//
// Initial Boolean flag for server found?
bool nextAvailable = false;
// Declare new instance of server signaling settings interface.
IUccServerSignalingSettings serverSignalingSettings = null;
// If OnFindServer returned collection of servers and IEnumerator for collection
//is not null
if (this.servers != null)
{
// Initialize server signaling settings by casting from endpoint instance.
serverSignalingSettings = this._endpoint as IUccServerSignalingSettings;
// Get the next server in the servers IEnumerator instance.
nextAvailable = this.servers.MoveNext();
}
// If next server was found
if (nextAvailable)
{
// Set found server as property value of server signaling settings and enable.
serverSignalingSettings.Server = this.servers.Current as IUccSignalingServer;
pEventSource.Enable(null);
}
else if (this.servers != null)
{
// Last server in collection was attempted and failed.
if (MessageBox.Show("Sign in again? ", "Invalid Credentials", MessageBoxButtons.RetryCancel) == DialogResult.Retry)
{
// Ask user for credentials again.
//
// getCredentials is an application modal dialog that presents a user with three text boxes. The
// user is challenged for user name, password, and domain. The values entered are available as public
// string properties (UserName, Password, Domain). If the user enters all three values and closes the dialog using
// the OK button, the DialogResult returned is DialogResult.OK. Otherwise, the user has not chosen to
// attempt to sign in again.
//
// A custom client application can implement this functionality any way but with the single restriction that
// the method chosen must return the three string values.
//
// NOTE: getCredentials is not an API. A custom client using this code example must create getCredentials
// in the current project to compile this example.
//
//
getCredentials askForCreds = new getCredentials();
askForCreds.ShowDialog();
if (askForCreds.DialogResult == DialogResult.OK)
{
// Reset enumerator to top of collection.
this.servers.Reset();
// Get first server.
nextAvailable = this.servers.MoveNext();
// If a server was found.
if (nextAvailable)
{
// Set found server as property value of server signaling settings and enable.
serverSignalingSettings.Server = this.servers.Current as IUccSignalingServer;
//
// Update credential cache with new credentials. This involves:
// Getting the existing credential for the realm.
// Removing the credential.
// Creating a new credential based on the new sign-in values supplied by the local user.
// Setting the new credential as the active credential for the next Enable().
//
// Declare new credential to receive user name and password.
UccCredential thisCredential = null;
// Get existing credential based on realm.
if (serverSignalingSettings.CredentialCache.TryGetCredential("*", out thisCredential))
{
// Remove the existing credential.
serverSignalingSettings.CredentialCache.RemoveCredential("*");
// Create a new credential with new user name and password.
UccCredential newCredential = null;
newCredential = serverSignalingSettings.CredentialCache.CreateCredential(
askForCreds.UserName,
askForCreds.Password,
askForCreds.Domain);
// Set the new credential into credential cache.
serverSignalingSettings.CredentialCache.SetCredential("*", newCredential);
// Enable the endpoint.
pEventSource.Enable(null);
}
}
}
else
{
MessageBox.Show("Sign-in Failed");
}
}
else
{
MessageBox.Show("Sign-in Failed");
}
}
}
}
else
{
// Sign in failed. Make the endpoint null.
pEventSource = null;
}
}
catch (COMException ex)
{
throw ex;
}
}
}
See Also
Concepts
Creating and Initializing a Platform Object
Create a Principal Endpoint