Collapse all Symbian^3 Product Developer Library

conn::CSBEClient Class Reference

class conn::CSBEClient : public CBase

The client to the Secure Backup Engine. This class is for use by a Secure Backup Server. It provides backup data and receives restore data. It encapsulates some state information as backup or restore operations require a range of actions to be undertaken in the correct order.

It is loaded into the same process as the Secure Backup Server - this is the client interface of the server that is the Secure Backup Engine.

Methods that transfer large amounts of data are asynchronous (to allow the Secure Backup Engine to carry out asynchronous operations) but synchronous versions are included for the benefit of clients that cannot handle asynchronous methods. The asynchronous methods should be used if possible.

Because of the potential large size of backup data it is not copied into descriptors but is located in a transfer buffer.

When requesting backup data the asynchronous call is made and the relevant AO (whose TRequestStatus was supplied) will be activated when the data is available and the completion code will indicate success or failure. If successful, the data can be accessed by means of the GetTransferDataInfo() method and the SignalTransferDataComplete() method is used to indicate that the transfer is complete and the transfer buffer can be re-used.

When supplying snapshot data or restore data the data is copied into a transfer buffer and the asynchronous call is made. Then the relevant AO will be activated when the data has been absorbed by the Secure Backup Engine. An error completion code is supplied. The Secure Backup Server must assume that the transfer buffer is in use until the AO is completed.

During a backup operation, all snapshot data should be provided (or data owners told that they will be doing a base backup) before any data is requested. This is because providing snapshots allows data owners to calculate their data and their data sizes. We cannot provide the expected data sizes until we have received all snapshots.

Once all snapshots have been provided, the order in which backup data is requested is not constrained (except that one multi-chunk set of data must be fully retrieved before the next is requested.

During a restore operation, the Secure Backup Engine expects data in the following order:

1) Registration files

2) Hash data for signed system files.

3) System files for all required data owners.

4) Data for data owners.

Stages (1) through (3) are required in a fixed order. Once stage (4) has been reached the SBE does not impose an order between data owners and does not require that all data from a specific data owner be restored before the next one be started, i.e. it is possible to send base data to all data owners and then increments (but this is not recommended).

Inherits from

conn::CSBEClient
- CBase

Public Member Functions
	~CSBEClient()
IMPORT_C void	AllSnapshotsSuppliedL()
IMPORT_C void	AllSnapshotsSuppliedL(TRequestStatus &)
IMPORT_C void	AllSystemFilesRestored()
IMPORT_C void	AllSystemFilesRestoredL(TRequestStatus &)
IMPORT_C TUint	DataChecksum(TDriveNumber, TSecureId)
IMPORT_C TUint	ExpectedDataSizeL(CSBGenericTransferType &)
IMPORT_C void	ListOfDataOwnersL(RPointerArray< CDataOwnerInfo > &)
IMPORT_C void	ListOfDataOwnersL(RPointerArray< CDataOwnerInfo > &, TRequestStatus &)
IMPORT_C CSBEClient *	NewL()
IMPORT_C void	PublicFileListL(TDriveNumber, CSBGenericDataType &, RFileArray &)
IMPORT_C void	PublicFileListL(TDriveNumber, CSBGenericDataType &, RFileArray &, TRequestStatus &)
IMPORT_C void	PublicFileListL(TDriveNumber, CSBGenericDataType &, RPointerArray< CSBEFileEntry > &, TBool &, TInt, TInt, TRequestStatus &)
IMPORT_C void	PublicFileListXMLL(TDriveNumber, TSecureId, HBufC *&)
IMPORT_C void	RawPublicFileListL(TDriveNumber, CSBGenericDataType &, RRestoreFileFilterArray &)
IMPORT_C void	RequestDataL(CSBGenericTransferType &, TRequestStatus &)
IMPORT_C void	RequestDataL(CSBGenericTransferType &)
IMPORT_C void	SIDStatusL(RSIDStatusArray &)
IMPORT_C void	SetBURModeL(const TDriveList &, TBURPartType, TBackupIncType)
IMPORT_C void	SetBURModeL(const TDriveList &, TBURPartType, TBackupIncType, TRequestStatus &)
IMPORT_C void	SetSIDListForPartialBURL(RSIDArray &)
IMPORT_C void	SupplyDataL(CSBGenericTransferType &, TBool, TRequestStatus &)
IMPORT_C void	SupplyDataL(CSBGenericTransferType &, TBool)
IMPORT_C TPtr8 &	TransferDataAddressL()
IMPORT_C TPtrC8 &	TransferDataInfoL(CSBGenericTransferType *&, TBool &)

