This topic provides information about the general platform behavior of the Microsoft Unified Communications Managed API 2.0 Core SDK.

  1. Begin Xxxmethods can throw InvalidOperationExceptionif the state of the object does not permit the operation to be carried out. An application is expected to have a catch block for all Begin Xxxmethod calls to ensure that a worker thread does not throw such an exception, thereby causing the application to crash.

  2. Every method should specify in its XML comments all known exceptions that could be thrown by that method. Because a method invocation involves a tree of method calls, it is not possible to enumerate all possible exceptions. However, every attempt has been made to ensure that UCMA 2.0 Core SDK methods throw only RealtimeException(or a class derived from this one), InvalidOperationException, RealtimeInvalidOperationException, or argument exceptions such as ArgumentException, ArgumentNullException.

  3. All operations that are created as a result of a method invocation must complete within the time appropriate for the method, irrespective of how an application is written. Some operations depend on the behavior of a remote endpoint. For example, an INVITE operation can take a long time if the remote endpoint sends a “180 Ringing” response periodically without ever accepting the invitation. It is the application’s responsibility to create its own timers for such operations.

  4. A method that depends on an extensible media provider can hang due to a poor implementation, such as by not completing an asynchronous operation exposed by the provider. It is the responsibility of the provider to ensure that their implementation meets the requirements discussed here and to follow any other .NET guidelines.

  5. The End Xxxmethod will not throw InvalidOperationException. It can throw ArgumentExceptionor RealtimeExceptionor any exception that is derived from RealtimeException.

  6. A component will not discard events if the event handler is nullbut the application did not have an opportunity to register for such events. The component is responsible for queuing a work item that will raise the event at the time the work item is processed. If the event handler is still nullat the time the work item is processed, the event will not be raised.

  7. If a method is expected to cause certain state changes in a component, all of these events will be placed in the queue ahead of the completion callback. For example, if a contact/group subscription session is established, all contacts and group events associated with the subscription will be raised before the method callback is invoked. The component will reflect the most recent state while the state transition events are placed in the queue. Thus, the application cannot expect the state of a component to match that of the event reported in the event handler.

  8. The platform will not raise an event or invoke a method callback while holding a platform lock.

  9. None of the public objects of the platform will be used by the platform for locking unless explicitly called out.

  10. If the platform exposes a collection to the application, the collection is a snapshot of the actual internal collection; hence it should be safe for the application to enumerate that collection. Any changes to the original collection after the snapshot has been obtained will not be reflected in the collection returned to the application. Thus, it is recommended that the application use events to keep track of collections rather than to access the property that returns a snapshot.

  11. When an asynchronous operation is completed, the platform will not keep any reference to the asynchronous result that corresponds to the operation.