lib/silcutil/silcstream.h

   1 /*
   2
   3   silcstream.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2005 Pekka Riikonen
   8
   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.
  12
  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.
  17
  18 */
  19
  20 /****h* silcutil/SILC Stream Interface
  21  *
  22  * DESCRIPTION
  23  *
  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.
  28  *
  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.
  32  *
  33  ***/
  34
  35 #ifndef SILCSTREAM_H
  36 #define SILCSTREAM_H
  37
  38 /****s* silcutil/SilcStreamAPI/SilcStream
  39  *
  40  * NAME
  41  *
  42  *    typedef void *SilcStream;
  43  *
  44  * DESCRIPTION
  45  *
  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.
  50  *
  51  ***/
  52 typedef void *SilcStream;
  53
  54 /****d* silcutil/SilcStreamAPI/SilcStreamStatus
  55  *
  56  * NAME
  57  *
  58  *    typedef enum { ... } SilcStreamStatus;
  59  *
  60  * DESCRIPTION
  61  *
  62  *    Stream status.  This status is returned into the SilcStreamNotifier
  63  *    callback function to indicate the status of the stream at a given
  64  *    moment.
  65  *
  66  * SOURCE
  67  */
  68 typedef enum {
  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 */
  76 } SilcStreamStatus;
  77 /***/
  78
  79 /****f* silcutil/SilcStreamAPI/SilcStreamNotifier
  80  *
  81  * SYNOPSIS
  82  *
  83  *    typedef void (*SilcStreamNotifier)(SilcStream stream,
  84  *                                       SilcStreamStatus status,
  85  *                                       void *context);
  86  *
  87  * DESCRIPTION
  88  *
  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
  92  *    stream occurred.
  93  *
  94  ***/
  95 typedef void (*SilcStreamNotifier)(SilcStream stream,
  96                                    SilcStreamStatus status,
  97                                    void *context);
  98
  99 /****s* silcutil/SilcStreamAPI/SilcStreamOps
 100  *
 101  * NAME
 102  *
 103  *    typedef struct { ... } SilcStreamOps;
 104  *
 105  * DESCRIPTION
 106  *
 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.
 111  *
 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.
 116  *
 117  * EXAMPLE
 118  *
 119  *    typedef struct {
 120  *      const SilcStreamOps *ops;
 121  *      ... other stuff ...
 122  *    } *SilcFooStream;
 123  *
 124  *    SilcFooStream foo;
 125  *    silc_stream_write(foo, data, data_len);
 126  *
 127  * SOURCE
 128  */
 129 typedef struct {
 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);
 133
 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);
 138
 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);
 142
 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);
 146
 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,
 150                    void *context);
 151 } SilcStreamOps;
 152 /***/
 153
 154 /****f* silcutil/SilcStreamAPI/silc_stream_read
 155  *
 156  * SYNOPSIS
 157  *
 158  *    int silc_stream_read(SilcStream stream, unsigned char *buf,
 159  *                         SilcUInt32 buf_len);
 160  *
 161  * DESCRIPTION
 162  *
 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.
 169  *
 170  ***/
 171 int silc_stream_read(SilcStream stream, unsigned char *buf,
 172                      SilcUInt32 buf_len);
 173
 174 /****f* silcutil/SilcStreamAPI/silc_stream_write
 175  *
 176  * SYNOPSIS
 177  *
 178  *    int silc_stream_write(SilcStream stream, const unsigned char *data,
 179  *                          SilcUInt32 data_len);
 180  *
 181  * DESCRIPTION
 182  *
 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.
 189  *
 190  ***/
 191 int silc_stream_write(SilcStream stream, const unsigned char *data,
 192                       SilcUInt32 data_len);
 193
 194 /****f* silcutil/SilcStreamAPI/silc_stream_close
 195  *
 196  * SYNOPSIS
 197  *
 198  *    SilcBool silc_stream_close(SilcStream stream);
 199  *
 200  * DESCRIPTION
 201  *
 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.
 206  *
 207  ***/
 208 SilcBool silc_stream_close(SilcStream stream);
 209
 210 /****f* silcutil/SilcStreamAPI/silc_stream_destroy
 211  *
 212  * SYNOPSIS
 213  *
 214  *    void silc_stream_destroy(SilcStream stream);
 215  *
 216  * DESCRIPTION
 217  *
 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.
 223  *
 224  ***/
 225 void silc_stream_destroy(SilcStream stream);
 226
 227 /****f* silcutil/SilcStreamAPI/silc_stream_set_notifier
 228  *
 229  * SYNOPSIS
 230  *
 231  *    void silc_stream_set_notifier(SilcStream stream,
 232  *                                  SilcStreamNotifier notifier,
 233  *                                  void *context);
 234  *
 235  * DESCRIPTION
 236  *
 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.
 242  *
 243  ***/
 244 void silc_stream_set_notifier(SilcStream stream, SilcStreamNotifier notifier,
 245                               void *context);
 246
 247 #endif /* SILCSTREAM_H */