Purpose

Location Centre is an umbrella application from where different Applications or Location based content/services (collectively called Location based applications henceforth) can be viewed and launched. Using Location Centre, the terminal user would be able to view all the location based applications and launch them either in the standalone mode or in the chained (embedded) mode.

By using Location Centre API, the Client application can also launch Location Centre as a popup dialog. The popup dialog can be customized to show a subset of location based applications by specifying characteristics defined by the Location Centre API or specifying the actual location based applications themselves. On selecting any of these applications displayed in the popup, the corresponding application would be launched by Location Centre. The Client application also has the provision of manually obtaining a customized list of location based applications and can launch a particular application directly.

Constraints

This API is valid for all platforms running on the Symbian^ 1 or later.

Classification

This API is a Domain API.

API description

Location Centre API is a Server-Client type API that acts as a client interface to the Location Centre Server, which provides the Location Centre related services to all client applications.

Using this API, the Client application can:

  • Show a list of location based applications in a popup dialog and launch them based on user selection.

  • Show a list of location based applications in a popup dialog and return back the identifier for the user selected application.

  • Retrieve a list of location based applications registered with Location Centre.

  • Launch a particular location based application directly.

  • Listen for notifications about changes to the state of location based applications.

The logical type of this API is Virtual Machine API and Library API. The technical type if this API is Server Client API.

Overview

Location Centre is an umbrella application from where other location based applications can be viewed and launched. Location Centre API provides the provision of incorporating Location Centre and Location Centre related services into the Client applications. On launching, Location Centre is displayed as a popup dialog as displayed below.

Location Centre pop-up dialog


Location Centre pop-up dialog

When the terminal user selecting any of these location based applications, the selected item is launched either in the standalone mode or in the chained (embedded) mode.

There are two types of registered applications:

Location based applications which can be displayed in Location Centre

Applications

Applications which can be launched using the generic Application framework.

Services/Content

Location based services/content which can be provided with certain associated applications. Location Centre uses the Document handler class for interpreting these services/contents and launching them in the associated application.

Each location based application can be identified by a set of characteristics. These characteristics are either specified by these applications when they register with Location Centre (see Location Centre Registration API for details regarding registration with Location Centre) or they are assigned to them by Location Centre on registration. Each application can exhibit none, one or more of these characteristics. The characteristics are of two types:

  • System characteristics:

    The system characteristics are the characteristics assigned by Location Centre to location based applications which register with it. The registering applications are agnostic of this characteristics. The system characteristics defined are:

    System characteristics for Location applications

    ROM based applications

    This characteristic is associated with all location based applications which are installed on the ROM.

  • Application characteristics:

    The application characteristics are the characteristics published by location based applications when registering with Location Centre. These characteristics generally define the functionality of the registering application which it wants to publish to the Client applications. The characteristics attributes defined are describe in the following table:

    Application characteristics for Location applications

    Settings application

    This characteristic is associated with all location based applications which have Settings related functionality. These applications are used to configure the user's terminal or the remote server for all Location related features.

    Personal data management application

    This characteristic is associated with all location based applications which have Personal Data Management related functionality. These applications enable the user to manage his personal information either on the terminal or on a remote server.

    Navigation application

    This characteristic is associated with all location based applications which have Navigation related functionality. These applications help the terminal user to navigate from one location to another.

    Location based events application.

    This characteristic is associated with all location based applications which are related to Location based events. These applications are generally based to trigger certain events based on the terminal's current Location.

    Remote positioning application

    This characteristic is associated with all location based applications which have Remote positioning related functionality. These applications are generally involved in determining the current location of other terminals or objects.

    Network service

    This characteristic is associated with all location based applications which are related to Network services. These applications are generally involved in the exchange of Location related information and services over the network.

    Application sending location enhanced messages

    This characteristic is associated with all location based applications which are used to send Location enhanced messages.

    Application providing on device location based content

    This characteristic is associated with all location based applications which provide Location based content which is stored on the terminal.

    Application providing remote location based content

    This characteristic is associated with all location based applications which provide Location based content that is stored remotely and needs to be accessed from the remote server. These applications would need connection to the network to access the Location based content.

    Map based application

    This characteristic is associated with all location based applications which position a particular geographic location of a map.

