Examples -Showing the use of the SIP Profile API

diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita --- 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 @@ - - - - - -Examples -Showing the use of the SIP Profile API -

The following sections describe how to use the SIP Profile API.

Creating a SIP profile
Modifying a SIP Profile
Enabling a SIP profile
Disabling a SIP profile
Destroying a SIP Profile
Retrieving a profile
Refreshing a SIP profile
Stopping SIP registration

Creating a -SIP profile

CSIPManagedProfileRegistry manages -the SIP profiles and provides the functions to add, update, and remove profiles -at run time.

The following steps describes how to create a SIP profile.

Create a default profile -that uses the CreateL() interface of CSIPManagedProfileRegistry(). CreateL() returns -an object of type CSIPManagedProfile.
Use SetParameter() of CSIPManagedProfile to -set the value for the profile parameters.
Use CSIPManagedProfileRegistry::SaveL() to -save the profile when the values are set.
When you call SaveL(), -wait until EProfileCreated event is reported in the observer. -When the event is received the profile is created.

- -

The following code snippet shows how to create and save a profile.

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

Modifying a -SIP Profile

The following steps describe how to modify a SIP profile.

The profile is modified -when you change the profile parameters and save the updated profile to the -permanent store.
When the updated profile -is saved to the permanent store the application gets the event notification EProfileUpdated.
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.
The profile must not -be used by another application while you update the profile. Use the CSIPManagedProfileRegistry::IsInUseL API -to check if the profile is currently in use.

Enabling a -SIP profile

The following steps describe how to enable a SIP profile.

A client of the SIP -Profile API must create a CSIPProfileRegistry object.

Note: -The client must provide an instance of the class CSIP to -create an object of the type CSIPProfileRegistry.
The client must implement -the callback functions defined in the MSIPProfileRegistryObserver interface -to get notified when the status of the profile is changed.
Create an instance of CSIPProfile using -a retrieve function of the CSIPPProfileRegistry class.
The profile parameters -are read from the getter functions of the CSIPProfile.
The client can use the -profile when you enable it through CSIPProfileRegistry and -leaves on failure.
The user must check -the profile status after the EnableL 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 MSIPProfileRegistryObserver callback -interface about the profile registration.

- -

The following code snippet shows how to enable a SIP profile.

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

Disabling a -SIP profile

The following steps describes how to disable a SIP -profile.

A client of the SIP -Profile API must create a CSIPProfileRegistry object

Note: -The client must provide an instance of the class CSIP to -create a CSIPProfileRegistry object.
The client must implement -the callback functions defined in the MSIPProfileRegistryObserver interface -to get notified with the events when the status of the profile is changed.
Use retrieve function -of the class CSIPPProfileRegistry to create an instance -of CSIPProfile.
The profile parameters -are read from the getter functions of the CSIPProfile.
Check the registration -status of the profile that uses the getter functions of CSIPProfile. -Disable the profile if it is registered.
An application gets -the notification event EProfileDeregistered if the de-registration -is successful, otherwise it leaves. The error is sent to the application through -the ProfileRegistryErrorOccurred callback function.

The following code snippet shows how to disable a SIP profile.

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

Destroying -a SIP Profile

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 sipprofiles.dat file in Epoc32\winscw\c\private\101F413C.

The -following steps describe how to destroy a SIP profile.

When the profile is -destroyed the application gets the event EProfileDestroyed.
- Registered: The removal -is two-step process, de-register the profile and remove the profile.
- De-registered : Removes -the profile from the permanent storage and the application is notified with -the event EProfileDestroyed.

The following code snippet shows how to disable a profile.

//Function leaves on failure. -CSIPManagedProfileRegistry::DestroyL(CSIPProfile& aSIPProfile); -

Retrieving -a profile

Retrieving a default profile

The following -code snippet shows how to retrieve the default profile.

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

Retrieving profiles by type

The following code -snippet shows how to retrieve profiles by type.

// 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(); -

Retrieving profiles by matching an AOR

The -following code snippet shows how to retrieve profiles by matching an AOR.

// 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(); -

Getting the registration events

The following code -snippet shows how to get the registration events for different scenarios.

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

Refreshing -a SIP profile

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 RefreshEnableL() function to:

Initiate the SIP registration -automatically.
Reduce the response -time for the SIP registration.
Improve the efficiency -of the application using the SIP stack during registration.

The RefreshEnableL 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 EProfileRegistered through -the MSIPProfileRegistryObserver.

To refresh enable -a profile, do the following steps:

Start the SIP Profile -server.
Fetch the profile that -must be refresh enabled from the SIP Profile Server.
- If the profile is not -Enabled the RefreshEnable API leaves with KErrArgument error.
- If the profile is Enabled -and in a Registered state then the API leaves with KErrAlreadyExists error.
- If the profile is Enabled -and in an Unregistered state then the RefreshEnable API -refreshes the connection through CSIPConnection::RefreshConnection() API. -The profile receives notification about the active connection and it automatically -registers again and sends EProfileRegistered event to the -application.
A REGISTER request sent -to the registrar server.
The registration status -of the profile is set to Registered.

The following sequence diagram shows how to enable a profile to refresh.

- -

The following code describes how to refresh enable a profile.

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

Stopping SIP -registration

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 RConnection.

The ForceDisable API -of the SIP stack stops all registration attempts and releases the access point. -The ForceDisable 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.

To use the ForceDisable API the application -must have Network Control capability. If the application does not have Network -Control capability and invokes the ForceDisable API, then -it receives ErrPermissionDenied (-46) error. Sending a ForceDisable 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 EProfileForciblyDisabled.

The following -code describes how to forcibly disable a profile.

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

