
                                 HEARTBEAT API

                                 Introduction:

   This   document   describes  the  application  program  interface  for
   heartbeat. The following are the interfaces available for heartbeat.
    1. [1]ll_cluster_new()
    2. [2]singon()
    3. [3]signoff()
    4. [4]delete()
    5. [5]set_msg_callback()
    6. [6]set_nstatus_callback()
    7. [7]set _ifstatus_callback()
    8. [8]init_nodewalk()
    9. [9]nextnode()
   10. [10]end_nodewalk()
   11. [11]init_ifwalk()
   12. [12]nextif()
   13. [13]end_ifwalk()
   14. [14]if_status()
   15. [15]sendclustermsg()
   16. [16]sendnodemsg()
   17. [17]inputfd()
   18. [18]msgready()
   19. [19]setmsgsignal()
   20. [20]rcvmsg()
   21. [21]readmsg()
   22. [22]setfmode()
   23. [23]get_parameter()
   24. [24]get_deadtime()
   25. [25]get_keepalive()
   26. [26]get_mynodeid()
   27. [27]get_logfacility()
   28. [28]get_resources()
   29. [29]errmsg()

                                 Description:

   The details of each of the api functions are as follows:

ll_cluster_new()

   ll_cluster_t *ll_cluster_new(const char *type)

   Parameter description:
          'type'   identifies  the  service  provider.  It's  value  must
          currently be "heartbeat".

   Description:
          Register  with  the  heartbeat  library  and  create  a  client
          instance of type "heartbeat"

   Return Value:
          returns a handle to the heartbeat library instance. This handle
          is  a  opaque object with a set of member functions. The member
          functions  provide the necessary mechanism to interact with the
          heartbeat daemon. Returns NULL on failure.

   Observation:
          Why  is 'type' parameter required when we know for sure that we
          are  only  interacting with the heartbeat daemon? Or is it that
          the  library wants to be generic and wants to interact with any
          arbitrary daemon? Yes.  The latter.

signon()

   int *signon(struct ll_cluster cinfo*, const char *service)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new()  'service'  is  the type of service, which the
          calling process registers with the heartbeat daemon.

   Description:
          This  function  sets  up  a  communication  link with the local
          heartbeat   daemon  and  registers  itself  for  the  'service'
          service. In the case of casual client the clientid is NULL. But
          in  the  case of non-casual client the clientid is non-NULL and
          it  indicates the service to which this client wants to sign on
          for.  This  special communication link setup with the heartbeat
          daemon  is  a  fifo.  Non-casual  clients interact using a fifo
          whose  name  is  derived  from  the pid of the clients process.
          Casual  clients  interact  with heartbeat daemon using the fifo
          whose name is derived from the 'service'string.

          The  heartbeat  daemon  has  no  notion for 'service'. Only the
          clients  registered  with  the  heartbeat  daemons for the same
          service, have the notion for that service.  'service' mostly is
          a  mechanism  of providing primitive group services to a set of
          non-casual clients registered for that service.

   Return value:
          On success returns HA_OK
          On failure returns HA_FAIL

signoff()

   int signoff(struct ll_cluster *cinfo)

   Parameter Description:
   'cinfo' 
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new()

   Description:
          This  function  deletes  the  communication link with the local
          heartbeat  daemon and unsubscribe itself from being a heartbeat
          client.

   Return Value:
          On success it returns HA_OK.
          On failure it returns HA_FAIL.

delete()

   int delete(struct ll_cluster *cinfo)

   Parameter Description:
   cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new()

   Description:
          This  operation is reverse of ll_cluster_new(). It unsubscribes
          itself   from   the   heartbeat   library  and  cleans  up  the
          corresponding datastructures.

   Return Value:
          On success returns HA_OK
          On failure returns HA_FAIL

