<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-9971A0B9-B2D7-59D3-8834-FDDEEC57AC67"><title>How to use the SIP Profile API</title><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-D9ED74C5-20D0-5636-993B-06C05CD90E6A"><title>Protocols</title> <p>This section provides the information about the protocol and error handling related to the SIP Profile API: </p> <ul><li id="GUID-71AB3403-EAD0-5444-8B54-8F9A9F463942"><p>When you create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object, the client connects to the shared SIP Profile server. <b>Note</b>: If the server is not running, it is started by the API implementation. </p> <p>When the <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object is deleted, the corresponding connection to the server is closed. The server stops if it has no other users. </p> </li> <li id="GUID-35DDE98D-1135-5556-8C8B-0CD5F65CA642"><p>The profile data is transferred from the server to the client when a user retrieves a <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> object through <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref>. </p> <p>When the client holds an instance of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> in its memory, all events related to the corresponding profile use <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> callback functions to notify the client. The callback functions are implemented by the client. </p> <p> <b>Note</b>: A <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> object is created each time a profile is retrieved. </p> </li> <li id="GUID-12B99D92-A992-5C77-8E3E-65472E1994AF"><p>When the client deletes the <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> object, the client is not notified about events. </p> </li> <li id="GUID-B13A5C15-B9EB-5AEF-A490-C4295762D0F8"><p>The profile must be active before a <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> object is used by the SIP Client API. Use the <xref href="GUID-F0663140-8AF3-3831-A741-483D276BF91C.dita#GUID-F0663140-8AF3-3831-A741-483D276BF91C/GUID-2CDFD2CB-C3C2-3765-9155-2899F76B0A40"><apiname>MSIPRegistrationContext::IsContextActive()</apiname></xref> function to check. A profile becomes active when it is enabled by the client and the state of the profile is <codeph>ERegistered</codeph>. <codeph>ERegistered</codeph> is an enum value of the <codeph>TSIPProfileState</codeph> enum defined in the class <xref href="GUID-F324C2F6-1336-361C-B270-EFBAA256C46A.dita"><apiname>CSIPProfileAgent</apiname></xref>. </p> </li> <li id="GUID-9B116C46-DE47-5838-9753-A7C05844F886"><p>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 <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref>. If the enabled profile is already registered, no additional registration or status change events are sent. </p> </li> <li id="GUID-5F49EEA6-523D-5080-92BA-344EDBE71C57"><p>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. </p> </li> <li id="GUID-0E0CD639-0976-5B47-A0D1-CB84BFF759D0"><p>When a profile is not needed by the client, it is disabled. When you delete an instance of the profile the profile is disabled. </p> </li> </ul> <p>The following illustration shows use of the SIP Profile API. </p> <fig id="GUID-191B67CA-9715-5A3F-A571-1353BF69F5A4"><image href="GUID-269D6756-98B5-5928-9A83-261C3F729BCE_d0e335760_href.png" placement="inline"/></fig> </section> <section id="GUID-7DDA5B21-FC36-54DC-A717-0BF360DD961B"><title>Error handling</title> <p>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. </p> <p>If an error occurs during an asynchronous operation, the error is passed to the client through the callback function <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita#GUID-91663686-42B7-3C88-B773-3C5343CDCFCE/GUID-8CDFC758-2BA9-3262-9A98-D2C9EC6E65C0"><apiname>MSIPProfileRegistryObserver::ProfileRegistryErrorOccurred()</apiname></xref>. 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. </p> </section> </conbody></concept>