The application characteristics and System characteristics mentioned above can be extended in the future to accommodate further additions.

These characteristics can be used by the client applications when using Location Centre API to customize the list of applications displayed in Location Centre or when retrieving the list of applications.

Use cases

The use cases of Location Centre API are:

  • Launch Location Centre pop-up dialog with location based applications.

  • Select a location based application from Location Centre pop-up dialog.

  • Get a list of all location based applications.

  • Launch a specified location based application directly.

  • Listening for notifications from Location Centre.

API class structure

Location Centre API consists of client side interface classes to Location Centre Server and data classes for applications registered with Location Centre.

Location Centre API class structure


Location Centre API class structure

Location Centre class descriptions

CLcService

CLcService class is a client side interface to Location Centre. This class allows the Client application to incorporate Location Centre and Location Centre related features into their application. Using this class, the Client application can

  • Launch Location Centre as a popup dialog with all or a subset of location based applications.

  • Select a location based application from Location Centre popup dialog.

  • Retrieve all or a subset of location based applications.

  • Launch a specified location based application directly.

  • Listening for notifications from Location Centre.

CLcLaunchParam

The class CLcLaunchParam acts as the input to Location Centre when the Client application wants to launch Location Centre with a specified set of location based application. Each such object contains an the Identifier of the application and the mode in which it must be launched if the terminal user selects it.

CLcLocationAppInfo

The class CLcLocationAppInfo holds information pertaining to location based applications. Each CLcLocationAppInfo object contains an unique identifier identifying the application, the name, icon and the characteristics of the application.

CLcLocationAppInfoArray

The class CLcLocationCentreAppInfoArray is a place holder for the all location based application information objects. The class contains a list of individual CLcLocationAppInfo objects.

TLcLocationAppFilter

The class TLcLocationAppFilter defines the filtering options that can be used for customizing Location Centre pop-up dialog. The filtering can be done based on the System characteristics and the Application characteristics defined in the Overview section.

MLcAppExitObserver

The class MLcAppExitObserver acts as the interface class definition which the Client application has to implement if it wants to be notified of the application exit event incase the location based application is launched as a chained (embedded) application.

MLcNotification

The class MLcNotification acts as the interface class definition which the Client Application has to implement if it wants to receive notifications regarding the changes in status of the location based applications.

Related APIs
  • CLcLaunchParam
  • CLcLocationAppInfo
  • CLcLocationAppInfoArray
  • CLcLocationCentreAppInfoArray
  • CLcService
  • MLcAppExitObserver
  • MLcNotification
  • TLcLocationAppFilter

Using the Location Centre API

In order to use any service from Location Centre, the Client application must first construct its own instance of the Location Centre Interface. This can be done by calling the CLcService::NewL() function which creates a Location Centre interface object on the heap. All other operations can be made on this instance. After the completion of all the desired operations, the Client application must delete the instance of the created object to free all the associated Location Centre resources.

If the Client application intends to provide a facility to the terminal user to be able to launch location based applications as a chained (embedded) application, then it must ensure that CLcService the instance is not deleted until the chained (embedded) application is closed (see use case: Launch Location Centre pop-up dialog with an application exit observer for obtaining the termination event from the chained (embedded) application) or until the destruction of the Client application itself. If this is not ensured, on deleting the CLcService object, there is a possibility that the chained (embedded) application would be closed and no callback notification is issued.

In general, since Location Centre API is a client side interface to the Location Centre server it is recommended that the Client application creates an instance of this class in its constructor and deletes it in the destructor.

Location Centre construction


Location Centre construction

class CMyLcClient : public CBase
    {
    
    // ... Member functions
    
private:
    CLcService    iLcService;
    // ... Other Data members
    };

CMyLcClient::ConstructL()
    {
    // …..
    // …..
    // Create Location Centre interface.

    iLcService = CLcService::NewL();
    // …..
    // …..
    }
    

CMyLcClient::~CMyLcClient()
    {
    // …..
    // …..
    delete iLcService
    // …..
    // …..
    }

The Client application does not require any capability to use Location centre API.

Launch Location Centre pop-up dialog