set_msg_callback()

   int  set_msg_callback(struct ll_cluster *cinfo,   const char *msgtype,
     llc_msg_callback_t callback, void * p)

   Parameter Description:

   cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new()

   'msgtype'
          is  the  type  of message on receipt of which the 'callback' is
          called.

   'callback'
          is  the  function  to be called on receipt of a message of type
          'msgtype'.

   'p'
          is the parameter to be passed to the 'callback' function.

   Description:
          This  function  registers  a  callback  function along with its
          parameter.  The  callback  function  is called by the heartbeat
          library  on  receipt  of  a  message of type 'msgtype' from the
          heartbeat daemon.

   NOTE:
          Neither  the  heartbeat  library nor heartbeat daemon interpret
          'msgtype'.  The  'msgtype'  is  interpreted only by the client.
          Clients  can  coin their own msgtype as long as all the clients
          signed up for the same service can interpret it.

   Return Value:
          On success HA_OK is returned.
          On failure HA_FAIL is returned.

set_nstatus_callback()

   int        set_nstatus_callback(struct        ll_cluster       *cinfo,
   llc_nstatus_callback_t cbf, void *p)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new

   'cbf'
          is the function pointer to be called on change of status of any
          node in the cluster.

   'p'
          is the parameter to be passed to the callback function.

   Description:
          This  function  registers  a  callback  function along with its
          parameter.  The  callback  function  is called by the heartbeat
          library on change of status of any node in the cluster.

   Return Value:
          On success HA_OK is returned.

   Observation:
          There  is  a  bug  in  this  function. It does not validate the
          'cinfo' parameter'. It should return HA_FAIL on failure.

set_ifstatus_callback()

   int        set_ifstatus_callback(struct       ll_cluster       *cinfo,
   llc_ifstatus_callback_t cbf, void *p)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new()

   cbf'
          is the function pointer to be called on change of status of any
          interface in the cluster.

   'p'
          is the parameter to be passed for the callback function.

   Description:
          This  function  registers  a  callback  function along with its
          parameter.  The  callback  function  is called by the heartbeat
          library  on  change  of  status of any network interface in the
          cluster in the view of the current cluster node.

   Return Value:
          On success HA_OK is returned.

          Also  there is a bug in this function. It does not validate the
          'cinfo' parameter'. It should return HA_FAIL on failure.

init_nodewalk()

   int init_nodewalk(struct ll_cluster_t *cinfo)

   Parameter Description:
   'cinfo' 
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new

   Description:
          This  function  talks to the heartbeat daemon and retrieves the
          set  of nodes that are part of the cluster. If the retrieval is
          successful HA_OK is returned.

   Return Value:
          On success HA_OK is returned
          On failure HA_FAIL is returned

