How to use the SIP Profile API

• Protocols

• Error handling

Creating a CSIPProfileRegistry object connects a client to the shared SIP Profile server. If the server is not currently running, it is started by the API implementation. When the CSIPProfileRegistry object is deleted, the corresponding connection to the server is closed. The server may stop at this point if it has no other users.

Retrieving a CSIPProfile object through CSIPProfileRegistry causes the profile data to be transferred from the server to the client. As long as the client holds this instance of CSIPProfile in its memory, all events related to the corresponding profile are notified to that client through calls to the MSIPProfileRegistryObserver callback functions (implemented by the client). Note that each retrieval of a profile creates a separate CSIPProfile object, even if the corresponding profile is the same.

After the client has deleted the CSIPProfile object, the client will no longer be notified about events.

Before a CSIPProfile object can be used by the SIP Client API, the profile must be active. This can be verified using the MSIPRegistrationContext::IsContextActive() function. A profile becomes active when it is enabled by the client and the state of the profile is ERegistered (this is an enum value of the TSIPProfileState enum defined in the class CSIPProfileAgent). Enabling the profile automatically leads to registration if the profile was not already registered. In this case, the registration status change is notified through MSIPProfileRegistryObserver. If the enabled profile was already registered, no additional registration or status change events are sent. The client of the API must wait for the registration to complete before using the profile by calling CSIPProfile::GetParameter(KSIPProfileRegistered,TBool aValue).

After a profile is enabled and registered, the client can use it to create SIP sessions using the SIP Client API. Enabling the profile also guarantees that it will not be removed from the system while being used by the client.

When a profile is no longer needed by the client, it should be disabled. Deleting the instance of the profile also causes that profile to be disabled.

The following diagram shows typical use of the API.

In general, 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 proper 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 no longer registered or enabled by the client.