// 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 <e32base.h>

#include <lbs/lbshostsettings.h>

#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);

	}