<?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_d0e562301_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>