Step 6: Handling Stored A-events
This step corresponds to test_agg_lib_6.
Stored A-events, as their name implies, are first stored on the device. Stored A-events are kept in the log table, and log tables are handled by the TBL library [not yet documented]. Each stored A-event is kept in the log until the AGG library has a chance to send it to the AggreGate server. Once recorded, these A-events won't be lost. Having an AggreGate server connection is not a precondition for the generation of stored A-events. The disadvantage is somewhat heavier implementation and slower event handling speed.
There will be a separate log table [not yet documented] (and a file on the flash disk) for each type of stored A-event in your application. This is because different A-event types can potentially have a different set of fields and, hence, the different storage format.
Another important point to discuss: if you come from a field like access control or IT, then you may be accustomed to a certain way of using the term "event". You probably dealt with events like "access granted", "access violation", "access denied", and so on. Each one of those is considered to be a separate "event".
With AggreGate, if it comes from the same log table, then it is the same A-event. The ACE A-event below is generated on "access granted", "access violation", etc., yet it is all the same single event called the "Access Control Event (ACE)". It is the event description that differentiates each ACE A-event instance. Keep this in mind when reviewing the code added in step 6.
The TBL library [not yet documented] is already in the project. We added it when we were creating the USER table.
Tables.xtxt now contains the ACE table. Note how there are three fields:
- The DT field for storing the date and time of the event.
- The AEL field for event the level. Stored A-events, like instant A-events, have the default event level which can be overridden. To be able to override, have a special field named AEL (A-event level) in your log table. This field must be of the byte type, with possible values from 0 to 5. Once you have the AEL field in the table, the event level for each particular event instance will come from this field.
- The DS field carrying the event description (like "access granted", "access violation", etc.). Notice how this field's size is only four characters — how can we possible fit a meaningful description in four characters?.. Read on and you will know!
Aggregate.xtxt now contains the ACE stored A-event. It "links" to the ACE table.
Call to agg_proc_data_sent() is in on_sock_data_sent() event handler.
New generate_door_event() sub is in device.tbs. We call this from on_button_pressed(). You don't have to be connected to the AggreGate server in order to be able to generate this event — that's the beauty of stored A-events. Whenever you press the MD button, one ACE event is generated. The description it carries for now is always "ACE". This is temporary — we will add real descriptions in the next step.
Notice how this procedure uses agg_stored_event_added(). You have to use it every time you add a stored A-event. It "nudges" the AGG library, i.e. tells it that there are stored events that haven't been sent to the server yet.
Notice that agg_proc_stored_events() is also called(). This is completely optional and serves to speed up the sending of the stored A-event to the AggreGate server. The AGG library already uses this procedure internally. Calling this "manually" just after doing agg_stored_event_added() may speed things up a bit, especially on big projects with heavy and complicated code.
Our sample code also makes use of callback_agg_convert_event_field(). If you put a breakpoint there you will notice that this procedure is invoked every time you generate a stored A-event. The procedure is called separately for each even't field, except the ACE field. The idea is the same as for the callback_agg_convert_setting call, which was discussed in Adding Setting A-variables: you get a chance to convert or change a field's value before sending it to the AggreGate Server. In our code we use the call to convert short event descriptions (abbreviations, really) into comprehensible lines of text!
To be able to see instances of your new event, right-click on the device in the tree and choose Monitor Related Events.