Private Member Functions
	CSBEClient()
void	ConstructL()

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
RSBEClientSession *	iClientSession

Constructor & Destructor Documentation

CSBEClient()

CSBEClient

(

)

[private]

Class constructor.

~CSBEClient()

IMPORT_C

~CSBEClient

(

)

Standard destructor

Member Functions Documentation

AllSnapshotsSuppliedL()

IMPORT_C void

AllSnapshotsSuppliedL

(

)

This method sets the type of backup to base for this particular data owner. The whole device may be subject to an incremental backup but a particular data owner may be subject to a base backup (if they have not been backed up previously). The reverse is not true.

This method must only be called when the device has just been put into backup mode. It must only be called once for a SID for a backup operation.

AllSnapshotsSuppliedL(TRequestStatus &)

IMPORT_C void

AllSnapshotsSuppliedL

(

TRequestStatus &

aStatus

)

This method which sets the type of backup to base for this particular data owner asynchronously. The whole device may be subject to an incremental backup but a particular data owner may be subject to a base backup (if they have not been backed up previously). The reverse is not true.

This method must only be called when the device has just been put into backup mode. It must only be called once for a SID for a backup operation.

Parameters

TRequestStatus & aStatus

is TRequestStatus&

AllSystemFilesRestored()

IMPORT_C void

AllSystemFilesRestored

(

)

This method is called when all system files have been provided to allow the Secure Backup Engine to start active data owners.

AllSystemFilesRestoredL(TRequestStatus &)

IMPORT_C void

AllSystemFilesRestoredL

(

TRequestStatus &

aStatus

)

This method is called asynchronously when all system files have been provided to allow the Secure Backup Engine to start active data owners.

Parameters

TRequestStatus & aStatus

is TRequestStatus&

ConstructL()

void

ConstructL

(

)

[private]

Construct this instance of CSBEClient

DataChecksum(TDriveNumber, TSecureId)

IMPORT_C TUint	DataChecksum	(	TDriveNumber	aDrive,
			TSecureId	aSID
		)

Get a 32-bit checksum for private data. This routine is for test purposes. It must be implemented but an invariant checksum value can be provided. Some tests may cause checksum values to be compared.

Parameters

TDriveNumber aDrive	the drive containing data being checksummed
TSecureId aSID	the data owner.

ExpectedDataSizeL(CSBGenericTransferType &)

IMPORT_C TUint

ExpectedDataSizeL

(

CSBGenericTransferType &

aGenericTransferType

)

This method returns the expected size of package data that will be supplied. The size data will be used for the purpose of tracking progess during a backup. If it is inaccurate then the user may see irregular progress but the actual backup data will not be affected so it is acceptable to return an estimated value.

This method must only be called during a backup operation. If it is called when the data owner is not ready for backup then the call will fail.

Parameters

CSBGenericTransferType & aGenericTransferType

Reference to a CSBGenericTransferType object

ListOfDataOwnersL(RPointerArray< CDataOwnerInfo > &)

IMPORT_C void

ListOfDataOwnersL

(

RPointerArray< CDataOwnerInfo > &

aDataOwners

)

Gets a list of all registered data owners. This method can be called regardless of backup or restore mode. N.B. If it is called before a restore the set may not include all data owners that are to be restored.

If the Secure Backup Engine has not parsed backup registration files then this call will trigger scanning and parsing.

Parameters

RPointerArray< CDataOwnerInfo > & aDataOwners

on return an array of information about backup data owners.

