Class RSystemAgent

RSystemAgent

Support

Supported from 6.0

Description

The standard client handle to the System Agent.

This is the standard interface between clients and the System Agent.

Those who need to access information and to be notified of changes to state variables maintained by the System Agent, use this class.

Note that after construction, RSystemAgentBase::Connect() must be called before using any of the services provided by this class.

Derivation

RHandleBase Handle to an object RSessionBase Client-side handle to a session with a server RSystemAgent The standard client handle to the System Agent RSystemAgentBase Base class for client handles to the System Agent

Defined in RSystemAgent:
GetState(), GetStates(), NotifyEventCancel(), NotifyOnAnyEvent(), NotifyOnCondition(), NotifyOnEvent(), RSystemAgent(), SetEventBufferEnabled()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

Inherited from RSessionBase:
Attach(), CreateSession(), EAutoAttach, EExplicitAttach, Send(), SendReceive(), SetRetry(), Share(), TAttachMode

Inherited from RSystemAgentBase:
Connect(), Version()

See also:

• RSystemAgentBase::Connect()
• CArrayFixFlat

RSystemAgent();

Description

Constructs an uninitialised instance.

TInt GetState(TUid aUid);

Description

Gets the value of the state variable identified by the specified UID.

Parameters

TUid aUid The UID identifying the state variable.

Return value

TInt The state variable, if successful; otherwise one of the system wide error codes; specifically, KErrNotFound, if the state variable cannot be found.

Notes:

• State variables are never negative.

TInt GetStates(const CArrayFixFlat<TUid>& aUids, CArrayFixFlat<TInt>& aStates);

Description

Gets the values of an array of state variables identified by the specified UIDs.

Parameters

const CArrayFixFlat<TUid>& aUids An array of UIDs identifying the state variables. CArrayFixFlat<TInt>& aStates On return, an array of state variables corresponding to the UIDs.

Return value

TInt KErrNone, if successful;KErrArgument, if the array of UIDs is empty; otherwise, one of the other system-wide error codes.

See also:

• TUid

void SetEventBufferEnabled(TBool aEnabled, TTimeIntervalSeconds aExpireTime);

Description

Enables or disables event buffering, explicitly specifying the expiry time. Events are only buffered if there is no outstanding notification request.

Disabling causes any events in the buffer to be deleted.

Parameters

TBool aEnabled ETrue, if event buffering is to be enabled. EFalse, if event buffering is to be disabled. TTimeIntervalSeconds aExpireTime The expiry time. All events are deleted from the buffer if a time interval greater than this occurs between events.

void SetEventBufferEnabled(TBool aEnabled);

Description

Enables or disables event buffering. Events are only buffered if there is no outstanding notification request.

There is a default expiry time of 10 seconds. All events are deleted from the buffer if a time interval greater than this occurs between events.

Disabling causes any events in the buffer to be deleted.

Parameters

TBool aEnabled ETrue, if event buffering is to be enabled. EFalse, if event buffering is to be disabled.

void NotifyOnEvent(TSysAgentEvent& aEvent);

Description

Requests notification of a change to a specific state variable.

Parameters

TSysAgentEvent& aEvent Encapsulates the notification request. Before calling the function, the UID identifying the state variable must be set into this object. When the notification request completes, the request status, TRequestStatus, encapsulated by this object, indicates the success or failure of the request. In particular, if an outstanding request is cancelled by a call to NotifyEventCancel(), then the request completes with a KErrCancel.

See also:

• TSysAgentEvent::Uid()
• TSysAgentEvent::SetUid()
• TSysAgentEvent::SetRequestStatus()
• TRequestStatus
• RSystemAgent::NotifyEventCancel()

void NotifyOnAnyEvent(TSysAgentEvent& aEvent);

Description

Requests notification of a change to any state variable.

Parameters

TSysAgentEvent& aEvent Encapsulates the notification request. When the notification request completes, the request status, TRequestStatus, encapsulated by this object, indicates the success or failure of the request. In particular, if an outstanding request is cancelled by a call toNotifyEventCancel(), then the request completes with aKErrCancel. On successful completion of the request, contains the UID of the state variable that changed and the value of that variable.

TInt NotifyOnCondition(CArrayFixFlat<TSysAgentCondition>& aConditions, TRequestStatus& aStatus);

Description

Requests notification when all of the specified conditions have been met.

Parameters

CArrayFixFlat<TSysAgentCondition>& aConditions An array of conditions to be met before the notification request can complete. TRequestStatus& aStatus The request status. On request completion, contains:KErrNone, if the request completes successfully;KErrCancel, if the outstanding request is cancelled by call to NotifyEventCancel(); otherwise, one of the other system-wide error codes.

Return value

TInt KErrNone, if successful;KErrArgument, if the array of conditions is empty; otherwise, one of the other system-wide error codes.

See also:

• TSysAgentCondition

void NotifyEventCancel();

Description

Cancels an outstanding request for notification.

An outstanding request completes withKErrCancel.