1BIBLESYNC(7)               Linux Programmer's Manual              BIBLESYNC(7)
2
3
4

NAME

6       biblesync - multicast navigation synchronization in Bible programs
7

SYNOPSIS

9       #include <biblesync.hh>
10
11       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
19       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
29       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
34       Public interface:
35
36       BibleSync *object = new BibleSync(string application,
37                                         string version,
38                                         string user);
39
40       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

DESCRIPTION

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
61       The value of BibleSync is found in several examples:
62
63       A  single  user  may  have  multiple  programs,  or  multiple   comput‐
64       ers/devices, all of which he wishes to follow along together.
65
66       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
69       In an instructional motif, BibleSync takes either the active or passive
70       mode, providing for a unidirectional navigation control.
71

BIBLESYNC ESSENTIALS

73       BibleSync  communicates using local multicast.  Three operational modes
74       are provided: Personal, Speaker, or Audience.
75
76       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
82       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
87       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
91       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
97       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
101       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
111       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
123       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
128       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
134       The domain parameter is currently fixed as "BIBLE-VERSE".  This will be
135       put to greater use in future revisions of the protocol.
136
137       BibleSync transmits no packet when the application leaves the conversa‐
138       tion.
139

PUBLIC INTERFACE

141   Object creation
142       The application must create a single BibleSync object, identifying  the
143       application's name, its version, and the user.
144
145   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
155   getMode
156       The application may request the current mode.
157
158   getVersion
159       The version string of the library itself is returned.
160
161   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
165   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
170   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
175   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
183   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
190   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
198   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
203   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

RECEIVE USE CASES

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
213   '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
220   '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
224   'S'
225       Speaker's initial recognition from beacon receipt.  Overloaded  parame‐
226       ters are available as for presence announcements.
227
228   'D'
229       Dead Speaker.  speakerkey holds the UUID key of a previously-identified
230       application which is no longer a candidate for listening.
231
232   'C'
233       Chat.  Message text is in alt and other parameters  are  overloaded  as
234       per announce, above.
235
236   '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
246   '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

NOTES

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
262       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
268       During every Receive() call, all waiting packets are processed.
269
270   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
277   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
294   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
305   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

SEE ALSO

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.
317
318
319
320Linux                             2018-04-27                      BIBLESYNC(7)
Impressum