5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2005 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/SILC Stream Interface
24 * SILC Stream API is a generic representation of a stream. A common API
25 * is defined that can be used to read from and write to the stream. Any
26 * other stream API derived from this API can use this same interface for
27 * sending and receiving.
29 * Note that stream implementations usually are not thread-safe. Always
30 * verify whether a stream implementation is thread-safe by checking their
31 * corresponding documentation.
38 /****s* silcutil/SilcStreamAPI/SilcStream
42 * typedef void *SilcStream;
46 * Abstact stream context representing any stream. All streams are using
47 * this abstraction so that the stream can be accessed using the standard
48 * silc_stream_* functions. All streams are destroyed by calling the
49 * silc_stream_destroy function.
52 typedef void *SilcStream;
54 /****d* silcutil/SilcStreamAPI/SilcStreamStatus
58 * typedef enum { ... } SilcStreamStatus;
62 * Stream status. This status is returned into the SilcStreamNotifier
63 * callback function to indicate the status of the stream at a given
69 SILC_STREAM_CAN_READ, /* Data available for reading */
70 SILC_STREAM_CAN_WRITE, /* Stream ready for writing */
71 SILC_STREAM_EOS, /* End of stream */
72 SILC_STREAM_CLOSED, /* Stream is closed */
73 SILC_STREAM_INVALID, /* Stream is invalid */
74 SILC_STREAM_NO_MEMORY, /* System out of memory */
75 SILC_STREAM_ERROR, /* Unknown error */
79 /****f* silcutil/SilcStreamAPI/SilcStreamNotifier
83 * typedef void (*SilcStreamNotifier)(SilcStream stream,
84 * SilcStreamStatus status,
89 * A callback of this type is called as stream notifier to notify of a
90 * certain action taken over the stream. This is called to notify for
91 * example that data is ready for reading, or writing or that end of
95 typedef void (*SilcStreamNotifier)(SilcStream stream,
96 SilcStreamStatus status,
99 /****s* silcutil/SilcStreamAPI/SilcStreamOps
103 * typedef struct { ... } SilcStreamOps;
107 * SILC Stream operations structure. This structure includes callback
108 * functions to the actual stream implementation. Any stream that
109 * use SILC Stream abstraction must fill this structure with the actual
110 * stream implementation.
112 * Each stream implementation MUST set this structure as the first field
113 * in their stream structure. As it is that structure that is passed
114 * to the silc_stream_* routines, the SILC Stream API expects that the
115 * SilcStream context starts with this structure.
120 * const SilcStreamOps *ops;
121 * ... other stuff ...
125 * silc_stream_write(foo, data, data_len);
130 /* This is called to read data from the stream. This is called when
131 silc_stream_read function was called. */
132 int (*read)(SilcStream stream, unsigned char *buf, SilcUInt32 buf_len);
134 /* This is called when writing data to the stream. This is called when
135 silc_stream_write function was called. */
136 int (*write)(SilcStream stream, const unsigned char *data,
137 SilcUInt32 data_len);
139 /* This is called to close the stream. This is called when the
140 silc_stream_close function was called. */
141 SilcBool (*close)(SilcStream stream);
143 /* This is called to destroy the stream. This is called when the
144 silc_stream_destroy function was called. */
145 void (*destroy)(SilcStream stream);
147 /* This is called to set a notifier callback to the stream. This is
148 called when silc_stream_set_notifier was called. */
149 void (*notifier)(SilcStream stream, SilcStreamNotifier callback,
154 /****f* silcutil/SilcStreamAPI/silc_stream_read
158 * int silc_stream_read(SilcStream stream, unsigned char *buf,
159 * SilcUInt32 buf_len);
163 * Reads data from the stream indicated by `stream' into the data buffer
164 * indicated by `buf' which is size of `buf_len'. This returns the amount
165 * of data read, zero (0) if end of stream occurred, -1 if data could
166 * not be read at this moment, or -2 if error occurred. If -1 is returned
167 * the notifier callback will later be called with SILC_STREAM_CAN_READ
168 * status when stream is again ready for reading.
171 int silc_stream_read(SilcStream stream, unsigned char *buf,
174 /****f* silcutil/SilcStreamAPI/silc_stream_write
178 * int silc_stream_write(SilcStream stream, const unsigned char *data,
179 * SilcUInt32 data_len);
183 * Writes `data_len' bytes of data to the stream indicated by `stream' from
184 * data buffer indicated by `data'. Returns the amount of data written,
185 * zero (0) if end of stream occurred, -1 if data could not be written
186 * at this moment, or -2 if error occurred. If -1 is returned the
187 * notifier callback will later be called with SILC_STREAM_CAN_WRITE
188 * status when stream is again ready for writing.
191 int silc_stream_write(SilcStream stream, const unsigned char *data,
192 SilcUInt32 data_len);
194 /****f* silcutil/SilcStreamAPI/silc_stream_close
198 * SilcBool silc_stream_close(SilcStream stream);
202 * Closes the stream indicated by `stream'. No data can be read or written
203 * to the stream after calling this function. Return TRUE if the stream
204 * could be closed. If action is taken on closed stream the notifier
205 * callback will be called with an error status.
208 SilcBool silc_stream_close(SilcStream stream);
210 /****f* silcutil/SilcStreamAPI/silc_stream_destroy
214 * void silc_stream_destroy(SilcStream stream);
218 * Destroy the stream indicated by `stream'. The `stream' will become
219 * invalid after this function returns. All streams are destroyed by
220 * calling this function. The silc_stream_close should be called
221 * before calling this function. However, if it is not called this
222 * function will call it.
225 void silc_stream_destroy(SilcStream stream);
227 /****f* silcutil/SilcStreamAPI/silc_stream_set_notifier
231 * void silc_stream_set_notifier(SilcStream stream,
232 * SilcStreamNotifier notifier,
237 * Set a notifier callback for the stream indicated by `stream' to be called
238 * when some action takes place on the stream. It is called for example
239 * when data is available for reading or writing, or if an error occurs.
240 * This can be called at any time for valid stream. If `notifier' is set
241 * to NULL no callback will be called for the stream.
244 void silc_stream_set_notifier(SilcStream stream, SilcStreamNotifier notifier,
247 #endif /* SILCSTREAM_H */