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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-CB3FC449-7994-5510-BD78-F1638CD48A9D" xml:lang="en"><title>Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    13 <p>The SIP Profile API provides the SIP registration service for applications.

    14 This API allows an application to register through a profile. The profile

    15 holds the information to provide the required registration behaviour. The

    16 behaviour of the registration service depends on the profile type used. </p>

    17 <p>Each standard has an associated profile type such as 3GPP R5 IMS, IETF,

    18 or proprietary. Each profile has a one-to-one communication with each SIP

    19 registration. The API allows more than one application to share the same profile

    20 and the same SIP registration. The implementation of the API stores SIP profiles

    21 in persistent store. </p>

    22 <p>A profile stores the following main parameters: </p>

    23 <ul>

    24 <li id="GUID-B7071F02-6EA0-5CE6-B143-A1840048218D"><p>The user-friendly name

    25 of the service provider. </p> </li>

    26 <li id="GUID-93B07153-99F2-54D3-8116-216E713296BC"><p>The type of the profile,

    27 for example 3GPP R5 IMS, IETF or proprietary. </p> </li>

    28 <li id="GUID-CD548B53-8C9E-5D13-820A-DE53183A7D25"><p>The registered public

    29 name of the user (SIP AOR). </p> </li>

    30 <li id="GUID-7CA9FF5E-B876-57DD-9203-B0DA282785D8"><p>The access provider

    31 identifier of the IAP used. </p> </li>

    32 <li id="GUID-850E144B-1F5A-55EF-8A71-9F6A404D05FC"><p>The address of the SIP

    33 registrar server, with optional connection and security parameters. </p> </li>

    34 <li id="GUID-214EEE38-6FAC-5349-8B9A-E5EFA53D0EAB"><p>The address of the SIP

    35 proxy server, with optional connection and security parameters. </p> </li>

    36 <li id="GUID-4C6501CC-2431-5027-B614-0BF7B8E56F76"><p>The compression and

    37 security preferences. </p> </li>

    38 <li id="GUID-7993263B-EA1C-5A87-A8D4-585A9B9A0EC8"><p>An indication if the

    39 profile is always registered automatically, or registered when it is used

    40 by an application. </p> </li>

    41 <li id="GUID-90F43095-BFBF-5858-8FCD-622C680A043D"><p>Any extension parameters

    42 stored as key-value pairs. </p> </li>

    43 </ul>

    44 <section id="GUID-D68DCE64-4F0A-55C7-87B7-AD0176DC000F"><title>Architectural

    45 Relationships</title> <p>The interface allows clients to share the common

    46 resources, profiles and SIP registrations through the client-server mechanism.

    47 It also gives access to permanently stored profiles and allows the reading

    48 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

    49 following table describes the capabilities the user must have to use the SIP

    50 Profile API. </p> <table id="GUID-DC2D1A38-8600-5071-B5DC-7C2E13B10DDA">

    51 <tgroup cols="1"><colspec colname="col0"/>

    52 <tbody>

    53 <row>

    54 <entry><p> <b>Capability</b>  </p> </entry>

    55 </row>

    56 <row>

    57 <entry><p> <codeph> NetworkControl</codeph>  </p> </entry>

    58 </row>

    59 <row>

    60 <entry><p> <codeph>NetworkServices</codeph>  </p> </entry>

    61 </row>

    62 <row>

    63 <entry><p> <codeph> ReadUserData</codeph>  </p> </entry>

    64 </row>

    65 </tbody>

    66 </tgroup>

    67 </table> <p id="GUID-3A7EC69E-9C4C-55ED-8998-07640410D17B"><b> Extending

    68 the API</b> </p> <p>The API cannot be extended. </p> </section>

    69 <section id="GUID-BB1CA3D9-B29C-54A7-9772-E9ACD6D57A1F"><title>SIP Profile

    70 API class structure</title> <p>The client must create a <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita"><apiname>CSIP</apiname></xref> object,

    71 and must implement the callback functions defined by the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> class.

    72 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

    73 is created using one of the retrieval functions that can be accessed through

    74 the <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> class. Profile data is copied from

    75 the permanent store into the new object. The copied values can be accessed

    76 using the access functions of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> <p>The

    77 client must enable a profile before you can use it. A profile can be enabled

    78 in the following ways: </p> <ul>

    79 <li id="GUID-C1F4C96E-794C-5CD1-81FE-2AD8208A8217"><p>provide an implementation

    80 of the <xref href="GUID-B889A3FD-3B14-3785-90AE-3546F0C9A5D4.dita"><apiname>MSIPConnectionObserver</apiname></xref> class </p> </li>

    81 <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>

    82 </ul> <p>When you enable a profile it is automatically registered. If the

    83 profile is not registered before it is enabled the client is notified about

    84 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

    85 function. </p> <p>When a profile is enabled, the client indicates that the

    86 profile is in use, and cannot be removed. You can update the profile but,

    87 it is not recommended. </p> <p>If required, the client can disable a profile.

    88 The client can then delete the <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> object. </p> <p>The

    89 following illustration shows the SDP Profile API class structure. </p> <fig id="GUID-333B9964-A742-55C4-A731-FF172B930C16">

    90 <image href="GUID-F2877A25-1FBC-5C7C-9542-9EDED2748AD3_d0e315964_href.png" placement="inline"/>

    91 </fig> </section>

    92 <section id="GUID-CBB17EE7-FA26-5D08-942B-223C6C5B5205"><title>Memory used</title> <p>The

    93 amount of memory used by a profile depends on its content. A normal usage

    94 is approximately 0.2 KB for each profile. The SIP Profile server monitors

    95 all instantiated profiles to send the asynchronous events to clients when

    96 required. It is recommended that clients create the minimum number of profiles

    97 required, and delete instances immediately when they are no longer required. </p> </section>

    98 </conbody></concept>