Collapse all Symbian^3 Product Developer Library

conn::RSBEClientSession Class Reference

class conn::RSBEClientSession : public RSessionBase

The client to the Secure Backup Engine

This class should be accessed only through the CSBEClient class. These two classes make up a facade pattern to protect against Binary Compatibility breaks. As large chunks of data are transferred using the global shared heap, this class owns an instantiation of CHeapWrapper that wraps access to the Global Shared Heap, providing an easier to use common interface.

Inherits from

conn::RSBEClientSession
- RSessionBase
  - RHandleBase

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

Protected Member Functions
void	PopulateLargePublicFileListL(TInt)
void	PopulateListOfDataOwnersL(TUint)
void	PopulatePublicFileListL(TUint)

Private Member Functions
	RSBEClientSession()
void	ConstructL()
TInt	GetGlobalSharedHeapHandle()
TInt	StartServer()

Inherited Functions
	RHandleBase::Attributes()const
	RHandleBase::BTraceId()const
	RHandleBase::DoExtendedClose()
	RHandleBase::Duplicate(const RThread &,TOwnerType)
	RHandleBase::FullName()const
	RHandleBase::FullName(TDes &)const
	RHandleBase::Handle()const
	RHandleBase::HandleInfo(THandleInfo *)
	RHandleBase::Name()const
	RHandleBase::NotifyDestruction(TRequestStatus &)
	RHandleBase::Open(const TFindHandleBase &,TOwnerType)
	RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
	RHandleBase::RHandleBase()
	RHandleBase::RHandleBase(TInt)
	RHandleBase::SetHandle(TInt)
	RHandleBase::SetHandleNC(TInt)
	RSessionBase::CreateSession(RServer2,const TVersion &)
	RSessionBase::CreateSession(RServer2,const TVersion &,TInt)
	RSessionBase::CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy ,TRequestStatus )
	RSessionBase::CreateSession(const TDesC &,const TVersion &)
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt)
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy ,TRequestStatus )
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
	RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)
	RSessionBase::Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)
	RSessionBase::Open(TInt,TOwnerType)
	RSessionBase::Open(TInt,const TSecurityPolicy &,TOwnerType)
	RSessionBase::Send(TInt)const
	RSessionBase::Send(TInt,const TIpcArgs &)const
	RSessionBase::SendReceive(TInt)const
	RSessionBase::SendReceive(TInt,TRequestStatus &)const
	RSessionBase::SendReceive(TInt,const TIpcArgs &)const
	RSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
	RSessionBase::SetReturnedHandle(TInt)
	RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
	RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
	RSessionBase::ShareAuto()
	RSessionBase::ShareProtected()

Inherited Enumerations
	RHandleBase:TAttributes
	RSessionBase:TAttachMode

Private Attributes
CSBECallbackHandler *	iCallbackHandler
RPointerArray< CDataOwnerInfo > *	iDataOwnersArray
RFileArray *	iFileArray
RPointerArray< CSBEFileEntry > *	iFileList
TBool *	iFinished
CHeapWrapper *	iGSHInterface
RChunk	iGlobalSharedHeap
TInt *	iTotalListCursor

Inherited Attributes
	RHandleBase::iHandle

Constructor & Destructor Documentation

RSBEClientSession()

RSBEClientSession

(

)

[private]

Class constructor.

~RSBEClientSession()

~RSBEClientSession

(

)

Class destructor.

Member Functions Documentation

AllSnapshotsSuppliedL()

void

AllSnapshotsSuppliedL

(

)

This methods informs the data owner that all snapshots have been supplied.

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

AllSnapshotsSuppliedL(TRequestStatus &)

void

AllSnapshotsSuppliedL

(

TRequestStatus &

aStatus

)

This methods informs the data owner that all snapshots have been supplied.

Parameters

TRequestStatus & aStatus

A reference to TRequestStatus

AllSystemFilesRestored()

void

AllSystemFilesRestored

(

)

Signal the Secure Backup Engine that registration files are to be parsed and Active data owners are to be started

AllSystemFilesRestoredL(TRequestStatus &)

void

AllSystemFilesRestoredL

(

TRequestStatus &

aStatus

)

Signal the Secure Backup Engine that registration files are to be parsed and Active data owners are to be started

Parameters

TRequestStatus & aStatus

A reference to TRequestStatus

Close()