Location Centre API can be used by Client applications to launch Location Centre as a pop-up dialog. On launching Location Centre as a pop-up dialog, all the Location based applications which are currently present on the user's terminal would be displayed. The terminal user can then select any of the listed location based applications and that the corresponding application would be launched in the default mode. (The default mode for launching would be the mode with which the application has registered with Location Centre. See Location Centre Registration API for more details). When selecting an item from the displayed list, Location Centre first validates it for its registration with Location Centre and only on successful validation does it proceed with the launching.

When Location Centre is being displayed as a pop-up dialog, any changes to the list of location based applications would be automatically reflected in the pop-up and the Client application does not need to explicitly listen to the notification events (see use case: Listening for notifications for details on how to register for notifications from Location Centre).

The following example illustrates Launching Location Centre pop up dialog with all location based applications.

Launching Location Centre popup dialog


Launching Location Centre popup dialog

CMyLcClient::MyLocationCentreOperationL()
    {
    // Client operations
    // ...
    // ...
    // Launch Location Centre popup in its default configuration
    // This would launch the popup dialog with all location based applications
    // The user can select any location based application from the list and the
    // corresponding application would be launched in its default mode
    
    iLcService->LaunchLocationCentreL();
     
    // Other client operations
    // ...
    // ...
    // ...
    
    }

Launch Location Centre pop-up dialog with a filtered list of location based applications

The Client application can launch Location Centre as a pop-up dialog with a filtered list of location based applications. This can be achieved by passing the filtering options to the use case: Launch Location Centre pop-up dialog.

The filtering of applications can be based on two aspects, namely, the System Characteristics and the Application Characteristics. In addition to it, it can also specify the Launching mode for all the applications displayed in the list. This would override the default launching mode that these applications would have specified during their registration.

On invoking this use-case, Location Centre displays the requested applications in a pop-up dialog. The terminal user can then select any of the listed applications and that the corresponding application or content/service would be launched in the specified mode (in case, the Client application has not specified any mode for launching then the application would be launched in their default mode).

In the example discussed below, the Client application uses Location Centre to display all ROM based Settings related location based applications.

Launching Location Centre with a filtere...


Launching Location Centre with a filtered list of location based applications

CMyLcClient::MyLocationCentreOperationL()
    {
    // Set the filter parameters
    TLcLocationAppFilter filter;
    
    // Only ROM based applications would be used for filtering
    filter.SetSystemCharacteristic( CLcLocationAppInfo::ESysCharRomBased );
    
    // Include only those those charatceristics specified by the System characteristics filter
    filter.SetSysCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
    
    // Only Settings related applications would be used for filtering
    filter.SetApplicationCharacteristic( CLcLocationAppInfo::EAppCharSettings );
    
    // Include only those those charatceristics specified by the application characteristics filter
    filter.SetAppCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
    
    // Launch Location Centre popup with the above filter
    // This would launch the popup dialog with all ROM based Settings applications
    // The user can select any Settings application from the list and the
    // corresponding application would be launched in its default mode
    iLcService->LaunchLocationCentreL( filter );
     
    }

Launch Location Centre pop-up dialog with a specified list of location based applications

The Client application can launch Location Centre as a pop-up dialog with a specified list of location based applications. It can pass the list of applications that it wants Location Centre to display (see use case: Launch Location Centre pop-up dialog for details regarding the displaying of Location Centre pop-up dialog).

In the example discussed below, the Client application uses Location Centre to display GPS data and Landmarks application. It also specifies that GPS data must be launched in the standalone mode if the user selects it and Landmarks application in the chained (embedded) mode.

Launching Location Centre with a specifi...


Launching Location Centre with a specified list of location based applications

CMyLcClient::MyLocationCentreOperationL()
    {
    // Create the paramters array
    RPointerArray<CLcLaunchParam>    array;
    
    // Set the first item of the array to be GPS data application which needs
    // to be launched in the stand alone mode.
    CLcLaunchParam* param1 = CLcLaunchParam::NewL( KGpsDataIdentifier, CLcLocationAppInfo::EStandAloneMode );
    
    array.Append( param1 );
    
    // Set the second item of the array to be Landmarks application which needs
    // to be launched in the stand alone mode.
    CLcLaunchParam* param2 = CLcLaunchParam::NewL( KLandmarksIdentifier, CLcLocationAppInfo::EChainedMode );
    
    array.Append( param2 );
    
    // Launch Location Centre popup with the above list of location based applications
    // This would launch the popup dialog with GPS data and Landmarks application.
    iLcService->LaunchLocationCentreL( array );
    }

