cgroggs.h

Go to the documentation of this file.

/*
 * This file is part of Cgroggs.
 * Copyright (C) 2008 Richard Kettlewell
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program 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
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
 * USA
 */
/** @mainpage Cgroggs
 *
 * Cgroggs is a C API for accessing RGTP servers.
 *
 * See:
 * - @ref cgroggs.h for the public API
 * - <a
 * href="http://www.greenend.org.uk/rjk/cgroggs/">http://www.greenend.org.uk/rjk/cgroggs/</a> for the Cgroggs home page.
 * - <a
 * href="http://www.groggs.group.cam.ac.uk/protocol.txt">http://www.groggs.group.cam.ac.uk/protocol.txt</a> for a description of the protocol
 * - @ref licence
 *
 */
/** @page licence Cgroggs Licence
 *
 * cgroggs is (c) 2008 Richard Kettlewell.
 * 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program 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
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
 * USA
 */

/** @file cgroggs.h
 * @brief Cgroggs Public API
 *
 * See:
 * - @ref types
 * - @ref setup
 * - @ref indx
 * - @ref items
 * - @ref misc
 * - @ref mem
 *
 * Notes:
 * - All symbols in this header start @b cgroggs_ or @b CGROGGS_.
 * Symbols starting @b cgroggs__ are used internally but don't appear
 * in the header.
 * - This is a UTF-8 API.  Article data etc passed to or from these functions is
 * always encoded in UTF-8.  This is independent of RGTP's encoding: the
 * library will perform any translations necessary.
 */

#ifndef CGROGGS_H
#define CGROGGS_H

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/** @defgroup types Data Types */

/*@{*/

/** @brief Handle type
 *
 * A handle represents a single server connection.  It's safe to use
 * multiple handles from multiple threads but not to use one handle
 * from multiple threads concurrently.
 *
 * Create a handle with cgroggs_new() and destroy it with cgroggs_destroy().
 */
typedef struct cgroggs_data *cgroggs_handle;

/** @brief Error codes
 *
 * Convert errors to strings with cgroggs_strerror().
 */
typedef enum {
  /** @brief Success
   *
   * Guaranteed to be zero.
   */
  cgroggs_ok = 0,

  /** @brief Out of memory */
  cgroggs_nomem,

  /** @brief Lost connection to server */
  cgroggs_lostconn,

  /** @brief Bad response from server */
  cgroggs_badresponse,

  /** @brief Cannot resolve hostname */
  cgroggs_badhost,

  /** @brief System call failed */
  cgroggs_syscall,

  /** @brief Cannot connect */
  cgroggs_cantconn,

  /** @brief Access denied by server */
  cgroggs_accessdenied,

  /** @brief Error response from response */
  cgroggs_servererror,

  /** @brief Invalid argument to some function */
  cgroggs_invalidarg,

  /** @brief Server requested some unimplemented feature */
  cgroggs_serverunimplemented,

  /** @brief Invalid hex digit */
  cgroggs_badhex,

  /** @brief Hex string too long */
  cgroggs_hextoolong,

  /** @brief Authentication failed */
  cgroggs_authfailed,

  /** @brief Server failed to authenticate with client */
  cgroggs_servercompromised,

  /** @brief Input string encoding is not valid */
  cgroggs_invalidencoding,

  /** @brief Cannot convert UTF-8 to wire encoding */
  cgroggs_cannotencode,

  /** @brief No such item */
  cgroggs_nosuchitem,
  
} cgroggs_error;

/** @brief Convert an error code to a string
 * @param e Error code
 * @return Description string
 *
 * The description formally uses the current locale's language and
 * encoding, but NB that currently there are no localizations other
 * than English!
 *
 * The error string should not be freed.
 */
const char *cgroggs_strerror(cgroggs_error e);

/*@}*/

/** @defgroup mem Memory Allocation
 *
 * By default, the standard functions malloc, free and realloc are used for
 * memory management.  It is possible to override this by settings @ref
 * cgroggs_malloc, @ref cgroggs_realloc and @ref cgroggs_free, for instance to
 * use a garbage collector.
 */

/*@{*/

/** @brief Function used to allocate memory
 *
 * The default value is malloc(), and this function is used in the
 * same way as that.
 */
extern void *(*cgroggs_malloc)(size_t n);

/** @brief Function used to reallocate memory
 *
 * The default value is realloc(), and this function is used in the
 * same way as that.
 */
extern void *(*cgroggs_realloc)(void *ptr, size_t n);

/** @brief Function used to free memory
 *
 * The default value is free(), and this function is used in the same
 * way as that.
 */
extern void (*cgroggs_free)(void *);

/*@}*/

