Naming Convention Used in Unified Communications Client API
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.
Microsoft Unified Communications Client API exposes a collection of interfaces, dispinterfaces, enumerations, and co-classes:
- In IUccPlatform, the interfaces encapsulate the states or operations of an API entity and are inherited from the IUnknown interface.
- In _IUccPlatformEvents, the dispinterfaces encapsulate events to be raised by an API entity.
- The enumerations define named constants or property identifiers. For example, the extended properties of the application framework appear in UCC_PLATFORM_CONTEXT, and supported authentication modes for a user to log on to the server appear in UCC_AUTHENTICATION_MODES.
- As shown in UccPlatform, a small number of co-classes are meant as the starting points to obtain certain interface pointers. The majority of co-classes are intended to illustrate that the implemented interface pointers of each co-class can be queried from each other by calling the QueryInterface method on their base (IUnknown) interface. In a .NET application, calling QueryInterface amounts to typecasting one interface to another. An instance of a co-class also serves as the source of the events defined by the dispinterfaces implemented by the co-class.
The design of the interfaces and dispinterfaces supports the asynchronous programming patterns required of any client-server based application, including a Unified Communications Client API client application. In such an application, a client issues a request, as a method on an operational interface, to the underlying server to perform a certain operation. Examples of such operational requests include signing in to or signing out of the server, initiating or accepting an invitation to join an instant messaging (IM) conversation, and publishing or subscribing to presence of a contact. After the request is issued, the client does not block the execution while waiting for the server to return any results. After the request is processed, the server returns the results (if any) or operational status by raising one or more events. To catch an event, the client must implement the corresponding event handler and advise the event source of the event handler implementation. This is also known as event registration. In Unified Communications Client API, an event handler is defined as a method in a dispinterface. The Unified Communications Client API naming convention conveys relationships among different API elements.
Co-Classes
The name of a co-class starts with Ucc and ends with a string describing the implemented functionalities. For example, UccAudioVideoSession encapsulates all the functionalities of an audio/video session. These functionalities are defined in the IUccAudioVideoSession, IUccSession, and IUccSessionCallControl interfaces and in _IUccAudioVideoSessionEvents, _IUccSessionEvents, _IUccSessionParticipantCollectionEvents, and _IUccSessionCallControlEvents dispinterfaces.
The majority of Unified Communications Client API co-classes cannot be co-created. They are intended to illustrate the dependency of related interfaces and can be used to determine which group of operational interfaces can be queried from each other (by calling the QueryInterface method on the IUnknown interface or performing a typecasting in a .NET application). Co-classes also describe what events an object can raise.
The co-creatable co-classes are used as a starting point to retrieve a pointer to an interface designated as the default interface. Other interfaces can then be obtained by QueryInterface operations on this and other interface objects. For a .NET application, the QueryInterface operation amounts to casting a source interface type into a destination interface type.
Interfaces
In Unified Communications Client API, all interface names start with IUcc followed by a description of the encapsulated functionality. For example, the general functionalities of a session are encapsulated by the IUccSession interface. The session-specific functionalities are encapsulated by type-specific session interfaces. An IM session supports text messages and an audio/video (AV) session requires explicit specifications of media channels. Therefore, an IM session requires the IUccSession and IUccInstantMessagingSession interface, while an AV session requires the IUccSession and IUccAudioVideoSession interface.
Note
The relationship between general and specific functionality is not represented by an interface inheritance hierarchy. Instead, the relationship is described by the containing relationship of the corresponding co-class.
When a Unified Communications Client API entity is used in a callback scenario, the corresponding interface name is preceded by an underscore (_) character. For example, _IUccSessionDescriptionEvaluator.
Events
In Unified Communications Client API, events are encapsulated in dispinterfaces. A dispinterface is an IDispatch interface in which the declared members (M), methods or properties, are invoked by the IDispatch::Invoke method instead of calling IDispatch::M directly.
Each dispinterface defines a collection of events that can be raised by a corresponding operational interface object. The members correspond to the event handlers. If the event handlers are registered, Unified Communications Client API invokes them when the corresponding events occur.
All dispinterface names start with an underscore (_) character and are followed by the operational interface names from which the corresponding events are raised. The names end with the Events suffix. The underscore character prefix indicates that the member methods are callback functions. The Events suffix indicates that they are dispinterfaces for events.
For example, events raised by an IUccSession object are defined in _IUccSessionEvents, events raised by an IUccInstantMessagingSession instance are defined in _IUccInstantMessagingSessionEvents, and events raised by IUccSessionManager are in _IUccSessionManagerEvents. Such events can be characterized as the direct responses to their matching requests or operations. There is another set of events indicating the consequences of certain operations. The dispinterfaces for these events do not have any matching source interfaces. For example, _IUccSessionParticipantCollectionEvents is such an interface. There is not an IUccSessionParticipantCollection interface acting as the source of these events. Instead, the event source is tied to the IUccSession interface because the participant collection is a property of a session. The events reflect the changes of this property as the result of certain requests made on a session.
For each event in Unified Communications Client API, there are two parameters conveying the event context and other event-specific information. The first parameter identifies the event source and the second parameter identifies the event data.
There are two types of events. The first type returns the operational status and the other type returns the results of operations. The naming conventions for these two types of events differ as follows:
- For events showing operational status, the naming convention is such that for an operation (Y) supported by an object (X), which is defined by a member of an operational interface, IUcc<X>::<Y>, the corresponding event name takes on the form of _IUcc<X>Events::On<Y>. For example, for the AddParticipant method, the corresponding event is named OnAddParticipant. For this type of event, the initiating operational request requires the input of the operation context (as encapsulated by IUccOperationContext). The corresponding event returns with an IUccOperationProgressEvent or IUccSessionTransferProgressEvent instance as the event data containing the information about the operational status.
- For events returning state updates as the result of an operation, the naming convention is such that for a state (S) of an object (O), IUcc<O>::<S>, the corresponding event name follows the _IUccOEvents::OnS<Changed> pattern. For example, a session participant can be in a state in which the participant is disconnected from, connecting, or already connected to a remote participant. Whenever the participant state changes, the participant object raises an OnStateChanged event. Similarly, a participant can be added to or removed from a session. When this occurs, an OnParticipantAdded or OnParticipantRemoved event is raised by a session object maintaining a collection of the session participants.
Enums
The names of the enumeration types (enum) use all uppercase letters. For example, UCC_SESSION_TYPE specifies the supported session types as UCCST_INSTANT_MESSAGING for an IM session, UCCST_AUDIO_VIDEO for an AV session, UCCST_CONFERENCE for a conference session, and UCCST_APPLICATION for an application session.
When the name of an enumeration type has a plural form (ending with an s), the member fields are bit-wise operable and can be passed in to method calls as LONG parameters. For example, UCC_MEDIA_TYPES defines supported media types used in Unified Communications Client API. A client can use UCC_MEDIA_TYPES.UCCMT_AUDIO to specify audio-only media, use UCC_MEDIA_TYPES.UCCMT_VIDEO for video-only media, or use UCC_MEDIA_TYPES.UCCMT_AUDIO | UCC_MEDIA_TYPES.UCCMT_VIDEO to specify audio and video.
Another set of enumeration types are used to define the property names (also known as property IDs) of properties associated with certain interfaces. For example, a conference session has various properties. One shows whether the conference is active and another describes the conference subject. The names or identifiers of all the properties of a conference session are specified in the UCC_CONFERENCE_SESSION_PROPERTY enumeration type. Also, enumeration types with names ending with _CONTEXT are used to specify extended properties associated with certain API entities. For example, UCC_SESSION_CONTEXT specifies the extended properties on a session. In addition to serving as the property identification, a property identifier (or name) is encoded with the information about the type of the property value, the scope of accessibility (read-only or read/write), and the associated class of the property. An application can discover such metadata about of property at run time. For more information, see UCC_PROPERTY_ACCESSIBILITY, UCC_PROPERTY_CLASS, UCC_PROPERTY_MASK, UCC_PROPERTY_MASK_INDEX, and UCC_PROPERTY_TYPE.