lib/silcutil/silcfdstream.h

   1 /*
   2
   3   silcfdstream.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2005 - 2007 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 File Descriptor Stream Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Implementation of SILC File Descriptor Stream.  The file descriptor
  25  * stream can be used read from and write to a file descriptor.  This
  26  * interface should be used only with real file descriptors, not with
  27  * sockets.  Use the SILC Socket Stream for sockets.
  28  *
  29  * SILC File Descriptor Stream is not thread-safe.  If same stream must be
  30  * used in multithreaded environment concurrency control must be employed.
  31  *
  32  ***/
  33
  34 #ifndef SILCFDSTREAM_H
  35 #define SILCFDSTREAM_H
  36
  37 /****f* silcutil/SilcFDStreamAPI/silc_fd_stream_create
  38  *
  39  * SYNOPSIS
  40  *
  41  *    SilcStream silc_fd_stream_create(int fd, SilcStack stack);
  42  *
  43  * DESCRIPTION
  44  *
  45  *    Creates file descriptor stream for the open file descriptor indicated
  46  *    by `fd'.  The stream is closed with the silc_stream_close and destroyed
  47  *    with the silc_stream_destroy.
  48  *
  49  *    If the silc_stream_set_notifier is called the stream is set to
  50  *    non-blocking mode.
  51  *
  52  *    If `stack' is non-NULL all memory is allocated from the `stack' and
  53  *    will be released back to `stack' after the stream is destroyed.
  54  *
  55  ***/
  56 SilcStream silc_fd_stream_create(int fd, SilcStack stack);
  57
  58 /****f* silcutil/SilcFDStreamAPI/silc_fd_stream_create2
  59  *
  60  * SYNOPSIS
  61  *
  62  *    SilcStream silc_fd_stream_create2(int read_fd, int write_fd,
  63  *                                      SilcStack stack);
  64  *
  65  * DESCRIPTION
  66  *
  67  *    Creates file descriptor stream for the open file descriptors indicated
  68  *    by `read_fd' and `write_fd'.  The `read_fd' must be opened for reading
  69  *    and `write_fd' opened for writing.  The stream is closed with the
  70  *    silc_stream_close and destroyed with the silc_stream_destroy.
  71  *
  72  *    If the silc_stream_set_notifier is called the stream is set to
  73  *    non-blocking mode.
  74  *
  75  *    If `stack' is non-NULL all memory is allocated from the `stack' and
  76  *    will be released back to `stack' after the stream is destroyed.
  77  *
  78  ***/
  79 SilcStream silc_fd_stream_create2(int read_fd, int write_fd, SilcStack stack);
  80
  81 /****f* silcutil/SilcFDStreamAPI/silc_fd_stream_file
  82  *
  83  * SYNOPSIS
  84  *
  85  *    SilcStream silc_fd_stream_file(const char *filename, SilcBool reading,
  86  *                                   SilcBool writing, SilcStack stack);
  87  *
  88  * DESCRIPTION
  89  *
  90  *    Same as silc_fd_stream_create but creates the stream by opening the
  91  *    file indicated by `filename'.  If the `reading' is TRUE the file is
  92  *    opened for reading.  If the `writing' is TRUE the file is opened
  93  *    for writing.
  94  *
  95  *    If the silc_stream_set_notifier is called the stream is set to
  96  *    non-blocking mode.
  97  *
  98  *    If `stack' is non-NULL all memory is allocated from the `stack' and
  99  *    will be released back to `stack' after the stream is destroyed.
 100  *
 101  ***/
 102 SilcStream silc_fd_stream_file(const char *filename, SilcBool reading,
 103                                SilcBool writing, SilcStack stack);
 104
 105 /****f* silcutil/SilcFDStreamAPI/silc_fd_stream_file2
 106  *
 107  * SYNOPSIS
 108  *
 109  *    SilcStream silc_fd_stream_file2(const char *read_file,
 110  *                                    const char *write_file,
 111  *                                    SilcStack stack);
 112  *
 113  * DESCRIPTION
 114  *
 115  *    Same as silc_fd_stream_file but creates the stream by opening `read_file'
 116  *    for reading and `write_file' for writing.
 117  *
 118  *    If the silc_stream_set_notifier is called the stream is set to
 119  *    non-blocking mode.
 120  *
 121  *    If `stack' is non-NULL all memory is allocated from the `stack' and
 122  *    will be released back to `stack' after the stream is destroyed.
 123  *
 124  ***/
 125 SilcStream silc_fd_stream_file2(const char *read_file, const char *write_file,
 126                                 SilcStack stack);
 127
 128 /****f* silcutil/SilcFDStreamAPI/silc_fd_stream_get_info
 129  *
 130  * SYNOPSIS
 131  *
 132  *    SilcBool
 133  *    silc_fd_stream_get_info(SilcStream stream, int *read_fd, int *write_fd);
 134  *
 135  * DESCRIPTION
 136  *
 137  *    Returns the file descriptors associated with the stream.  The 'write_fd'
 138  *    is available only if the stream was created with silc_fd_stream_create2
 139  *    function.
 140  *
 141  ***/
 142 SilcBool silc_fd_stream_get_info(SilcStream stream,
 143                                  int *read_fd, int *write_fd);
 144
 145 /****f* silcutil/SilcFDStreamAPI/silc_fd_stream_get_error
 146  *
 147  * SYNOPSIS
 148  *
 149  *    int silc_fd_stream_get_error(SilcStream stream);
 150  *
 151  * DESCRIPTION
 152  *
 153  *    If error occurred during file descriptor stream operations, this
 154  *    function can be used to retrieve the error number that occurred.
 155  *
 156  ***/
 157 int silc_fd_stream_get_error(SilcStream stream);
 158
 159 #endif /* SILCFDSTREAM_H */