<?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 id="GUID-CB3FC449-7994-5510-BD78-F1638CD48A9D" xml:lang="en"><title>Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The SIP Profile API provides the SIP registration service for applications.
This API allows an application to register through a profile. The profile
holds the information to provide the required registration behaviour. The
behaviour of the registration service depends on the profile type used. </p>
<p>Each standard has an associated profile type such as 3GPP R5 IMS, IETF,
or proprietary. Each profile has a one-to-one communication with each SIP
registration. The API allows more than one application to share the same profile
and the same SIP registration. The implementation of the API stores SIP profiles
in persistent store. </p>
<p>A profile stores the following main parameters: </p>
<ul>
<li id="GUID-B7071F02-6EA0-5CE6-B143-A1840048218D"><p>The user-friendly name
of the service provider. </p> </li>
<li id="GUID-93B07153-99F2-54D3-8116-216E713296BC"><p>The type of the profile,
for example 3GPP R5 IMS, IETF or proprietary. </p> </li>
<li id="GUID-CD548B53-8C9E-5D13-820A-DE53183A7D25"><p>The registered public
name of the user (SIP AOR). </p> </li>
<li id="GUID-7CA9FF5E-B876-57DD-9203-B0DA282785D8"><p>The access provider
identifier of the IAP used. </p> </li>
<li id="GUID-850E144B-1F5A-55EF-8A71-9F6A404D05FC"><p>The address of the SIP
registrar server, with optional connection and security parameters. </p> </li>
<li id="GUID-214EEE38-6FAC-5349-8B9A-E5EFA53D0EAB"><p>The address of the SIP
proxy server, with optional connection and security parameters. </p> </li>
<li id="GUID-4C6501CC-2431-5027-B614-0BF7B8E56F76"><p>The compression and
security preferences. </p> </li>
<li id="GUID-7993263B-EA1C-5A87-A8D4-585A9B9A0EC8"><p>An indication if the
profile is always registered automatically, or registered when it is used
by an application. </p> </li>
<li id="GUID-90F43095-BFBF-5858-8FCD-622C680A043D"><p>Any extension parameters
stored as key-value pairs. </p> </li>
</ul>
<section id="GUID-D68DCE64-4F0A-55C7-87B7-AD0176DC000F"><title>Architectural
Relationships</title> <p>The interface allows clients to share the common
resources, profiles and SIP registrations through the client-server mechanism.
It also gives access to permanently stored profiles and allows the reading
of profile configuration values. </p> <p>All lengthy operations are asynchronous. </p> <p id="GUID-EFED18E0-D710-5484-B44B-905188C55894"><b>Capability information</b> </p> <p>The
following table describes the capabilities the user must have to use the SIP
Profile API. </p> <table id="GUID-DC2D1A38-8600-5071-B5DC-7C2E13B10DDA">
<tgroup cols="1"><colspec colname="col0"/>
<tbody>
<row>
<entry><p> <b>Capability</b>  </p> </entry>
</row>
<row>
<entry><p> <codeph> NetworkControl</codeph>  </p> </entry>
</row>
<row>
<entry><p> <codeph>NetworkServices</codeph>  </p> </entry>
</row>
<row>
<entry><p> <codeph> ReadUserData</codeph>  </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p id="GUID-3A7EC69E-9C4C-55ED-8998-07640410D17B"><b> Extending
the API</b> </p> <p>The API cannot be extended. </p> </section>
<section id="GUID-BB1CA3D9-B29C-54A7-9772-E9ACD6D57A1F"><title>SIP Profile
API class structure</title> <p>The client must create a <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita"><apiname>CSIP</apiname></xref> object,
and must implement the callback functions defined by the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> class.
A client of the SIP Profile API must then create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object. </p> <p>A <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> object
is created using one of the retrieval functions that can be accessed through
the <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> class. Profile data is copied from
the permanent store into the new object. The copied values can be accessed
using the access functions of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> <p>The
client must enable a profile before you can use it. A profile can be enabled
in the following ways: </p> <ul>
<li id="GUID-C1F4C96E-794C-5CD1-81FE-2AD8208A8217"><p>provide an implementation
of the <xref href="GUID-B889A3FD-3B14-3785-90AE-3546F0C9A5D4.dita"><apiname>MSIPConnectionObserver</apiname></xref> class </p> </li>
<li id="GUID-5BE21413-BF91-53F8-923F-555B4014B973"><p>call <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita#GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9/GUID-DB3F6FFC-FE96-3A35-A60F-DAAAFF13C357"><apiname>CSIPProfileRegistry::EnableL()</apiname></xref> </p> </li>
</ul> <p>When you enable a profile it is automatically registered. If the
profile is not registered before it is enabled the client is notified about
the registration status through the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita#GUID-91663686-42B7-3C88-B773-3C5343CDCFCE/GUID-FAC7E932-24CB-3C5E-B2A4-057B33C784FC"><apiname>MSIPProfileRegistryObserver::ProfileRegistryEventOccurred()</apiname></xref> callback
function. </p> <p>When a profile is enabled, the client indicates that the
profile is in use, and cannot be removed. You can update the profile but,
it is not recommended. </p> <p>If required, the client can disable a profile.
The client can then delete the <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> object. </p> <p>The
following illustration shows the SDP Profile API class structure. </p> <fig id="GUID-333B9964-A742-55C4-A731-FF172B930C16">
<image href="GUID-F2877A25-1FBC-5C7C-9542-9EDED2748AD3_d0e342089_href.png" placement="inline"/>
</fig> </section>
<section id="GUID-CBB17EE7-FA26-5D08-942B-223C6C5B5205"><title>Memory used</title> <p>The
amount of memory used by a profile depends on its content. A normal usage
is approximately 0.2 KB for each profile. The SIP Profile server monitors
all instantiated profiles to send the asynchronous events to clients when
required. It is recommended that clients create the minimum number of profiles
required, and delete instances immediately when they are no longer required. </p> </section>
</conbody></concept>