Examples Showing the use of the SIP Profile API

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

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.

  1. Create a default profile that uses the CreateL() interface of CSIPManagedProfileRegistry(). CreateL() returns an object of type CSIPManagedProfile.

  2. Use SetParameter() of CSIPManagedProfile to set the value for the profile parameters.

  3. Use CSIPManagedProfileRegistry::SaveL() to save the profile when the values are set.

  4. 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:[email protected]");
    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.

  1. The profile is modified when you change the profile parameters and save the updated profile to the permanent store.

  2. When the updated profile is saved to the permanent store the application gets the event notification EProfileUpdated.

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

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

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

  2. The client must implement the callback functions defined in the MSIPProfileRegistryObserver interface to get notified when the status of the profile is changed.

  3. Create an instance of CSIPProfile using a retrieve function of the CSIPPProfileRegistry class.

  4. The profile parameters are read from the getter functions of the CSIPProfile.

  5. The client can use the profile when you enable it through CSIPProfileRegistry and leaves on failure.

  6. 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:[email protected]");
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:[email protected]");
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.

  1. 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:[email protected]" ), 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:[email protected]");
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);
Parent topic: SIP Profile API
© Nokia 2010.