Launch Location Centre popup dialog without a specified list of location based applications

The Client application can launch Location Centre as a popup dialog without a specified list of location based applications. It can pass the list of applications that it does not want Location Centre to display (see use case: Launch Location Centre pop-up dialog for details regarding the displaying of Location Centre pop-up dialog).

In the example discussed below, the Client application uses Location Centre to display all location based applications other than GPS data and Landmarks application. It also specifies that these applications must be launched in the chained (embedded) mode when the terminal user selects on any of them.

Launching Location Centre without a spec...


Launching Location Centre without a specified list of location based applications

CMyLcClient::MyLocationCentreOperationL()
    {
    
    // Create the paramters array
    RArray<TPtrC>    array;
    
    // Append the GPS Data parameter object
    array.Append( KGpsDataIdentifier );
    
    // Append the Landmarks parameter object
    array.Append( KLandmarksIdentifier );
    
    // Launch Location Centre popup with the above list of location based applications
    // This would launch the popup dialog with GPS data and Landmarks application.
    iLcService->LaunchLocationCentreL( array, CLcLocationAppInfo::EStandAloneMode );
    
    }

Launch Location Centre pop-up dialog with an Application exit observer

Location Centre API provides the Client application with a provision of registering an observer to notify the exit of the selected location based application. While using use case: Launch Location Centre pop-up dialog the client application can also specify an observer. Incase, the associated application content/service is launched as a chained (embedded) application then on user exiting this application a notification would be provided to Location Centre using the observer.

In the example discussed below, the Client application uses Location Centre to display all location based applications. The class CLcMyClient inherits from MLcAppExitObserver and acts an observer to receive notifications from Location Centre for termination of the launched application. Since, the CMyLcClient listens for the termination of the launched application it is necessary that this class holds the CLcService object as a member variable and destroys it only after the application exit observer is invoked.

Launching Location Centre with an Applic...


Launching Location Centre with an Application Exit observer

class CMyLcClient : public MLcAppExitObserver
    {
    // ...
    // ...
    // CMyLcClient member functions
    // ...
    // ...
public: // Inherited from MLcAppExitObserver
    void HandleChainedLocationAppExitL( TInt aReason );

private:
    // .. 
    // Other data members
    // ..
    CLcService    iLcService;
    }

void CMyLcClient::ConstructL()
    {
    iLcService = CLcService::NewL();
    }

CMyLcClient::~CMyLcClient()
    {
    // ...
    // Delete other variables.
    // ...

    delete iLcService;
    }

void CMyLcClient::HandleChainedLocationAppExitL( TInt aReason )
    {
    // Handle Application exit operations
    }

CMyLcClient::MyLocationCentreOperationL()
    {
    
    // Launch Location Centre popup in its default configuration
    // The CMyLcClient also inherits from MLcAppExitObserver and passes itself as 
    // an observer for notification regarding the termination of the selected
    // Location based Applicaiton   
    // This would launch the popup dialog with all location based applications
    // The user can select any location based application from the list and the
    // corresponding application would be launched in the chained mode
    iLcService->LaunchLocationCentreL( CLcLocationAppInfo::EChainedMode, this );
     
    }
Related APIs
  • CLcMyClient
  • CLcService
  • CMyLcClient
  • MLcAppExitObserver

Select a location based application from the Location Centre pop-up dialog

The Client application can select a location based application from Location Centre popup dialog. When invoking this use-case, Location Centre displays all the available (or a filtered list of location based applications) in a pop-up dialog. The terminal user can then select any of the listed applications and the identifier corresponding to it is returned.

The terminal user can now use the selected application identifier to launch it in a particular mode directly (see use case: Launch a specified location based application directly for launching a location based application) or store it for future reference.

When Location Centre is being displayed as a pop-up dialog, any changes to the list of location based applications would be automatically reflected in the pop-up and the Client application does not need to explicitly listen to the notification events (see use case: Listening for notifications for details on how to register for notifications from Location Centre)

Select a location based application from...


Select a location based application from Location Centre

