<?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_d0e342598_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&amp; aUid, MSIPObserver&amp; 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-&gt;CreateL( typeInfo );

    // Set the values in the newly created profile.
    TUint32 iapId(11);
    aProfile-&gt;SetParameter(KSIPAccessPointId,iapId);
    
            _LIT8(aor,"sip:user@192.168.0.35");
    aProfile-&gt;SetParameter(KSIPUserAor,aor);
 
// Save the profile
    iManagedProfileRegistry-&gt;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_d0e342733_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&lt;CSIPProfile&gt; 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-&gt;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-&gt;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&lt;CSIPProfile&gt; 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-&gt;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-&gt;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&amp; 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-&gt;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&lt;CSIPProfile&gt; 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-&gt;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&lt;CSIPProfile&gt; profiles;

// Profiles matching a given AOR are returned in the array.
iProfileRegistry-&gt;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_d0e343048_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&amp; aSIPProfile, MSIPConnectionObserver&amp; 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&lt;CSIPProfile&gt; 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-&gt;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>