
                                 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)

References

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