How to use the SIP Profile API

Protocols

This section provides the information about the protocol and error handling related to the SIP Profile API:

• When you create a CSIPProfileRegistry object, the client connects to the shared SIP Profile server. Note: If the server is not running, it is started by the API implementation.

  When the CSIPProfileRegistry object is deleted, the corresponding connection to the server is closed. The server stops if it has no other users.

• The profile data is transferred from the server to the client when a user retrieves a CSIPProfile object through CSIPProfileRegistry.

  When the client holds an instance of CSIPProfile in its memory, all events related to the corresponding profile use MSIPProfileRegistryObserver callback functions to notify the client. The callback functions are implemented by the client.

  Note: A CSIPProfile object is created each time a profile is retrieved.

• When the client deletes the CSIPProfile object, the client is not notified about events.

• The profile must be active before a CSIPProfile object is used by the SIP Client API. Use the MSIPRegistrationContext::IsContextActive() function to check. A profile becomes active when it is enabled by the client and the state of the profile is ERegistered. ERegistered is an enum value of the TSIPProfileState enum defined in the class CSIPProfileAgent.

• All profiles are automatically registered when they are enabled. If a profile is not registered before being enabled, the registration status change is acknowledged through MSIPProfileRegistryObserver. If the enabled profile is already registered, no additional registration or status change events are sent.

• When a profile is enabled and registered, the client can use it and the SIP Client API to create SIP sessions. An enabled profile cannot be removed from the system while it is used by the client.

• When a profile is not needed by the client, it is disabled. When you delete an instance of the profile the profile is disabled.

The following illustration shows use of the SIP Profile API.

Error handling

The errors are indicated by return codes, by functions leaving, or by calling callback functions. If an error occurs during a synchronous operation initiated by the client, the called function leaves with a correct error code.

If an error occurs during an asynchronous operation, the error is passed to the client through the callback function MSIPProfileRegistryObserver::ProfileRegistryErrorOccurred(). In this case, both the profile identifier and an error code are passed to the client. Any error passed to the client means that the indicated profile is not registered or enabled by the client.