CMyLcClient::MyLocationCentreOperationL()
    {    
    // Place holder for the selected location based application
    TPtrC    identifer;
    
    // Launch Location Centre popup in its default configuration
    // This would launch the popup dialog with all location based applications
    // The user can select any location based application from the list and the
    // corresponding application's identifier would be returned to the caller.
    identifier.Set( iLcService->SelectLocationApplicationL());
    
    // The client can now operate on the identifier
    }

Select a location based application from a filtered list of location based applications

The Client application can select a location based application as specified in use case: Select a location based application from the Location Centre popup dialog. But instead of displaying all applications the Client application can configure Location Centre to display only a subset of the registered applications. The filtering can be imposed in the same manner as described in use case: Launch Location Centre pop-up dialog with a filtered list of location based applications.

In the example discussed below, the Client application uses Location Centre to select a location based application from all ROM based Settings related location based applications.

CMyLcClient::MyLocationCentreOperationL()
    {
    
    // Set the filter parameters
    TLcLocationAppFilter filter;
    
    // Only ROM based applications would be used for filtering
    filter.SetSystemCharacteristic( CLcLocationAppInfo::ESysCharRomBased );
    
    // Include only those those charatceristics specified by the System characteristics filter
    filter.SetSysCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
    
    // Only Settings related applications would be used for filtering
    filter.SetApplicationCharacteristic( CLcLocationAppInfo::EAppCharSettings );
    
    // Include only those those charatceristics specified by the application characteristics filter
    filter.SetAppCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
    
    // Place holder for the selected location based application
    TPtrC    identifer;
    
    // Launch Location Centre popup with the above filter
    // This would launch the popup dialog with all ROM based Settings related location based applications
    // The user can select any location based application from the list and the
    // corresponding application's identifier would be returned to the caller.
    identifier.Set( iLcService->SelectLocationApplicationL( filter ));
    
    // The client can now operate on the identifier
    }

Get a list of all location based applications

The Client application can obtain a list of all location based applications that are currently registered and not-absent. This is the default behavior which the Client Application would experience when the retrieval function is invoked without any customizing. On invoking this use-case, Location Centre returns back a list of the available location based applications.

The Client application can use this functionality either in the synchronous mode or in the asynchronous mode. The Client application when using this function in the asynchronous mode must use an Active object and not use User::WaitForRequest( ).

Retrieving a list of all location based...


Retrieving a list of all location based applications synchronously

CMyLcClient::MyLocationCentreOperationL()
    {
    
    CLcLocationAppInfoArray* locArray = NULL;
    
    // Get all the location based applications which as currently present on the mobile terminal
    locArray = iLcService->GetLocationApplicationsL();
    
    // Assume ownership of the App info array 
    CleanupStack::PushL( locArray );
    
    // ...
    // ...
    // Array Operations
    // ...
    // ...
    
    // Pop and Destroy the Application information array
    CleanupStack::PopAndDestroy( locArray );
    }

Retrieving a list of all location based...


Retrieving a list of all location based applications asynchronously

class CMyLcClient : public CActive
    {
public:
    // ...
    // Other member functions
    // ...

public: // Ineherited from CActive
    void RunL();

    void DoCanel();

private:
    // ...
    // Other data members
    // ...
    
    CLcService                   iLcService;

    CLcLocationAppInfoArray*     iAppInfoArray;
    };

void CMyLcClient::RunL()
    {
    if( iStatus.Int() == KErrNone )
        {
        // Now the iAppInfoArray is updated with the latest list from Location Centre.

        // ...
        // ...
        // Array Operations
        // ...
        // ...
        }
    }

CMyLcClient::MyLocationCentreOperationL( CLcService&       aLcService )
    {
    
    // Get all the location based applications which as currently present on the mobile terminal
    iLcService->GetLocationApplicationsL( iStatus, iAppInfoArray );
    SetActive();
    }

Get a filtered list of location based applications

The Client application can obtain a filtered list of all location based applications that are currently registered and not-absent. On invoking this use-case, Location Centre returns back a list of the available applications which satisfy the filtering criterion. The filtering can be imposed in the same manner as described in use case: Launch Location Centre pop-up dialog with a filtered list of location based applications. The Client application can use this functionality either in the synchronous mode or in the asynchronous mode.

