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  * Buffer stream is not thread-safe.  If the same buffer stream must be
  36  * used in multithreaded environment concurrency control must be employed.
  37  *
  38  ***/
  39
  40 #ifndef SILCBUFFERSTREAM_H
  41 #define SILCBUFFERSTREAM_H
  42
  43 /****f* silcutil/SilcBufferReceiveCallback
  44  *
  45  * SYNOPSIS
  46  *
  47  *    typedef void (*SilcBufferReceiveCallback)(SilcResult status,
  48  *                                              SilcStream stream,
  49  *                                              SilcBuffer buffer,
  50  *                                              void *context);
  51  *
  52  * DESCRIPTION
  53  *
  54  *    Callback function to deliver the received `buffer' from the `stream'.
  55  *    The `buffer' is the buffer that was sent to the stream.  If more than
  56  *    one buffers were sent each is delivered separately to this callback.
  57  *    The `status' will indicate an error if such occurred in the stream.
  58  *    The `buffer' is NULL in case of error.  The receiver must free
  59  *    the `buffer'.
  60  *
  61  ***/
  62 typedef void (*SilcBufferReceiveCallback)(SilcResult status,
  63                                           SilcStream stream,
  64                                           SilcBuffer buffer,
  65                                           void *context);
  66
  67 /****f* silcutil/silc_buffer_stream_create
  68  *
  69  * SYNOPSIS
  70  *
  71  *    SilcStream silc_buffer_stream_create(SilcStream stream,
  72  *                                         SilcBufferReceiveCallback receiver,
  73  *                                         void *context);
  74  *
  75  * DESCRIPTION
  76  *
  77  *    Creates a buffer stream and returns it.  The `stream' is the underlaying
  78  *    stream to be used to actually send the buffer and receive buffers.
  79  *    The returned stream is used with this API to send the buffers.  The
  80  *    `stream' must stay valid as long the buffer stream is used.
  81  *
  82  *    To send buffers to the stream silc_buffer_stream_send can be used.
  83  *    The silc_stream_write cannot be used with the returned stream.  Buffers
  84  *    coming from the `stream' will be delivered to the `receiver' callback.
  85  *    The returned stream and `context' will also be delivered to `receiver'.
  86  *
  87  *    The returned stream must be destroyed by calling silc_stream_destroy.
  88  *    Other SilcStream API functions cannot be used with buffer stream.
  89  *
  90  ***/
  91 SilcStream silc_buffer_stream_create(SilcStream stream,
  92                                      SilcBufferReceiveCallback receiver,
  93                                      void *context);
  94
  95 /****f* silcutil/silc_buffer_stream_send
  96  *
  97  * SYNOPSIS
  98  *
  99  *    SilcBool silc_buffer_stream_send(SilcStream stream,
 100  *                                     SilcBuffer buffer);
 101  *
 102  * DESCRIPTION
 103  *
 104  *    Sends `buffer' to the buffer stream indicated by `stream'.  If the
 105  *    `stream' is not a buffer stream created by silc_buffer_stream_create
 106  *    this will return FALSE.  Returns FALSE on error and sets silc_errno.
 107  *
 108  ***/
 109 SilcBool silc_buffer_stream_send(SilcStream stream,
 110                                  SilcBuffer buffer);
 111
 112 #endif /* SILCBUFFERSTREAM_H */