Creating and Initializing a Platform Object

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.

A Unified Communications Client API client must first instantiate and initialize a UccPlatform co-class before it can use the functionalities supported by Unified Communications Client API. This class implements the IUccPlatform interface and raises the events defined in the _IUccPlatformEvents dispinterface. To catch the events, the application must implement event handlers for these events and register the event handlers with the initialized UccPlatform object.

Once initialized, the platform object can be used as a factory object to create IUccEndpoint instances and to obtain the IUccMediaDeviceManager interface pointer.

Before you exit the application or after the Unified Communications Client API functionalities are no longer needed, the application should shut down the initialized platform object and clear any allocated resources. For example, the application should cancel all event registrations with the platform before the registration is obsolete.

Create a Platform Object

In a .NET application, to create a UccPlatform object, the constructor of the UccPlatform co-class is called:

_platform = new UccPlatform();

To ensure that Unified Communications Client API types are properly referenced without the namespace prefix in a .NET application, the "Microsoft.Office.Interop.UccApi" namespace should be imported into the class definition:

using Microsoft.Office.Interop.UccApi;

This type of import requires the addition of Microsoft.Office.Interop.UccApi.dll to the application's project. Microsoft.Office.Interop.UccApi.dll is used as a reference to the primary interop assembly. For more information, see Create a Visual Studio Project for a Unified Communications Client API Client.

To create the platform object in a C++ application, the client must call the CoCreateInstance function provided by the COM library:

IUccPlatform* pIUccPlatform;
HRESULT hr = CoCreateInstance(CLSID_UccPlatform,
                              NULL,
                              CLSCTX_
                              RIID_IUccPlatform,
                              (void**) pIUccPlatform);

For the client to call the CoCreateInstance function provided by the COM library, the appropriate header files must be included in the application project. For more information, see Using Unified Communications Client API in Win32/C++ Client.

Advise the Platform of Event Handlers

The platform object raises two types of events when the platform is shut down and the IP address of the underlying server changed:

• OnShutdown
• OnIpAddrChange

These events provide the client with opportunities to react to the situations. For example, the client may want to clear obsolete application-allocated resources associated with the platform object before the platform is shut down. The client may also want to notify the user of the change in the connection to the underlying server before it is shut down.

To catch these events by implementing the required event handlers, clients should follow the event protocol specified in the _IUccPlatformEvents dispinterface, and register the implemented event handlers with the previously created UccPlatform object.

In COM, to register the event to connect the event source with the event sink, you call the Advise method on the IConnectionPoint interface within the COM library.

For a C# code example showing the registration of a event so it connects the event source with the event sink, see Code Listing: Basic Event Registration and Other Helper Methods in C#. As shown in the following code example, a .NET application can register the platform events by calling the AdviseForEvents<_IUccPlatformEvents> method.

AdviseForEvents<_IUccPlatformEvents>(_platform, this);

For information about Win32 C++ clients registering events, see Catching Unified Communications Client API Events Using ATL Templates.

Initialize the Platform

After creating a platform object and advising it of implemented event handlers, the platform must be initialized, as shown in the following C# code example. Using an uninitialized platform generates an error.

In the following code example, appName is a string holding the name of the custom client implementing Unified Communications Client API. The platform uses the argument to name a tracing file that can be created for application debugging purposes.

The context object in the second argument position can be used to provide information about the process used to initialize the platform to a platform event handling function. The context is an optional argument. You must pass Null when not providing a context object.

//create a context object
IUccContext cx = new UccContext();

//initialize the platform and pass the context
_platform.Initialize(appName, cx);

For a code example that implements the IUccPlatform co-class, see Code Listing: Programming Platform Object in C#.

Close the Platform

Once the platform is deemed no longer needed or before the application exits, the client should shut down the platform by calling the Shutdown method. Platform shutdown is an asynchronous two-step process. After the shutdown call, the client application must wait for and handle the OnShutdown event originating from the IUccPlatform object. Part of this event handling involves cancelling the previously advised events of the _IUccPlatformEvents type.

It is an error to call any other Unified Communications Client API methods or properties before the platform object is initialized or after it is closed.

Handle Platform Events

To handle platform events, the callback functions defined as the members of the _IUccPlatformEvents interface must be implemented. There are two platform-related events:

• OnShutdown
• OnIpAddrChange.

Event handling is application specific. For a sample implementation, see Code Listing: Handling Platform Events in C#. In the sample implementation, all registered platform events are unadvised through a call to the UnadviseForEvents<_IUccPlatformEvents> method shown in Code Listing: Basic Event Registration and Other Helper Methods in C#.

See Also

Concepts

Code Listing: Basic Event Registration and Other Helper Methods in C#