Since, the list of applications is returned to the Client application in this Use case, any changes to the list of location based applications would not be communicated implicitly to the Client application. On the occurrence of such an event, the list maintained by the Client application would be stale. Its the responsibility of the Client application to listen for such notifications by registering an observer to Location Centre and re-fetch the list as and when the notifications are received.

In the example discussed below, the Client application uses Location Centre to retrieve all ROM based Settings related location based applications.

The following code snippet explains the synchronous mode of retrieving all ROM based Settings related location based applications.

CMyLcClient::MyLocationCentreOperationL()
    {
    
    // Set the filter parameters
    TLcLocationAppFilter filter;
    
    // Only ROM based applications would be used for filtering
    filter.SetSystemCharacteristic( CLcLocationAppInfo::ESysCharRomBased );
    
    // Include only those those charatceristics specified by the System characteristics filter
    filter.SetSysCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
    
    // Only Settings related applications would be used for filtering
    filter.SetApplicationCharacteristic( CLcLocationAppInfo::EAppCharSettings );
    
    // Include only those those charatceristics specified by the application characteristics filter
    filter.SetAppCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
    
    CLcLocationAppInfoArray* locArray = NULL;
    
    // Get all the location based applications which as currently present on the mobile terminal
    locArray = iLcService->GetLocationApplicationsL( &filter );
    
    // Assume ownership of the App info array 
    CleanupStack::PushL( locArray );
    
    // ...
    // ...
    // Array Operations
    // ...
    // ...
    
    // Pop and Destroy Location Centre interface and the Application information array
    CleanupStack::PopAndDestroy( locArray );
    }

The following code snippet explains the asynchronous mode of retrieving all ROM based Settings related location based applications.

class CMyLcClient : public CActive
    {
public:
    // ...
    // Other member functions
    // ...

public: // Ineherited from CActive
    void RunL();

    void DoCanel();

private:
    // ...
    // Other data members
    // ...
    
    CLcService                   iLcService;

    CLcLocationAppInfoArray*     iAppInfoArray;
    };

void CMyLcClient::RunL()
    {
    if( iStatus.Int() == KErrNone )
        {
        // Now the iAppInfoArray is updated with the latest list from Location Centre.

        // ...
        // ...
        // Array Operations
        // ...
        // ...
        }
    }

CMyLcClient::MyLocationCentreOperationL()
    {
    
    // Set the filter parameters
    TLcLocationAppFilter filter;
    
    // Only ROM based applications would be used for filtering
    filter.SetSystemCharacteristic( CLcLocationAppInfo::ESysCharRomBased );
    
    // Include only those those charatceristics specified by the System characteristics filter
    filter.SetSysCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
    
    // Only Settings related applications would be used for filtering
    filter.SetApplicationCharacteristic( CLcLocationAppInfo::EAppCharSettings );
    
    // Include only those those charatceristics specified by the application characteristics filter
    filter.SetAppCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
    

    // Get all the location based applications which as currently present on the mobile terminal
    iLcService->GetLocationApplicationsL( iStatus, &filter, iAppInfoArray );
    SetActive();
    }

Launch a specified location based application directly

The Client application can launch a specified location based application in the desired mode directly. The application that is to be launched is identified by a Unique identifier which is specified by the Application or Content/Service when it registers with Location Centre. See Location Centre Registration API for details regarding the registration procedure.

Location Centre first validates whether the application corresponding to the identifier is currently registered with itself and on successful validation, it launches the corresponding location based application. The Client application can also specify the mode in which the applications must be launched.

In the example discussed below, the Client application uses Location Centre to launch Landmarks application in the standalone mode.

Launching a specified location based app...


Launching a specified location based application directly

CMyLcClient::MyLocationCentreOperationL()
    {    
    // Launch Landmarks application in the Stand alone mode
    iLcService->LaunchLocationApplicationL( KLandmarksIdentifier, CLcLocationAppInfo::EStandAloneMode );
    }

Listening for notifications

The Client application can register for receiving notification of changes in the state of the location based applications. The changes in states can occur in the following contexts:

  • When a new application registers into Location Centre. In this case, the application would be immediately available for all Location Centre operations.

  • When an already registered application de-registers. In this case, the application will be removed from Location Centre. Hence, it would not be available for any further Location Centre operations.

  • When a location based application is present on a removable media (like Memory card) and the media is removed. In this case, for all practical purposes the application behaves as in the previous context. The difference being that the application does not get removed from Location Centre but is marked as an Absent application. When the removable media is reinserted, the application immediately becomes available for all Location Centre operations.

  • When an removable media containing an Absent application is reinserted. In this case, the application would be immediately available for all Location Centre operations.

  • When Location Centre server terminates prematurely. In this case, no further notification would be issued and all further operations on Location Centre would fail.