+ + + + + +Examples +Showing the use of the SIP Profile API +

The following sections describe how to use the SIP Profile API.

Creating a SIP profile
Modifying a SIP Profile
Enabling a SIP profile
Disabling a SIP profile
Destroying a SIP Profile
Retrieving a profile
Refreshing a SIP profile
Stopping SIP registration

Creating a +SIP profile

CSIPManagedProfileRegistry manages +the SIP profiles and provides the functions to add, update, and remove profiles +at run time.

The following steps describes how to create a SIP profile.

Create a default profile +that uses the CreateL() interface of CSIPManagedProfileRegistry(). CreateL() returns +an object of type CSIPManagedProfile.
Use SetParameter() of CSIPManagedProfile to +set the value for the profile parameters.
Use CSIPManagedProfileRegistry::SaveL() to +save the profile when the values are set.
When you call SaveL(), +wait until EProfileCreated event is reported in the observer. +When the event is received the profile is created.

+ +

The following code snippet shows how to create and save a profile.

/*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. +

Modifying a +SIP Profile

The following steps describe how to modify a SIP profile.

The profile is modified +when you change the profile parameters and save the updated profile to the +permanent store.
When the updated profile +is saved to the permanent store the application gets the event notification EProfileUpdated.
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.
The profile must not +be used by another application while you update the profile. Use the CSIPManagedProfileRegistry::IsInUseL API +to check if the profile is currently in use.

Enabling a +SIP profile

The following steps describe how to enable a SIP profile.

A client of the SIP +Profile API must create a CSIPProfileRegistry object.

Note: +The client must provide an instance of the class CSIP to +create an object of the type CSIPProfileRegistry.
The client must implement +the callback functions defined in the MSIPProfileRegistryObserver interface +to get notified when the status of the profile is changed.
Create an instance of CSIPProfile using +a retrieve function of the CSIPPProfileRegistry class.
The profile parameters +are read from the getter functions of the CSIPProfile.
The client can use the +profile when you enable it through CSIPProfileRegistry and +leaves on failure.
The user must check +the profile status after the EnableL 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 MSIPProfileRegistryObserver callback +interface about the profile registration.

+ +

The following code snippet shows how to enable a SIP profile.

+/*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. +

Disabling a +SIP profile

The following steps describes how to disable a SIP +profile.

A client of the SIP +Profile API must create a CSIPProfileRegistry object

Note: +The client must provide an instance of the class CSIP to +create a CSIPProfileRegistry object.
The client must implement +the callback functions defined in the MSIPProfileRegistryObserver interface +to get notified with the events when the status of the profile is changed.
Use retrieve function +of the class CSIPPProfileRegistry to create an instance +of CSIPProfile.
The profile parameters +are read from the getter functions of the CSIPProfile.
Check the registration +status of the profile that uses the getter functions of CSIPProfile. +Disable the profile if it is registered.
An application gets +the notification event EProfileDeregistered if the de-registration +is successful, otherwise it leaves. The error is sent to the application through +the ProfileRegistryErrorOccurred callback function.

The following code snippet shows how to disable a SIP profile.

/*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) +

Destroying +a SIP Profile

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 sipprofiles.dat file in Epoc32\winscw\c\private\101F413C.

The +following steps describe how to destroy a SIP profile.

When the profile is +destroyed the application gets the event EProfileDestroyed.
- Registered: The removal +is two-step process, de-register the profile and remove the profile.
- De-registered : Removes +the profile from the permanent storage and the application is notified with +the event EProfileDestroyed.

The following code snippet shows how to disable a profile.

//Function leaves on failure. +CSIPManagedProfileRegistry::DestroyL(CSIPProfile& aSIPProfile); +

Retrieving +a profile

Retrieving a default profile

The following +code snippet shows how to retrieve the default profile.

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

Retrieving profiles by type

The following code +snippet shows how to retrieve profiles by type.

// 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(); +

Retrieving profiles by matching an AOR

The +following code snippet shows how to retrieve profiles by matching an AOR.

// 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(); +

Getting the registration events

The following code +snippet shows how to get the registration events for different scenarios.

// 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; + } +}

Refreshing +a SIP profile

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 RefreshEnableL() function to:

Initiate the SIP registration +automatically.
Reduce the response +time for the SIP registration.
Improve the efficiency +of the application using the SIP stack during registration.

The RefreshEnableL 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 EProfileRegistered through +the MSIPProfileRegistryObserver.

To refresh enable +a profile, do the following steps:

Start the SIP Profile +server.
Fetch the profile that +must be refresh enabled from the SIP Profile Server.
- If the profile is not +Enabled the RefreshEnable API leaves with KErrArgument error.
- If the profile is Enabled +and in a Registered state then the API leaves with KErrAlreadyExists error.
- If the profile is Enabled +and in an Unregistered state then the RefreshEnable API +refreshes the connection through CSIPConnection::RefreshConnection() API. +The profile receives notification about the active connection and it automatically +registers again and sends EProfileRegistered event to the +application.
A REGISTER request sent +to the registrar server.
The registration status +of the profile is set to Registered.

The following sequence diagram shows how to enable a profile to refresh.

+ +

The following code describes how to refresh enable a profile.

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

Stopping SIP +registration

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 RConnection.

The ForceDisable API +of the SIP stack stops all registration attempts and releases the access point. +The ForceDisable 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.

To use the ForceDisable API the application +must have Network Control capability. If the application does not have Network +Control capability and invokes the ForceDisable API, then +it receives ErrPermissionDenied (-46) error. Sending a ForceDisable 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 EProfileForciblyDisabled.

The following +code describes how to forcibly disable a profile.

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

\ No newline at end of file