History API docs

[Alex Kiernan]

Here's the documentation as far as I've got; I'm still wrestling with
how to handle some of the makedbz/makehistory issues, but I figured
getting feedback on this would be a sensible thing (I've just realised
pod2text has emboldened with *bold*, which I guess is kind confusing):

NAME
    his - routines for managing INN history

SYNOPSIS
    #include <inn/history.h>

    struct history;

    struct histstats { int hitpos; int hitneg; int misses; int dne;
    };

    struct history *HISopen(const char **path*, const char
    **method*, int *flags*);

    bool HISclose(struct history **history*);

    bool HISsync(struct history **history*);

    void HISsetcache(struct history **history*, size_t *size*);

    bool HISlookup(struct history **history*, const char **key*,
    time_t **arrived*, time_t **posted*, time_t **expires*, TOKEN
    **token*);

    bool HIScheck(struct history **history*, const char **key*);

    bool HISwrite(struct history **history*, const char **key*,
    time_t *arrived*, time_t *posted*, time_t *expires*, const TOKEN
    **token*);

    bool HISreplace(struct history **history*, const char **key*,
    time_t *arrived*, time_t *posted*, time_t *expires*, const TOKEN
    **token*);

    bool HISexpire(struct history **history*, void **cookie*, time_t
    *threshold*, bool (**exists*)(void *cookie, time_t arrived,
    time_t posted, time_t expires, const TOKEN *token));

    bool HISwalk(struct history **history*, void **cookie*, bool
    (**callback*)(void *cookie, time_t arrived, time_t posted,
    time_t expires, const TOKEN *token));

    struct histstats HISstats(struct history **history*);

    const char *HISerror(struct history **history*);

DESCRIPTION
    These functions provide provide access to the INN history
    database. They maintain key/value pairs in an opaque database
    whilst providing for expiry of outdated information.

    The history structure is an opaque handle returned from HISopen.

    The HISopen function opens the history file designated by *path*
    using the mode *flags* using the specified *method*. *flags* may
    be HIS_RDONLY to indicate that read only access to the history
    database is desired, or HIS_RDWR for read/write access. History
    methods are defined at build time; the current history method
    available is "hisv6". On success a newly initialised history
    handle is returned, or NULL on failure.

    The HISclose function closes the handle *history* and
    deallocates any resources associated with it. It returns false
    on failure or true on success.

    The HISsync function synchronises any outstanding transactions
    associated with *history* to disk.

    HISsetcache associates a cache used for speeding up HIScheck
    with *history*. The cache will occuy approximately *size* bytes.

    HISlookup retrieves a token from *history* based on the passed
    *key* (normally the Message-ID). If now entry with an associated
    token can be found, HISlookup will return false. If a token is
    found *arrived*, *expires* and *posted* are filled in with the
    message arrival, expiry and posting times respectively (or zero
    if the time component is not available), in addition to *token*
    being set to the retrieved token and a function return value of
    true. Any of arrived, expires, posted or token may be NULL in
    which case that component is not returned to the caller, without
    affecting the return value.

    HIScheck checks the database *history* for *key* (normally the
    Message-ID); if *key* has previously been set via HISwrite,
    HIScheck returns true, else false.

    HISwrite writes a new entry to the database *history* to be
    associated with *key*. *arrived*, *posted*, *expired* specify
    the arrival, posting and expiry time respectively; *posted* and
    *expired* may be specifed as <= 0 in which case that component
    shall be treated as absent in the database. *token* is
    associated with the specified *key*; if NULL then the history
    database merely remembers that this *key* has been seen,
    together with its arrival time. HISwrite returns true on
    success, or false on failure. The behaviour when *key* is not
    unique with respect to the existing entries in *history* is
    unspecified.

    HISexpire expires the history database associated with
    *history*. Entries in the database with an arrival time less
    than *threshold* are automatically deleted from the database,
    messages with an arrival time greater than or equal to threshold
    are passed to the discrimination function *exists*.

    If *exists*() returns false it indicates that stored entity
    associated with token is no longer available (or no longer
    required), but the history entry should be kept until it meets
    the *threshold* constraint. If *exists*() returns true the entry
    is kept as is in the newly expired history database.

    The *exists* function is passed the arrival, posting and expiry
    times, in addition to the token associated with the entry. Note
    that posting and/or expiry may be zero, but that token will
    never be NULL (such entries are handled solely via the threshold
    mechanism).

    The parameter *cookie* is passed to the discrimination function
    and may be used for any purpose required by the caller.

    If the discrimination function attempts to access the underlying
    database during the callback the behaviour is unspecified.

    HISwalk provides an iteration function for the specified
    *history* database. For every entry in the history database
    *callback* is invoked passing the *cookie*, arrival, posting and
    expiry times, in addition to the token associated with the
    entry. If the *callback*() returns false the iteration is
    aborted and HISwalk returns false to the caller.

    If the callback function attempts to access the underlying
    database during the callback the behaviour is unspecified.


-- 
Alex Kiernan, Principal Engineer, Development, Thus PLC