ListOfDataOwnersL(RPointerArray< CDataOwnerInfo > &, TRequestStatus &)

IMPORT_C void	ListOfDataOwnersL	(	RPointerArray< CDataOwnerInfo > &	aDataOwners,
			TRequestStatus &	aStatus
		)

Gets a list of all registered data owners asynchronously. This method can be called regardless of backup or restore mode. N.B. If it is called before a restore the set may not include all data owners that are to be restored.

If the Secure Backup Engine has not parsed backup registration files then this call will trigger scanning and parsing.

Parameters

RPointerArray< CDataOwnerInfo > & aDataOwners	on return an array of information about backup data owners.
TRequestStatus & aStatus	is TRequestStatus&

NewL()

IMPORT_C CSBEClient *

NewL

(

)

[static]

Standard creation method.

PublicFileListL(TDriveNumber, CSBGenericDataType &, RFileArray &)

IMPORT_C void	PublicFileListL	(	TDriveNumber	aDrive,
			CSBGenericDataType &	aGenericDataType,
			RFileArray &	aFiles
		)

Gets a list of actual public files associated with an SID for partial backup. This allows a client to backup only the public files associated with an SID. This method must only be called when the device is in backup mode as the set of files may not be final until then. This method takes no account of any snapshots - the full list of candidate public files is returned and it is up to the Secure Backup Server to check file attributes if an incremental backup is required.

If the Secure Backup Engine has not parsed backup registration files then this call will trigger scanning and parsing.

Parameters

TDriveNumber aDrive	the drive concerned.
CSBGenericDataType & aGenericDataType	reference to the data type.
RFileArray & aFiles	on return an array of information about files.

PublicFileListL(TDriveNumber, CSBGenericDataType &, RFileArray &, TRequestStatus &)

IMPORT_C void	PublicFileListL	(	TDriveNumber	aDrive,
			CSBGenericDataType &	aGenericDataType,
			RFileArray &	aFiles,
			TRequestStatus &	aStatus
		)

Gets a list of actual public files associated with an SID for partial backup asynchronously. This allows a client to backup only the public files associated with an SID. This method must only be called when the device is in backup mode as the set of files may not be final until then. This method takes no account of any snapshots - the full list of candidate public files is returned and it is up to the Secure Backup Server to check file attributes if an incremental backup is required.

If the Secure Backup Engine has not parsed backup registration files then this call will trigger scanning and parsing.

Parameters

TDriveNumber aDrive	the drive concerned.
CSBGenericDataType & aGenericDataType	reference to the data type.
RFileArray & aFiles	on return an array of information about files.
TRequestStatus & aStatus	is TRequestStatus&

PublicFileListL(TDriveNumber, CSBGenericDataType &, RPointerArray< CSBEFileEntry > &, TBool &, TInt, TInt, TRequestStatus &)

IMPORT_C void	PublicFileListL	(	TDriveNumber	aDrive,
			CSBGenericDataType &	aGenericDataType,
			RPointerArray< CSBEFileEntry > &	aFileList,
			TBool &	aFinished,
			TInt	aTotalListCursor,
			TInt	aMaxResponseSize,
			TRequestStatus &	aStatus
		)

This asynchronous method is used to retrieve the list of public files for the specified data owner on the specified drive. Upon completion of aStatus, the caller should check aFileList

Parameters

TDriveNumber aDrive	The drive that contains the public files being retrieved
CSBGenericDataType & aGenericDataType	The identifier for the data owner that owns the public files
RPointerArray< CSBEFileEntry > & aFileList	Upon completion of aStatus, this array will contain the list of public files returned
TBool & aFinished	Upon completion of aStatus, this flag will be set to indicate that there are more file entries available for this data owner and another call to this method should be made
TInt aTotalListCursor	Specifies the index into the complete list of public files for this data owner to start the next chunk of file entries from. The number of entries returned by a call to this method can be determined by querying the count of aFileList
TInt aMaxResponseSize	The maximum total size in bytes of externalised CSBEFileEntry objects that will be returned
TRequestStatus & aStatus	The TRequestStatus that will be completed once the engine has fully processed this request

