5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2005 - 2007 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 * reading and writing.
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 */
74 /****f* silcutil/SilcStreamAPI/SilcStreamNotifier
78 * typedef void (*SilcStreamNotifier)(SilcStream stream,
79 * SilcStreamStatus status,
84 * A callback of this type is called as stream notifier to notify of a
85 * certain action taken over the stream. This is called to notify for
86 * example that data is ready for reading, or writing or that end of
90 typedef void (*SilcStreamNotifier)(SilcStream stream,
91 SilcStreamStatus status,
94 /****s* silcutil/SilcStreamAPI/SilcStreamOps
98 * typedef struct { ... } SilcStreamOps;
102 * SILC Stream operations structure. This structure includes callback
103 * functions to the actual stream implementation. Any stream that
104 * use SILC Stream abstraction must fill this structure with the actual
105 * stream implementation.
107 * Each stream implementation MUST set this structure as the first field
108 * in their stream structure. As it is that structure that is passed
109 * to the silc_stream_* routines, the SILC Stream API expects that the
110 * SilcStream context starts with this structure.
115 * const SilcStreamOps *ops;
116 * ... other stuff ...
120 * silc_stream_write(foo, data, data_len);
125 /* This is called to read data from the stream. This is called when
126 silc_stream_read function was called. */
127 int (*read)(SilcStream stream, unsigned char *buf, SilcUInt32 buf_len);
129 /* This is called when writing data to the stream. This is called when
130 silc_stream_write function was called. */
131 int (*write)(SilcStream stream, const unsigned char *data,
132 SilcUInt32 data_len);
134 /* This is called to close the stream. This is called when the
135 silc_stream_close function was called. */
136 SilcBool (*close)(SilcStream stream);
138 /* This is called to destroy the stream. This is called when the
139 silc_stream_destroy function was called. */
140 void (*destroy)(SilcStream stream);
142 /* This is called to set a notifier callback to the stream and schedule
143 the stream. Stream should not be scheduled before calling this
144 function. If stream does not need scheduler then the scheduler can
145 be ignored. This is called when silc_stream_set_notifier was called.
146 Returns FALSE if the stream could not be scheduled. */
147 SilcBool (*notifier)(SilcStream stream, SilcSchedule schedule,
148 SilcStreamNotifier callback, void *context);
150 /* This is called to return the associated scheduler, if set. This is
151 called when silc_stream_get_schedule was called. */
152 SilcSchedule (*get_schedule)(SilcStream stream);
156 /****f* silcutil/SilcStreamAPI/silc_stream_read
160 * int silc_stream_read(SilcStream stream, unsigned char *buf,
161 * SilcUInt32 buf_len);
165 * Reads data from the stream indicated by `stream' into the data buffer
166 * indicated by `buf' which is size of `buf_len'. This returns the amount
167 * of data read, zero (0) if end of stream occurred, -1 if data could
168 * not be read at this moment, or -2 if error occurred. If -1 is returned
169 * the notifier callback will later be called with SILC_STREAM_CAN_READ
170 * status when stream is again ready for reading.
172 * If error occurred the error code can be retrieved with silc_errno.
175 int silc_stream_read(SilcStream stream, unsigned char *buf,
178 /****f* silcutil/SilcStreamAPI/silc_stream_write
182 * int silc_stream_write(SilcStream stream, const unsigned char *data,
183 * SilcUInt32 data_len);
187 * Writes `data_len' bytes of data to the stream indicated by `stream' from
188 * data buffer indicated by `data'. Returns the amount of data written,
189 * zero (0) if end of stream occurred, -1 if data could not be written
190 * at this moment, or -2 if error occurred. If -1 is returned the
191 * notifier callback will later be called with SILC_STREAM_CAN_WRITE
192 * status when stream is again ready for writing.
194 * If error occurred the error code can be retrieved with silc_errno.
197 int silc_stream_write(SilcStream stream, const unsigned char *data,
198 SilcUInt32 data_len);
200 /****f* silcutil/SilcStreamAPI/silc_stream_close
204 * SilcBool silc_stream_close(SilcStream stream);
208 * Closes the stream indicated by `stream'. No data can be read or written
209 * to the stream after calling this function. Return TRUE if the stream
210 * could be closed. If action is taken on closed stream the notifier
211 * callback may be called with an error status.
214 SilcBool silc_stream_close(SilcStream stream);
216 /****f* silcutil/SilcStreamAPI/silc_stream_destroy
220 * void silc_stream_destroy(SilcStream stream);
224 * Destroy the stream indicated by `stream'. The `stream' will become
225 * invalid after this function returns. All streams are destroyed by
226 * calling this function. The silc_stream_close should be called
227 * before calling this function. However, if it is not called this
228 * function will call it.
231 void silc_stream_destroy(SilcStream stream);
233 /****f* silcutil/SilcStreamAPI/silc_stream_set_notifier
237 * SilcBool silc_stream_set_notifier(SilcStream stream,
238 * SilcSchedule schedule,
239 * SilcStreamNotifier notifier,
244 * Schedule `stream' for stream events. Set the `notifier' callback to
245 * be called when some event takes place on the stream. The event will
246 * be delievered to the `notifier' callback with the `context'. It is
247 * called for example when data is available for reading or writing, or
248 * if an error occurs. This can be called at any time for valid stream.
249 * This call will also set the `stream' into non-blocking mode.
251 * If `notifier' is set to NULL no callback will be called for the stream,
252 * and the stream is not scheduled anymore.
254 * This function returns FALSE if the stream could not be scheduled.
255 * Returns TRUE on success. The `schedule' must always be non-NULL.
258 SilcBool silc_stream_set_notifier(SilcStream stream, SilcSchedule schedule,
259 SilcStreamNotifier notifier, void *context);
261 /****f* silcutil/SilcStreamAPI/silc_stream_get_schedule
265 * SilcSchedule silc_stream_get_schedule(SilcStream stream);
269 * Returns the scheduler that has been associated with the `stream', or
270 * NULL if one has not been set for the `stream'.
273 SilcSchedule silc_stream_get_schedule(SilcStream stream);
275 #endif /* SILCSTREAM_H */