void

(

)

Closes the Secure Backup Engine handle.

Connect()

TInt

Connect

(

)

Connects the handle to the Secure Backup Engine.

ConstructL()

void

ConstructL

(

)

[private]

Symbian second phase constructor

ExpectedDataSizeL(CSBGenericTransferType &)

TUint

ExpectedDataSizeL

(

CSBGenericTransferType &

aGenericTransferType

)

Get the expected total size of the data to be returned by the SBE for the purposes of calculating progress information

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

Parameters

CSBGenericTransferType & aGenericTransferType

Reference to the identifier of the data to be retrieved

GetGlobalSharedHeapHandle()

TInt

GetGlobalSharedHeapHandle

(

)

[private]

Requests the handle for the Global Anonymous Shared Heap from the server that owns it and sets the member RChunk with it.

ListOfDataOwnersL(RPointerArray< CDataOwnerInfo > &)

void

ListOfDataOwnersL

(

RPointerArray< CDataOwnerInfo > &

aDataOwners

)

Return the list of private data owners on the device that have backup registration files. If a leave does occur, then aDataOwners

Parameters

RPointerArray< CDataOwnerInfo > & aDataOwners

Pointer array holding the list of Data owners requiring backup functionality. Any items present in this array will be lost

ListOfDataOwnersL(RPointerArray< CDataOwnerInfo > &, TRequestStatus &)

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

Return the list of private data owners on the device that have backup registration files. If a leave does occur, then aDataOwners

Parameters

RPointerArray< CDataOwnerInfo > & aDataOwners	Pointer array holding the list of Data owners requiring backup functionality. Any items present in this array will be lost
TRequestStatus & aStatus	is TRequestStatus&

NewL()

RSBEClientSession *

NewL

(

)

[static]

Symbian OS constructor

PopulateLargePublicFileListL(TInt)

void

PopulateLargePublicFileListL

(

TInt

aResult

)

[protected]

Callback following the asynchronous completion of the request for the public file list

Parameters

TInt aResult

The error code returned by the engine as a result of the initial request

PopulateListOfDataOwnersL(TUint)

void

PopulateListOfDataOwnersL

(

TUint

aBufferSize

)

[protected]

Method to perform and IPC call to populate list of data owners.

Parameters

TUint aBufferSize

Size of the buffer needed to be allocated for the IPC call

PopulatePublicFileListL(TUint)

void

PopulatePublicFileListL

(

TUint

aBufferSize

)

[protected]

Method to perform and IPC call to populate list of public files.

Parameters

TUint aBufferSize

Size of the buffer needed to be allocated for the IPC call

PublicFileListL(TDriveNumber, CSBGenericDataType &, RFileArray &)

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

Get the list of public files to backup for a particular Data Owner on a particular drive

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

Parameters

TDriveNumber aDrive	The drive that the public files exist on
CSBGenericDataType & aGenericDataType	Reference to the generic data type that is being passed to the SBEngine.
RFileArray & aFiles	An empty array of file information that will be filled with details of the public files

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

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

Get the list of public files to backup for a particular Data Owner on a particular drive

Parameters

TDriveNumber aDrive	The drive that the public files exist on
CSBGenericDataType & aGenericDataType	Reference to the generic data type that is being passed to the SBEngine.
RFileArray & aFiles	An empty array of file information that will be filled with details of the public files
TRequestStatus & aStatus	A reference to TRequestStatus

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

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 *&)

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

Get the list of public files in XML format

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

Parameters

TDriveNumber aDrive	The drive to get the list for
TSecureId aSID	The SID of the data owner to get the public files for
HBufC *& aFileList	The descriptor to populate on return should be NULL

RawPublicFileListL(TDriveNumber, CSBGenericDataType &, RRestoreFileFilterArray &)

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

Get the list of public files to backup for a particular Data Owner on a particular drive for a partial restore

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

Parameters

TDriveNumber aDrive	The drive that the public files exist on
CSBGenericDataType & aGenericDataType	Reference to the generic data type that is passed to the SBEngine.
RRestoreFileFilterArray & aFileFilter	Empty array that will be filled with the files/directories to be backed up on return

RequestDataL(CSBGenericTransferType &, TRequestStatus &)

void	RequestDataL	(	CSBGenericTransferType &	aGenericTransferType,
			TRequestStatus &	aStatus
		)