PublicFileListXMLL(TDriveNumber, TSecureId, HBufC *&)

IMPORT_C void	PublicFileListXMLL	(	TDriveNumber	aDrive,
			TSecureId	aSID,
			HBufC *&	aFileList
		)

Gets a list of public files and directories associated with an SID for partial backup or restore. This method returns the data in the form of an XML description for compatibility with older devices.

This method can be called regardless of the backup or restore mode as it does not rely on the set of public files being final.

If the Secure Backup Engine has not parsed backup registration files then this call will trigger scanning and parsing.

Parameters

TDriveNumber aDrive	the drive concerned.
TSecureId aSID	the data owner.
HBufC *& aFileList	on return a description of the list of files and directories. Must be NULL

RawPublicFileListL(TDriveNumber, CSBGenericDataType &, RRestoreFileFilterArray &)

IMPORT_C void	RawPublicFileListL	(	TDriveNumber	aDrive,
			CSBGenericDataType &	aGenericDataType,
			RRestoreFileFilterArray &	aFileFilter
		)

Gets a list of public files and directories associated with an SID for partial restore. This method must only be called when the device is in restore mode. This method must only be called after a registration file has been supplied and parsed. Directories can be distinguished from files by a terminating slash.

During a restore operation, the client will have the archive or public files available but the Secure Backup Engine does not. Therefore, the engine cannot list the exact files. This method returns the list of files or directories that were specified in the backup registration file without further analysis and the client can use this information to filter public files for restore.

This allows a client that has taken a full backup to be selective about restore .

If the Secure Backup Engine has not parsed backup registration files then this call will trigger scanning and parsing.

Parameters

TDriveNumber aDrive	the drive concerned.
CSBGenericDataType & aGenericDataType	reference to the data type.
RRestoreFileFilterArray & aFileFilter	on return an array of names of files or directories for restore.

RequestDataL(CSBGenericTransferType &, TRequestStatus &)

IMPORT_C void	RequestDataL	(	CSBGenericTransferType &	aGenericTransferType,
			TRequestStatus &	aStatus
		)

This method requests package data from the Secure Backup Engine asynchronously. When the relevant AO completes the returned data (and information about it) can be accessed by calling TransferDataInfoL().

Some forms of backup data may be larger than can be handled in one transfer, in which case this method should be called again with the same arguments until all data is signalled as supplied.

Parameters

CSBGenericTransferType & aGenericTransferType	Reference to a CSBGenericTransferType object
TRequestStatus & aStatus	the request status of an Active Object to be completed when the data has been received

RequestDataL(CSBGenericTransferType &)

IMPORT_C void

RequestDataL

(

CSBGenericTransferType &

aGenericTransferType

)

This synchronous method requests backup data from the Secure Backup Engine. When the method returns the returned data (and information about it) can be accessed by calling TransferDataInfoL().

Some forms of backup data may be larger than can be handled in one transfer, in which case this method should be called again with the same arguments until all data is signalled as supplied.

Parameters

CSBGenericTransferType & aGenericTransferType

Reference to a CSBGenericTransferType object

SIDStatusL(RSIDStatusArray &)

IMPORT_C void

SIDStatusL

(

RSIDStatusArray &

aSIDStatus

)

Gets the status of a set of data owners. This method must only be called in backup or restore mode.

You must populate the array with the TDataOwnerAndStatus's for each secure id the client is interested in.

Parameters

RSIDStatusArray & aSIDStatus

an array of structures for information about data owners. On return the status information is filled in.

SetBURModeL(const TDriveList &, TBURPartType, TBackupIncType)

IMPORT_C void	SetBURModeL	(	const TDriveList &	aDriveList,
			TBURPartType	aBURType,
			TBackupIncType	aBackupIncType
		)

Sets B&R on or off and sets the base / increment and full / partial mode and the affected drives

Parameters

const TDriveList & aDriveList	the drives affected.
TBURPartType aBURType	is a full or partial backup or restore desired or normal operation.
TBackupIncType aBackupIncType	is a backup base or incremental (ignored for restore operations).

