--- name: "biblesync" section: "7" platform: "linux" package: "biblesync" version: "2.2.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/biblesync" --- # biblesync(7) multicast navigation synchronization in Bible programs ## NAME biblesync - multicast navigation synchronization in Bible programs ## SYNOPSIS **#include \** **typedef enum***\_BibleSync\_mode* **{** *BSP\_MODE\_DISABLE***,** *BSP\_MODE\_PERSONAL***,** *BSP\_MODE\_SPEAKER***,** *BSP\_MODE\_AUDIENCE***,** *N\_BSP\_MODE* **} BibleSync\_mode;** **typedef enum***\_BibleSync\_xmit\_status* **{** *BSP\_XMIT\_OK***,** *BSP\_XMIT\_FAILED***,** *BSP\_XMIT\_NO\_SOCKET***,** *BSP\_XMIT\_BAD\_TYPE***,** *BSP\_XMIT\_NO\_AUDIENCE\_XMIT***,** *BSP\_XMIT\_RECEIVING***,** *N\_BSP\_XMIT* **} BibleSync\_xmit\_status;** **typedef void (\*BibleSync\_navigate)(char** *cmd***, string** *speakerkey***,** **string** *bible***, string** *ref***, string** *alt***,** **string** *group***, string** *domain***,** **string** *info***, string** *dump***);** Public interface: **BibleSync \*object = new BibleSync(string** *application***,** **string** *version***,** **string** *user***);** **BibleSync\_mode BibleSync::setMode(BibleSync\_mode** *mode***,** **BibleSync\_navigate \****nav\_func***,** **string** *passPhrase***);** **BibleSync\_mode BibleSync::getMode(void);** **string BibleSync::getVersion(void);** **string BibleSync::getPassphrase(void);** **BibleSync\_xmit\_status BibleSync::Transmit(string** *bible***, string** *ref***, string** *alt***,** **string** *group***, string** *domain***);** **BibleSync\_xmit\_status BibleSync::Chat(string** *message***);** **static int BibleSync::Receive(void \****object***);** **bool BibleSync::setPrivate(bool** *privacy***);** **void BibleSync::setBeaconCount(uint8\_t** *count***);** **void BibleSync::setUser(string** *user***);** **void BibleSync::listenToSpeaker(bool** *listen***, string** *speakerkey***);** ## DESCRIPTION *BibleSync* is a published protocol specification by which cooperating Bible programs navigate together. It is implemented as a C++ class providing a small, clean interface including basic setup, take-down, transmit, polled receive, and a bare few utility methods. The value of *BibleSync* is found in several examples: A single user may have multiple programs, or multiple computers/devices, all of which he wishes to follow along together. Similarly, a group of people working closely together, such as translators or a group Bible study, can stay together as they work. In an instructional motif, *BibleSync* takes either the active or passive mode, providing for a unidirectional navigation control. ## BIBLESYNC ESSENTIALS *BibleSync* communicates using local multicast. Three operational modes are provided: Personal, Speaker, or Audience. In Personal mode, BibleSync operates as a peer among peers, both sending and receiving navigation synchronization on the shared local multicast network. Applications are expected to respond appropriately to navigation, and to send synchronization events of their own as the user moves about his Bible. In Speaker or Audience mode, *BibleSync* either transmits only (Speaker) or receives only (Audience) navigation. The Audience is expected to follow along with the Speaker's direction. The Speaker ignores incoming navigation; the Audience transmits no navigation. The difference between Personal and Speaker/Audience is thus strictly as to whether both sides of the conversation are active for each participant. On startup of the protocol, BibleSync transmits a presence announcement, informing other communication partners of the application's participation. *BibleSync* makes this announcement available to the application; whether the application shows these announcements to the user is the application designer's choice. Thereafter, as appropriate to the operational mode selected, BibleSync is tasked with polled reception of incoming navigation event packets and transmission of navigation event packets on the user's part. Transmitters (Personal and Speaker modes) issue availability beacons every 10 seconds. Received beacons for previously-unknown Speakers are handed up to the application as "new Speaker" events. These beacons provide for receivers (Personal and Audience modes) to maintain a managed list of available Speakers. Furthermore, when a transmitter ceases to issue beacons, its presence in the list of available Speakers is aged out until being removed after 30 seconds of beacon silence. The application is again informed as a Speaker ages out with a "dead Speaker" event. Default listening behavior is that the first Speaker heard via beacon is marked for listening. Other transmitters claiming Speaker status via beacon are initially ignored, but their presence is made known to the application. This provides for the application to maintain a list from which the user can select Speakers he wishes to synchronize his application. It is useful for the application to provide blanket "listen to all" and "listen to none" functions, as well as per-Speaker selections, informing *BibleSync* of these choices. In any case, this default "first Speaker only" policy can be overridden by the application with any other policy desired, through the use of **listenToSpeaker()** as the application designer requires. Synchronization events include 5 data elements: The Bible abbreviation; the verse reference; an alternate reference (if desired; not required) which may allow the application to interpret better based on variant versification; a synchronization group identifier; and the domain. The group identifier is a single digit between 1 and 9. The specification is imprecise as to this parameter's use. The initial implementation of *BibleSync* in *Xiphos* uses the synchronization group as an indicator of the tab number in its tabbed interface: Not only is the Bible navigated, but the tab in which to navigate is selected. The domain parameter is currently fixed as "BIBLE-VERSE". This will be put to greater use in future revisions of the protocol. *BibleSync* transmits no packet when the application leaves the conversation. ## PUBLIC INTERFACE ### Object creation The application must create a single BibleSync object, identifying the application's name, its version, and the user. ### setMode setMode identifies how *BibleSync* should behave. The application must provide as well the navigation callback function by which *BibleSync* will inform the application of incoming events; the callback makes all the navigation parameters provided in event packets available to the application. setMode returns the resulting mode. The application provides the passphrase to be used as well; this argument defaults to "" (empty string), indicating that the existing passphrase should be left in place. ### getMode The application may request the current mode. ### getVersion The version string of the library itself is returned. ### getPassphrase Intended for use when preparing to enter any active mode, the application may request the current passphrase, so as to provide a default. ### Transmit The protocol requires all the indicated parameters, but all have defaults in **Transmit:** KJV, Gen.1.1, empty alternate, 1, and BIBLE-VERSE. ### Chat This is a method for transmission of casual text messages to all others in the conversation. It is expected to be received by applications who will display them in a suitable manner to the user. ### Receive This is a static method accessible from either C or C++. It must be called with the object pointer so as to re-enter object context for the private internal receiver. **Receive()** must be called regularly (i.e. polled) as long as it continues to return TRUE. When it returns FALSE, it means that the mode has changed to BSP\_MODE\_DISABLE, and the scheduled polling should stop. See also the note below on polled reception. ### setPrivate In the circumstance where the user has multiple programs running on a single computer and does not want his navigation broadcast outside that single system, when in Personal mode, the application may also request privacy. The effect is to set multicast TTL to zero, meaning that packets will not go out on the wire. ### setBeaconCount Beacon transmission occurs during every Nth call to Receive(); the default value is 10. This presumes the application will call Receive() once per second. If the application will call Receive() less frequently, divide that time (say, 2 seconds) into 10 to get a value (5) to use with this call. Use setBeaconCount() prior to enabling Personal or Speaker mode. ### setUser If the application allows the user to set a name via settings dialog, setUser() is available to re-assign the associated user name as seen by others. ### listenToSpeaker Aside from default listen behavior detailed above, the application specifically asks to listen or not to listen to specific Speakers. The key is as provided during the notification of a new Speaker. ## RECEIVE USE CASES There are 7 values for the *cmd* parameter of the *nav\_func.* In all cases, the *dump* parameter provides the raw content of an arriving packet. ### 'A' Announce. A general presence message is in *alt,* and the individual elements are also available, as overloaded use of the parameters: *bible* contains the user; *ref* contains the IP address; *group* contains the application name and version; and *domain* contains the device identification. ### 'N' Navigation. The *bible, ref, alt, group,* and *domain* parameters are presented as they arrived. *info* and *dump* are also available. ### 'S' Speaker's initial recognition from beacon receipt. Overloaded parameters are available as for presence announcements. ### 'D' Dead Speaker. *speakerkey* holds the UUID key of a previously-identified application which is no longer a candidate for listening. ### 'C' Chat. Message text is in *alt* and other parameters are overloaded as per announce, above. ### 'M' Mismatch. The incoming event packet is mismatched, either against the current passphrase or for a navigation synchronization packet when *BibleSync* is in Speaker mode. The *info* parameter begins with either "announce" or "sync", plus the user and IP address from whom the packet came. As well, in the sync case, the regular *bible, ref, alt, group,* and *domain* parameters are available. In the announce case, the presence message is in *alt,* with overloaded individual parameters as previously described. ### 'E' Error. This indicates network errors and malformed packets. The application's *nav\_func* is provided only the *info* and *dump* parameters. ## NOTES ### Polled reception The application must provide a means by which to poll regularly for incoming packets. In *Xiphos,* which is built on GTK and GLib, this is readily provided by mechanisms like g\_timeout\_add(), which sets a regular interval call of the indicated function. GLib will re-schedule the call as long as the called function returns TRUE. When it returns FALSE, GLib un-schedules the call. **Receive()** adheres to this straightforward convention. Therefore, it is imperative that every time the application moves from disabled to any non-disabled mode, Receive is again scheduled for polled use. A 1-second poll interval is expected. Brief experience during development has shown that longer intervals lead to a perception of lag. If the application designer nonetheless expects to call **Receive()** less frequently, it is necessary to use **setBeaconCount()** to change the number of calls to it between beacon transmissions. During every **Receive()** call, all waiting packets are processed. ### No datalink security *BibleSync* is a protocol defined for a friendly environment. It offers no security in its current specification, and any packet sniffer such as [wireshark(1)](/wireshark/1.md) or [tcpdump(8)](/tcpdump/8.md) can see the entire conversation. The specification makes passing reference to future encryption, but at this time none is implemented. ### Managed Speaker lists The addition of transmitter beacons was a result of initial experience showing that it can be too easy for a user to mis-start BibleSync, or for a malicious user to interject himself into serious work. The goal of beacons is to provide a means by which, on the one hand, the user can be made aware of who is attempting to be a Speaker and, on the other hand, confine the set of Speakers whom the user will permit to make synchronization changes in the application. The simplest use of 'S' new Speaker notification events is to respond with **listenToSpeaker(***true***,** *speakerkey***)** which in effect makes *BibleSync* behave as though there are no beacons. More serious use of 'S'/'D' is for the application to manage its own sense of available Speakers, providing a means by which the user can make sensible selections about how to react to each Speaker's presence. *BibleSync* can be told to listen to legitimate Speakers, and to ignore interlopers, whether intended maliciously or merely due to other users' inadvertent behavior. ### Sending verse lists One of the better uses of *BibleSync* is in sharing verse lists. Consider a relatively weak application, perhaps on a mobile device, and a desktop-based application with strong search capability. Run searches on the desktop, and send the result via *BibleSync* to the mobile app. The *ref* parameter is not confined to a single reference. In normal citation syntax, the verse reference may consist of semicolon-separated references, comma-separated verses, and hyphen-separated ranges. Be aware that the specification has a relatively short limit on packet size, so that at most a few dozen references will be sent. ### Standard reference syntax It is the responsibility of the application to transmit references in standard format. *BibleSync* neither validates nor converts the application's incoming *bible, ref,* and *alt* parameters. The specification references the BibleRef and OSIS specifications. ## SEE ALSO http://biblesyncprotocol.wikispaces.com (user "General\_Public", password "password"), http://semanticbible.com/bibleref/bibleref-specification.html, **[socket(2)](/socket/2.md),** **[setsockopt(2)](/setsockopt/2.md),** **[select(2)](/select/2.md),** **[recvfrom(2)](/recvfrom/2.md),** **[sendto(2)](/sendto/2.md),** and **[ip(7)](/ip/7.md),** especially sections on *IP\_ADD\_MEMBERSHIP,* *IP\_MULTICAST\_IF,* *IP\_MULTICAST\_LOOP,* and *IP\_MULTICAST\_TTL.*