xref: /illumos-gate/usr/src/lib/libtecla/common/chrqueue.h (revision 1da57d551424de5a9d469760be7c4b4d4f10a755)
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 /*-----------------------------------------------------------------------
36  * This module implements a queue of characters to be processed in some
37  * way. It is used by gl_get_line() to maintain a queue of characters
38  * to be sent to a remote terminal. Characters are recorded in a
39  * dynamically extensible list of fixed sized buffers.
40  */
41 
42 typedef struct GlCharQueue GlCharQueue;
43 
44 /*
45  * Create a new character queue.
46  */
47 GlCharQueue *_new_GlCharQueue(void);
48 
49 /*
50  * Delete a redundant character queue.
51  */
52 GlCharQueue *_del_GlCharQueue(GlCharQueue *cq);
53 
54 /*
55  * Append an array of n characters to a character queue.
56  */
57 int _glq_append_chars(GlCharQueue *cq, const char *chars, int n,
58 		      GlWriteFn *write_fn, void *data);
59 
60 /*
61  * Clear a character queue.
62  */
63 void _glq_empty_queue(GlCharQueue *cq);
64 
65 /*
66  * Return a count of the number of characters in the queue.
67  */
68 int _glq_char_count(GlCharQueue *cq);
69 
70 /*
71  * A structure of the following type is used by _glq_peek_chars() to
72  * return characters at the start of the queue.
73  */
74 typedef struct {
75   const char *buff;  /* A pointer to the first undeleted byte in the */
76                      /*  first buffer of the queue. */
77   int nbuff;         /* The number of characters in buff[] */
78 } GlCharQueueBuff;
79 
80 /*
81  * Enumerator values of the following type are returned by
82  * _glq_flush_queue() to indicate the status of the flush operation.
83  */
84 typedef enum {
85   GLQ_FLUSH_DONE,   /* The flush operation completed successfully */
86   GLQ_FLUSH_AGAIN,  /* The flush operation couldn't be completed on this */
87                     /*  call. Call this function again when the output */
88                     /*  channel can accept further output. */
89   GLQ_FLUSH_ERROR   /* Unrecoverable error. */
90 } GlqFlushState;
91 
92 /*
93  * Transfer as much of the contents of a character queue to an output
94  * channel as possible, returning before the queue is empty if the
95  * write_fn() callback says that it can't currently write anymore.
96  */
97 GlqFlushState _glq_flush_queue(GlCharQueue *cq, GlWriteFn *write_fn,
98 			       void *data);
99 
100 /*
101  * Provide information about the last error that occurred while calling
102  * any of the above functions.
103  */
104 const char *_glq_last_error(GlCharQueue *cq);
105 
106 #endif
107