Collapse all Symbian^3 Application Developer Library

RProcessRoot Class Reference

class RProcessRoot : public RSessionBase

The client interface to the Process Rootserver. Allows e.g. the Process Reference Configurator application to configure the Process with desired modules, bindings and later resources (memory,cpu,...).

Inherits from

RProcessRoot
- RSessionBase
  - RHandleBase

Public Member Functions
IMPORT_C void	Bind ( TRequestStatus &, RootServer::TRSBindingInfo &)
IMPORT_C void	CancelBind ( RootServer::TRSSubModuleAddress &, RootServer::TRSSubModuleAddress &)
IMPORT_C void	CancelLoadModule (const CommsFW::TCFModuleName &)
IMPORT_C void	CancelUnbind ( RootServer::TRSSubModuleAddress &, RootServer::TRSSubModuleAddress &)
IMPORT_C void	CancelUnloadModule (const CommsFW::TCFModuleName &)
IMPORT_C void	Close ()
IMPORT_C TInt	Connect (const TDesC &)
IMPORT_C TInt	EnumerateBindings (const CommsFW::TCFSubModuleAddress &, RootServer::TRSIter &, RootServer::TRSBindingInfo &)
IMPORT_C TInt	EnumerateModules ( RootServer::TRSIter &, CommsFW::TCFModuleName &)
IMPORT_C TInt	EnumerateSubModules (const CommsFW::TCFModuleName &, RootServer::TRSIter &, CommsFW::TCFSubModuleName &)
IMPORT_C TInt	GetModuleInfo (const CommsFW::TCFModuleName &, RootServer::TRSModuleInfo &)
IMPORT_C void	LoadModule ( TRequestStatus &, const RootServer::TRSStartModuleParams &, const TDesC8 &)
IMPORT_C void	SendMessage ( TRequestStatus &, const CommsFW::TCFModuleName &, TInt , TDes8 &)
IMPORT_C TInt	SendMessage (const CommsFW::TCFModuleName &, TInt , TDes8 &)
IMPORT_C TInt	Shutdown ()
IMPORT_C void	Unbind ( TRequestStatus &, RootServer::TRSUnBindingInfo &)
IMPORT_C void	UnloadModule ( TRequestStatus &, const CommsFW::TCFModuleName &, RootServer::TRSUnLoadType )
IMPORT_C TVersion	Version ()

Private Member Functions
TInt	SendReceive ( TInt , const TIpcArgs &)

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 &,TRequestStatus &)const
	RSessionBase::SetReturnedHandle(TInt)
	RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
	RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
	RSessionBase::ShareAuto()
	RSessionBase::ShareProtected()

Inherited Enumerations
	RHandleBase:TAttributes
	RSessionBase:TAttachMode

Inherited Attributes
	RHandleBase::iHandle

Member Functions Documentation

Bind(TRequestStatus &, RootServer::TRSBindingInfo &)

IMPORT_C void	Bind	(	TRequestStatus &	aStatus,
			RootServer::TRSBindingInfo &	aBindInfo
		)

Binds two modules. Several types of binding are available: EHierarchical is the standard top-bottom binding in the protocol hierarchy. If this type is specified, iName1 of TRSBindingInfo is considered top-level module of the binding and iName2 is considered the bottom-level part. Also, this type of binding allows the top-level module to be a server. ECustom is a "Horizontal" binding between two SPM's. Typical use is when a SPM employs another SPM for doing some processing and communicates via the standard message queues. TRSBindingInfo

capability: NetworkControl The Security ID of the caller will be checked to ensure that this request came from the comms configurator

Parameters

TRequestStatus & aStatus	The request status used to contain completion information for the function.
RootServer::TRSBindingInfo & aBindInfo	The information regarding the binding request.

CancelBind(RootServer::TRSSubModuleAddress &, RootServer::TRSSubModuleAddress &)

IMPORT_C void	CancelBind	(	RootServer::TRSSubModuleAddress &	aName1,
			RootServer::TRSSubModuleAddress &	aName2
		)

Cancels asynchronous binding of two modules. There is no guarantee the binding is canceled. A best effort is made and the asynchronous request waiting for the module to load returns KErrCanceled on success. TRSSubModuleAddress

Parameters

RootServer::TRSSubModuleAddress & aName1	Name of module which is binding to aName2.
RootServer::TRSSubModuleAddress & aName2	Name of module which is binding to aName1.

CancelLoadModule(const CommsFW::TCFModuleName &)

IMPORT_C void

CancelLoadModule

(

const CommsFW::TCFModuleName &

aName

)

Cancels asynchronous loading of a Service Provider Module. There is no guarantee the module loading is canceled. A best effort is made and the asynchronous request waiting for the module to load returns with KErrCanceled on success. TCFModuleName

