Provided by: libbiblesync-dev_2.1.0-2build1_amd64 bug

NAME

       biblesync - multicast navigation synchronization in Bible programs

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

       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) or tcpdump(8) 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),  setsockopt(2),
       select(2), recvfrom(2), sendto(2), and ip(7), especially  sections  on  IP_ADD_MEMBERSHIP,
       IP_MULTICAST_IF, IP_MULTICAST_LOOP, and IP_MULTICAST_TTL.