/** @defgroup setup Setup And Teardown
 *
 * Every application will have to call cgroggs_new() and cgroggs_configure().
 * The other functions in this section are only used for special purposes and
 * need not be called in most applications.
 */

/*@{*/

/** @brief Create a new handle
 * @param cp Where to store new handle
 * @return Error code
 *
 * The new handle won't be be configured or connected.  See
 * cgroggs_configure() for the former; connection is automatic when
 * necessary or can be forced with cgroggs_connect().
 */
cgroggs_error cgroggs_new(cgroggs_handle *cp);

/** @brief Destroy a handle
 * @param c Handle to destroy (or NULL)
 *
 * Disconnects from the server (if necessary) and destroys all state owned by
 * @p c.  If @p c is NULL then nothing happens.  It is not safe to use @p c
 * afterwards.
 */
void cgroggs_destroy(cgroggs_handle c);

/** @brief Configure a handle
 * @param c Handle
 * @param host Host to connect to
 * @param port Port to connect to (or NULL to use default)
 * @param user Username to login as (or NULL to read as guest)
 * @param secret Authentication secret (or NULL)
 * @param level Desired access level (1-3)
 * @return Error code
 *
 * You must configure the handle before connecting (or performing any
 * operation which requires a connection, which is most of them).  New
 * configuration will only take effect next time a connection is
 *
 * Values are copied so the argument pointers need not remain live
 * after the call has completed.
 *
 * NB this function just records the information you give it, it does
 * not do a DNS lookup (and so it does not block).
 */
cgroggs_error cgroggs_configure(cgroggs_handle c,
                                const char *host,
                                const char *port,
                                const char *user,
                                const char *secret,
                                int level);

/** @brief Connect to server
 * @param c Handle
 * @return Error code
 *
 * Connects to the server, including authorizing if necessary to achieve the
 * required access level.
 *
 * If the handle is already connected then nothing happens.  If you
 * want to force reconnection you should call cgroggs_disconnect()
 * first.
 *
 * This function does not have to be called; if other functions need a
 * connection they will automatically make one.
 */
cgroggs_error cgroggs_connect(cgroggs_handle c);

/** @brief Disconnect from server
 * @param c Handle
 * @return Error code
 *
 * cgroggs_destroy() automatically calls this function and in general
 * it's never formally needed.  However if you wish to force a
 * disconnect and reconnect for some reason this might be useful.
 *
 * If the handle is not connected then nothing happens.
 */
cgroggs_error cgroggs_disconnect(cgroggs_handle c);

/** @brief Change access level
 * @param c Handle
 * @param newlevel Desired new access level (1-3)
 * @return Error code
 *
 * Changes the desired access level.  On success, the new access level will be
 * requested even for reconnections on this handle; i.e. you must all this
 * function again to downgrade access, disconnecting and reconnecting is not
 * sufficient.
 *
 * If the connection is already at the desired access level then no action is
 * taken.
 */
cgroggs_error cgroggs_alvl(cgroggs_handle c, int newlevel);

/*@}*/

/** @defgroup indx Fetching The Index
 *
 * Use cgroggs_index_fetch() to fetch updates to the server index.  Generally
 * you want to fetch only updates to this, and keep a local copy of existing
 * information.
 */

/*@{*/

/** @brief Index handle type
 *
 * A index handle contains the result of calling cgroggs_index_fetch().
 * Destroy with cgroggs_index_destroy().
 *
 * Index items are numbered from 0, with the oldest item first (so date and
 * sequence number will increase).  NB that sequence numbers should be expected
 * to wrap, and should be compared using functions from @ref seq.
 *
 * Accessor functions:
 * - cgroggs_index_count()
 * - cgroggs_index_sequence()
 * - cgroggs_index_date()
 * - cgroggs_index_id()
 * - cgroggs_index_user()
 * - cgroggs_index_subject()
 * - cgroggs_index_type()
 */
typedef struct cgroggs_index_data *cgroggs_index;

/** @brief Fetch the index
 * @param c Handle
 * @param date Starting time or 0
 * @param is_sequence If non-zero, @p date is a sequence number
 * @param indexp Where to store index handle
 * @return Error code
 *
 * Fetches the index.
 *
 * If @p date is non-0 then only index entries since that timestamp (or
 * sequence number) will be fetched.  Otherwise all index entries will b
 * fetched.
 *
 * A handle to the index is returned via @p indexp.  The handle can be
 * destroyed with cgroggs_index_destroy(), and values extracted from it with
 * the accessor functions in this section.
 */
cgroggs_error cgroggs_index_fetch(cgroggs_handle c,
                                  unsigned long date,
                                  int is_sequence,
                                  cgroggs_index *indexp);

/** @brief Destroy an index
 * @param i Index handle
 */
void cgroggs_index_destroy(cgroggs_index i);