Parameters

const CommsFW::TCFModuleName & aName

Name of module which is loading.

CancelUnbind(RootServer::TRSSubModuleAddress &, RootServer::TRSSubModuleAddress &)

IMPORT_C void	CancelUnbind	(	RootServer::TRSSubModuleAddress &	aName1,
			RootServer::TRSSubModuleAddress &	aName2
		)

Cancels asynchronous unbinding of two modules. There is no guarantee the unbinding is canceled. A best effort is made and the asynchronous request waiting for the module to load returns KErrCanceled on success. TRSSubModuleAddress

Parameters

RootServer::TRSSubModuleAddress & aName1	Name of module which is unbinding from aName2.
RootServer::TRSSubModuleAddress & aName2	Name of module which is unbinding from aName1.

CancelUnloadModule(const CommsFW::TCFModuleName &)

IMPORT_C void

CancelUnloadModule

(

const CommsFW::TCFModuleName &

aName

)

Cancel asynchronous unloading of a Service Provider Module. There is no guarantee the module unloading is canceled. A best effort is made and the asynchronous request waiting for the module to load returns KErrCanceled on success. TCFModuleName

Parameters

const CommsFW::TCFModuleName & aName

Name of module which is unloading.

Close()

IMPORT_C void

(

)

Tells server that this session is being closed

Connect(const TDesC &)

IMPORT_C TInt

Connect

(

const TDesC &

aServerName

)

Use this function to open a session to the Root Server. Default number of message slots is defined in KDefaultMessageSlots. As with any server, the connection should be closed after use. RHandleBase provides the necessary Close() function, which should be called when the server session is no longer required.

Parameters

const TDesC & aServerName

EnumerateBindings(const CommsFW::TCFSubModuleAddress &, RootServer::TRSIter &, RootServer::TRSBindingInfo &)

IMPORT_C TInt	EnumerateBindings	(	const CommsFW::TCFSubModuleAddress &	aSubModuleAddr,
			RootServer::TRSIter &	aPosition,
			RootServer::TRSBindingInfo &	aBinding
		)

Gets information about the bindings on one module. The client can enumerate bindings one at a time, with the first message specifying the iReset flag (in the TRSEnumerateBindInfo struct) true, and subsequent requests for all bind infos specify this as false, in which case the Root Server will write from where it left off from the last request. TCFSubModuleAddress TRSIter TRSBindingInfo

Parameters

const CommsFW::TCFSubModuleAddress & aSubModuleAddr	The address of the SubModule in question
RootServer::TRSIter & aPosition	Position in enumeration. Correlator for the Rootserver.
RootServer::TRSBindingInfo & aBinding	On succesful return contains binding information.

EnumerateModules(RootServer::TRSIter &, CommsFW::TCFModuleName &)

IMPORT_C TInt	EnumerateModules	(	RootServer::TRSIter &	aPosition,
			CommsFW::TCFModuleName &	aModuleName
		)

Through repeated calls returns the list of names of running Service Provider Modules. Notes:

The current position in an enumeration is maintained for each client session, meaning that to perform two consecutive enumerations two RProcessRoot's must be used.
The order in which the modules are returned is undefined.
The enumeration returned is not a snapshot from the start, i.e. if modules are loaded or unloaded during the enumeration then a module could be skipped or returned twice. TRSIter TCFModuleName

Parameters

RootServer::TRSIter & aPosition	Position in enumeration.
CommsFW::TCFModuleName & aModuleName	Contains module upon successful return.

EnumerateSubModules(const CommsFW::TCFModuleName &, RootServer::TRSIter &, CommsFW::TCFSubModuleName &)

IMPORT_C TInt	EnumerateSubModules	(	const CommsFW::TCFModuleName &	aModuleName,
			RootServer::TRSIter &	aPosition,
			CommsFW::TCFSubModuleName &	aSubModuleName
		)

Returns a list of running Service Provider Modules. The client can enumerate sub-modules one at a time by providing a TCFSubModuleName. The enumerator aPosition is a correlator for Rootserver use. TCFModuleName TRSIter TCFSubModuleName

Parameters

const CommsFW::TCFModuleName & aModuleName	Name of module.
RootServer::TRSIter & aPosition	Position in enumeration, correlator for the Rootserver.
CommsFW::TCFSubModuleName & aSubModuleName	A name to be returned

GetModuleInfo(const CommsFW::TCFModuleName &, RootServer::TRSModuleInfo &)

IMPORT_C TInt	GetModuleInfo	(	const CommsFW::TCFModuleName &	aName,
			RootServer::TRSModuleInfo &	aModuleInfo
		)

Gets information about one module. TCFModuleName TRSModuleInfo