The Client application can listen to notifications by setting the Notification observer to Location Centre. In case it want to stop listening for notifications, it can remove the observer.

Listening for notifications


Listening for notifications

class CMyLcClient : public MLcNotification
    {
    // ...
    // ...
    // CMyLcClient member functions
    // ...
    // ...
public: // Inherited from MLcNotification
    void LcStatusChangedL( TInt aErrorCode );

private:
    // ...
    // Data members
    // ...

    CLcService*    iLcService;
    }

void CMyLocClient::LcStatusChangedL( TInt aErrorCode )
    {
    // Handle Location centre status changed operations
    // Generally this means that the previous information obtained from LC
    // stands stale. For eg. If the client application had fetched a list
    // of location based applications before the status change event was 
    // called then possibly, the list is now stale and the Client has to
    // re-fetch the list.
    }

CMyLcClient::MyLocationCentreOperationL()
    {
    // Register for notification
    // CMyLcClient is inherited from MLcNotification. Hence, it acts as the 
    // observer to Location Centre where it communicates changes in states to
    // location based applications
    iLcService-> StartNotifyL( *this );
    }

Error handling

Location Centre API uses the standard error reporting mechanism. In case of irrecoverable error, panics are used. In all other conditions, errors are reported using return codes and leaves.

The following table gives the summarization of all the error codes used in Location Centre API

Location Centre API error codes

KErrInUse

If there is an outstanding request present on Location Centre.

KErrNotFound

If there is no location based application corresponding to the filter parameters or identifier passed to Location Centre API.

KErrServerTerminated

If there is a premature termination of an outstanding request. This might generally be due to the termination of the Location Centre server. On occurrence of this error, any further requests to Location Centre would also fail with the same error code.

KErrNotSupported

If the requested operation is not supported by Location Centre. For e.g. this might occur when a Client application which does not have a UI context requests for launching the Location Centre pop-up dialog.

The following table summarizes the panic codes defined by Location Centre API. All Panics would be generated with a Panic category: LocationCentre

Location Centre API panic codes

0 ELcInvalidIndex Code with which Location Centre panics when the Client application has requested for a Location Application information object from an index which does not exit.
Related APIs
  • KErrInUse
  • KErrNotFound
  • KErrNotSupported
  • KErrServerTerminated

Memory overhead

Each location based application is identified by a Location Application Information object. On an average considering that, the identifier for an application is 256 characters long (considering UTF-8 format this would be 512 bytes), the display name being 64 characters long (128 bytes) and including the memory for the icon object and the flags, the memory consumption would be around 1K bytes for each object.

When the Client application is using Location Centre API for retrieving the list of location based applications then the memory overhead is dependent on the number of application informations that are returned. Since, the ownership of the list is transferred back to the Client application it is advised that they should destroy them as soon as they are not needed in order to release unused heap memory.

When the Client application is using Location Centre API for displaying Location Centre as a popup then in addition to fetching the list of location based applications some additional memory is also required for displaying the list in a popup dialog.

Extensions to the API

The list of characteristics (i.e. both System and Application characteristics) and the type of location based applications can be extended in future.

Limitations of the API

There are no known limitations in the usage of this API.

Related APIs
  • CLcService
  • CLcService::NewL()

Glossary

Abbreviations

API Application Programming Interface

UID

Unique Identifier.

URL

Universal Resource Locator.

Definitions

Location Centre Location Centre is an umbrella application from where different location based applications can be viewed and launched.

Location based applications

All components which can register into Location Centre are collectively referred to as location based applications.

Absent applications

Applications which are registered with Location but not physical present on the mobile terminal's file system. This generally occurs when a registered application is present on a removable drive and the corresponding drive has been removed. On reinsertion of the drive, such applications would automatically become non-absent or present. In such a case, the user of the Location Centre API would be able to use these applications without any reregistration.

References

Location Centre Registration API