Collapse all Symbian^3 Application Developer Library

CLbsHostSettingsStore Class Reference

class CLbsHostSettingsStore : public CBase

A class that encapsulates a host settings data store.

A host settings data store contains settings that describe the server hosts that the LBS subsystem uses. For example, for the SUPL protocol, the data store contains settings for the SUPL servers that are used for location requests (from local client applications and from the network), settings that define the authentication type that should be used between client and server and the internet access point to use for network connections. This class has methods to create a new host settings store, to create, modify and delete host settings and set the host settings that should be used as defaults. MLbsHostSettingsStoreObserver

Inherits from

CLbsHostSettingsStore
- CBase

Public Member Functions
	~CLbsHostSettingsStore ()
IMPORT_C TInt	CreateHostSettings (const TLbsHostSettingsBase &, TLbsHostCreatorId , TLbsHostSettingsId &)
IMPORT_C TInt	DeleteHostSettings ( TLbsHostSettingsId )
IMPORT_C TInt	GetDefaultHostSettings ( TLbsHostSettingsBase &)
IMPORT_C TInt	GetDefaultHostSettings ( TLbsHostSettingsBase &, TLbsHostSettingsId &)
IMPORT_C TInt	GetHostSettings ( TLbsHostSettingsId , TLbsHostSettingsBase &)
IMPORT_C TInt	GetNextHostSettings ( TLbsHostSettingsBase &, TLbsHostSettingsId &)
IMPORT_C TInt	GetNextHostSettingsByCreator ( TLbsHostCreatorId , TLbsHostSettingsBase &, TLbsHostSettingsId &)
IMPORT_C CLbsHostSettingsStore *	NewL ( TLbsHostStoreId )
IMPORT_C CLbsHostSettingsStore *	NewL ( TLbsHostStoreId , MLbsHostSettingsStoreObserver &)
IMPORT_C TInt	RewindHostSettings ()
IMPORT_C TInt	SetDefaultHostSettings ( TLbsHostSettingsId )
IMPORT_C TInt	UpdateHostSettings ( TLbsHostSettingsId , const TLbsHostSettingsBase &)

Protected Member Functions
	CLbsHostSettingsStore ()
void	ConstructL ( TLbsHostStoreId , MLbsHostSettingsStoreObserver *)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Private Attributes
CLbsHostSettingsStoreImpl *	iImplementation
MLbsHostSettingsStoreImpl *	iSettingsStore

Constructor & Destructor Documentation

CLbsHostSettingsStore()

CLbsHostSettingsStore

(

)

[protected]

Default constructor for the settings store.

~CLbsHostSettingsStore()

IMPORT_C

~CLbsHostSettingsStore

(

)

Closes the connection to the host settings store and disposes of all open or used resources.

Member Functions Documentation

ConstructL(TLbsHostStoreId, MLbsHostSettingsStoreObserver *)

void	ConstructL	(	TLbsHostStoreId	aStoreId,
			MLbsHostSettingsStoreObserver *	aObserver
		)	[protected]

Creates and assigns the internal resources required by the data store library.

Parameters

TLbsHostStoreId aStoreId	Specifies which host settings store to utilise.
MLbsHostSettingsStoreObserver * aObserver	If non NULL, the observer receives notifications about updates to store specified by aStoreId.

CreateHostSettings(const TLbsHostSettingsBase &, TLbsHostCreatorId, TLbsHostSettingsId &)

IMPORT_C TInt	CreateHostSettings	(	const TLbsHostSettingsBase &	aSettings,
			TLbsHostCreatorId	aCreatorId,
			TLbsHostSettingsId &	aSettingsId
		)

Creates a new host settings entry in the data store.

The index of the new entry is returned via the parameter aSettingsId.

The aSettings parameter contains the details of the new host entry. This parameter must be derived from TLbsHostSettingsBase and be compatible with entries in the data store. For SUPL related hosts, the aSettings parameter must be of type TLbsHostSettingsSupl .

Creating a new entry in the data store does not change the "default" host entry. If the application wishes to make the new entry the default host it must call SetDefaultHost() with the index of that entry.

capability: WriteDeviceData

GetHostSettings() SetDefaultHost() DefaultHostIndex()

Parameters

const TLbsHostSettingsBase & aSettings	Supplied by the caller and contains the various configuration parameters for the specified host.
TLbsHostCreatorId aCreatorId	Specifies which application type has created the entry. This is used to distinguish between network and user provision entries.
TLbsHostSettingsId & aSettingsId	Returned parameter that contains the ID of the newly created host entry in the data store.

DeleteHostSettings(TLbsHostSettingsId)

