Create a Principal Endpoint

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.

For a user to sign in to Microsoft Office Communications Server, a client application must create an IUccEndpoint object, register for the endpoint events as defined in the _IUccEndpointEvents dispinterface, implement the event handlers, and then send the server a registration request. When the registration is complete and the local user's credentials are accepted, the principal endpoint is enabled.

A client application should use other Microsoft Unified Communications Client API operations involving the endpoint only after the endpoint is enabled. A client is enabled after receiving OnEnable with a StatusCode greater than or equal to zero. The client application must obtain server configuration and the local user's configuration before collaboration operations can be performed.

The following example creates and enables an IUccEndpoint object representing the local user. The this.selfURI class field encapsulates the local user's URI. For more information about event registration and handling _IUccEndpointEvents events, see Enable an Endpoint.

The endpoint object serves many functions including publication management, subscription management, media connectivity management, server signaling settings management, and conference management.

Create a Principal Endpoint

To create an endpoint

1. Create an instance of the UccPlatform object that implements the IUccPlatform and _IUccPlatformEvents interfaces. In C++, this object is created by calling the CoCreateInstance function of the COM library. In C#, use the class constructor of UccPlatform to create the object.

2. Initialize the IUccPlatform object, and then register for the _IUccPlatformEvents raised by the platform object. The client must also implement the registered event handlers.

3. Create a new UccUriManager instance and then call the ParseUri method, passing a SIP-formatted endpoint URI string. The return value of the call is a UccUri object that implements the IUccUri interface. This object is passed in the first argument position to the CreateEndpoint endpoint.

4. Create an endpoint object by calling the CreateEndpoint method on the IUccPlatform interface. The client must provide the user's SIP URI and specify the name or IP address of the server running Office Communications Server. The client must also implement the event handlers and register the handlers with the newly created endpoint object to receive at least the OnEnable event necessary to complete the registration process. At this point, the endpoint is not connected to the server. For information about implementing event handlers, see Advise for and Handle Events in a Unified Communications Client API Client

5. Configure the server sign-in profile by using the IUccServerSignalingSettings interface to specify the user credentials (user name, password, and domain). Specifying invalid credentials generates failed endpoint registration attempts for all servers in the enterprise server pool.

   If the client is configuring a signaling server instance instead of using the automatic server discovery process, the Server property is set to the client-configured instance of IUccSignalingServer. After setting the Server property, the client should enable the endpoint.

At this point, the client has created a platform, a principal endpoint, and the server signaling settings object is configured. If the client is to control a public switch telephone network (PSTN) telephone or a telephone that is enabled for Unified Communications, a proxy endpoint must be created. Otherwise, the client should begin the process of discovering available signaling servers and user sign in.

The platform object serves as a factory that creates necessary endpoint objects. The following example creates a principal endpoint.

/// <summary>
/// Creates a principal server-based endpoint for the local user
/// </summary>
/// <param name="pLocalUserUriString">string URI of local user</param>
/// <returns>IUccEndpoint</returns>
private IUccEndpoint pr_CreateLocalEndpoint(string pLocalUserUriString)
{
    // Create URI manager object to parse SIP URI address of local user.
    UccUriManager UriManager = new UccUriManagerClass();

    // Parse SIP address to created UccUri object used to create endpoint.
    UccUri localUserUri = UriManager.ParseUri(pLocalUserUriString);

    // Declare return value object.
    IUccEndpoint returnValue = null;

    // Create the SIP endpoint and advise for endpoint events.
    // 3rd param: endpoint Id can be assigned but is omitted here.
    // 4th param: operation context can be assigned but is omitted here.
    returnValue = this._platform.CreateEndpoint(
        UCC_ENDPOINT_TYPE.UCCET_PRINCIPAL_SERVER_BASED,
        localUserUri,
        null,
        null);

    // If the endpoint was created, advise for endpoint events such as
    // OnEnable and OnDisable.
    if (returnValue != null)
    {
        UCC_Advise<_IUccEndpointEvents>(
            returnValue,
            this);

    }
    return returnValue;
}

Advise for Endpoint Events

Events related to an IUccEndpoint object include the events defined by the _IUccEndpointEvents event.

In the previous example, the client must handle the events defined in _IUccEndpointEvents in order to complete the sign-in and sign-out process. To handle these events, the client must implement the OnEnable and OnDisable methods. To catch the events, the client application must advise a new IUccEndpoint instance about each implementation of an event handler. For more information, see Code Listing: UccApiEndpointEventSink Class in C#.

// If returnValue (IUccEndpoint) was created, advise for endpoint events such as
// OnEnable and OnDisable.
if (returnValue != null)
{
    UCC_Advise<_IUccEndpointEvents>(
        returnValue,
        this);
}

In the previous example, the new principal endpoint is advised that the current class object (this) has implemented handlers for the events defined in _IUccEndpointEvents.

For information about the UCC_Advise event-related function, see Code Listing: Basic Event Registration and Other Helper Methods in C#.

An endpoint can also raise other events defined in _IUccServerSignalingSettingsEvents, _IUccSessionManagerEvents and _IUccPublicationManagerEvents. After a principal endpoint is created, the client can handle each event. We recommend that you first obtain the interface pointers to the corresponding IUccSessionManager and IUccPublicationManager and then process the events.

For a code example showing a C# class that represents a server-based principal endpoint, see Code Listing: Programming Endpoint Object in C#.