Symbian3/SDK/Source/GUID-CB3FC449-7994-5510-BD78-F1638CD48A9D.dita
changeset 0 89d6a7a84779
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-CB3FC449-7994-5510-BD78-F1638CD48A9D.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,98 @@
+<?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_d0e315964_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>
\ No newline at end of file