usr/src/lib/libtecla/common/chrqueue.h

   1 #ifndef chrqueue_h
   2 #define chrqueue_h
   3
   4 /*
   5  * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
   6  *
   7  * All rights reserved.
   8  *
   9  * Permission is hereby granted, free of charge, to any person obtaining a
  10  * copy of this software and associated documentation files (the
  11  * "Software"), to deal in the Software without restriction, including
  12  * without limitation the rights to use, copy, modify, merge, publish,
  13  * distribute, and/or sell copies of the Software, and to permit persons
  14  * to whom the Software is furnished to do so, provided that the above
  15  * copyright notice(s) and this permission notice appear in all copies of
  16  * the Software and that both the above copyright notice(s) and this
  17  * permission notice appear in supporting documentation.
  18  *
  19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  20  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  21  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
  22  * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
  23  * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
  24  * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
  25  * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  26  * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  27  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  28  *
  29  * Except as contained in this notice, the name of a copyright holder
  30  * shall not be used in advertising or otherwise to promote the sale, use
  31  * or other dealings in this Software without prior written authorization
  32  * of the copyright holder.
  33  */
  34
  35 #pragma ident   "%Z%%M% %I%     %E% SMI"
  36
  37 /*-----------------------------------------------------------------------
  38  * This module implements a queue of characters to be processed in some
  39  * way. It is used by gl_get_line() to maintain a queue of characters
  40  * to be sent to a remote terminal. Characters are recorded in a
  41  * dynamically extensible list of fixed sized buffers.
  42  */
  43
  44 typedef struct GlCharQueue GlCharQueue;
  45
  46 /*
  47  * Create a new character queue.
  48  */
  49 GlCharQueue *_new_GlCharQueue(void);
  50
  51 /*
  52  * Delete a redundant character queue.
  53  */
  54 GlCharQueue *_del_GlCharQueue(GlCharQueue *cq);
  55
  56 /*
  57  * Append an array of n characters to a character queue.
  58  */
  59 int _glq_append_chars(GlCharQueue *cq, const char *chars, int n,
  60                       GlWriteFn *write_fn, void *data);
  61
  62 /*
  63  * Clear a character queue.
  64  */
  65 void _glq_empty_queue(GlCharQueue *cq);
  66
  67 /*
  68  * Return a count of the number of characters in the queue.
  69  */
  70 int _glq_char_count(GlCharQueue *cq);
  71
  72 /*
  73  * A structure of the following type is used by _glq_peek_chars() to
  74  * return characters at the start of the queue.
  75  */
  76 typedef struct {
  77   const char *buff;  /* A pointer to the first undeleted byte in the */
  78                      /*  first buffer of the queue. */
  79   int nbuff;         /* The number of characters in buff[] */
  80 } GlCharQueueBuff;
  81
  82 /*
  83  * Enumerator values of the following type are returned by
  84  * _glq_flush_queue() to indicate the status of the flush operation.
  85  */
  86 typedef enum {
  87   GLQ_FLUSH_DONE,   /* The flush operation completed successfully */
  88   GLQ_FLUSH_AGAIN,  /* The flush operation couldn't be completed on this */
  89                     /*  call. Call this function again when the output */
  90                     /*  channel can accept further output. */
  91   GLQ_FLUSH_ERROR   /* Unrecoverable error. */
  92 } GlqFlushState;
  93
  94 /*
  95  * Transfer as much of the contents of a character queue to an output
  96  * channel as possible, returning before the queue is empty if the
  97  * write_fn() callback says that it can't currently write anymore.
  98  */
  99 GlqFlushState _glq_flush_queue(GlCharQueue *cq, GlWriteFn *write_fn,
 100                                void *data);
 101
 102 /*
 103  * Provide information about the last error that occurred while calling
 104  * any of the above functions.
 105  */
 106 const char *_glq_last_error(GlCharQueue *cq);
 107
 108 #endif