Using the System Agent interface

The interface to System Agent is designed to operate within an active object environment. See also Inter process communication.

The typical usage pattern is to create an active object that owns a TSysAgentEvent.

For example:

class CMyInboxObserver : public CActive
    {
    ...
    void StartL();
    void ConstructL();
    ...
private :
    RSystemAgent iSysAgent;
    TSysAgentEvent iSysAgentEvent;
    }

void CMyInboxObserver::StartL()
    {
    iSysAgentEvent.SetRequestStatus(iStatus);
    iSysAgentEvent.SetUid(KUidInboxStatus);
    iSysAgent.NotifyOnEvent(iSysAgentEvent);
    SetActive();
    }

void CMyInboxObserver::ConstructL()
    {
    User::LeaveIfError(iSysAgent.Connect());
    }

Note the following points:

• The request status passed to TSysAgentEvent must be initialised.

• The event type must be initialised.

• The TSysAgentEvent object should not be declared on the stack. System Agent expects to be able to write back the state of the changed event on request completion, and there is a high probability that any variable declared on the stack will be out of scope by the time the request completes.

Once an event has occurred, a client must re-issue the RSystemAgent::NotifyOnEvent() to request notification of the next event. If an event occurs in the time between notification of an event and the issuing of another NotifyOnEvent() request, the client will miss it.

As events can follow one another in quick succession (for example, InfraRed), System Agent provides a buffering mechanism for events.

If a buffer is used and an event of interest occurs while a client is busy dealing with a previous event, then the next client request for event notification completes immediately. That event is then removed from the buffer.

As an additional option, the length of time for which events are buffered can also be specified. This correlates very approximately with the size of the buffer. Every time an event is added to the buffer, a count down timer is restarted. For example, if the timer value is 5 seconds, and events occur after 1 sec, 4 sec and 8 sec, then, if the client re-issues a request after 9 sec, the buffer will contain 3 events. If the timer expires before the next event occurs, then any remaining events are deleted from the buffer on the grounds that these events are now too old to be of use.

Note that events are only buffered if the client has no notification request outstanding. If the client has a notification request outstanding, then the request completes as usual.

Clients enable buffering through a call to RSystemAgent::SetEventBufferEnabled().