Location Settings API

The availability attribute defines if a PSY is totally hidden from the system and its use through the Location Acquisition API is disabled.

The following code example shows how to hide the PSY from the PSY list and prevent its use:

// Open the storage
CPosModules* db = CPosModules::OpenL();
CleanupStack::PushL( db );

// Assuming the positioning plug-in UID is known
const TPositionModuleId id = {0x12345678};

// Disable the PSY and hide it from the list
CPosModuleUpdate* updateParams = CPosModuleUpdate::NewLC();
updateParams->SetUpdateAvailability( EFalse );
updateParams->SetUpdateVisibility( EFalse );

// Commit changes
db->UpdateModuleL( id, *updateParams );

CleanupStack::PopAndDestroy( updateParams );
CleanupStack::PopAndDestroy( db );

Changing the priority order of PSYs

The client application can retrieve and change the priority order of installed PSYs using methods from the CPosModules class. The priority of a single PSY is retrieved using CPosModules::PriorityL(). The whole priority list is returned by CPosModules::ModuleIdListL().

There are several methods to change positioning plug-in priorities:

• CPosModules::SetModulePriorityL() (two variants) allows a client to change priority of a single PSY. A change to one PSY can affect the priorities of other PSYs.

• CPosModules::SetModulePrioritiesL() allows a client to specify the required order of all the PSYs at the same time.

The following example code demonstrates how a client can upgrade a PSY to the highest priority.

void MakePluginTopmostPriorityL( TPositionModuleId aModuleId )
{
// Open the storage
CPosModules* db = CPosModules::OpenL();
CleanupStack::PushL( db );

const TInt KTopMostPriority = 0;
db->SetModulePriorityL( aModuleId, KTopMostPriority );

CleanupStack::PopAndDestroy( updateParams );
CleanupStack::PopAndDestroy( db );
}

CPosModules::SetModulePrioritiesL() allows a client to set the order of all PSYs immediately by supplying a list of plug-in IDs in the required order. Note that all the visible plug-ins must be declared in the supplied list: it is required that the list contains the same set of PSY IDs as it would be returned by CPosModules::ModuleIdListL().

Note: Invisible PSYs are not ordered, i.e. they do not have any priority. When an invisible PSY is made visible, it will be assigned a priority according to its preference (defined in Positioning Plug-In Information API) and an internal sorting algorithm of the Location Framework.

The following example shows how the client could move a PSY to the first place in priority order by specifying a whole new priority list:

void MakePluginTopmostPriority2L( TPositionModuleId aModuleId )
{
// Open the storage
CPosModules* db = CPosModules::OpenL();
CleanupStack::PushL( db );

// Get current list first
CPosModuleIdList* idList = db->ModuleIdListLC();
TInt currentPriority = idList->Find( aModuleId );
idList->MoveL( currentPriority, 0 );

// Save new order
db->SetModulePrioritiesL( *idList );

CleanupStack::PopAndDestroy( idList );
CleanupStack::PopAndDestroy( db );
}

Listening to settings change events

A client can register an observer to listen for changes in the location settings. The observer is notified when any change occurs. The observer is set by calling CPosModules::SetObserverL(). The observer must implement the MPosModulesObserver interface to receive settings change notifications. The observer can be removed by calling CPosModules::RemoveObserver().

The event information is defined by TPosModulesEvent , which contains the ID of the affected module (if the event is associated with a single module) and type of the event. Event types are defined by TPosModulesEventType.

Note: Events are reported as detected by comparing current global settings with their local copy created for the observer. This copy is created when event observer is set by CPosModules::SetObserverL(). It is updated whenever changes are detected. This means that no events will be reported to the observer if no changes have happened since the observer was set.

Many events imply changes in priority order. If the client is interested in priority order it should reload the list of PSYs by calling CPosModules::ModuleIdListL() whenever such an event is reported.

Table 2 describes possible events.

Table 2. Settings event types and their meaning.

Figure 4 shows basic steps that a client takes to listen for changes in location settings:

Figure 4. Figure 4. Listening to change events

This example shows how a client can listen for PSY events:

class CModuleEventListener : public CBase, public MPosModulesObserver
    {
    public:
        CModuleEventListener( CPosModules& aSettings );
        // Starts observing change events
        void StartObservingL();
        // Stops observing change events
        void StopObservingL();

    public: // from MPosModulesObserver
        void HandleSettingsChangeL( TPosModulesEvent aEvent );
        ...

    private:
        CPosModules& iSettings;
    };

// Constructor stores reference to CPosModules
CModuleEventListener::CModuleEventListener( CPosModules& aSettings )
: iSettings( aSettings )
    {
    }

void CMyEventListener::StartObservingL()
    {
    iSettings.SetObserverL( *this );
    }

void CMyEventListener::StopObserving()
    {
    iSettings.RemoveObserver();
    }

// Called whenever change in location settings is detected
void CMyEventListener::HandleSettingsChangeL( TPosModulesEvent aEvent )
    {
    switch ( aEvent.iType )
        {
        case EPosModulesEventModuleInstalled:
            // new PSY installed, add to UI
            break;
        case EPosModulesEventModuleRemoved:
            // remove PSY from UI
            break;
        case EPosModulesEventPrioritiesChanged:
            // reload PSY list and update UI
            break;
        case EPosModulesEventCostChanged:
            // check new state and update UI, if needed
            break;
        case EPosModulesEventAvailabilityChanged:
            // check new state and update UI, if needed
            break;
        case EPosModulesEventVisibilityChanged:
            // check new state and update UI, as needed
            break;
        case EPosModulesEventUnspecified:
        default:
            // reload PSY list and update UI, many changes happened
            break;
        }
    }