libiphb.h

/**
   @brief Interface to the IP heartbeat service (libiphb).

   @file libiphb.h

   @author Raimo Vuonnala <raimo.vuonnala@nokia.com>
   @author Semi Malinen <semi.malinen@nokia.com>

   Copyright (C) 2008-2011 Nokia Corporation.
   Copyright (C) AsteroidOS contributors (libiphb-timerfd).

   This file is part of libiphb-timerfd.

   libiphb-timerfd is free software; you can redistribute it and/or modify
   it under the terms of the GNU Lesser General Public License version 2.1
   as published by the Free Software Foundation.

   It is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
   FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
   more details.

   You should have received a copy of the GNU Lesser General Public License
   along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef IPHB_H
#define IPHB_H

#include <time.h>

/** Handle to the iphb service (NULL is an invalid handle). */
typedef void *iphb_t;

/**
   Open the iphb service.

   @param dummy  For compatibility, can be NULL.

   @return       Handle for iphb, or NULL on error (check errno). On error the
                 caller should behave as if there were no heartbeat service.
*/
iphb_t iphb_open(int *dummy);

/**
   "Global sync" predefined values (slots), see iphb_wait().

   The timeline is divided into fixed global slots; all waiters for a given slot
   are woken at the same time (lower-value waiters wake too), which lets
   independent clients coalesce their wakeups.
*/
#define IPHB_GS_WAIT_30_SEC   30          //!< 30 second wakeup slot
#define IPHB_GS_WAIT_2_5_MINS (2*60+30)   //!< 2.5 minute wakeup slot
#define IPHB_GS_WAIT_5_MINS   (5*60)      //!< 5 minute wakeup slot
#define IPHB_GS_WAIT_10_MINS  (10*60)     //!< 10 minute wakeup slot
#define IPHB_GS_WAIT_30_MINS  (30*60)     //!< 30 minute wakeup slot
#define IPHB_GS_WAIT_1_HOUR   (60*60)     //!< 1 hour wakeup slot
#define IPHB_GS_WAIT_2_HOURS  (2*60*60)   //!< 2 hour wakeup slot
#define IPHB_GS_WAIT_10_HOURS (10*60*60)  //!< 10 hour wakeup slot

/**
   Wait for the next heartbeat.

   @param iphbh     Handle from iphb_open().
   @param mintime   Seconds that MUST elapse before the heartbeat is reacted to.
                    Value 0 means "wake me when somebody else is woken".
   @param maxtime   Seconds by which the wait MUST end. Keeping maxtime - mintime
                    large lets clients sync. Setting mintime == maxtime to an
                    IPHB_GS_WAIT_* value selects a global synchronisation slot.
   @param must_wait 1 to block until the heartbeat, 0 to drive the descriptor
                    yourself via select()/poll() (see iphb_get_fd()).

   @return          Seconds waited, or (time_t)-1 on error (check errno).
*/
time_t
iphb_wait(iphb_t iphbh, unsigned short mintime, unsigned short maxtime,
          int must_wait);

/**
   Wait for the next heartbeat (extended form).

   There can be only one wakeup per iphb handle. Calling this cancels any
   previously programmed wakeup. Passing zero for both mintime and maxtime
   cancels the pending wakeup without programming a new one.

   If mintime == maxtime, a global wakeup slot is used rather than a ranged
   wakeup; use the predefined IPHB_GS_WAIT_* values to maximise synchronous
   wakeups.

   @param iphbh     Handle from iphb_open().
   @param mintime   Seconds that MUST elapse before the heartbeat is reacted to.
   @param maxtime   Seconds by which the wait SHOULD end. Keeping maxtime -
                    mintime large maximises the chance of coalescing with other
                    iphb clients.
   @param must_wait If non-zero, block until the wakeup before returning. Zero
                    means you will use select()/poll() on the descriptor from
                    iphb_get_fd(); once it becomes readable the pending data
                    must be flushed (see iphb_discard_wakeups()).
   @param resume    If non-zero, the device is woken from suspend to end the
                    wait. Use zero if the client can wait until the device
                    leaves suspend for some other reason.

   @return          Seconds waited, or (time_t)-1 on error (check errno).
*/
time_t
iphb_wait2(iphb_t iphbh, unsigned mintime, unsigned maxtime, int must_wait,
           int resume);

/**
   Acknowledge that the application woke up by some means other than iphb.

   @param iphbh     Handle from iphb_open().

   @return          >= 0 on success (number of wakeup bytes discarded),
                    -1 on error (check errno).
*/
int
iphb_I_woke_up(iphb_t iphbh);

/**
   Discard any pending wakeups on the handle's descriptor.

   Intended primarily for the Qt wrapper.

   @param iphbh     Handle from iphb_open().

   @return          >= 0 on success (number of bytes discarded),
                    -1 on error (check errno).
*/
int
iphb_discard_wakeups(iphb_t iphbh);

/**
   Get the descriptor to use with select()/poll().

   @param iphbh     Handle from iphb_open().

   @return          A descriptor usable with select()/poll(), or -1 on error
                    (check errno). Note: this is a timerfd, so drain it with
                    read() (an 8-byte expiration count), not recv().
*/
int
iphb_get_fd(iphb_t iphbh);

/** iphb statistics. */
struct iphb_stats {
  unsigned int clients;  //!< number of active iphb clients
  unsigned int waiting;  //!< number of clients waiting for a heartbeat
  unsigned int next_hb;  //!< seconds until the next heartbeat, 0 if none pending
};

/**
   Get statistics.

   @param iphbh     Handle from iphb_open().
   @param stats     Placeholder filled in on success.

   @return          0 on success, -1 on error (check errno).
*/
int
iphb_get_stats(iphb_t iphbh, struct iphb_stats *stats);

/**
   Close the iphb service.

   @param iphbh     Handle from iphb_open().

   @return          Always NULL (convenient for clearing the caller's handle).
*/
iphb_t
iphb_close(iphb_t iphbh);

#endif /* IPHB_H */