#ifndef _REPO_H_5550e663_
#define _REPO_H_5550e663_

/* This file is in the public domain. */

#include "structs.h"

/*
 * Repository support code.
 */

/*
 * A REPO is typedeffed in structs.h.  REPO_PRIV and REPO_CURSOR are
 *  opaque types private to repo.c.
 *
 * Cursors, represented by REPO_CURSORs, are an important interface
 *  concept.  A cursor is created for a repo with two timestamp values
 *  and steps through all entries in the repo which are bracketed by
 *  the timestamp values.  A cursor is said to have a sample when
 *  repo_cursor_eof() returns false on it after a repo_cursor_rewind()
 *  or repo_cursor_advance().
 */
typedef struct repo_priv REPO_PRIV;
typedef struct repo_cursor REPO_CURSOR;

/*
 * A REPO has:
 *
 * link, a link field for the linked lists REPOs are kept in.
 *
 * name, the name by which the repository is known in the config file.
 *
 * filename, the name given as the filename of the data file.  This may
 *  not actually be a simple file.
 *
 * type, the type of data kept in the repository.
 *
 * maxgap, the maximum interval between samples that can occur without
 *  being considered a gap in the data.
 *
 * priv, a data blob private to repo.c.
 */
struct repo {
  REPO *link;
  char *name;
  char *filename;
  DATATYPE type;
  TIMEINTVL maxgap;
  REPO_PRIV *priv;
  } ;

/*
 * Open a repository.  The first arg is the pathname; the second arg is
 *  an error-reporting function, which is required to throw out.  Since
 *  errors throw out, if this returns, it always returns a REPO_PRIV *.
 *  This corresponds roughly to a file descriptor open onto a file.  It
 *  is the caller's responsibility to save the REPO_PRIV pointer in the
 *  priv member of the relevant REPO.
 */
extern REPO_PRIV *repo_open(const char *, void (*)(const char *, ...));

/*
 * Test to see if two REPO_PRIVs are open onto the same repository
 *  (return nonzero) or not (return zero).
 */
extern int repo_same(REPO_PRIV *, REPO_PRIV *);

/*
 * Close a REPO_PRIV, freeing up data structures as necessary.
 */
extern void repo_close(REPO_PRIV *);

/*
 * Free a REPO.  This includes calling repo_close on its REPO_PRIV.
 */
extern void repo_free(REPO *);

/*
 * Free a whole linked list of REPOs, the root of which is passed in.
 */
extern void repo_free_chain(REPO *);

/*
 * Look up a REPO by name, given a LISTEN (used to find mappings and a
 *  repository list), a name, and an error function which is called on
 *  error (which is required to throw out).  Since errors throw out, if
 *  this returns, it returns successfully, with a REPO pointer.
 */
extern REPO *repo_lookup(LISTEN *, const char *, void (*)(const char *, ...));

/*
 * Record data in a REPO.  The arguments after the REPO pointer are the
 *  timestamp, the data, and an error callback (which is required to
 *  throw out).
 */
extern void repo_record(REPO *, unsigned long long int, const char *, void (*)(const char *, ...));

/*
 * Open a new REPO_CURSOR on the given REPO.  The first TIMESTAMP is
 *  the low value, the seocnd the high; the cursor steps through all
 *  timestamps not lower than the low value but lower than the high
 *  value (that is, the lower bound is inclusive; the upper bound,
 *  exclusive).
 */
extern REPO_CURSOR *repo_cursor_open(REPO *, TIMESTAMP, TIMESTAMP);

/*
 * Close down a REPO_CURSOR.
 */
extern void repo_cursor_close(REPO_CURSOR *);

/*
 * Reset a REPO_CURSOR to the beginning of its scan.  (It may show EOF
 *  immediately; this means there are no entries in the time bracket in
 *  the repository.)
 */
extern void repo_cursor_rewind(REPO_CURSOR *);

/*
 * Test to see whether a REPO_CURSOR has any more samples to return.
 *  Zero means "not at EOF", ie, there's a sample available; nonzero
 *  means "at EOF", ie, no more samples.
 */
extern int repo_cursor_eof(REPO_CURSOR *);

/*
 * Return the timestamp of the REPO_CURSOR's current sample.  This is
 *  valid only when the cursor has a sample.
 */
extern TIMESTAMP repo_cursor_stamp(REPO_CURSOR *);

/*
 * Return the data of the REPO_CURSOR's current sample, as a string.
 *  This is valid only when the cursor has a sample.  The pointed-to
 *  data remains valid until repo_cursor_advance or repo_cursor_rewind
 *  is called on the REPO_CURSOR - or, of course, repo_cursor_close.
 *
 * As indicated by the const on the pointed-to chars, the caller must
 *  not modify the pointed-to string.
 */
extern const char *repo_cursor_data(REPO_CURSOR *);

/*
 * Advance a REPO_CURSOR to the the next sample in its window, or EOF.
 *  After this, if repo_cursor_eof() returns false then the cursor has
 *  a sample; otherwise, not.
 */
extern void repo_cursor_advance(REPO_CURSOR *);

#endif