2 title: Binder events guide
5 Signaling agents are services that send events to any clients that
6 are subscribed to receive it.
7 The sent events carry any data.
9 To have a good understanding of how to:
11 - write a signaling agent.
12 - actions of subscribing.
13 - actions of unsubscribing.
14 - actions of producing.
15 - actions of sending and receiving.
17 Events must be described and explained.
21 The basis of a signaling agent is shown in the following figure:
23 ![scenario of using events](pictures/signaling-basis.svg)
25 This figure shows the main role of the signaling framework for the events
28 For people not familiar with the framework, a signaling agent and
29 a “binding” are similar.
31 ### Subscribing and unsubscribing
33 - Subscribing is the action that makes a client able to receive
34 data from a signaling agent.
38 1. Create resources for generating the data.
39 2. Deliver the data to the client.
41 These two aspects are not handled by the same piece of software.
43 1. Generating the data is the responsibility of the developer of the signaling agent
44 2. Delivering the data is handled by the framework.
46 When a client subscribes for data, the agent must:
48 1. Check that the subscription request is correct.
49 2. Establish the computation chain of the required data (if not already done).
50 3. Create a named event for the computed data (if not already done).
51 4. Ask the framework to establish the subscription to the event for the request.
52 5. Optionally give indications about the event in the reply to the client.
54 The first two steps do not involve the framework.
55 They are linked to the business logic of the binding.
56 The request can be any description of the requested data
57 and the computing stream can be of any nature,
58 this is specific to the binding.
60 As said before, the framework uses and integrates **libsystemd** and its event
62 Within the framework, **libsystemd** is the standard API/library for
63 bindings expecting to setup and handle I/O, timer or signal events.
65 Steps 3 and 4 are bound to the framework.
67 The agent must create an object for handling the propagation of produced
69 That object is called “event” in the framework.
70 An event has a name that allows clients to distinguish it from other
73 Events are created using the ***afb\_api\_make\_event*** function
74 that takes the api that creates the event and the name of the event.
78 event = afb_api_make_event(api, name);
81 Once created, the event can be used either to push data to its
82 subscribers or to broadcast data to any listener.
84 The event must be used to establish the subscription for the requesting
86 This is done using the ***afb\_req\_subscribe*** function
87 that takes the current request object and event and associates them
92 rc = afb_req_subscribe(req, event);
95 When successful, this function make the connection between the event and
96 the client that emitted the request.
97 The client becomes a subscriber of the event until it unsubscribes or disconnects.
98 The ***afb\_req\_subscribe*** function will fail:
100 - if the client connection is weak.
101 - if the request comes from a HTTP link.
103 To receive signals, the client must be connected.
105 The AGL framework allows connections using WebSocket.
107 The name of the event is either a well known name or an ad hoc name
108 forged for the use case.
110 Let's see a basic example:
112 - client A expects to receive the speed in km/h every second.
113 - client B expects the speed in mph twice a second.
115 In that case, there are two different events because it is not the same
116 unit and it is not the same frequency.
117 Having two different events allows to associate clients to the correct event.
118 But this doesn't tell any word about the name of these events.
119 The designer of the signaling agent has two options for naming:
121 1. names can be the same (“speed” for example) with sent data
122 self describing itself or having a specific tag (requiring from
123 clients awareness about requesting both kinds of speed isn't safe).
124 2. names of the event include the variations (by example:
125 “speed-km/h-1Hz” and “speed-mph-2Hz”) and, in that case, sent data
126 can self describe itself or not.
128 In both cases, the signaling agent might have to send the name of the
129 event and/or an associated tag to its client in the reply of the
131 This is part of the step 5 above.
133 The framework only uses the event (not its name) for:
139 When the requested data is already generated and the event used for
140 pushing it already exists, the signaling agent must not instantiate a
141 new processing chain and must not create a new event object for pushing
143 The signaling agent must reuse the existing chain and event.
145 Unsubscribing is made by the signaling agent on a request of its client.
146 The ***afb\_req\_unsubscribe*** function tells the framework to
147 remove the requesting client from the event's list of subscribers.
151 afb_req_unsubscribe(req, event);
154 Subscription count does not matter to the framework:
156 - Subscribing the same client several times has the same effect that subscribing only one time.
158 Thus, when unsubscribing is invoked, it becomes immediately effective.
160 #### More on naming events
162 - Within the AGL framework, a signaling agent is a binding that has an API prefix.
164 This prefix is meant to be unique and to identify the binding API.
165 The names of the events that this signaling agent creates are
166 automatically prefixed by the framework, using the API prefix of the
169 Thus, if a signaling agent of API prefix ***api*** creates an event
170 of name ***event*** and pushes data to that event, the subscribers
171 will receive an event of name ***api/event***.
173 ### Generating and pushing signals and data
175 - This of the responsibility of the designer of the signaling agent to establish the processing chain for generating events.
177 In many cases, this can be achieved using I/O or timer or signal events inserted in the main loop.
178 For this case, the AGL framework uses **libsystemd** and
179 provide a way to integrates to the main loop of this library using
180 afb\_api\_get\_event\_loop.
184 sdev = afb_api_get_event_loop(api);
185 rc = sd_event_add_io(sdev, &source, fd, EPOLLIN, myfunction, NULL);
188 In some other cases, the events are coming from D-Bus.
189 In that case, the framework also uses **libsystemd** internally to access D-Bus.
190 It provides two methods to get the available D-Bus objects, already existing and
191 bound to the main **libsystemd** event loop.
192 Use either ***afb\_api\_get\_system\_bus*** or
193 ***afb\_api\_get\_user\_bus*** to get the required instance.
194 Then use functions of **libsystemd** to handle D-Bus.
196 In some rare cases, the generation of the data requires to start a new
199 When a data is generated and ready to be pushed, the signaling agent
200 should call the function ***afb\_event\_push***.
204 rc = afb_event_push(event, JSON);
206 stop_generating(event);
207 afb_event_unref(event);
211 The function ***afb\_event\_push*** pushes json data to all the subscribers.
212 It then returns the count of subscribers.
213 When the count is zero, there is no subscriber listening for the event.
214 The example above shows that in that case, the signaling agent stops to
215 generate data for the event and tells that it doesn't use it anymore by calling
216 **afb\_event\_unref**.
218 This is one possible option.
219 Other valuable options are:
221 - do nothing and continue to generate and push the event.
222 - just stop to generate and push the data but keep the event existing.
224 ### Receiving the signals
226 Understanding what a client expects when it receives signals, events or
227 data shall be the most important topic of the designer of a signaling
229 The good point here is that because JSON[^1] is the exchange
230 format, structured data can be sent in a flexible way.
232 The good design is to allow as much as possible the client to describe
233 what is needed with the goal to optimize the processing to the
236 ### The exceptional case of wide broadcast
238 Some data or events have so much importance that they can be widely
239 broadcasted to alert any listening client.
240 Examples of such an alert are:
242 - system is entering/leaving “power safe” mode
243 - system is shutting down
244 - the car starts/stops moving
247 An event can be broadcasted using one of the two following methods:
249 - ***afb\_api\_broadcast\_event***
250 - ***afb\_event\_broadcast***
255 afb_api_broadcast_event(api, name, json);
261 event = afb_api_make_event(api, name);
263 afb_event_broadcast(event, json);
266 As for other events, the name of events broadcasted using
267 ***afb\_api\_broadcast\_event*** are automatically prefixed by
268 the framework with API prefix.
270 ## Reference of functions
272 See the [references for functions of class afb_event](3_Binder_References.md#v-FUNCTIONS-OF-CLASS-afb_event)
274 ### Function onevent (field of afbBindingExport)
276 Binding can designate an event handling function using the field **onevent**
277 of the structure **afb_binding_t**.
279 This function is called when an event is broadcasted or when an event that the
280 api subscribed to (through call or subcall mechanism) is pushed.
281 That behavior allows a service to react to an event and do what it is to do if
282 this is relevant for it.
283 (ie: car back camera detects imminent collision and broadcast it, then
284 appropriate service enable parking brake.).
288 The apis functions allow to declare event handling callbacks. These callbacks are
289 called on reception of an event matching a pattern and a receive in more that
290 the event name and its companion JSON data, a user defiend closure and the api
291 that is used to create it.