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

</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">

</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">

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