SetBURModeL(const TDriveList &, TBURPartType, TBackupIncType, TRequestStatus &)

IMPORT_C void	SetBURModeL	(	const TDriveList &	aDriveList,
			TBURPartType	aBURType,
			TBackupIncType	aBackupIncType,
			TRequestStatus &	aStatus
		)

Sets B&R on or off and sets the base / increment and full / partial mode and the affected drives asynchronously.

Parameters

const TDriveList & aDriveList	the drives affected.
TBURPartType aBURType	is a full or partial backup or restore desired or normal operation.
TBackupIncType aBackupIncType	is a backup base or incremental (ignored for restore operations).
TRequestStatus & aStatus	is TRequestStatus&

SetSIDListForPartialBURL(RSIDArray &)

IMPORT_C void

SetSIDListForPartialBURL

(

RSIDArray &

aSIDs

)

If a partial backup is required then this sets the list of data owners. This method must only be called when the device has just been put into backup or restore mode. It must only be called once for a backup or restore operation.

Parameters

RSIDArray & aSIDs

array of affected data owners.

SupplyDataL(CSBGenericTransferType &, TBool, TRequestStatus &)

IMPORT_C void	SupplyDataL	(	CSBGenericTransferType &	aGenericTransferType,
			TBool	aFinished,
			TRequestStatus &	aStatus
		)

This method supplies some form of package data during a backup or restore operation asynchronously.

When the relevant Active Object is completed the Secure Backup Engine has absorbed the supplied data.

Some forms of data may be larger than can be handled in one transfer, in which case this method should be called again with the same arguments until all data has been supplied.

Parameters

CSBGenericTransferType & aGenericTransferType	Reference to a CSBGenericTransferType object
TBool aFinished	ETrue if this buffer is the last one for this package uid, drive and data type
TRequestStatus & aStatus	the request status of an Active Object to be completed when the data has been transferred

SupplyDataL(CSBGenericTransferType &, TBool)

IMPORT_C void	SupplyDataL	(	CSBGenericTransferType &	aGenericTransferType,
			TBool	aFinished
		)

This synchronous method supplies some form of package data during a backup or restore operation.

When the method returns the Secure Backup Engine has absorbed the supplied data.

Some forms of data may be larger than can be handled in one transfer, in which case this method should be called again with the same arguments until all data has been supplied.

Parameters

CSBGenericTransferType & aGenericTransferType	Reference to a CSBGenericTransferType object
TBool aFinished	ETrue if this buffer is the last one for this package uid, drive and data type

TransferDataAddressL()

IMPORT_C TPtr8 &

TransferDataAddressL

(

)

Provides access to the base of the global chunk used to transfer data between the Secure Backup Engine and a Secure Backup Server. This method should be used when the Secure Backup Server is providing data to the Secure Backup Engine (either as part of a restore operation or when supplying snapshots during a backup operation.

The Secure Backup Engine only uses one global chunk at a time. It is not permissible to try to carry out multiple backup or restore operations in parallel. Normally a chunk of global heap would be protected by a mutex. In this case, all the methods of the Secure Backup Engine must be regarded as synchronous and mutually exclusive - it is not permissible to make parallel calls.

The global chunk used during a backup or restore operation may change and so the address must be requested whenever required rather than being cached.

TransferDataInfoL(CSBGenericTransferType *&, TBool &)

IMPORT_C TPtrC8 &	TransferDataInfoL	(	CSBGenericTransferType *&	aGenericTransferType,
			TBool &	aFinished
		)

Provides access to the data received from the Secure Backup Engine during a backup operation.

This method should be called after a synchronous or asynchronous request for data has completed.

Parameters

CSBGenericTransferType *& aGenericTransferType	Reference to a CSBGenericTransferType pointer. Must be NULL
TBool & aFinished	ETrue if the data is the last chunk, EFalse if there is more to request.

Member Data Documentation

RSBEClientSession * iClientSession

RSBEClientSession *

iClientSession

[private]

Pointer to the client session R class wrapped by this class