IMPORT_C TInt

DeleteHostSettings

(

TLbsHostSettingsId

aSettingsId

)

Removes the host information with the specified ID from the data store.

If the specified host is currently defined as the default host no other host automatically becomes the new default. It is the responsibility of the calling application to select a new default host. This is done using the SetDefaultHostSettings() method.

capability: WriteDeviceData

NumHosts() GetHostSettings()

Parameters

TLbsHostSettingsId aSettingsId

Indicates which host setting to delete.

GetDefaultHostSettings(TLbsHostSettingsBase &)

IMPORT_C TInt

GetDefaultHostSettings

(

TLbsHostSettingsBase &

aSettings

)

const

Retrieves the settings for the host that is currently specified as the default host.

The default host is primarily used to decide which network server should be used to service terminal initiated location requests.

The default host is only changed by calling SetDefaultHostSettings() .Adding or updating the settings for a host does not automatically make it the default.

SetDefaultHostSettings

Parameters

TLbsHostSettingsBase & aSettings

On a successful return, contains the details of the default host.

GetDefaultHostSettings(TLbsHostSettingsBase &, TLbsHostSettingsId &)

IMPORT_C TInt	GetDefaultHostSettings	(	TLbsHostSettingsBase &	aSettings,
			TLbsHostSettingsId &	aSettingsId
		)	const

Retrieves the settings for the host that is currently specified as the default host.

The default host is primarily used to decide which network server should be used to service terminal initiated location requests.

The default host is only changed by calling SetDefaultHostSettings() .Adding or updating the settings for a host does not automatically make it the default.

SetDefaultHostSettings

Parameters

TLbsHostSettingsBase & aSettings	On a successful return, contains the details of the default host.
TLbsHostSettingsId & aSettingsId	On a successful return, contains the ID of the default host.

GetHostSettings(TLbsHostSettingsId, TLbsHostSettingsBase &)

IMPORT_C TInt	GetHostSettings	(	TLbsHostSettingsId	aSettingsId,
			TLbsHostSettingsBase &	aSettings
		)	const

Retrieves the settings for a particular host settings ID.

The host settings ID is a persistent identifier that uniquely specifies a host settings within one data store. This method locates and retrieves the settings for the host indicated by the parameter aSettingsId. If the method returns succcessfully, the paramter aSettings contains the details of the specified host.

The ID for a particular host settings can be retrieved by calling TLbsHostSettingsBase::HostSettingsId() .

An application can monitor data store changes using the observer interface MLbsHostSettingsStoreObserver (passing it as parameter in CLbsHostSettingsStore::NewL() ).

The parameter aSettings must be derived from TLbsHostSettingsBase . For SUPL related host information, the aSettings parameters must be of type TLbsHostSettingsSupl .

TLbsHostSettingsBase::HostSettingsId() TLbsHostSettingsSupl MLbsHostSettingsStoreObserver

Parameters

TLbsHostSettingsId aSettingsId	Specifies the ID of the host setting that should be retrieved.
TLbsHostSettingsBase & aSettings	On a successful return, contains the settings for host specified by aSettingsId.

GetNextHostSettings(TLbsHostSettingsBase &, TLbsHostSettingsId &)

IMPORT_C TInt	GetNextHostSettings	(	TLbsHostSettingsBase &	aSettings,
			TLbsHostSettingsId &	aSettingsId
		)

Retrieves index of the next host settings following on from the specified host settings ID.

Used in conjunction with RewindHostSettings() this method allows a client application to iterate through the entire contents of the data store.

Before calling GetNextHostSettings() at the beginning of an iteration, the client application must call RewindHostSettings() . This resets the client's view of the data store. When the client subsequently calls GetNextHostSettings() the details of the first host settings will be returned.

To iterate through all host settings contained in the data store, the client application should continue to call GetNextHostSettings() until the method returns KErrNotFound. The method returns KErrNotFound if there are no further host settings contained in the data store.

NumHosts() TLbsHostSettingsSupl MLbsHostSettingsStoreObserver NewL()

Parameters

TLbsHostSettingsBase & aSettings	On a successful return, contains the details of the next host contained in the data store.
TLbsHostSettingsId & aSettingsId	On a successful return, contains the ID of the next host contained in the data store.

GetNextHostSettingsByCreator(TLbsHostCreatorId, TLbsHostSettingsBase &, TLbsHostSettingsId &)

IMPORT_C TInt	GetNextHostSettingsByCreator	(	TLbsHostCreatorId	aCreatorId,
			TLbsHostSettingsBase &	aSettings,
			TLbsHostSettingsId &	aSettingsId
		)

