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  ***/
  30
  31 #ifndef SILCSTREAM_H
  32 #define SILCSTREAM_H
  33
  34 /****s* silcutil/SilcStreamAPI/SilcStream
  35  *
  36  * NAME
  37  *
  38  *    typedef void *SilcStream;
  39  *
  40  * DESCRIPTION
  41  *
  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.
  46  *
  47  ***/
  48 typedef void *SilcStream;
  49
  50 /****d* silcutil/SilcStreamAPI/SilcStreamStatus
  51  *
  52  * NAME
  53  *
  54  *    typedef enum { ... } SilcStreamStatus;
  55  *
  56  * DESCRIPTION
  57  *
  58  *    Stream status.  This status is returned into the SilcStreamNotifier
  59  *    callback function to indicate the status of the stream at a given
  60  *    moment.
  61  *
  62  * SOURCE
  63  */
  64 typedef enum {
  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 */
  72 } SilcStreamStatus;
  73 /***/
  74
  75 /****f* silcutil/SilcStreamAPI/SilcStreamNotifier
  76  *
  77  * SYNOPSIS
  78  *
  79  *    typedef void (*SilcStreamNotifier)(SilcStream stream,
  80  *                                       SilcStreamStatus status,
  81  *                                       void *context);
  82  *
  83  * DESCRIPTION
  84  *
  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
  88  *    stream occurred.
  89  *
  90  ***/
  91 typedef void (*SilcStreamNotifier)(SilcStream stream,
  92                                    SilcStreamStatus status,
  93                                    void *context);
  94
  95 /****s* silcutil/SilcStreamAPI/SilcStreamOps
  96  *
  97  * NAME
  98  *
  99  *    typedef struct { ... } SilcStreamOps;
 100  *
 101  * DESCRIPTION
 102  *
 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.
 107  *
 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.
 112  *
 113  * EXAMPLE
 114  *
 115  *    typedef struct {
 116  *      const SilcStreamOps *ops;
 117  *      ... other stuff ...
 118  *    } *SilcFooStream;
 119  *
 120  *    SilcFooStream foo;
 121  *    silc_stream_write(foo, data, data_len);
 122  *
 123  * SOURCE
 124  */
 125 typedef struct {
 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);
 129
 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);
 134
 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);
 138
 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);
 142
 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,
 146                    void *context);
 147 } SilcStreamOps;
 148 /***/
 149
 150 /****f* silcutil/SilcStreamAPI/silc_stream_read
 151  *
 152  * SYNOPSIS
 153  *
 154  *    int silc_stream_read(SilcStream stream, unsigned char *buf,
 155  *                         SilcUInt32 buf_len);
 156  *
 157  * DESCRIPTION
 158  *
 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.
 165  *
 166  ***/
 167 int silc_stream_read(SilcStream stream, unsigned char *buf,
 168                      SilcUInt32 buf_len);
 169
 170 /****f* silcutil/SilcStreamAPI/silc_stream_write
 171  *
 172  * SYNOPSIS
 173  *
 174  *    int silc_stream_write(SilcStream stream, const unsigned char *data,
 175  *                          SilcUInt32 data_len);
 176  *
 177  * DESCRIPTION
 178  *
 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.
 185  *
 186  ***/
 187 int silc_stream_write(SilcStream stream, const unsigned char *data,
 188                       SilcUInt32 data_len);
 189
 190 /****f* silcutil/SilcStreamAPI/silc_stream_close
 191  *
 192  * SYNOPSIS
 193  *
 194  *    bool silc_stream_close(SilcStream stream);
 195  *
 196  * DESCRIPTION
 197  *
 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.
 202  *
 203  ***/
 204 bool silc_stream_close(SilcStream stream);
 205
 206 /****f* silcutil/SilcStreamAPI/silc_stream_destroy
 207  *
 208  * SYNOPSIS
 209  *
 210  *    void silc_stream_destroy(SilcStream stream);
 211  *
 212  * DESCRIPTION
 213  *
 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.
 219  *
 220  ***/
 221 void silc_stream_destroy(SilcStream stream);
 222
 223 /****f* silcutil/SilcStreamAPI/silc_stream_set_notifier
 224  *
 225  * SYNOPSIS
 226  *
 227  *    void silc_stream_set_notifier(SilcStream stream,
 228  *                                  SilcStreamNotifier notifier,
 229  *                                  void *context);
 230  *
 231  * DESCRIPTION
 232  *
 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.
 238  *
 239  ***/
 240 void silc_stream_set_notifier(SilcStream stream, SilcStreamNotifier notifier,
 241                               void *context);
 242
 243 #endif /* SILCSTREAM_H */