diff -r 000000000000 -r 9cfd9a3ee49c networkprotocolmodules/suplprotocolmodule/HostSettingsApi/src/lbshostsettings.cpp --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/networkprotocolmodules/suplprotocolmodule/HostSettingsApi/src/lbshostsettings.cpp Tue Feb 02 01:50:39 2010 +0200 @@ -0,0 +1,444 @@ +// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// Implementation of the LBS Host Settings Interface +// +// + +/** + @file + @publishedPartner + @deprecated +*/ + + +#include + +#include +#include "lbshostsettingsimpl.h" + +//============================================================================= +// MLbsHostSettingsStoreObserver +//============================================================================= + +/** +Provides the version of the observer interface. This can be used +by the host settings storage library to determine the functionality +supported by the client application. + +@return Version of the observer interface. +*/ +EXPORT_C TVersion MLbsHostSettingsStoreObserver::Version() const + { + return TVersion(0, 0, 0); + } + + +/** +Should not be used. Provides for future expansion of the observer interface. +*/ +EXPORT_C TAny* MLbsHostSettingsStoreObserver::ExtendedInterface + ( + TInt /*aFunctionNumber*/, + TAny* /*aPtr1*/, + TAny* /*aPtr2*/ + ) + { + return NULL; + } + + +//============================================================================= +// CLbsHostSettingsBase +// CLbsHostSettingsStore::ConstructL() is defined in the impl.cpp file, in +// order to transparently provide multiple implementations +//============================================================================= + +/** +Default constructor for the settings store. +*/ +CLbsHostSettingsStore::CLbsHostSettingsStore() + { + } + + +/** +Creates a new connection to the host settings stored for the specified settings store ID. +Each ID defines + +@param aStoreId Specifies the host settings store to open. The value specifies a settings store +for a specific protocol, for example SUPL. + +@return An Instance of the storage class. The calling application becomes the +owner of the returned instance and is responsible its cleanup. +*/ +EXPORT_C CLbsHostSettingsStore* CLbsHostSettingsStore::NewL(TLbsHostStoreId aStoreId) + { + CLbsHostSettingsStore* newStore = new (ELeave) CLbsHostSettingsStore(); + CleanupStack::PushL(newStore); + newStore->ConstructL(aStoreId, NULL); + CleanupStack::Pop(newStore); + return newStore; + } + +/** +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. + +@param aStoreId Specifies the host settings store to open. +@param aObserver The observer receives notifications of updates to +the host settings store specified by aStoreId. + +@return A storage class instance. The calling application becomes the +owner of the returned instance and is responsible its cleanup. +*/ +EXPORT_C CLbsHostSettingsStore* CLbsHostSettingsStore::NewL(TLbsHostStoreId aStoreId, MLbsHostSettingsStoreObserver& aObserver) + { + CLbsHostSettingsStore* newStore = new (ELeave) CLbsHostSettingsStore(); + CleanupStack::PushL(newStore); + newStore->ConstructL(aStoreId, &aObserver); + CleanupStack::Pop(newStore); + return newStore; + } + +/** +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. + +@param aSettingsId Specifies the ID of the host setting that should be retrieved. +@param aSettings On a successful return, contains the settings for host specified by +aSettingsId. + +@return 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. + +@see TLbsHostSettingsBase::HostSettingsId() +@see TLbsHostSettingsSupl +@see MLbsHostSettingsStoreObserver +*/ +EXPORT_C TInt CLbsHostSettingsStore::GetHostSettings(TLbsHostSettingsId aSettingsId,TLbsHostSettingsBase& aSettings) const + { + return iSettingsStore->GetHostSettings(aSettingsId, aSettings); + } + + +/** +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 KErrNone if successful. A negative (error) if it is not possible +reset the client view of the data store. + +@see GetNextHostSettings() +@see GetNextHostSettingsByCreator() +*/ +EXPORT_C TInt CLbsHostSettingsStore::RewindHostSettings() + { + return iSettingsStore->RewindHostSettings(); + } + + +/** +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. + +@param aSettings On a successful return, contains the details of the +next host contained in the data store. + +@param aSettingsId On a successful return, contains the ID of the +next host contained in the data store. + +@return 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. + +@see NumHosts() +@see TLbsHostSettingsSupl +@see MLbsHostSettingsStoreObserver +@see NewL() +*/ +EXPORT_C TInt CLbsHostSettingsStore::GetNextHostSettings(TLbsHostSettingsBase& aSettings, TLbsHostSettingsId& aSettingsId + ) + { + return iSettingsStore->GetNextHostSettings(aSettings, 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. + +@param aCreatorId Specifies the creator ID to be searched for. + +@param aSettings On a successful return, contains the details of the +next host contained in the data store with the specified Creator ID. + +@param aSettingsId On a successful return, contains the ID of the +next host contained in the data store with the specified Creator ID. + +@return 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. + +@see NumHosts() +@see TLbsHostSettingsSupl +@see MLbsHostSettingsStoreObserver +@see NewL() +*/ +EXPORT_C TInt CLbsHostSettingsStore::GetNextHostSettingsByCreator(TLbsHostCreatorId aCreatorId, TLbsHostSettingsBase& aSettings, TLbsHostSettingsId& aSettingsId) + { + return iSettingsStore->GetNextHostSettingsByCreator(aCreatorId, aSettings, aSettingsId); + } + +/** + +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. + +@param aSettingsId Specifies the ID of the host settings to overwrite. +@param aSettings Supplied by the caller and contains the updated configuration +parameters for the specified host. + +@return 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 +@capability NetworkServices +@capability Location +@see GetHostSettings() +@see TLbsHostSettingsSupl() +*/ +EXPORT_C TInt CLbsHostSettingsStore::UpdateHostSettings(TLbsHostSettingsId aSettingsId, const TLbsHostSettingsBase& aSettings) + { + return iSettingsStore->UpdateHostSettings(aSettingsId, aSettings); + } + +/** + +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. + +@param aSettingsId Indicates which host setting to delete. + +@return KErrNone when the host settings specified by aHostIndex has been deleted. +A negative (error) value when there has been a problem removing the specified settings. +KErrNotFound when the specified host ID is invalid or the associated host setting has already been deleted. + +@capability WriteDeviceData +@see NumHosts() +@see GetHostSettings() +*/ +EXPORT_C TInt CLbsHostSettingsStore::DeleteHostSettings(TLbsHostSettingsId aSettingsId) + { + return iSettingsStore->DeleteHostSettings(aSettingsId); + } + +/** +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. + +@param aSettings On a successful return, contains the details of the default host. + +@return KErrNone when the default host settings ID has been retrieved. +@return A negative (error) value is returned when it is not possible to obtain the +active host. +@return KErrNotFound is returned if there is no currently defined active host. +@return KErrNotFound is also returned when there are no actual host settings +defined. +@return KErrArgument If the class type of parameter aSettings is incompatible +with data types used by the data store. + +@see SetDefaultHostSettings +*/ +EXPORT_C TInt CLbsHostSettingsStore::GetDefaultHostSettings(TLbsHostSettingsBase& aSettings) const + { + TLbsHostSettingsId discardedId; + return iSettingsStore->GetDefaultHostSettings(aSettings, discardedId); + } + +/** +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. + +@param aSettings On a successful return, contains the details of the default host. +@param aSettingsId On a successful return, contains the ID of the default host. + +@return KErrNone when the default host settings ID has been retrieved. +@return A negative (error) value is returned when it is not possible to obtain the +active host. +@return KErrNotFound is returned if there is no currently defined active host. +@return KErrNotFound is also returned when there are no actual host settings +defined. +@return KErrArgument If the class type of parameter aSettings is incompatible +with data types used by the data store. + +@see SetDefaultHostSettings +*/ +EXPORT_C TInt CLbsHostSettingsStore::GetDefaultHostSettings(TLbsHostSettingsBase& aSettings, TLbsHostSettingsId& aSettingsId) const + { + return iSettingsStore->GetDefaultHostSettings(aSettings, 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. + +@param aSettingsId Specifies the ID of the host to use as the default. + +@return KErrNone if the default host has been successfully updated. +A negative (error) value if it is not possible to set the active +host to that specified by aHostIndex. KErrNotFound if the specified +host ID is invalid or the associated host setting has been deleted. + +@capability WriteDeviceData +@capability NetworkServices +@capability Location +@see GetDefaultHostSettings() +*/ +EXPORT_C TInt CLbsHostSettingsStore::SetDefaultHostSettings(TLbsHostSettingsId aSettingsId) + { + return iSettingsStore->SetDefaultHostSettings(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. + +@param aSettings Supplied by the caller and contains the various configuration +parameters for the specified host. + +@param aCreatorId Specifies which application type has created the entry. +This is used to distinguish between network and user provision entries. + +@param aSettingsId Returned parameter that contains the ID of +the newly created host entry in the data store. + +@return 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 +@see GetHostSettings() +@see SetDefaultHost() +@see DefaultHostIndex() +*/ + +EXPORT_C TInt CLbsHostSettingsStore::CreateHostSettings(const TLbsHostSettingsBase& aSettings,TLbsHostCreatorId aCreatorId,TLbsHostSettingsId& aSettingsId) + { + return iSettingsStore->CreateHostSettings(aSettings, aCreatorId, aSettingsId); + } + +