Retrieves the ID and details of the next host settings (provisioned by the specified creator) in the data store

When a host setting is created, the client application specifies the ID of the type of "creator". This indicates (for example) if the settings was created by a control panel application or provisioned from the network.

Used in conjunction with RewindHostSettings() , a client application can use GetNextHostSettingsByCreator() to retrieve one or more host settings based on the ID of their creator.

To iterate through all host settings contained in the data store, the client application should continue to call GetNextHostSettingsByCreator() until the method returns KErrNotFound. The method returns KErrNotFound when there are no further host settings contained in the data store.

NumHosts() TLbsHostSettingsSupl MLbsHostSettingsStoreObserver NewL()

Parameters

TLbsHostCreatorId aCreatorId	Specifies the creator ID to be searched for.
TLbsHostSettingsBase & aSettings	On a successful return, contains the details of the next host contained in the data store with the specified Creator ID.
TLbsHostSettingsId & aSettingsId	On a successful return, contains the ID of the next host contained in the data store with the specified Creator ID.

NewL(TLbsHostStoreId)

IMPORT_C CLbsHostSettingsStore *

NewL

(

TLbsHostStoreId

aStoreId

)

[static]

Creates a new connection to the host settings stored for the specified settings store ID. Each ID defines

Parameters

TLbsHostStoreId aStoreId

Specifies the host settings store to open. The value specifies a settings store for a specific protocol, for example SUPL.

NewL(TLbsHostStoreId, MLbsHostSettingsStoreObserver &)

IMPORT_C CLbsHostSettingsStore *	NewL	(	TLbsHostStoreId	aStoreId,
			MLbsHostSettingsStoreObserver &	aObserver
		)	[static]

Creates a new connection to the host settings stored for the specified protocol. By specifying an observer, the calling application will receive a notification whenever the specified store is updated by another client.

Note: The client application will not receive an update notification for changes made by itself.

Parameters

TLbsHostStoreId aStoreId	Specifies the host settings store to open.
MLbsHostSettingsStoreObserver & aObserver	The observer receives notifications of updates to the host settings store specified by aStoreId.

RewindHostSettings()

IMPORT_C TInt

RewindHostSettings

(

)

Resets the client's view of the data store.

RewindHostSettings() is used in conjunction with GetNextHostSettings() and GetNextHostSettingsByCreator() .

Before calling GetNextHostSettings() or GetNextHostSettingsByCreator() for the first time, the client application must call RewindHostSettings() . This resets the client's view of the data store. When a client subsequently calls GetNextHostSettings() or GetNextHostSettingsByCreator() the details of the first host settings will be returned.

GetNextHostSettings() GetNextHostSettingsByCreator()

SetDefaultHostSettings(TLbsHostSettingsId)

IMPORT_C TInt

SetDefaultHostSettings

(

TLbsHostSettingsId

aSettingsId

)

Changes the default host to that specified by the supplied ID.

The default host is primarily used to decide which network server should be used to service terminal initiated location requests.

capability: WriteDeviceData

capability: NetworkServices

capability: Location

GetDefaultHostSettings()

Parameters

TLbsHostSettingsId aSettingsId

Specifies the ID of the host to use as the default.

UpdateHostSettings(TLbsHostSettingsId, const TLbsHostSettingsBase &)

IMPORT_C TInt	UpdateHostSettings	(	TLbsHostSettingsId	aSettingsId,
			const TLbsHostSettingsBase &	aSettings
		)

Replaces the settings for an existing host settings entry in the data store.

Note: The data in the parameter aSettings must have been initially obtained by calling GetHostSettings() on the same data store. For SUPL related hosts, the aSettings parameters must be of type TLbsHostSettingsSupl .

Updating an entry does not change the default host for the particular data store. If the application wishes to make the updated entry the default host, it must call SetDefaultHost() with the index of that entry.

capability: WriteDeviceData

capability: NetworkServices

capability: Location

GetHostSettings() TLbsHostSettingsSupl()

Parameters

TLbsHostSettingsId aSettingsId	Specifies the ID of the host settings to overwrite.
const TLbsHostSettingsBase & aSettings	Supplied by the caller and contains the updated configuration parameters for the specified host.

Member Data Documentation

CLbsHostSettingsStoreImpl * iImplementation

CLbsHostSettingsStoreImpl *

iImplementation

[private]

In order to maintain two implementations behind one interface we are holding two different versions of the implementation. The pointer to the C class will only be used for instantiation and destruction, we shall use the pointer to the mixin for everything else.

MLbsHostSettingsStoreImpl * iSettingsStore

MLbsHostSettingsStoreImpl *

iSettingsStore

[private]