freebsd-ports/net/tinyfugue/files/mccp.h

/*
 * Client decompression module for the mud client compression protocol.
 * See http://homepages.ihug.co.nz/~icecube/compress/ for more details.
 *
 * mccpDecompress.h - header definitions. #include this in your client code.
 *
 * Oliver Jowett <icecube$ihug.co.nz>. Demangle address as needed.
 *
 * This code is placed in the public domain.
 *
 */

/* Modified: 981203 */

/*
 *
 * mc_state is an opaque type representing the current compression state of
 * a connection. You should include a (mc_state *) in the information you
 * store for a server connection.
 *
 * Initialization / cleanup:
 *
 *   When a connection is initiated, call mudcompress_new, and store the
 *   resulting pointer in your server connection information. This pointer is
 *   used as a handle for all other functions. This does NOT begin compression
 *   - it just initialises various internal structures.
 *
 *   When a connection is terminated, call mudcompress_delete with the handle
 *   to delete all memory allocated by the decompressor for the connection.
 *
 * Reading / writing:
 *
 *   Reading from the server connection must go through the decompressor at
 *   all times. The decompressor handles both negotiation and decompression
 *   transparently - it receives input directly from the server, then provides
 *   the main client code with decompressed data, hiding all protocol details.
 *
 *   When data is received from the mud server, call mudcompress_receive,
 *   passing it the handle for the connection, a pointer to the data read,
 *   and the length of data read. It is VITAL that ALL data read is passed
 *   to the decompressor - including data with embedded NULs!
 *
 *   After mudcompress_receive has been called, call mudcompress_pending() to
 *   see if any decompressed data is available. It returns the number of
 *   bytes pending.
 *
 *   If there is pending data waiting, call mudcompress_get to retrieve it.
 *   This fills up to "size" bytes in the provided buffer "buf", and returns
 *   the number of bytes copied. Your client can now process this data as if
 *   it had been directly read from the server.
 *
 *   Be sure to check mudcompress_pending again after calling mudcompress_get!
 *   Removing some data from the decompress buffer may have allowed the
 *   decompressor to decompress some more data - in which case, you want to
 *   process it immediately, rather than waiting for another read from the
 *   mud server.
 *
 *   Regularly call mudcompress_response. If non-NULL, you need to write the
 *   returned string to the mud server. This is needed when the decompressor
 *   is negotiating compression with the server. When called,
 *   mudcompress_response clears any pending string, so be sure to save its
 *   return value!
 *
 * Status information:
 *
 *   mudcompress_error returns non-0 if there has been a (fatal) decompression
 *   error. In this case, all you can do is tell the user that something went
 *   wrong and close the connection.
 *
 *   mudcompress_stats fills in the two (unsigned long *) values passed, with
 *   the number of compressed bytes read, and the number of bytes that they
 *   decompressed to.
 *
 *   mudcompress_compressing returns non-0 if the connection is currently
 *   using compression.
 *
 */

#ifndef MUDCOMPRESS_H
#define MUDCOMPRESS_H

#ifdef __cplusplus
extern "C" {
#endif

    /*  Opaque handle for a decompressor. Details defined in Compress.c - you
     *  should never need to see them externally.
     */
    struct mc_state_s;
    typedef struct mc_state_s mc_state;

    /*  Create a new decompressor. Return a handle to it.
     */
    mc_state *mudcompress_new(void);

    /*  Deallocate a decompressor and associated data. 'state' is invalid
     *  afterthis call.
     */
    void mudcompress_delete(mc_state *state);

    /*  Perform decompression and negotiation on some received data.
     *  'data' is a pointer to the received data, 'len' is its length.
     */
    void mudcompress_receive(mc_state *state, const char *data, unsigned len);

    /*  Return the number of pending decompressed bytes that can currently
     *  be read by mudcompress_get
     */
    int mudcompress_pending(mc_state *state);

    /*  Return true (non-0) if this decompressor encountered a fatal error.
     */
    int mudcompress_error(mc_state *state);

    /*  Read decompressed data from the decompressor into 'buf', up to a
     *  maximum of 'size' bytes. Returns the number of bytes actually copied.
     */
    int mudcompress_get(mc_state *state, char *buf, int size);

    /*  Set *comp to the number of compressed bytes read, and *uncomp to the
     *  number of bytes they expanded to, for this decompressor.
     */
    void mudcompress_stats(mc_state *state, unsigned long *comp, unsigned long *uncomp);

    /*  Check for a negotiation response. If this returns NULL, no output is
     *  needed. If it returns non-NULL, it points to a NUL-terminated string
     *  that should be sent to the mud server. Calling this function clears
     *  the pending string (so be sure to save the result).
     */
    const char *mudcompress_response(mc_state *state);

    /*  Return true (non-0) if this decompressor has successfully negotiated
     *  compression and is currently performing decompression.
     */
    int mudcompress_compressing(mc_state *state);

#ifdef __cplusplus
}
#endif

#endif