Use of buffering

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().