/** @brief Count the number of items in an index
 * @param i Index handle
 * @return Item count
 *
 * Index items are numbered starting from 0.
 */
int cgroggs_index_count(cgroggs_index i);

/** @brief Get an index item's sequence number
 * @param i Index handle
 * @param item Item number (from 0)
 * @return Sequence number
 *
 * If @p item is not valid, 0 is returned.
 */
unsigned long cgroggs_index_sequence(cgroggs_index i, int item);

/** @brief Get an index item's timestamp
 * @param i Index handle
 * @param item Item number (from 0)
 * @return Sequence number
 *
 * If @p item is not valid, 0 is returned.
 */
unsigned long cgroggs_index_date(cgroggs_index i, int item);

/** @brief Get an index item's ID
 * @param i Index handle
 * @param item Item number (from 0)
 * @return Pointer to ID
 *
 * The ID for a motd update is "".
 *
 * The returned string points "inside" @p i, and becomes invalid when @p i is
 * destroyed.
 *
 * If @p item is not valid, NULL is returned.
 */
const char *cgroggs_index_id(cgroggs_index i, int item);

/** @brief Get an index item's user
 * @param i Index handle
 * @param item Item number (from 0)
 * @return Pointer to username
 *
 * The returned string points "inside" @p i, and becomes invalid when @p i is
 * destroyed.
 *
 * If @p item is not valid, NULL is returned.
 */
const char *cgroggs_index_user(cgroggs_index i, int item);

/** @brief Get an index item's subject
 * @param i Index handle
 * @param item Item number (from 0)
 * @return Pointer to subject (UTF-8)
 *
 * The subject for a motd update is "".
 *
 * The returned string points "inside" @p i, and becomes invalid when @p i is
 * destroyed.
 *
 * If @p item is not valid, NULL is returned.
 */
const char *cgroggs_index_subject(cgroggs_index i, int item);

/** @brief Get an index item's type
 * @param i Index handle
 * @param item Item number (from 0)
 * @return Type code
 *
 * The type codes from the protocol specification are:
 * - 'R' for a reply
 * - 'I' for a new item
 * - 'C' for a continuation
 * - 'F' for a continued item
 * - 'E' for an edited item
 * - 'M' for a motd update
 *
 * If @p item is not valid, 0 is returned.
 */
int cgroggs_index_type(cgroggs_index i, int item);

/*@}*/

/** @defgroup items Fetching Items */

/*@{*/

/** @brief Item handle type
 *
 * Use cgroggs_item_fetch() to fetch an item and cgroggs_item_destroy() to
 * destroy a handle.
 *
 * Accessor functions:
 * - cgroggs_item_continued_from()
 * - cgroggs_item_continued_in()
 * - cgroggs_item_last_edit()
 * - cgroggs_item_last_reply() 
 * - cgroggs_item_count() 
 * - cgroggs_item_reply_sequence() 
 * - cgroggs_item_reply_date() 
 * - cgroggs_item_reply() 
 */
typedef struct cgroggs_item_data *cgroggs_item;

/** @brief Fetch an item
 * @param c Handle
 * @param id Item ID to fetch
 * @param jp Where to put item handle
 *
 * Fetches an item.
 */
cgroggs_error cgroggs_item_fetch(cgroggs_handle c,
                                 const char *id,
                                 cgroggs_item *jp);

/** @brief @brief Destroy an item handle
 * @param j Item handle
 */
void cgroggs_item_destroy(cgroggs_item j);

/** @brief Get an item's continued-from field
 * @param j Item handle
 * @return Item ID this was continued from, or NULL
 *
 * The returned string points "inside" @p j, and becomes invalid when @p j is
 * destroyed.
 */
const char *cgroggs_item_continued_from(cgroggs_item j);

/** @brief Get an item's continued-in field
 * @param j Item handle
 * @return Item ID this is continued in, or NULL
 *
 * The returned string points "inside" @p j, and becomes invalid when @p j is
 * destroyed.
 */
const char *cgroggs_item_continued_in(cgroggs_item j);

/** @brief Get an item's last-edit field
 * @param j Item handle
 * @return Last edit sequence number
 */
unsigned long cgroggs_item_last_edit(cgroggs_item j);

/** @brief Get an item's last-reply field
 * @param j Item handle
 * @return Last reply sequence number
 */
unsigned long cgroggs_item_last_reply(cgroggs_item j);

/** @brief Get an item's reply count
 * @param j Item handle
 * @return Number of replies
 */
int cgroggs_item_count(cgroggs_item j);

/** @brief Get an item reply's sequence number
 * @param j Item handle
 * @param n Reply number (from 0)
 * @return Sequence number
 *
 * If @p n is not valid, 0 is returned.
 */
