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.
34 /****s* silcutil/SilcStreamAPI/SilcStream
38 * typedef void *SilcStream;
42 * Abstact stream context representing any stream. All streams are using
43 * this abstraction so that the stream can be accessed using the standard
44 * silc_stream_* functions. All streams are destroyed by calling the
45 * silc_stream_destroy function.
48 typedef void *SilcStream;
50 /****d* silcutil/SilcStreamAPI/SilcStreamStatus
54 * typedef enum { ... } SilcStreamStatus;
58 * Stream status. This status is returned into the SilcStreamNotifier
59 * callback function to indicate the status of the stream at a given
65 SILC_STREAM_CAN_READ, /* Data available for reading */
66 SILC_STREAM_CAN_WRITE, /* Stream ready for writing */
67 SILC_STREAM_EOS, /* End of stream */
68 SILC_STREAM_CLOSED, /* Stream is closed */
69 SILC_STREAM_INVALID, /* Stream is invalid */
70 SILC_STREAM_NO_MEMORY, /* System out of memory */
71 SILC_STREAM_ERROR, /* Unknown error */
75 /****f* silcutil/SilcStreamAPI/SilcStreamNotifier
79 * typedef void (*SilcStreamNotifier)(SilcStream stream,
80 * SilcStreamStatus status,
85 * A callback of this type is called as stream notifier to notify of a
86 * certain action taken over the stream. This is called to notify for
87 * example that data is ready for reading, or writing or that end of
91 typedef void (*SilcStreamNotifier)(SilcStream stream,
92 SilcStreamStatus status,
95 /****s* silcutil/SilcStreamAPI/SilcStreamOps
99 * typedef struct { ... } SilcStreamOps;
103 * SILC Stream operations structure. This structure includes callback
104 * functions to the actual stream implementation. Any stream that
105 * use SILC Stream abstraction must fill this structure with the actual
106 * stream implementation.
108 * Each stream implementation MUST set this structure as the first field
109 * in their stream structure. As it is that structure that is passed
110 * to the silc_stream_* routines, the SILC Stream API expects that the
111 * SilcStream context starts with this structure.
116 * const SilcStreamOps *ops;
117 * ... other stuff ...
121 * silc_stream_write(foo, data, data_len);
126 /* This is called to read data from the stream. This is called when
127 silc_stream_read function was called. */
128 int (*read)(SilcStream stream, unsigned char *buf, SilcUInt32 buf_len);
130 /* This is called when writing data to the stream. This is called when
131 silc_stream_write function was called. */
132 int (*write)(SilcStream stream, const unsigned char *data,
133 SilcUInt32 data_len);
135 /* This is called to close the stream. This is called when the
136 silc_stream_close function was called. */
137 bool (*close)(SilcStream stream);
139 /* This is called to destroy the stream. This is called when the
140 silc_stream_destroy function was called. */
141 void (*destroy)(SilcStream stream);
143 /* This is called to set a notifier callback to the stream. This is
144 called when silc_stream_set_notifier was called. */
145 void (*notifier)(SilcStream stream, SilcStreamNotifier callback,
150 /****f* silcutil/SilcStreamAPI/silc_stream_read
154 * int silc_stream_read(SilcStream stream, unsigned char *buf,
155 * SilcUInt32 buf_len);
159 * Reads data from the stream indicated by `stream' into the data buffer
160 * indicated by `buf' which is size of `buf_len'. This returns the amount
161 * of data read, zero (0) if end of stream occurred, -1 if data could
162 * not be read at this moment, or -2 if error occurred. If -1 is returned
163 * the notifier callback will later be called with SILC_STREAM_CAN_READ
164 * status when stream is again ready for reading.
167 int silc_stream_read(SilcStream stream, unsigned char *buf,
170 /****f* silcutil/SilcStreamAPI/silc_stream_write
174 * int silc_stream_write(SilcStream stream, const unsigned char *data,
175 * SilcUInt32 data_len);
179 * Writes `data_len' bytes of data to the stream indicated by `stream' from
180 * data buffer indicated by `data'. Returns the amount of data written,
181 * zero (0) if end of stream occurred, -1 if data could not be written
182 * at this moment, or -2 if error occurred. If -1 is returned the
183 * notifier callback will later be called with SILC_STREAM_CAN_WRITE
184 * status when stream is again ready for writing.
187 int silc_stream_write(SilcStream stream, const unsigned char *data,
188 SilcUInt32 data_len);
190 /****f* silcutil/SilcStreamAPI/silc_stream_close
194 * bool silc_stream_close(SilcStream stream);
198 * Closes the stream indicated by `stream'. No data can be read or written
199 * to the stream after calling this function. Return TRUE if the stream
200 * could be closed. If action is taken on closed stream the notifier
201 * callback will be called with an error status.
204 bool silc_stream_close(SilcStream stream);
206 /****f* silcutil/SilcStreamAPI/silc_stream_destroy
210 * void silc_stream_destroy(SilcStream stream);
214 * Destroy the stream indicated by `stream'. The `stream' will become
215 * invalid after this function returns. All streams are destroyed by
216 * calling this function. The silc_stream_close should be called
217 * before calling this function. However, if it is not called this
218 * function will call it.
221 void silc_stream_destroy(SilcStream stream);
223 /****f* silcutil/SilcStreamAPI/silc_stream_set_notifier
227 * void silc_stream_set_notifier(SilcStream stream,
228 * SilcStreamNotifier notifier,
233 * Set a notifier callback for the stream indicated by `stream' to be called
234 * when some action takes place on the stream. It is called for example
235 * when data is available for reading or writing, or if an error occurs.
236 * This can be called at any time for valid stream. If `notifier' is set
237 * to NULL no callback will be called for the stream.
240 void silc_stream_set_notifier(SilcStream stream, SilcStreamNotifier notifier,
243 #endif /* SILCSTREAM_H */