--- a/Symbian3/SDK/Source/GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,381 +1,381 @@
-<?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-6E221034-9A01-53AB-8374-315C38CCA21E" xml:lang="en"><title>Examples
-Showing the use of the SIP Profile API</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p>The following sections describe how to use the SIP Profile API. </p>
-<ul>
-<li id="GUID-D5503066-5783-5D3D-9EC3-DBC7CEE398B3"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-82D83B96-FF89-5F6A-9A65-C448F103A2F5">Creating a SIP profile</xref> </p> </li>
-<li id="GUID-EE2733CC-B951-5970-BC00-2D8F3E0F6EFA"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-72003F70-79B8-5D23-977D-E736AD3E5B42">Modifying a SIP Profile</xref> </p> </li>
-<li id="GUID-6FCDC117-944D-57D6-BB49-77845972077E"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-27B07919-C5D5-5F8A-B2A3-AC2577E19C92">Enabling a SIP profile</xref> </p> </li>
-<li id="GUID-CBD94827-C48F-5E91-88F8-A2E962BB08B9"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-628DCA48-F8B4-5E6F-AC1B-731EAB1A9D62">Disabling a SIP profile</xref> </p> </li>
-<li id="GUID-610AAF1B-B350-5102-9DA4-82FBC04FC527"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-E607BA8F-50CC-5CF6-9D7E-E31319825507">Destroying a SIP Profile</xref> </p> </li>
-<li id="GUID-3108093C-35E5-56C2-A3C2-03527816E537"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-EABE2455-4D59-58AE-8D02-24FD4A7A82B1">Retrieving a profile</xref> </p> </li>
-<li id="GUID-1BE93BE1-2B70-53C8-B6FD-48278322517F"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-471F4EBB-2FE4-561D-9B74-555061797C45">Refreshing a SIP profile</xref> </p> </li>
-<li id="GUID-F6CD986B-C019-58E6-B71D-39F42AB03AA6"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-289B2BF5-AF58-5E1E-B905-F1255EFC7FEB">Stopping SIP registration</xref> </p> </li>
-</ul>
-<section id="GUID-82D83B96-FF89-5F6A-9A65-C448F103A2F5"><title>Creating a
-SIP profile</title> <p> <xref href="GUID-5266AB0D-705C-3011-A92B-DA82BC212999.dita"><apiname> CSIPManagedProfileRegistry</apiname></xref> manages
-the SIP profiles and provides the functions to add, update, and remove profiles
-at run time. </p> <p>The following steps describes how to create a SIP profile. </p> <ol id="GUID-F9ECD3BD-52AC-5370-8336-4EEB619B1F58">
-<li id="GUID-C0A00EF9-72F1-53DB-8CCB-BE7B4BF3D7F3"><p>Create a default profile
-that uses the <xref href="GUID-A9C883F9-3C6D-32BF-A278-4DCBDA18F687.dita"><apiname>CreateL()</apiname></xref> interface of <xref href="GUID-B2F66C7C-4E81-307C-B836-314D0A89D8D6.dita"><apiname>CSIPManagedProfileRegistry()</apiname></xref>. <xref href="GUID-A9C883F9-3C6D-32BF-A278-4DCBDA18F687.dita"><apiname>CreateL()</apiname></xref> returns
-an object of type <codeph>CSIPManagedProfile</codeph>. </p> </li>
-<li id="GUID-76CD5953-C5A9-51C0-9E66-2444AFE458D6"><p>Use <codeph>SetParameter()</codeph> of <xref href="GUID-CDE67614-1A7A-3082-8D8D-71645668A0DE.dita"><apiname>CSIPManagedProfile</apiname></xref> to
-set the value for the profile parameters. </p> </li>
-<li id="GUID-8F762BAF-0D4B-580D-8A8B-BE3B68C2BF90"><p>Use <xref href="GUID-5266AB0D-705C-3011-A92B-DA82BC212999.dita#GUID-5266AB0D-705C-3011-A92B-DA82BC212999/GUID-50D99686-5C79-3F7F-9C7D-4FC23EE41832"><apiname>CSIPManagedProfileRegistry::SaveL()</apiname></xref> to
-save the profile when the values are set. </p> </li>
-<li id="GUID-1B40AA8E-6326-5631-B83E-5230192FBC0E"><p>When you call <xref href="GUID-475D1AF4-F8C2-3243-99DC-43419979A858.dita"><apiname>SaveL()</apiname></xref>,
-wait until <xref href="GUID-92312598-A5DA-36B9-AF46-E7EE80452792.dita"><apiname>EProfileCreated</apiname></xref> event is reported in the observer.
-When the event is received the profile is created. </p> </li>
-</ol> <fig id="GUID-13F7B1AB-7F1A-544F-AC9C-26780E4FC517">
-<image href="GUID-46A91D57-7864-53AD-903C-B978B0C61DAD_d0e342329_href.jpg" placement="inline"/>
-</fig> <p>The following code snippet shows how to create and save a profile. </p> <codeblock id="GUID-EFDEE0D4-00C9-520E-B1FA-18E48702DE7F" xml:space="preserve">/*Client must create an instance of the CSIP class. The API used for this is, here TUid must be an application UID.*/
-
-CSIP* CSIP::NewL(const TUid& aUid, MSIPObserver& aObserver);
-
-/* CSIPManagedProfileRegistry manages SIP profiles and provides functions for adding, updating, or removing profiles at run time. */
-
-iManagedProfileRegistry= CSIPManagedProfileRegistry::NewL(aObserver);
-
-/* CreateL() of CSIPManagedProfileRegistry is used to create a profile with default values. This takes ProfileType as parameter so define a profile type.*/
-
-/* Profilename */
- _LIT8( KProfileName, "ims" );
-
- // Used to set and get the parameters of the profile
- CSIPManagedProfile* aProfile = NULL;
-
- // Set the profile type , profile name.
- TSIPProfileTypeInfo typeInfo;
- typeInfo.iSIPProfileClass = TSIPProfileTypeInfo:: EIms;
- typeInfo.iSIPProfileName = KProfileName;
-
- // Creates the profile of type IETF with default values
- aProfile = iManagedProfileRegistry->CreateL( typeInfo );
-
- // Set the values in the newly created profile.
- TUint32 iapId(11);
- aProfile->SetParameter(KSIPAccessPointId,iapId);
-
- _LIT8(aor,"sip:user@192.168.0.35");
- aProfile->SetParameter(KSIPUserAor,aor);
-
-// Save the profile
- iManagedProfileRegistry->SaveL(*aProfile);
-
-// Wait for EProfileCreated event on the observer.
-</codeblock> </section>
-<section id="GUID-72003F70-79B8-5D23-977D-E736AD3E5B42"><title>Modifying a
-SIP Profile</title> <p>The following steps describe how to modify a SIP profile. </p> <ol id="GUID-AFE64969-68F3-594C-8324-F0943694AB19">
-<li id="GUID-FE7DBAA3-03C5-5CFC-BFB8-C63DDF7AA6A3"><p>The profile is modified
-when you change the profile parameters and save the updated profile to the
-permanent store. </p> </li>
-<li id="GUID-6B61FCF7-C753-534E-BF2D-293FE7A16F6E"><p>When the updated profile
-is saved to the permanent store the application gets the event notification <codeph>EProfileUpdated</codeph>. </p> </li>
-<li id="GUID-614CA2D4-ED93-58A7-B3FC-8F86C3BA3A7C"><p>Depending on the updated
-parameters, the update leads to no actions, to registration or to re-registration.
-The profile is re-registered if it is configured for auto-registration when
-the profile is updated. </p> </li>
-<li id="GUID-9A12EC08-7C67-551E-A7FE-5A114A36F721"><p>The profile must not
-be used by another application while you update the profile. Use the <xref href="GUID-5266AB0D-705C-3011-A92B-DA82BC212999.dita#GUID-5266AB0D-705C-3011-A92B-DA82BC212999/GUID-E6E0D735-28EC-3BFD-8359-68FDC39108EE"><apiname>CSIPManagedProfileRegistry::IsInUseL</apiname></xref> API
-to check if the profile is currently in use. </p> </li>
-</ol> </section>
-<section id="GUID-27B07919-C5D5-5F8A-B2A3-AC2577E19C92"><title>Enabling a
-SIP profile</title> <p>The following steps describe how to enable a SIP profile. </p> <ol id="GUID-1D340099-1F58-5E19-8380-1CC187CB7632">
-<li id="GUID-7E306B08-C5A3-534F-9122-17D81BDAB5C2"><p>A client of the SIP
-Profile API must create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object. </p> <p> <b>Note</b>:
-The client must provide an instance of the class <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita"><apiname>CSIP</apiname></xref> to
-create an object of the type <codeph>CSIPProfileRegistry</codeph>. </p> </li>
-<li id="GUID-E8B43A46-B6F0-5466-A039-D0565EAA0895"><p>The client must implement
-the callback functions defined in the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> interface
-to get notified when the status of the profile is changed. </p> </li>
-<li id="GUID-FDB514C2-5B6A-5FB6-AECD-BEF264DD700B"><p>Create an instance of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> using
-a retrieve function of the <xref href="GUID-DDB0FD0C-267F-3AAB-8519-78065180E0BD.dita"><apiname>CSIPPProfileRegistry</apiname></xref> class. </p> </li>
-<li id="GUID-B3B9F1DF-A195-5E37-84BD-2A951C472BC8"><p>The profile parameters
-are read from the getter functions of the <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> </li>
-<li id="GUID-47997C80-FE84-5FAF-A5A1-E634215BD362"><p>The client can use the
-profile when you enable it through <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> and
-leaves on failure. </p> </li>
-<li id="GUID-FBC081E2-D61E-58DB-9237-6673FB9231E0"><p>The user must check
-the profile status after the <xref href="GUID-93D33C84-8A6B-3A94-9797-1412489323F0.dita"><apiname>EnableL</apiname></xref> function is called.
-If the profile is not registered after this function is called, the user must
-wait until it gets a notification through the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> callback
-interface about the profile registration. </p> </li>
-</ol> <fig id="GUID-9300C461-D490-5E0B-84A6-AD40F95B8DE7">
-<image href="GUID-5C52B6B9-546C-5152-A968-B91CB3D885A0_d0e342464_href.jpg" placement="inline"/>
-</fig> <p>The following code snippet shows how to enable a SIP profile. </p> <codeblock id="GUID-1A52EE02-D6E9-5795-995B-6B5ADFD131B4" xml:space="preserve">
-/*With the assumption that the profile was created and is saved to the persistent storage. */
-//Create an Instance of SIP client
-
-iSip = CSIP::NewL( aAppUid );
-
-//use CSIPProfileRegistry to get the saved profile.
-
-iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this);
-
-//Retrieve the profiles by the AOR
-
-_LIT8(KAor,"sip:user@10.192.192.43");
-TDesC8 aor(KAor);
-
-RPointerArray<CSIPProfile> profiles;
-
-/* Find and put the matching profiles by the given AOR into the pointer array.
-Returns the set of profiles which has the provided AOR.*/
-
-iProfileRegistry->ProfilesL(KAor,profiles);
-
-// Check the profile count. Get the required profile if the count is positive non-zero.
-TInt profile_cnt = profiles.Count() ;
-iProfile = profiles[0];
-iProfileRegistry->EnableL( *iProfile, *this );
-
-//Application gets the event EProfileRegistered if the registration is successful.
-</codeblock> </section>
-<section id="GUID-628DCA48-F8B4-5E6F-AC1B-731EAB1A9D62"><title>Disabling a
-SIP profile</title> <p>The following steps describes how to disable a SIP
-profile. </p> <ul>
-<li id="GUID-8EF332BF-6FD9-50B2-B29C-A24B29B4829D"><p>A client of the SIP
-Profile API must create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object </p> <p> <b>Note</b>:
-The client must provide an instance of the class <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita"><apiname>CSIP</apiname></xref> to
-create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object. </p> </li>
-<li id="GUID-0715DDFB-639B-5843-BFC8-75E53D807698"><p>The client must implement
-the callback functions defined in the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> interface
-to get notified with the events when the status of the profile is changed. </p> </li>
-<li id="GUID-8C06A1DB-BAE9-5718-B10D-3D262981B100"><p>Use retrieve function
-of the class <xref href="GUID-DDB0FD0C-267F-3AAB-8519-78065180E0BD.dita"><apiname>CSIPPProfileRegistry</apiname></xref> to create an instance
-of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> </li>
-<li id="GUID-4A1D7F52-7146-541C-91AE-E9CB5B8D5DD5"><p>The profile parameters
-are read from the getter functions of the <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> </li>
-<li id="GUID-3D2ADA9A-DC9B-501D-B6DA-68BDA1B747FA"><p>Check the registration
-status of the profile that uses the getter functions of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>.
-Disable the profile if it is registered. </p> </li>
-<li id="GUID-E042394C-6AF3-5951-8F26-C4473DBDD143"><p>An application gets
-the notification event <codeph>EProfileDeregistered</codeph> if the de-registration
-is successful, otherwise it leaves. The error is sent to the application through
-the <codeph>ProfileRegistryErrorOccurred</codeph> callback function. </p> </li>
-</ul> <p>The following code snippet shows how to disable a SIP profile. </p> <codeblock id="GUID-40C08581-81ED-5A7E-90D9-36966992191A" xml:space="preserve">/*With the assumption that the profile was created and is saved to the persistent storage.
-//Create an instance of SIP client
-iSip = CSIP::NewL( aAppUid
-
-/*use CSIPProfileRegistry to get the saved profile.*/
-iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this);
-
- /*Retrieve the profiles by the AOR*/
-_LIT8(KAor,"sip:user@10.192.192.43");
-TDesC8 aor(KAor);
-
-RPointerArray<CSIPProfile> profiles;
-
-// Find and put the matching profiles by the given AOR into the pointer array
-// Returns the set of profiles which has the provided AOR.
-iProfileRegistry->ProfilesL(KAor,profiles);
-
-/* Check the profile count. Get the required profile if the count is positive non-zero.*/
-TInt profile_cnt = profiles.Count() ;
-iProfile = profiles[0];
-
-// Registered is a bool type variable. Check the registration status of the iProfile.
-// Registered holds TRUE if it is registered otherwise FALSE
-iProfile->GetParameter( KSIPProfileRegistered, registered );
-
-/* If the iProfile is registered ( the Registered variable must hold TRUE for iProfile )*/
-/* Disable API returns KErrNone if the profile was disabled successfully otherwise there is a system-wide error.*/
-CSIPProfileRegistry::Disable(*iProfile)
-</codeblock> </section>
-<section id="GUID-E607BA8F-50CC-5CF6-9D7E-E31319825507"><title>Destroying
-a SIP Profile</title> <p>When you destroy a SIP profile it is permanently
-removed from the permanent storage and it cannot be used. The profile information
-is removed from the <filepath>sipprofiles.dat</filepath> file in Epoc32\winscw\c\private\101F413C. </p> <p>The
-following steps describe how to destroy a SIP profile. </p> <ol id="GUID-04F9358C-2AED-58F7-9404-01A4588590D1">
-<li id="GUID-3E72E3A2-3A3B-5433-8F38-6EB5AE517E50"><p>When the profile is
-destroyed the application gets the event <codeph>EProfileDestroyed</codeph>. </p> </li>
-<li id="GUID-D562B0C1-DC27-5615-AB19-70A978C4AF41"><ul>
-<li id="GUID-EDF14357-0BCB-539C-B569-01F19C02265E"><p>Registered: The removal
-is two-step process, de-register the profile and remove the profile. </p> </li>
-</ul> <ul>
-<li id="GUID-A1EC272B-AF21-572D-B16E-367EF21796BE"><p>De-registered : Removes
-the profile from the permanent storage and the application is notified with
-the event EProfileDestroyed. </p> </li>
-</ul> </li>
-</ol> <p>The following code snippet shows how to disable a profile. </p> <codeblock id="GUID-0784D25C-7AA0-53C1-B386-AC54F072833D" xml:space="preserve">//Function leaves on failure.
-CSIPManagedProfileRegistry::DestroyL(CSIPProfile& aSIPProfile);
-</codeblock> </section>
-<section id="GUID-EABE2455-4D59-58AE-8D02-24FD4A7A82B1"><title>Retrieving
-a profile</title> <p><b>Retrieving a default profile</b> </p> <p>The following
-code snippet shows how to retrieve the default profile. </p> <codeblock id="GUID-3D64A865-38B6-539F-8C6B-CE10996B24A3" xml:space="preserve">// Retrieving a default profile.
-CSIPProfile* profile = iProfileRegistry->DefaultProfileL();
-
-// When a client retrieves a profile, its ownership is transferred to that client, so it becomes responsible
-// for deleting the instances when they are no longer needed.
-
-delete profile;
-</codeblock> <p><b>Retrieving profiles by type</b> </p> <p>The following code
-snippet shows how to retrieve profiles by type. </p> <codeblock id="GUID-26097346-72B3-51A9-ABB3-37B8B138B28D" xml:space="preserve">// To retrieve more than one profile, the client must create
-// an RPointerArray object to holding pointers to instances of CSIPProfile.
-
-RPointerArray<CSIPProfile> profiles;
-
-// The wanted type is defined using a variable of type TSIPProfileTypeInfo.
-
-TSIPProfileTypeInfo type;
-type.iSIPProfileClass = TSIPProfileTypeInfo::EInternet;
-type.iSIPProfileName = _L8("IETF");
-
-// Profiles matching a given type are returned in the array.
-iProfileRegistry->ProfilesL(type, profiles);
-...
-// When a client retrieves a profile, its ownership is transferred to that
-// client, so it becomes responsible for deleting the instances when they are
-// no longer needed.
-profiles.ResetAndDestroy();
-</codeblock> <p><b>Retrieving profiles by matching an AOR</b> </p> <p>The
-following code snippet shows how to retrieve profiles by matching an AOR. </p> <codeblock id="GUID-71C88079-A622-5C95-B6C4-91066E99D021" xml:space="preserve">// To retrieve more than one profile, the client must create
-// an RPointerArray object to hold pointers to instances of CSIPProfile.
-RPointerArray<CSIPProfile> profiles;
-
-// Profiles matching a given AOR are returned in the array.
-iProfileRegistry->ProfilesL(_L8( "sip:jane.doe@foo.com" ), profiles );
-...
-
-// When a client retrieves a profile, its ownership is transferred to that
-// client, so it becomes responsible for deleting the instances when they are no longer needed.
-profiles.ResetAndDestroy();
-</codeblock> </section>
-<section><title>Getting the registration events</title> <p>The following code
-snippet shows how to get the registration events for different scenarios. </p> <codeblock id="GUID-4BCCE827-AD41-5DB0-A71F-611F1DF4BE25" xml:space="preserve">// A callback function, which must be implemented by the client, is called when the registration status
-of a profile owned by the client is changed.
-
-void CMySIPClient:: ProfileRegistryEventOccurred(TUint32 aProfileId,
-MSIPProfileRegistryObserver::TEvent aEvent)
- {
- iProfileId = aProfileId;
- switch(aEvent)
- {
- case EProfileCreated:
- {
- iEventId = EAdded;
- break;
- }
- case EProfileUpdated:
- {
- iEventId = EUpdated;
- break;
- }
- case EProfileRegistered:
- {
- iEventId = CMySIPClient::ERegistered;
- break;
- }
- case EProfileDeregistered:
- {
- iEventId = CMySIPClient::EDeregistered;
- break;
- }
- case EProfileDestroyed:
- {
- iEventId = ERemoved;
- break;
- }
- default:
- break;
- }
-}</codeblock> </section>
-<section id="GUID-471F4EBB-2FE4-561D-9B74-555061797C45"><title>Refreshing
-a SIP profile</title> <p>The SIP profile can use either WLAN or GPRS connections
-to register to the SIP server. In case of WLAN, a registered SIP profile changes
-its state to an unregistered state when the handset is out of WLAN coverage.
-On re-entering the WLAN zone, the WLAN automatically scans to identify the
-available access points and then the SIP profile is automatically registered
-back with the server. This process is time consuming and is not efficient.
-So, the client uses the <xref href="GUID-1AEB6899-9942-3BBC-9ABA-8C0ACFCE3174.dita"><apiname>RefreshEnableL()</apiname></xref> function to: </p> <ul>
-<li id="GUID-A19E0054-71CA-55A4-BF75-9481189D81DC"><p>Initiate the SIP registration
-automatically. </p> </li>
-<li id="GUID-E42A6C7C-0238-5C33-9CDA-4691801D8E04"><p>Reduce the response
-time for the SIP registration. </p> </li>
-<li id="GUID-54F38CF7-D29D-5D30-954E-D7DD88D6B022"><p>Improve the efficiency
-of the application using the SIP stack during registration. </p> </li>
-</ul> <p>The <xref href="GUID-D5A82B9C-A86E-318F-85D7-B9DC69968DB0.dita"><apiname>RefreshEnableL</apiname></xref> API refreshes the connection
-on the used access point if it is not active. Refresh enabling a profile means
-that the user has enabled the profile but is unregistered because of a connection
-loss. For example, in a WLAN network, a connection refresh request to the
-bearer monitor starts the WLAN scanning if it is stopped. When the Connection
-Active notification is received, the stack automatically registers the profile
-and gives a notification to the client with the event <xref href="GUID-F78ECFEB-441F-3D55-9909-A3F82F738F7E.dita"><apiname>EProfileRegistered</apiname></xref> through
-the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref>. </p> <p>To refresh enable
-a profile, do the following steps: </p> <ul>
-<li id="GUID-221E3B9E-86DF-5200-ADA6-55E724688028"><p>Start the SIP Profile
-server. </p> </li>
-<li id="GUID-59833E8F-9619-5C72-8891-2E2D63B6B8CF"><p>Fetch the profile that
-must be refresh enabled from the SIP Profile Server. </p> <ul>
-<li id="GUID-0C52D86D-3ADA-5D6D-AEC5-07D1554A9C11"><p>If the profile is not
-Enabled the <xref href="GUID-E72E5C9A-ADAE-346A-8EF9-DACD7D23F318.dita"><apiname>RefreshEnable</apiname></xref> API leaves with <codeph>KErrArgument</codeph> error. </p> </li>
-<li id="GUID-EFC454B5-6F99-58A3-B3ED-9983DE0C1A4E"><p>If the profile is Enabled
-and in a Registered state then the API leaves with <codeph>KErrAlreadyExists</codeph> error. </p> </li>
-<li id="GUID-6B5728C4-F42C-5208-A6E4-1AF5641A13E3"><p>If the profile is Enabled
-and in an Unregistered state then the <xref href="GUID-E72E5C9A-ADAE-346A-8EF9-DACD7D23F318.dita"><apiname>RefreshEnable</apiname></xref> API
-refreshes the connection through <xref href="GUID-2A070F4D-A35B-3505-BE86-E6C7A2F27B94.dita#GUID-2A070F4D-A35B-3505-BE86-E6C7A2F27B94/GUID-956F2ADC-40D6-3C15-949A-80789DF04550"><apiname>CSIPConnection::RefreshConnection()</apiname></xref> API.
-The profile receives notification about the active connection and it automatically
-registers again and sends <xref href="GUID-F78ECFEB-441F-3D55-9909-A3F82F738F7E.dita"><apiname>EProfileRegistered</apiname></xref> event to the
-application. </p> </li>
-</ul> </li>
-<li id="GUID-9CA4CA87-17C7-54D0-AEAF-F415DA5D934E"><p>A REGISTER request sent
-to the registrar server. </p> </li>
-<li id="GUID-FF40934C-588D-5ED6-8041-410103FB6D53"><p>The registration status
-of the profile is set to Registered. </p> </li>
-</ul> <p>The following sequence diagram shows how to enable a profile to refresh. </p> <fig id="GUID-5EF1953C-E56D-59C2-B443-F1B77DD7E73D">
-<image href="GUID-8D9FE811-3F8A-5C2A-B76A-5C0248179590_d0e342779_href.jpg" placement="inline"/>
-</fig> <p>The following code describes how to refresh enable a profile. </p> <codeblock id="GUID-1A13F3D3-C4B7-50E5-B5AF-F0CABF02758C" xml:space="preserve">//Checks if the profile is already enabled and requests the Profile Agent to refresh it.
-// If the profile is not enabled it leaves with KErrArgument.
-
-void RefreshEnableL(CSIPProfile& aSIPProfile, MSIPConnectionObserver& aObserver)
-</codeblock> </section>
-<section id="GUID-289B2BF5-AF58-5E1E-B905-F1255EFC7FEB"><title>Stopping SIP
-registration</title> <p>In a setup, where there is no registrar, the SIP stack
-tries to send REGISTER messages to the network for at least 3 minutes and
-reserves the access point usage. During these 3 minutes the client cannot
-use another WLAN access point without destroying the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref>. </p> <p>The <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API
-of the SIP stack stops all registration attempts and releases the access point.
-The <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API in the profile agent module improves
-the responsiveness of the applications using the SIP stack. It avoids situations
-where an application is waiting for the SIP stack to complete a registration
-procedure. </p> <p>To use the <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API the application
-must have Network Control capability. If the application does not have Network
-Control capability and invokes the <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API, then
-it receives <codeph>ErrPermissionDenied (-46</codeph>) error. Sending a <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API
-does not force the SIP stack to send any message to the network, instead it
-destroys the SIP transaction for that profile and cleans all the resources
-associated with that profile. The Profile Agent also notifies all the observers
-with the event <xref href="GUID-1B01576C-59DC-3958-9631-3094ED0DB46D.dita"><apiname>EProfileForciblyDisabled</apiname></xref>. </p> <p>The following
-code describes how to forcibly disable a profile. </p> <codeblock id="GUID-3D1556EB-AD13-5640-8104-83D08BF0D207" xml:space="preserve">// With the assumption that the profile is created and is saved to the persistent storage create an instance of the SIP client
-iSip = CSIP::NewL( aAppUid );
-
-// Use CSIPProfileRegistry to get the saved profile.
-iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this);
-
-// Retrieve the profiles by the AOR
-_LIT8(KAor,"sip:user@10.192.192.43");
-TDesC8 aor(KAor);
-RPointerArray<CSIPProfile> profiles;
-
-// Find and add the matching profiles by the given AOR into the pointer array
-// Returns the set of profiles which has the provided AOR.
-iProfileRegistry->ProfilesL(KAor,profiles);
-
-// Check the profile count. Get the required profile if the count is positive non-zero.
-TInt profile_cnt = profiles.Count() ;
-iProfile = profiles[0];
-
-// If the iProfile is registered (the Registered variable must hold TRUE for iProfile)
-// Disable API returns KErrNone if the profile is disabled successfully otherwise there is a system-wide error.
-CSIPProfileRegistry::ForceDisable(*iProfile);</codeblock> </section>
+<?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-6E221034-9A01-53AB-8374-315C38CCA21E" xml:lang="en"><title>Examples
+Showing the use of the SIP Profile API</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>The following sections describe how to use the SIP Profile API. </p>
+<ul>
+<li id="GUID-D5503066-5783-5D3D-9EC3-DBC7CEE398B3"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-82D83B96-FF89-5F6A-9A65-C448F103A2F5">Creating a SIP profile</xref> </p> </li>
+<li id="GUID-EE2733CC-B951-5970-BC00-2D8F3E0F6EFA"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-72003F70-79B8-5D23-977D-E736AD3E5B42">Modifying a SIP Profile</xref> </p> </li>
+<li id="GUID-6FCDC117-944D-57D6-BB49-77845972077E"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-27B07919-C5D5-5F8A-B2A3-AC2577E19C92">Enabling a SIP profile</xref> </p> </li>
+<li id="GUID-CBD94827-C48F-5E91-88F8-A2E962BB08B9"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-628DCA48-F8B4-5E6F-AC1B-731EAB1A9D62">Disabling a SIP profile</xref> </p> </li>
+<li id="GUID-610AAF1B-B350-5102-9DA4-82FBC04FC527"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-E607BA8F-50CC-5CF6-9D7E-E31319825507">Destroying a SIP Profile</xref> </p> </li>
+<li id="GUID-3108093C-35E5-56C2-A3C2-03527816E537"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-EABE2455-4D59-58AE-8D02-24FD4A7A82B1">Retrieving a profile</xref> </p> </li>
+<li id="GUID-1BE93BE1-2B70-53C8-B6FD-48278322517F"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-471F4EBB-2FE4-561D-9B74-555061797C45">Refreshing a SIP profile</xref> </p> </li>
+<li id="GUID-F6CD986B-C019-58E6-B71D-39F42AB03AA6"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-289B2BF5-AF58-5E1E-B905-F1255EFC7FEB">Stopping SIP registration</xref> </p> </li>
+</ul>
+<section id="GUID-82D83B96-FF89-5F6A-9A65-C448F103A2F5"><title>Creating a
+SIP profile</title> <p> <xref href="GUID-5266AB0D-705C-3011-A92B-DA82BC212999.dita"><apiname> CSIPManagedProfileRegistry</apiname></xref> manages
+the SIP profiles and provides the functions to add, update, and remove profiles
+at run time. </p> <p>The following steps describes how to create a SIP profile. </p> <ol id="GUID-F9ECD3BD-52AC-5370-8336-4EEB619B1F58">
+<li id="GUID-C0A00EF9-72F1-53DB-8CCB-BE7B4BF3D7F3"><p>Create a default profile
+that uses the <xref href="GUID-A9C883F9-3C6D-32BF-A278-4DCBDA18F687.dita"><apiname>CreateL()</apiname></xref> interface of <xref href="GUID-B2F66C7C-4E81-307C-B836-314D0A89D8D6.dita"><apiname>CSIPManagedProfileRegistry()</apiname></xref>. <xref href="GUID-A9C883F9-3C6D-32BF-A278-4DCBDA18F687.dita"><apiname>CreateL()</apiname></xref> returns
+an object of type <codeph>CSIPManagedProfile</codeph>. </p> </li>
+<li id="GUID-76CD5953-C5A9-51C0-9E66-2444AFE458D6"><p>Use <codeph>SetParameter()</codeph> of <xref href="GUID-CDE67614-1A7A-3082-8D8D-71645668A0DE.dita"><apiname>CSIPManagedProfile</apiname></xref> to
+set the value for the profile parameters. </p> </li>
+<li id="GUID-8F762BAF-0D4B-580D-8A8B-BE3B68C2BF90"><p>Use <xref href="GUID-5266AB0D-705C-3011-A92B-DA82BC212999.dita#GUID-5266AB0D-705C-3011-A92B-DA82BC212999/GUID-50D99686-5C79-3F7F-9C7D-4FC23EE41832"><apiname>CSIPManagedProfileRegistry::SaveL()</apiname></xref> to
+save the profile when the values are set. </p> </li>
+<li id="GUID-1B40AA8E-6326-5631-B83E-5230192FBC0E"><p>When you call <xref href="GUID-475D1AF4-F8C2-3243-99DC-43419979A858.dita"><apiname>SaveL()</apiname></xref>,
+wait until <xref href="GUID-92312598-A5DA-36B9-AF46-E7EE80452792.dita"><apiname>EProfileCreated</apiname></xref> event is reported in the observer.
+When the event is received the profile is created. </p> </li>
+</ol> <fig id="GUID-13F7B1AB-7F1A-544F-AC9C-26780E4FC517">
+<image href="GUID-46A91D57-7864-53AD-903C-B978B0C61DAD_d0e336132_href.jpg" placement="inline"/>
+</fig> <p>The following code snippet shows how to create and save a profile. </p> <codeblock id="GUID-EFDEE0D4-00C9-520E-B1FA-18E48702DE7F" xml:space="preserve">/*Client must create an instance of the CSIP class. The API used for this is, here TUid must be an application UID.*/
+
+CSIP* CSIP::NewL(const TUid& aUid, MSIPObserver& aObserver);
+
+/* CSIPManagedProfileRegistry manages SIP profiles and provides functions for adding, updating, or removing profiles at run time. */
+
+iManagedProfileRegistry= CSIPManagedProfileRegistry::NewL(aObserver);
+
+/* CreateL() of CSIPManagedProfileRegistry is used to create a profile with default values. This takes ProfileType as parameter so define a profile type.*/
+
+/* Profilename */
+ _LIT8( KProfileName, "ims" );
+
+ // Used to set and get the parameters of the profile
+ CSIPManagedProfile* aProfile = NULL;
+
+ // Set the profile type , profile name.
+ TSIPProfileTypeInfo typeInfo;
+ typeInfo.iSIPProfileClass = TSIPProfileTypeInfo:: EIms;
+ typeInfo.iSIPProfileName = KProfileName;
+
+ // Creates the profile of type IETF with default values
+ aProfile = iManagedProfileRegistry->CreateL( typeInfo );
+
+ // Set the values in the newly created profile.
+ TUint32 iapId(11);
+ aProfile->SetParameter(KSIPAccessPointId,iapId);
+
+ _LIT8(aor,"sip:user@192.168.0.35");
+ aProfile->SetParameter(KSIPUserAor,aor);
+
+// Save the profile
+ iManagedProfileRegistry->SaveL(*aProfile);
+
+// Wait for EProfileCreated event on the observer.
+</codeblock> </section>
+<section id="GUID-72003F70-79B8-5D23-977D-E736AD3E5B42"><title>Modifying a
+SIP Profile</title> <p>The following steps describe how to modify a SIP profile. </p> <ol id="GUID-AFE64969-68F3-594C-8324-F0943694AB19">
+<li id="GUID-FE7DBAA3-03C5-5CFC-BFB8-C63DDF7AA6A3"><p>The profile is modified
+when you change the profile parameters and save the updated profile to the
+permanent store. </p> </li>
+<li id="GUID-6B61FCF7-C753-534E-BF2D-293FE7A16F6E"><p>When the updated profile
+is saved to the permanent store the application gets the event notification <codeph>EProfileUpdated</codeph>. </p> </li>
+<li id="GUID-614CA2D4-ED93-58A7-B3FC-8F86C3BA3A7C"><p>Depending on the updated
+parameters, the update leads to no actions, to registration or to re-registration.
+The profile is re-registered if it is configured for auto-registration when
+the profile is updated. </p> </li>
+<li id="GUID-9A12EC08-7C67-551E-A7FE-5A114A36F721"><p>The profile must not
+be used by another application while you update the profile. Use the <xref href="GUID-5266AB0D-705C-3011-A92B-DA82BC212999.dita#GUID-5266AB0D-705C-3011-A92B-DA82BC212999/GUID-E6E0D735-28EC-3BFD-8359-68FDC39108EE"><apiname>CSIPManagedProfileRegistry::IsInUseL</apiname></xref> API
+to check if the profile is currently in use. </p> </li>
+</ol> </section>
+<section id="GUID-27B07919-C5D5-5F8A-B2A3-AC2577E19C92"><title>Enabling a
+SIP profile</title> <p>The following steps describe how to enable a SIP profile. </p> <ol id="GUID-1D340099-1F58-5E19-8380-1CC187CB7632">
+<li id="GUID-7E306B08-C5A3-534F-9122-17D81BDAB5C2"><p>A client of the SIP
+Profile API must create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object. </p> <p> <b>Note</b>:
+The client must provide an instance of the class <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita"><apiname>CSIP</apiname></xref> to
+create an object of the type <codeph>CSIPProfileRegistry</codeph>. </p> </li>
+<li id="GUID-E8B43A46-B6F0-5466-A039-D0565EAA0895"><p>The client must implement
+the callback functions defined in the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> interface
+to get notified when the status of the profile is changed. </p> </li>
+<li id="GUID-FDB514C2-5B6A-5FB6-AECD-BEF264DD700B"><p>Create an instance of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> using
+a retrieve function of the <xref href="GUID-DDB0FD0C-267F-3AAB-8519-78065180E0BD.dita"><apiname>CSIPPProfileRegistry</apiname></xref> class. </p> </li>
+<li id="GUID-B3B9F1DF-A195-5E37-84BD-2A951C472BC8"><p>The profile parameters
+are read from the getter functions of the <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> </li>
+<li id="GUID-47997C80-FE84-5FAF-A5A1-E634215BD362"><p>The client can use the
+profile when you enable it through <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> and
+leaves on failure. </p> </li>
+<li id="GUID-FBC081E2-D61E-58DB-9237-6673FB9231E0"><p>The user must check
+the profile status after the <xref href="GUID-93D33C84-8A6B-3A94-9797-1412489323F0.dita"><apiname>EnableL</apiname></xref> function is called.
+If the profile is not registered after this function is called, the user must
+wait until it gets a notification through the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> callback
+interface about the profile registration. </p> </li>
+</ol> <fig id="GUID-9300C461-D490-5E0B-84A6-AD40F95B8DE7">
+<image href="GUID-5C52B6B9-546C-5152-A968-B91CB3D885A0_d0e336267_href.jpg" placement="inline"/>
+</fig> <p>The following code snippet shows how to enable a SIP profile. </p> <codeblock id="GUID-1A52EE02-D6E9-5795-995B-6B5ADFD131B4" xml:space="preserve">
+/*With the assumption that the profile was created and is saved to the persistent storage. */
+//Create an Instance of SIP client
+
+iSip = CSIP::NewL( aAppUid );
+
+//use CSIPProfileRegistry to get the saved profile.
+
+iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this);
+
+//Retrieve the profiles by the AOR
+
+_LIT8(KAor,"sip:user@10.192.192.43");
+TDesC8 aor(KAor);
+
+RPointerArray<CSIPProfile> profiles;
+
+/* Find and put the matching profiles by the given AOR into the pointer array.
+Returns the set of profiles which has the provided AOR.*/
+
+iProfileRegistry->ProfilesL(KAor,profiles);
+
+// Check the profile count. Get the required profile if the count is positive non-zero.
+TInt profile_cnt = profiles.Count() ;
+iProfile = profiles[0];
+iProfileRegistry->EnableL( *iProfile, *this );
+
+//Application gets the event EProfileRegistered if the registration is successful.
+</codeblock> </section>
+<section id="GUID-628DCA48-F8B4-5E6F-AC1B-731EAB1A9D62"><title>Disabling a
+SIP profile</title> <p>The following steps describes how to disable a SIP
+profile. </p> <ul>
+<li id="GUID-8EF332BF-6FD9-50B2-B29C-A24B29B4829D"><p>A client of the SIP
+Profile API must create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object </p> <p> <b>Note</b>:
+The client must provide an instance of the class <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita"><apiname>CSIP</apiname></xref> to
+create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object. </p> </li>
+<li id="GUID-0715DDFB-639B-5843-BFC8-75E53D807698"><p>The client must implement
+the callback functions defined in the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> interface
+to get notified with the events when the status of the profile is changed. </p> </li>
+<li id="GUID-8C06A1DB-BAE9-5718-B10D-3D262981B100"><p>Use retrieve function
+of the class <xref href="GUID-DDB0FD0C-267F-3AAB-8519-78065180E0BD.dita"><apiname>CSIPPProfileRegistry</apiname></xref> to create an instance
+of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> </li>
+<li id="GUID-4A1D7F52-7146-541C-91AE-E9CB5B8D5DD5"><p>The profile parameters
+are read from the getter functions of the <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> </li>
+<li id="GUID-3D2ADA9A-DC9B-501D-B6DA-68BDA1B747FA"><p>Check the registration
+status of the profile that uses the getter functions of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>.
+Disable the profile if it is registered. </p> </li>
+<li id="GUID-E042394C-6AF3-5951-8F26-C4473DBDD143"><p>An application gets
+the notification event <codeph>EProfileDeregistered</codeph> if the de-registration
+is successful, otherwise it leaves. The error is sent to the application through
+the <codeph>ProfileRegistryErrorOccurred</codeph> callback function. </p> </li>
+</ul> <p>The following code snippet shows how to disable a SIP profile. </p> <codeblock id="GUID-40C08581-81ED-5A7E-90D9-36966992191A" xml:space="preserve">/*With the assumption that the profile was created and is saved to the persistent storage.
+//Create an instance of SIP client
+iSip = CSIP::NewL( aAppUid
+
+/*use CSIPProfileRegistry to get the saved profile.*/
+iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this);
+
+ /*Retrieve the profiles by the AOR*/
+_LIT8(KAor,"sip:user@10.192.192.43");
+TDesC8 aor(KAor);
+
+RPointerArray<CSIPProfile> profiles;
+
+// Find and put the matching profiles by the given AOR into the pointer array
+// Returns the set of profiles which has the provided AOR.
+iProfileRegistry->ProfilesL(KAor,profiles);
+
+/* Check the profile count. Get the required profile if the count is positive non-zero.*/
+TInt profile_cnt = profiles.Count() ;
+iProfile = profiles[0];
+
+// Registered is a bool type variable. Check the registration status of the iProfile.
+// Registered holds TRUE if it is registered otherwise FALSE
+iProfile->GetParameter( KSIPProfileRegistered, registered );
+
+/* If the iProfile is registered ( the Registered variable must hold TRUE for iProfile )*/
+/* Disable API returns KErrNone if the profile was disabled successfully otherwise there is a system-wide error.*/
+CSIPProfileRegistry::Disable(*iProfile)
+</codeblock> </section>
+<section id="GUID-E607BA8F-50CC-5CF6-9D7E-E31319825507"><title>Destroying
+a SIP Profile</title> <p>When you destroy a SIP profile it is permanently
+removed from the permanent storage and it cannot be used. The profile information
+is removed from the <filepath>sipprofiles.dat</filepath> file in Epoc32\winscw\c\private\101F413C. </p> <p>The
+following steps describe how to destroy a SIP profile. </p> <ol id="GUID-04F9358C-2AED-58F7-9404-01A4588590D1">
+<li id="GUID-3E72E3A2-3A3B-5433-8F38-6EB5AE517E50"><p>When the profile is
+destroyed the application gets the event <codeph>EProfileDestroyed</codeph>. </p> </li>
+<li id="GUID-D562B0C1-DC27-5615-AB19-70A978C4AF41"><ul>
+<li id="GUID-EDF14357-0BCB-539C-B569-01F19C02265E"><p>Registered: The removal
+is two-step process, de-register the profile and remove the profile. </p> </li>
+</ul> <ul>
+<li id="GUID-A1EC272B-AF21-572D-B16E-367EF21796BE"><p>De-registered : Removes
+the profile from the permanent storage and the application is notified with
+the event EProfileDestroyed. </p> </li>
+</ul> </li>
+</ol> <p>The following code snippet shows how to disable a profile. </p> <codeblock id="GUID-0784D25C-7AA0-53C1-B386-AC54F072833D" xml:space="preserve">//Function leaves on failure.
+CSIPManagedProfileRegistry::DestroyL(CSIPProfile& aSIPProfile);
+</codeblock> </section>
+<section id="GUID-EABE2455-4D59-58AE-8D02-24FD4A7A82B1"><title>Retrieving
+a profile</title> <p><b>Retrieving a default profile</b> </p> <p>The following
+code snippet shows how to retrieve the default profile. </p> <codeblock id="GUID-3D64A865-38B6-539F-8C6B-CE10996B24A3" xml:space="preserve">// Retrieving a default profile.
+CSIPProfile* profile = iProfileRegistry->DefaultProfileL();
+
+// When a client retrieves a profile, its ownership is transferred to that client, so it becomes responsible
+// for deleting the instances when they are no longer needed.
+
+delete profile;
+</codeblock> <p><b>Retrieving profiles by type</b> </p> <p>The following code
+snippet shows how to retrieve profiles by type. </p> <codeblock id="GUID-26097346-72B3-51A9-ABB3-37B8B138B28D" xml:space="preserve">// To retrieve more than one profile, the client must create
+// an RPointerArray object to holding pointers to instances of CSIPProfile.
+
+RPointerArray<CSIPProfile> profiles;
+
+// The wanted type is defined using a variable of type TSIPProfileTypeInfo.
+
+TSIPProfileTypeInfo type;
+type.iSIPProfileClass = TSIPProfileTypeInfo::EInternet;
+type.iSIPProfileName = _L8("IETF");
+
+// Profiles matching a given type are returned in the array.
+iProfileRegistry->ProfilesL(type, profiles);
+...
+// When a client retrieves a profile, its ownership is transferred to that
+// client, so it becomes responsible for deleting the instances when they are
+// no longer needed.
+profiles.ResetAndDestroy();
+</codeblock> <p><b>Retrieving profiles by matching an AOR</b> </p> <p>The
+following code snippet shows how to retrieve profiles by matching an AOR. </p> <codeblock id="GUID-71C88079-A622-5C95-B6C4-91066E99D021" xml:space="preserve">// To retrieve more than one profile, the client must create
+// an RPointerArray object to hold pointers to instances of CSIPProfile.
+RPointerArray<CSIPProfile> profiles;
+
+// Profiles matching a given AOR are returned in the array.
+iProfileRegistry->ProfilesL(_L8( "sip:jane.doe@foo.com" ), profiles );
+...
+
+// When a client retrieves a profile, its ownership is transferred to that
+// client, so it becomes responsible for deleting the instances when they are no longer needed.
+profiles.ResetAndDestroy();
+</codeblock> </section>
+<section><title>Getting the registration events</title> <p>The following code
+snippet shows how to get the registration events for different scenarios. </p> <codeblock id="GUID-4BCCE827-AD41-5DB0-A71F-611F1DF4BE25" xml:space="preserve">// A callback function, which must be implemented by the client, is called when the registration status
+of a profile owned by the client is changed.
+
+void CMySIPClient:: ProfileRegistryEventOccurred(TUint32 aProfileId,
+MSIPProfileRegistryObserver::TEvent aEvent)
+ {
+ iProfileId = aProfileId;
+ switch(aEvent)
+ {
+ case EProfileCreated:
+ {
+ iEventId = EAdded;
+ break;
+ }
+ case EProfileUpdated:
+ {
+ iEventId = EUpdated;
+ break;
+ }
+ case EProfileRegistered:
+ {
+ iEventId = CMySIPClient::ERegistered;
+ break;
+ }
+ case EProfileDeregistered:
+ {
+ iEventId = CMySIPClient::EDeregistered;
+ break;
+ }
+ case EProfileDestroyed:
+ {
+ iEventId = ERemoved;
+ break;
+ }
+ default:
+ break;
+ }
+}</codeblock> </section>
+<section id="GUID-471F4EBB-2FE4-561D-9B74-555061797C45"><title>Refreshing
+a SIP profile</title> <p>The SIP profile can use either WLAN or GPRS connections
+to register to the SIP server. In case of WLAN, a registered SIP profile changes
+its state to an unregistered state when the handset is out of WLAN coverage.
+On re-entering the WLAN zone, the WLAN automatically scans to identify the
+available access points and then the SIP profile is automatically registered
+back with the server. This process is time consuming and is not efficient.
+So, the client uses the <xref href="GUID-1AEB6899-9942-3BBC-9ABA-8C0ACFCE3174.dita"><apiname>RefreshEnableL()</apiname></xref> function to: </p> <ul>
+<li id="GUID-A19E0054-71CA-55A4-BF75-9481189D81DC"><p>Initiate the SIP registration
+automatically. </p> </li>
+<li id="GUID-E42A6C7C-0238-5C33-9CDA-4691801D8E04"><p>Reduce the response
+time for the SIP registration. </p> </li>
+<li id="GUID-54F38CF7-D29D-5D30-954E-D7DD88D6B022"><p>Improve the efficiency
+of the application using the SIP stack during registration. </p> </li>
+</ul> <p>The <xref href="GUID-D5A82B9C-A86E-318F-85D7-B9DC69968DB0.dita"><apiname>RefreshEnableL</apiname></xref> API refreshes the connection
+on the used access point if it is not active. Refresh enabling a profile means
+that the user has enabled the profile but is unregistered because of a connection
+loss. For example, in a WLAN network, a connection refresh request to the
+bearer monitor starts the WLAN scanning if it is stopped. When the Connection
+Active notification is received, the stack automatically registers the profile
+and gives a notification to the client with the event <xref href="GUID-F78ECFEB-441F-3D55-9909-A3F82F738F7E.dita"><apiname>EProfileRegistered</apiname></xref> through
+the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref>. </p> <p>To refresh enable
+a profile, do the following steps: </p> <ul>
+<li id="GUID-221E3B9E-86DF-5200-ADA6-55E724688028"><p>Start the SIP Profile
+server. </p> </li>
+<li id="GUID-59833E8F-9619-5C72-8891-2E2D63B6B8CF"><p>Fetch the profile that
+must be refresh enabled from the SIP Profile Server. </p> <ul>
+<li id="GUID-0C52D86D-3ADA-5D6D-AEC5-07D1554A9C11"><p>If the profile is not
+Enabled the <xref href="GUID-E72E5C9A-ADAE-346A-8EF9-DACD7D23F318.dita"><apiname>RefreshEnable</apiname></xref> API leaves with <codeph>KErrArgument</codeph> error. </p> </li>
+<li id="GUID-EFC454B5-6F99-58A3-B3ED-9983DE0C1A4E"><p>If the profile is Enabled
+and in a Registered state then the API leaves with <codeph>KErrAlreadyExists</codeph> error. </p> </li>
+<li id="GUID-6B5728C4-F42C-5208-A6E4-1AF5641A13E3"><p>If the profile is Enabled
+and in an Unregistered state then the <xref href="GUID-E72E5C9A-ADAE-346A-8EF9-DACD7D23F318.dita"><apiname>RefreshEnable</apiname></xref> API
+refreshes the connection through <xref href="GUID-2A070F4D-A35B-3505-BE86-E6C7A2F27B94.dita#GUID-2A070F4D-A35B-3505-BE86-E6C7A2F27B94/GUID-956F2ADC-40D6-3C15-949A-80789DF04550"><apiname>CSIPConnection::RefreshConnection()</apiname></xref> API.
+The profile receives notification about the active connection and it automatically
+registers again and sends <xref href="GUID-F78ECFEB-441F-3D55-9909-A3F82F738F7E.dita"><apiname>EProfileRegistered</apiname></xref> event to the
+application. </p> </li>
+</ul> </li>
+<li id="GUID-9CA4CA87-17C7-54D0-AEAF-F415DA5D934E"><p>A REGISTER request sent
+to the registrar server. </p> </li>
+<li id="GUID-FF40934C-588D-5ED6-8041-410103FB6D53"><p>The registration status
+of the profile is set to Registered. </p> </li>
+</ul> <p>The following sequence diagram shows how to enable a profile to refresh. </p> <fig id="GUID-5EF1953C-E56D-59C2-B443-F1B77DD7E73D">
+<image href="GUID-8D9FE811-3F8A-5C2A-B76A-5C0248179590_d0e336582_href.jpg" placement="inline"/>
+</fig> <p>The following code describes how to refresh enable a profile. </p> <codeblock id="GUID-1A13F3D3-C4B7-50E5-B5AF-F0CABF02758C" xml:space="preserve">//Checks if the profile is already enabled and requests the Profile Agent to refresh it.
+// If the profile is not enabled it leaves with KErrArgument.
+
+void RefreshEnableL(CSIPProfile& aSIPProfile, MSIPConnectionObserver& aObserver)
+</codeblock> </section>
+<section id="GUID-289B2BF5-AF58-5E1E-B905-F1255EFC7FEB"><title>Stopping SIP
+registration</title> <p>In a setup, where there is no registrar, the SIP stack
+tries to send REGISTER messages to the network for at least 3 minutes and
+reserves the access point usage. During these 3 minutes the client cannot
+use another WLAN access point without destroying the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref>. </p> <p>The <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API
+of the SIP stack stops all registration attempts and releases the access point.
+The <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API in the profile agent module improves
+the responsiveness of the applications using the SIP stack. It avoids situations
+where an application is waiting for the SIP stack to complete a registration
+procedure. </p> <p>To use the <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API the application
+must have Network Control capability. If the application does not have Network
+Control capability and invokes the <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API, then
+it receives <codeph>ErrPermissionDenied (-46</codeph>) error. Sending a <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API
+does not force the SIP stack to send any message to the network, instead it
+destroys the SIP transaction for that profile and cleans all the resources
+associated with that profile. The Profile Agent also notifies all the observers
+with the event <xref href="GUID-1B01576C-59DC-3958-9631-3094ED0DB46D.dita"><apiname>EProfileForciblyDisabled</apiname></xref>. </p> <p>The following
+code describes how to forcibly disable a profile. </p> <codeblock id="GUID-3D1556EB-AD13-5640-8104-83D08BF0D207" xml:space="preserve">// With the assumption that the profile is created and is saved to the persistent storage create an instance of the SIP client
+iSip = CSIP::NewL( aAppUid );
+
+// Use CSIPProfileRegistry to get the saved profile.
+iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this);
+
+// Retrieve the profiles by the AOR
+_LIT8(KAor,"sip:user@10.192.192.43");
+TDesC8 aor(KAor);
+RPointerArray<CSIPProfile> profiles;
+
+// Find and add the matching profiles by the given AOR into the pointer array
+// Returns the set of profiles which has the provided AOR.
+iProfileRegistry->ProfilesL(KAor,profiles);
+
+// Check the profile count. Get the required profile if the count is positive non-zero.
+TInt profile_cnt = profiles.Count() ;
+iProfile = profiles[0];
+
+// If the iProfile is registered (the Registered variable must hold TRUE for iProfile)
+// Disable API returns KErrNone if the profile is disabled successfully otherwise there is a system-wide error.
+CSIPProfileRegistry::ForceDisable(*iProfile);</codeblock> </section>
</conbody></concept>
\ No newline at end of file