Parameters

const CommsFW::TCFModuleName & aName	Name of module to query.
RootServer::TRSModuleInfo & aModuleInfo	Information about the module state.

LoadModule(TRequestStatus &, const RootServer::TRSStartModuleParams &, const TDesC8 &)

IMPORT_C void	LoadModule	(	TRequestStatus &	aStatus,
			const RootServer::TRSStartModuleParams &	aParams,
			const TDesC8 &	aIniData
		)

Launch a new Service Provider Module. The name of the new SPM instance (aParams.iParams.iName) must be unique and must be used in any further communication concerning this SPM instance, such as binding. The contents of the initialisation data parameter (aIniData) are specific to the module. It could be empty, contain the contents of an associated INI file or contain some other data specified by the specific SPM implementation. Attempts to load a SPM with a name equal to that of an existing SPM is not possible. It is required that the DLL contains the SPM secondary UID of 0x101f7418. TRSStartModuleParams

capability: NetworkControl The Security ID of the caller will be checked to ensure that this request came from the comms configurator

Parameters

TRequestStatus & aStatus	The request status used to contain completion information for the function.
const RootServer::TRSStartModuleParams & aParams	Parameters needed to load the Provider Module.
const TDesC8 & aIniData	Module specific ini data.

SendMessage(TRequestStatus &, const CommsFW::TCFModuleName &, TInt, TDes8 &)

IMPORT_C void	SendMessage	(	TRequestStatus &	aStatus,
			const CommsFW::TCFModuleName &	aName,
			TInt	aType,
			TDes8 &	aData
		)

Sends a message to the module TCFMessageType for message/data types CNetMessage

Parameters

TRequestStatus & aStatus	The request status used to contain completion information for the function.
const CommsFW::TCFModuleName & aName	xxx
TInt aType	a type determining the type of data in aData param
TDes8 & aData	a data specific to the message and it's type given by aType. All aData is expected to be CNetMessage based serialised instance

SendMessage(const CommsFW::TCFModuleName &, TInt, TDes8 &)

IMPORT_C TInt	SendMessage	(	const CommsFW::TCFModuleName &	aName,
			TInt	aType,
			TDes8 &	aData
		)

Sends a message to the module TCFMessageType for message/data types CNetMessage

Parameters

const CommsFW::TCFModuleName & aName	xx
TInt aType	a type determining the type of data in aData param
TDes8 & aData	a data specific to the message and it's type given by aType. All aData is expected to be CNetMessage based serialised instance

SendReceive(TInt, const TIpcArgs &)

TInt	SendReceive	(	TInt	aFunction,
			const TIpcArgs &	aArgs
		)	const [private, inline]

Issues a synchronous request to the server with the specified function number and arguments.

panic: USER 72 if the function number is negative.

Parameters

TInt aFunction	The function number identifying the request.
const TIpcArgs & aArgs	A set of up to 4 arguments and their types to be passed to the server.

Shutdown()

IMPORT_C TInt

Shutdown

(

)

Shuts down the process RootServer

capability: NetworkControl The Security ID of the caller will be checked to ensure that this request came from the comms configurator

Unbind(TRequestStatus &, RootServer::TRSUnBindingInfo &)

IMPORT_C void	Unbind	(	TRequestStatus &	aStatus,
			RootServer::TRSUnBindingInfo &	aUnBindInfo
		)

Unbinds two modules. All bindings between the two modules are unbound and the states for each module are updated in the object. TRSUnBindingInfo

capability: NetworkControl The Security ID of the caller will be checked to ensure that this request came from the comms configurator

Parameters

TRequestStatus & aStatus	The request status used to contain completion information for the function.
RootServer::TRSUnBindingInfo & aUnBindInfo	Holds the unbinding info.

UnloadModule(TRequestStatus &, const CommsFW::TCFModuleName &, RootServer::TRSUnLoadType)

IMPORT_C void	UnloadModule	(	TRequestStatus &	aStatus,
			const CommsFW::TCFModuleName &	aName,
			RootServer::TRSUnLoadType	aType
		)

Unloads a Service Provider Module. TCFModuleName TRSUnLoadType

capability: NetworkControl The Security ID of the caller will be checked to ensure that this request came from the comms configurator

Parameters

TRequestStatus & aStatus	The request status used to contain completion information for the function.
const CommsFW::TCFModuleName & aName	Name of module to unload
RootServer::TRSUnLoadType aType	Type of unload (optional/graceful/ungraceful).

Version()

IMPORT_C TVersion

Version

(

)

const

Returns the client side version number. Use this function to get the version number. The version number may be incremented in future releases of the Root Server. If extra features are added in such releases, the version number may be used by application programs as a basis for assessing the capabilities of the Root Server.