unsigned long cgroggs_item_reply_sequence(cgroggs_item j, int n);

/** @brief Get an item reply's date
 * @param j Item handle
 * @param n Reply number (from 0)
 * @return Date
 *
 * If @p n is not valid, 0 is returned.
 */
unsigned long cgroggs_item_reply_date(cgroggs_item j, int n);

/** @brief Get an item reply's text
 * @param j Item handle
 * @param n Reply number (from 0)
 * @param nlinesp Where to store line count
 * @return Array of lines (UTF-8)
 *
 * If @p n is not valid, NULL is returned and @p nlinesp is set to 0.
 *
 * The returned array points "inside" @p j, and becomes invalid when @p j is
 * destroyed.
 */
const char *const *cgroggs_item_reply(cgroggs_item j, int n, int *nlinesp);

/** @brief Get item summary information
 * @param c Handle
 * @param id Item ID
 * @param contfromp Where to store continued-from ID, or NULL
 * @param continp Where to store continued-in ID, or NULL
 * @param lasteditp Where to store last edit sequence number, or NULL
 * @param lastreplyp Where to store last reply sequence number, or NULL
 * @param flagsp Where to store flags, or NULL
 * @param subjectp Where to store subject, or NULL
 * @return Error code
 *
 * All the strings are allocated as with cgroggs_malloc() and must be freed by
 * the caller.
 *
 * Valid flags for @p flagsp are:
 * - CGROGGS_STAT_EDITED - item has been edited
 * - CGROGGS_STAT_REPLIED - item has had a reply
 */
cgroggs_error cgroggs_stat(cgroggs_handle c,
                           const char *id,
                           char **contfromp,
                           char **continp,
                           unsigned long *lasteditp,
                           unsigned long *lastreplyp,
                           unsigned long *flagsp,
                           char **subjectp);

/** @brief Item has been edited
 *
 * Set in the @p flagsp return from cgroggs_stat() if the item has been edited.
 * If the item has not been edited then the @p lasteditp value is meaningless.
 */
#define CGROGGS_STAT_EDITED 0x00000001

/** @brief Item has had a reply
 *
 * Set in the @p flagsp return from cgroggs_stat() if the item has been
 * editedreplied.  If the item has not been replied then the @p lastreplyp
 * value is meaningless.
 *
 * A reply here includes the initial contribution.
 */
#define CGROGGS_STAT_REPLIED 0x00000002

/*@}*/

/** @defgroup seq Sequence Number Comparison
 *
 * These functions provide comparison for 32-bit sequence numbers.  The rule
 * adopted is that @f$A>B@f$ iff @f$B-A <2^{31} (mod 2^{32})@f$.
 */

/*@{*/

/** @brief Compare 32-bit sequence numbers
 * @param a Sequence number
 * @param b Sequence number
 * return 1 if @p a is less than @p b, else 0
 */
int cgroggs_seq_lt(unsigned long a, unsigned long b);

/** @brief Compare 32-bit sequence numbers
 * @param a Sequence number
 * @param b Sequence number
 * return 1 if @p a is less than or equal to @p b, else 0
 */
int cgroggs_seq_le(unsigned long a, unsigned long b);

/** @brief Compare 32-bit sequence numbers
 * @param a Sequence number
 * @param b Sequence number
 * return 1 if @p a is greater than @p b, else 0
 */
int cgroggs_seq_gt(unsigned long a, unsigned long b);

/** @brief Compare 32-bit sequence numbers
 * @param a Sequence number
 * @param b Sequence number
 * return 1 if @p a is greater than or equal to @p b, else 0
 */
int cgroggs_seq_ge(unsigned long a, unsigned long b);

/*@}*/

/** @defgroup misc Miscellaneous Operations */

/*@{*/

/** @brief Retrieve server motd
 * @param c Handle
 * @param vecp Where to store lines of message (UTF-8)
 * @param nvecp Where to store line count
 * @param lastchangep Where to store sequence number, or NULL
 * @param timestampp Where to store timestamp, or NULL
 * @return Error code
 *
 * Retrieves the server's message of the day.  The message is returned as an
 * array of pointers, one for each line.  Both the array and the individual
 * lines are separately allocated via cgroggs_malloc(), and must be freed by
 * the caller.
 *
 * If there is no motd then the sequence number and timestamp will both be 0.
 */
cgroggs_error cgroggs_motd(cgroggs_handle c,
                           char ***vecp,
                           int *nvecp,
                           unsigned long *lastchangep,
                           unsigned long *timestampp);

/*@}*/

#ifdef __cplusplus
};
#endif

#endif /* CGROGGS_H */

/*
Local Variables:
c-basic-offset:2
comment-column:40
fill-column:79
indent-tabs-mode:nil
End:
*/

---