lib/silcutil/silcbufferstream.h

   1 /*
   2
   3   silcbufferstream.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2008 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/Buffer Stream Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Buffer stream interface to send and receive buffers.  The benefit of this
  25  * interface is that the receiver need not parse buffers from the received
  26  * data but each buffer sent is delivered separately to the receiver
  27  * callback, even if multiple buffers were received at the same time.  The
  28  * length of the buffer is delivered with the data.  The buffer data follows
  29  * a 32-bit length field in the stream.
  30  *
  31  * This interface is named SILC Buffer Stream API instead of simply SILC
  32  * Packet API which would be more desriptive name but that API name is already
  33  * used by another SILC distribution.
  34  *
  35  ***/
  36
  37 #ifndef SILCBUFFERSTREAM_H
  38 #define SILCBUFFERSTREAM_H
  39
  40 /****f* silcutil/SilcBufferReceiveCallback
  41  *
  42  * SYNOPSIS
  43  *
  44  *    typedef void (*SilcBufferReceiveCallback)(SilcResult status,
  45  *                                              SilcStream stream,
  46  *                                              SilcBuffer buffer,
  47  *                                              void *context);
  48  *
  49  * DESCRIPTION
  50  *
  51  *    Callback function to deliver the received `buffer' from the `stream'.
  52  *    The `buffer' is the buffer that was sent to the stream.  If more than
  53  *    one buffers were sent each is delivered separately to this callback.
  54  *    The `status' will indicate an error if such occurred in the stream.
  55  *    The `buffer' is NULL in case of error.  The receiver must free
  56  *    the `buffer'.
  57  *
  58  ***/
  59 typedef void (*SilcBufferReceiveCallback)(SilcResult status,
  60                                           SilcStream stream,
  61                                           SilcBuffer buffer,
  62                                           void *context);
  63
  64 /****f* silcutil/silc_buffer_stream_create
  65  *
  66  * SYNOPSIS
  67  *
  68  *    SilcStream silc_buffer_stream_create(SilcStream stream,
  69  *                                         SilcBufferReceiveCallback receiver,
  70  *                                         void *context);
  71  *
  72  * DESCRIPTION
  73  *
  74  *    Creates a buffer stream and returns it.  The `stream' is the underlaying
  75  *    stream to be used to actually send the buffer and receive buffers.
  76  *    The returned stream is used with this API to send the buffers.  The
  77  *    `stream' must stay valid as long the buffer stream is used.
  78  *
  79  *    To send buffers to the stream silc_buffer_stream_send can be used.
  80  *    The silc_stream_write cannot be used with the returned stream.  Buffers
  81  *    coming from the `stream' will be delivered to the `receiver' callback.
  82  *    The returned stream and `context' will also be delivered to `receiver'.
  83  *
  84  *    The returned stream must be destroyed by calling silc_stream_destroy.
  85  *    Other SilcStream API functions cannot be used with buffer stream.
  86  *
  87  ***/
  88 SilcStream silc_buffer_stream_create(SilcStream stream,
  89                                      SilcBufferReceiveCallback receiver,
  90                                      void *context);
  91
  92 /****f* silcutil/silc_buffer_stream_send
  93  *
  94  * SYNOPSIS
  95  *
  96  *    SilcBool silc_buffer_stream_send(SilcStream stream,
  97  *                                     SilcBuffer buffer);
  98  *
  99  * DESCRIPTION
 100  *
 101  *    Sends `buffer' to the buffer stream indicated by `stream'.  If the
 102  *    `stream' is not a buffer stream created by silc_buffer_stream_create
 103  *    this will return FALSE.  Returns FALSE on error and sets silc_errno.
 104  *
 105  ***/
 106 SilcBool silc_buffer_stream_send(SilcStream stream,
 107                                  SilcBuffer buffer);
 108
 109 #endif /* SILCBUFFERSTREAM_H */