1BIBLESYNC(7) Linux Programmer's Manual BIBLESYNC(7)
2
6 biblesync - multicast navigation synchronization in Bible programs
7
9 #include <biblesync.hh>
10 typedef enum_BibleSync_mode {
12 BSP_MODE_DISABLE,
13 BSP_MODE_PERSONAL,
14 BSP_MODE_SPEAKER,
15 BSP_MODE_AUDIENCE,
16 N_BSP_MODE
17 } BibleSync_mode;
18 typedef enum_BibleSync_xmit_status {
20 BSP_XMIT_OK,
21 BSP_XMIT_FAILED,
22 BSP_XMIT_NO_SOCKET,
23 BSP_XMIT_BAD_TYPE,
24 BSP_XMIT_NO_AUDIENCE_XMIT,
25 BSP_XMIT_RECEIVING,
26 N_BSP_XMIT
27 } BibleSync_xmit_status;
28 typedef void (*BibleSync_navigate)(char cmd, string speakerkey,
30 string bible, string ref, string alt,
31 string group, string domain,
32 string info, string dump);
33 Public interface:
35 BibleSync *object = new BibleSync(string application,
37 string version,
38 string user);
39 BibleSync_mode BibleSync::setMode(BibleSync_mode mode,
41 BibleSync_navigate *nav_func,
42 string passPhrase);
43 BibleSync_mode BibleSync::getMode(void);
44 string BibleSync::getVersion(void);
45 string BibleSync::getPassphrase(void);
46 BibleSync_xmit_status BibleSync::Transmit(string bible, string ref, string alt,
47 string group, string domain);
48 BibleSync_xmit_status BibleSync::Chat(string message);
49 static int BibleSync::Receive(void *object);
50 bool BibleSync::setPrivate(bool privacy);
51 void BibleSync::setBeaconCount(uint8_t count);
52 void BibleSync::setUser(string user);
53 void BibleSync::listenToSpeaker(bool listen, string speakerkey);
54
56 BibleSync is a published protocol specification by which cooperating
57 Bible programs navigate together. It is implemented as a C++ class
58 providing a small, clean interface including basic setup, take-down,
59 transmit, polled receive, and a bare few utility methods.
60 The value of BibleSync is found in several examples:
62 A single user may have multiple programs, or multiple comput‐
64 ers/devices, all of which he wishes to follow along together.
65 Similarly, a group of people working closely together, such as transla‐
67 tors or a group Bible study, can stay together as they work.
68 In an instructional motif, BibleSync takes either the active or passive
70 mode, providing for a unidirectional navigation control.
71
73 BibleSync communicates using local multicast. Three operational modes
74 are provided: Personal, Speaker, or Audience.
75 In Personal mode, BibleSync operates as a peer among peers, both send‐
77 ing and receiving navigation synchronization on the shared local multi‐
78 cast network. Applications are expected to respond appropriately to
79 navigation, and to send synchronization events of their own as the user
80 moves about his Bible.
81 In Speaker or Audience mode, BibleSync either transmits only (Speaker)
83 or receives only (Audience) navigation. The Audience is expected to
84 follow along with the Speaker's direction. The Speaker ignores incom‐
85 ing navigation; the Audience transmits no navigation.
86 The difference between Personal and Speaker/Audience is thus strictly
88 as to whether both sides of the conversation are active for each par‐
89 ticipant.
90 On startup of the protocol, BibleSync transmits a presence announce‐
92 ment, informing other communication partners of the application's par‐
93 ticipation. BibleSync makes this announcement available to the appli‐
94 cation; whether the application shows these announcements to the user
95 is the application designer's choice.
96 Thereafter, as appropriate to the operational mode selected, BibleSync
98 is tasked with polled reception of incoming navigation event packets
99 and transmission of navigation event packets on the user's part.
100 Transmitters (Personal and Speaker modes) issue availability beacons
102 every 10 seconds. Received beacons for previously-unknown Speakers are
103 handed up to the application as "new Speaker" events. These beacons
104 provide for receivers (Personal and Audience modes) to maintain a man‐
105 aged list of available Speakers. Furthermore, when a transmitter
106 ceases to issue beacons, its presence in the list of available Speakers
107 is aged out until being removed after 30 seconds of beacon silence.
108 The application is again informed as a Speaker ages out with a "dead
109 Speaker" event.
110 Default listening behavior is that the first Speaker heard via beacon
112 is marked for listening. Other transmitters claiming Speaker status
113 via beacon are initially ignored, but their presence is made known to
114 the application. This provides for the application to maintain a list
115 from which the user can select Speakers he wishes to synchronize his
116 application. It is useful for the application to provide blanket "lis‐
117 ten to all" and "listen to none" functions, as well as per-Speaker
118 selections, informing BibleSync of these choices. In any case, this
119 default "first Speaker only" policy can be overridden by the applica‐
120 tion with any other policy desired, through the use of listenToS‐
121 peaker() as the application designer requires.
122 Synchronization events include 5 data elements: The Bible abbreviation;
124 the verse reference; an alternate reference (if desired; not required)
125 which may allow the application to interpret better based on variant
126 versification; a synchronization group identifier; and the domain.
127 The group identifier is a single digit between 1 and 9. The specifica‐
129 tion is imprecise as to this parameter's use. The initial implementa‐
130 tion of BibleSync in Xiphos uses the synchronization group as an indi‐
131 cator of the tab number in its tabbed interface: Not only is the Bible
132 navigated, but the tab in which to navigate is selected.
133 The domain parameter is currently fixed as "BIBLE-VERSE". This will be
135 put to greater use in future revisions of the protocol.
136 BibleSync transmits no packet when the application leaves the conversa‐
138 tion.
139
141 Object creation
142 The application must create a single BibleSync object, identifying the
143 application's name, its version, and the user.
144 setMode
146 setMode identifies how BibleSync should behave. The application must
147 provide as well the navigation callback function by which BibleSync
148 will inform the application of incoming events; the callback makes all
149 the navigation parameters provided in event packets available to the
150 application. setMode returns the resulting mode. The application pro‐
151 vides the passphrase to be used as well; this argument defaults to ""
152 (empty string), indicating that the existing passphrase should be left
153 in place.
154 getMode
156 The application may request the current mode.
157 getVersion
159 The version string of the library itself is returned.
160 getPassphrase
162 Intended for use when preparing to enter any active mode, the applica‐
163 tion may request the current passphrase, so as to provide a default.
164 Transmit
166 The protocol requires all the indicated parameters, but all have
167 defaults in Transmit: KJV, Gen.1.1, empty alternate, 1, and BIBLE-
168 VERSE.
169 Chat
171 This is a method for transmission of casual text messages to all others
172 in the conversation. It is expected to be received by applications who
173 will display them in a suitable manner to the user.
174 Receive
176 This is a static method accessible from either C or C++. It must be
177 called with the object pointer so as to re-enter object context for the
178 private internal receiver. Receive() must be called regularly (i.e.
179 polled) as long as it continues to return TRUE. When it returns FALSE,
180 it means that the mode has changed to BSP_MODE_DISABLE, and the sched‐
181 uled polling should stop. See also the note below on polled reception.
182 setPrivate
184 In the circumstance where the user has multiple programs running on a
185 single computer and does not want his navigation broadcast outside that
186 single system, when in Personal mode, the application may also request
187 privacy. The effect is to set multicast TTL to zero, meaning that
188 packets will not go out on the wire.
189 setBeaconCount
191 Beacon transmission occurs during every Nth call to Receive(); the
192 default value is 10. This presumes the application will call Receive()
193 once per second. If the application will call Receive() less fre‐
194 quently, divide that time (say, 2 seconds) into 10 to get a value (5)
195 to use with this call. Use setBeaconCount() prior to enabling Personal
196 or Speaker mode.
197 setUser
199 If the application allows the user to set a name via settings dialog,
200 setUser() is available to re-assign the associated user name as seen by
201 others.
202 listenToSpeaker
204 Aside from default listen behavior detailed above, the application
205 specifically asks to listen or not to listen to specific Speakers. The
206 key is as provided during the notification of a new Speaker.
207
209 There are 7 values for the cmd parameter of the nav_func. In all
210 cases, the dump parameter provides the raw content of an arriving
211 packet.
212 'A'
214 Announce. A general presence message is in alt, and the individual
215 elements are also available, as overloaded use of the parameters: bible
216 contains the user; ref contains the IP address; group contains the
217 application name and version; and domain contains the device identifi‐
218 cation.
219 'N'
221 Navigation. The bible, ref, alt, group, and domain parameters are pre‐
222 sented as they arrived. info and dump are also available.
223 'S'
225 Speaker's initial recognition from beacon receipt. Overloaded parame‐
226 ters are available as for presence announcements.
227 'D'
229 Dead Speaker. speakerkey holds the UUID key of a previously-identified
230 application which is no longer a candidate for listening.
231 'C'
233 Chat. Message text is in alt and other parameters are overloaded as
234 per announce, above.
235 'M'
237 Mismatch. The incoming event packet is mismatched, either against the
238 current passphrase or for a navigation synchronization packet when
239 BibleSync is in Speaker mode. The info parameter begins with either
240 "announce" or "sync", plus the user and IP address from whom the packet
241 came. As well, in the sync case, the regular bible, ref, alt, group,
242 and domain parameters are available. In the announce case, the pres‐
243 ence message is in alt, with overloaded individual parameters as previ‐
244 ously described.
245 'E'
247 Error. This indicates network errors and malformed packets. The
248 application's nav_func is provided only the info and dump parameters.
249
251 Polled reception
252 The application must provide a means by which to poll regularly for
253 incoming packets. In Xiphos, which is built on GTK and GLib, this is
254 readily provided by mechanisms like g_timeout_add(), which sets a regu‐
255 lar interval call of the indicated function. GLib will re-schedule the
256 call as long as the called function returns TRUE. When it returns
257 FALSE, GLib un-schedules the call. Receive() adheres to this straight‐
258 forward convention. Therefore, it is imperative that every time the
259 application moves from disabled to any non-disabled mode, Receive is
260 again scheduled for polled use.
261 A 1-second poll interval is expected. Brief experience during develop‐
263 ment has shown that longer intervals lead to a perception of lag. If
264 the application designer nonetheless expects to call Receive() less
265 frequently, it is necessary to use setBeaconCount() to change the num‐
266 ber of calls to it between beacon transmissions.
267 During every Receive() call, all waiting packets are processed.
269 No datalink security
271 BibleSync is a protocol defined for a friendly environment. It offers
272 no security in its current specification, and any packet sniffer such
273 as wireshark(1) or tcpdump(8) can see the entire conversation. The
274 specification makes passing reference to future encryption, but at this
275 time none is implemented.
276 Managed Speaker lists
278 The addition of transmitter beacons was a result of initial experience
279 showing that it can be too easy for a user to mis-start BibleSync, or
280 for a malicious user to interject himself into serious work. The goal
281 of beacons is to provide a means by which, on the one hand, the user
282 can be made aware of who is attempting to be a Speaker and, on the
283 other hand, confine the set of Speakers whom the user will permit to
284 make synchronization changes in the application. The simplest use of
285 'S' new Speaker notification events is to respond with listenToS‐
286 peaker(true, speakerkey) which in effect makes BibleSync behave as
287 though there are no beacons. More serious use of 'S'/'D' is for the
288 application to manage its own sense of available Speakers, providing a
289 means by which the user can make sensible selections about how to react
290 to each Speaker's presence. BibleSync can be told to listen to legiti‐
291 mate Speakers, and to ignore interlopers, whether intended maliciously
292 or merely due to other users' inadvertent behavior.
293 Sending verse lists
295 One of the better uses of BibleSync is in sharing verse lists. Con‐
296 sider a relatively weak application, perhaps on a mobile device, and a
297 desktop-based application with strong search capability. Run searches
298 on the desktop, and send the result via BibleSync to the mobile app.
299 The ref parameter is not confined to a single reference. In normal
300 citation syntax, the verse reference may consist of semicolon-separated
301 references, comma-separated verses, and hyphen-separated ranges. Be
302 aware that the specification has a relatively short limit on packet
303 size, so that at most a few dozen references will be sent.
304 Standard reference syntax
306 It is the responsibility of the application to transmit references in
307 standard format. BibleSync neither validates nor converts the applica‐
308 tion's incoming bible, ref, and alt parameters. The specification ref‐
309 erences the BibleRef and OSIS specifications.
310
312 http://biblesyncprotocol.wikispaces.com (user "General_Public", pass‐
313 word "password"), http://semanticbible.com/bibleref/bibleref-specifica‐
314 tion.html, socket(2), setsockopt(2), select(2), recvfrom(2), sendto(2),
315 and ip(7), especially sections on IP_ADD_MEMBERSHIP, IP_MULTICAST_IF,
316 IP_MULTICAST_LOOP, and IP_MULTICAST_TTL.
317Linux 2018-04-27 BIBLESYNC(7)