CLbsHostSettingsStore Class Reference

#include <lbs/lbshostsettings.h>

Link against: lbshostsettings.lib

class CLbsHostSettingsStore : public CBase

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

Detailed Description

Deprecated

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.

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

Member Function Documentation

ConstructL ( TLbsHostStoreId, MLbsHostSettingsStoreObserver * )

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

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

Parameters
aStoreId	Specifies which host settings store to utilise.
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.

See also: GetHostSettings() SetDefaultHost() DefaultHostIndex()

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

Return Value: KErrNone when a new entry was successfully created in the data store. A negative (error) value is returned when it has not been possible to create a new host settings entry in the data store. KErrArgument if the class type of parameter aSettings is incompatible with data types used by the data store or some settings have undefined values.

Capability
WriteDeviceData

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.

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

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

Parameters
aSettings	On a successful return, contains the details of the default host.
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.

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

Return Value: KErrNone when the settings for the specified host are successfully returned. A negative (error) value when it is not possible to return the stored settings for the specified host. KErrNotFound when the specified host ID is invalid or the associated host setting has been deleted. KErrArgument if the class type of parameter aSettings is incompatible for the information contained in the data store.

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.

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

Return Value: KErrNone if host settings have been found. A negative (error) value if it is not possible to return the stored settings for the specified host. KErrNotFound if there are no further host settings contained in the data store. KErrArgument if the class type of parameter aSettings is incompatible for the information 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.

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

Return Value: KErrNone if a host with the specified creator has been found and its details successfully returned. A negative (error) value if it is not possible to return the stored settings for the specified host. KErrNotFound when there are no further host settings contained in the data store with the specified creator ID. KErrArgument if the class type of parameter aSettings is incompatible for the information contained in the data store.

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
aStoreId	Specifies the host settings store to open. The value specifies a settings store for a specific protocol, for example SUPL.

Return Value: An Instance of the storage class. The calling application becomes the owner of the returned instance and is responsible its cleanup.

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
aStoreId	Specifies the host settings store to open.
aObserver	The observer receives notifications of updates to the host settings store specified by aStoreId.

Return Value: A storage class instance. The calling application becomes the owner of the returned instance and is responsible its cleanup.

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.

Return Value: KErrNone if successful. A negative (error) if it is not possible reset the client view of the data store.

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.

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

See also: GetHostSettings() TLbsHostSettingsSupl()

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

Return Value: KErrNone when the entry has been successfully updated. A negative (error) value is returned when it has not been possible to update the host settings entry. KErrNotFound if the host settings ID information specified aSettingsId is invalid or has been deleted. KErrArgument if the parameter aSettings does not contains valid settings for host. In particular, it was not obtained using the GetHostSettings() on the same data store or is of the wrong class type.

Capability
WriteDeviceData
NetworkServices
Location