Asynchronous request of the Secure Backup Engine to supply data for a particular data owner. When the supplied TRequestStatus has been completed by the server, TransferDataInfoL should be called to retrieve the requested data.

Parameters

CSBGenericTransferType & aGenericTransferType	Reference to the identifier of the data requested
TRequestStatus & aStatus	TRequestStatus object used by the server to signal the client that a response is ready

RequestDataL(CSBGenericTransferType &)

void

RequestDataL

(

CSBGenericTransferType &

aGenericTransferType

)

Synchronous request of the Secure Backup Engine to supply data for a particular data owner. When the supplied TRequestStatus has been completed by the server, TransferDataInfoL should be called to retrieve the requested data.

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

Parameters

CSBGenericTransferType & aGenericTransferType

Reference to the identifier of the data requested

SIDStatusL(RSIDStatusArray &)

void

SIDStatusL

(

RSIDStatusArray &

aSIDStatus

)

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

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

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)

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

Set the Backup and Restore mode on/off and configure the BUR options

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

Parameters

const TDriveList & aDriveList	Array of drives that are to be backed up during the operations
TBURPartType aBURType	Set the device into Full/Partial BUR or normal operation
TBackupIncType aBackupIncType	Base/Incremental backup

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

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

Set the Backup and Restore mode on/off and configure the BUR options asynchronously.

Parameters

const TDriveList & aDriveList	Array of drives that are to be backed up during the operations
TBURPartType aBURType	Set the device into Full/Partial BUR or normal operation
TBackupIncType aBackupIncType	Base/Incremental backup
TRequestStatus & aStatus	A reference to TRequestStatus

SetSIDListForPartialBURL(RSIDArray &)

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.

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

Parameters

RSIDArray & aSIDs

array of affected data owners.

StartServer()

TInt

StartServer

(

)

[private, static]

Start the server as a thread on WINS or a process on ARM.

Called by Connect when the kernel is unable to create a session with the SBE server (as its not running).

SupplyDataL(CSBGenericTransferType &, TBool)

void	SupplyDataL	(	CSBGenericTransferType &	aGenericTransferType,
			TBool	aFinished
		)

Synchronous method for signalling to the server that the client has placed an amount of data in the Global Shared Heap and

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

Parameters

CSBGenericTransferType & aGenericTransferType	Information about the data that has been transferred
TBool aFinished	ETrue indicates that additional SupplyDataL calls will be made as part of this transfer operation

SupplyDataL(CSBGenericTransferType &, TBool, TRequestStatus &)

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

Synchronous method for signalling to the server that the client has placed an amount of data in the Global Shared Heap and

leave: If a synchronous IPC call to the SBEngine returns an error code (i.e. if SBEngine leaves)

Parameters

CSBGenericTransferType & aGenericTransferType	Information about the data that has been transferred
TBool aFinished	ETrue indicates that additional SupplyDataL calls will be made as part of this transfer operation
TRequestStatus & aStatus

TransferDataAddressL()

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 CSecureBackupEngine 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 &)

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	Pointer reference that a Generic Transfer Type is allocated to
TBool & aFinished	Flag that will be set to ETrue if the data on the GSH is the last in the series

Version()

TVersion

Version

(

)

const

Returns the version of this API

Member Data Documentation

CSBECallbackHandler * iCallbackHandler

CSBECallbackHandler *

iCallbackHandler

[private]

Async callback handler for handling responses from the sbengine

RPointerArray< CDataOwnerInfo > * iDataOwnersArray

RPointerArray< CDataOwnerInfo > *

iDataOwnersArray

[private]

Pointer to the Client's Data Owners Array

RFileArray * iFileArray

RFileArray *

iFileArray

[private]

Poitner to the Client's File Array

RPointerArray< CSBEFileEntry > * iFileList

RPointerArray< CSBEFileEntry > *

iFileList

[private]

Attributes that store parameters passed into async methods

TBool * iFinished

TBool *

iFinished

[private]

CHeapWrapper * iGSHInterface

CHeapWrapper *

iGSHInterface

[private]

Pointer to a CheapWrapper object that marshalls access to the Global Shared Heap

RChunk iGlobalSharedHeap

RChunk

iGlobalSharedHeap

[private]

Handle to the Global Shared Heap

TInt * iTotalListCursor

TInt *

iTotalListCursor

[private]