nextnode()

   char *nextnode(ll_cluster_t *cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to  the  library  instance  gotten  through
          ll_cluster_new().

   Description/Return Value:,
          This  function  returns  the next node in the cluster, which is
          cached  in  the heartbeat library. If no more node is available
          it returns NULL.

end_nodewalk()

   int end_nodewalk(ll_cluster_t *cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   Description:
          This   clears  the  cluster  node  information  cached  in  the
          heartbeat library.

   Return Value:
          returns HA_OK on success  and HA_FAIL on failure.

init_ifwalk()

   int init_ifwalk(struct ll_cluster_t *cinfo, char *host)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new

   'host'
          is  the  node  in  the  cluster whose network interfaces are of
          interest.

   Description:
          This  function talks to the heartbeat daemon and caches all the
          network interface information associated with 'host' node. This
          caching is done in the heartbeat library.

   Return Value:
          If  the  network  interface  information  can  be  successfully
          retrieved, HA_OK is returned. Failure returns HA_FAIL.

nextif()

     char * nextif(ll_cluster_t *cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   Description:
          This  function returns the next network interface of the 'host'
          node in the cluster, which is cached in the heartbeat library.

   NOTE:
          The 'host' is the node of the cluster specified during the call
          to init_ifwalk()

   Return Value:
          If no more interfaces are available it returns NULL.

end_ifwalk()

   int end_ifwalk(ll_cluster_t *cinfo)

   Parameter Description:
   'cinfo' 
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   Description:
          This  clears  the  network  interface information cached in the
          heartbeat library.

   Return Value:
          returns HA_OK on success and HA_FAIL of failure.

if_status()

   char *  if_status(ll_cluster_t *cinfo, const char *host,
   const char *ifname)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   'host'
          is the node name whose interface's status is queried.

   'ifname' is the name of the interface whose status is queried.
   Description:
          This  function returns a string that specifies the state of the
          interface 'ifname' on cluster node 'host'

   Return Value:
          It returns "up" if the link is active and "dead" if the link is
          down. NULL if there was a error.

sendclustermsg()

   int sendclustermsg(ll_cluster_t *cinfo, struct ha_msg* msg)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   'msg' 
          is  the  message to be sent to all non-casual clients signed up
          for the same service as that of the calling client.

   Description:
          This  function  broadcasts  the  message  to all members of the
          group.

   Return Value:
          This  function  returns HA_FAIL if called by a casual client or
          if there was some other failure.
          On success it returns HA_OK.

sendnodemsg()

   int sendnodemsg(ll_cluster_t *cinfo, struct ha_msg* msg,
   const char *nodename)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   'msg'
          is  the  message to be sent to a non-casual client signed on to
          the same service on node 'nodename'.

   Description:
          This function sends the message to a non-casual client residing
          on  node  'nodename'.  The  client belongs to the same group as
          that of the calling client.

   Return Value:
          This  function  returns HA_FAIL if called by a casual client or
          if there was some other failure.
          On success it returns HA_OK.

inputfd()

   int inputfd(ll_cluster * cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   Description/Return Value:
          returns  the  file  descriptor  of the communication link setup
          with the local heartbeat daemon.
          On failure it returns -1.

   Observation:
          This function is needed in order to be able to perform a select
          function  which selects on incoming API messages. It should not
          be used for any other purpose.

msgready()

   int msgready(ll_cluster_t *cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   Description:
          checks if there is any message to be read.

   Return Value:
          If  a  message  is  ready  to  be  read returns non zero value.
          Otherwise returns 0.

setmsgsignal()

   int setmsgsignal(ll_cluster_t *cinfo, int nsig)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   'nsig'
          is  the  signal  to  be  used by heartbeat daemon to signal the
          client process.

   Description:
          This  function  informs the heartbeat daemon send signal number
          'nsig' whenever a message arrives for it.

   Return Value:
          returns HA_OK on success
          and HA_FAIL on failure

rcvmsg()

   int rcvmsg(ll_cluster_t *cinfo,  int blocking)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   'blocking'
          indicates whether to block for the receipt of a message or not.

   Description/Return Value:
          This  function  returns  true if a message for which a callback
          function was not registered is received.

          If  blocking  is set, then it waits till a message arrives. But
          it  returns  true only if that message does not have a callback
          registered.

   NOTE:
          In all cases, received messages are deleted by this call.

   Observation:
          This  interface  is  provided  as  a  convenience  to allow for
          clients  which  only  process  certain  message  types  through
          registered  callback functions to never have to worry about the
          possibility  of  failing  to  destroy  their  messages.  If you
          process  all  messages  you  handle  with  callbacks, then this
          function  is a convenient choice. Otherwise, you likely need to
          use readmsg().

readmsg()

   struct ha_msg * readmsg(ll_cluster_t *cinfo, int blocking)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   'blocking'
          indicates whether to block for the receipt of a message or not.

   Description/Return Value:
          This function is same as rcvmsg except that it returns messages
          without registered callbacks to the caller (and does not delete
          them).  It returns the next message for which a callback is not
          registered.

          If  'blocking'  is set to FALSE, it will not wait for a message
          to  arrive. It returns NULL if there is not currently a message
          ready to read which is not intercepted by a callback function.

   NOTE:
          The  message  returned  must  be  disposed off by the caller by
          calling ha_msg_del().

setfmode()

   int setfmode(ll_cluster_t *cinfo, int mode)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   'mode'
          indicates  the  type  of messages to be delivered to the client
          and to filter out the rest.

          The modes have the following meanings:

        LLC_FILTER_DEFAULT
                All  messages destined to this client are received, along
                with all that are addressed to all clients.

        LLC_FILTER_PMODE
                All  messages,  but filter out heartbeats that don't tell
                us anything new.

        LLC_FILTER_ALLHB
                All heartbeats including those that don't change status.

        LLC_FILTER_RAW
                All packets from all interfaces, even duplicates. Packets
                with authentication errors are still ignored.

   Description:
          This  function  sets up the type of messages that the client is
          interested;  to be received from the local heartbeat daemon. It
          is mainly used for debugging.

   Return Value:
          returns HA_OK on success and HA_FAIL on failure

   get_parameter()

          char* get_parameter(struct ll_cluster_t * cinfo, char *pname)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new

   'pname'
          is the name of the parameter to retrieve

   Description:
          This  function  retrieves the value of the named parameter from
          heartbeat. The parameters supported are listed in <hb_api.h>.

   Return Value:
          If  the  network  interface  information  can  be  successfully
          retrieved,  a pointer to a malloced string is returned. NULL is
          returned  on  failure.   This value is malloced, and the caller
          must free the return value is no longer needed.

   get_deadtime()

          long get_deadtime(struct ll_cluster_t * cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new

   Description:
          This function retrieves the deadtime value from heartbeat.  The
          value returned is in milliseconds.

   Return Value:
          The return value is the deadtime, measured in milliseconds.

   get_keepalive()

          long get_keepalive(struct ll_cluster_t * cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   Description:
          This  function  retrieves  the  keepalive value from heartbeat.
          The value returned is in milliseconds.

   Return Value:
          The  return  value  is  the  keepalive  interval,  measured  in
          milliseconds.

get_mynodeid()

   const char * get_mynodeid(ll_cluster_t *cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new

   Description/Return Value:
          This  function returns the node id of the current cluster node.
           It  is  generally (though not always) the same as the uname -n
          name  of  the  current  server.   The  return value is a static
          value.

   get_logfacility()

          long get_logfacility(struct ll_cluster_t * cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new().

   Description:
          This  function  retrieves the logfacility value from heartbeat.

   Return Value:
          The  return  value  is  the logfacility currently being used by
          heartbeat.    If  there  is  no  log  facility  being  used  by
          heartbeat, then it will return -1.

get_resources()

   const char * get_resources(ll_cluster_t *cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new

   Description/Return Value:
          This  function  returns  the  current  resource  allocation  as
          supported  by  the  current  resource management function.  The
          return  value  is  a  static  string containing one of "local",
          "foreign",  "all",  "none" or "transition"..  "local" means the
          local  nodes  is  supporting  only  local resources.  "foreign"
          means  the  local  node  is  supporting  only foreign resources
          (those  belonging  to  the  other node).  "all" means the local
          node  is  supporting  all  cluster resources.  "none" means the
          local   node   is   not   providing   any   cluster  resources.
          "transition"  means that resources are currently in transition.
           If  heartbeat is not providing resource management, the return
          value will be NULL.

errmsg()

   const char * errmsg(ll_cluster_t *cinfo)

   Parameter Description:
   'cinfo'
          is   the   handle   to   the   library   instance  got  through
          ll_cluster_new

   Description/Return Value:
          This  function  returns the last set of error messages from the
          previous  API  call.  This  is  not  a very wonderful interface
          (according to alanr)

参照

   1. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#ll_cluster_new%28%29
   2. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#signon%28%29
   3. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#signoff%28%29
   4. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#delete%28%29
   5. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#set_msg_callback%28%29
   6. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#set_nstatus_callback%28%29
   7. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#set_ifstatus_callback%28%29
   8. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#init_nodewalk%28%29
   9. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#nextnode%28%29
  10. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#end_nodewalk%28%29
  11. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#init_ifwalk%28%29
  12. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#nextif%28ll_cluster_t%20*cinfo%29
  13. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#end_ifwalk%28%29
  14. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#if_status%28%29
  15. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#sendclustermsg%28%29
  16. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#sendnodemsg%28%29
  17. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#inputfd%28%29
  18. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#msgready%28%29
  19. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#setmsgsignal%28%29
  20. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#rcvmsg%28%29
  21. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#readmsg%28%29
  22. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#setfmode%28%29
  23. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#get_parameter
  24. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#get_deadtime
  25. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#get_keepalive
  26. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#get_mynodeid
  27. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#get_logfacility
  28. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#get_resources
  29. file://localhost/tmp/heartbeat-2.1.4-1/doc/heartbeat_api.html#errmsg%28%29
