NAME

SYNOPSIS

#include <biblesync.hh>

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

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

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

RECEIVE USE CASES

NOTES

SEE ALSO