glib-2.0/glib/giochannel.h

0001 /* GLIB - Library of useful routines for C programming
0002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General Public
0017  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  */
0019
0020 /*
0021  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
0022  * file for a list of people on the GLib Team.  See the ChangeLog
0023  * files for a list of changes.  These files are distributed with
0024  * GLib at ftp://ftp.gtk.org/pub/gtk/.
0025  */
0026
0027 #ifndef __G_IOCHANNEL_H__
0028 #define __G_IOCHANNEL_H__
0029
0030 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0031 #error "Only <glib.h> can be included directly."
0032 #endif
0033
0034 #include <glib/gconvert.h>
0035 #include <glib/gmain.h>
0036 #include <glib/gstring.h>
0037
0038 G_BEGIN_DECLS
0039
0040 /* GIOChannel
0041  */
0042
0043 typedef struct _GIOChannel  GIOChannel;
0044 typedef struct _GIOFuncs        GIOFuncs;
0045
0046 typedef enum
0047 {
0048   G_IO_ERROR_NONE,
0049   G_IO_ERROR_AGAIN,
0050   G_IO_ERROR_INVAL,
0051   G_IO_ERROR_UNKNOWN
0052 } GIOError;
0053
0054 #define G_IO_CHANNEL_ERROR g_io_channel_error_quark()
0055
0056 typedef enum
0057 {
0058   /* Derived from errno */
0059   G_IO_CHANNEL_ERROR_FBIG,
0060   G_IO_CHANNEL_ERROR_INVAL,
0061   G_IO_CHANNEL_ERROR_IO,
0062   G_IO_CHANNEL_ERROR_ISDIR,
0063   G_IO_CHANNEL_ERROR_NOSPC,
0064   G_IO_CHANNEL_ERROR_NXIO,
0065   G_IO_CHANNEL_ERROR_OVERFLOW,
0066   G_IO_CHANNEL_ERROR_PIPE,
0067   /* Other */
0068   G_IO_CHANNEL_ERROR_FAILED
0069 } GIOChannelError;
0070
0071 typedef enum
0072 {
0073   G_IO_STATUS_ERROR,
0074   G_IO_STATUS_NORMAL,
0075   G_IO_STATUS_EOF,
0076   G_IO_STATUS_AGAIN
0077 } GIOStatus;
0078
0079 typedef enum
0080 {
0081   G_SEEK_CUR,
0082   G_SEEK_SET,
0083   G_SEEK_END
0084 } GSeekType;
0085
0086 typedef enum
0087 {
0088   G_IO_FLAG_NONE GLIB_AVAILABLE_ENUMERATOR_IN_2_74 = 0,
0089   G_IO_FLAG_APPEND = 1 << 0,
0090   G_IO_FLAG_NONBLOCK = 1 << 1,
0091   G_IO_FLAG_IS_READABLE = 1 << 2,   /* Read only flag */
0092   G_IO_FLAG_IS_WRITABLE = 1 << 3,   /* Read only flag */
0093   G_IO_FLAG_IS_WRITEABLE = 1 << 3,      /* Misspelling in 2.29.10 and earlier */
0094   G_IO_FLAG_IS_SEEKABLE = 1 << 4,   /* Read only flag */
0095   G_IO_FLAG_MASK = (1 << 5) - 1,
0096   G_IO_FLAG_GET_MASK = G_IO_FLAG_MASK,
0097   G_IO_FLAG_SET_MASK = G_IO_FLAG_APPEND | G_IO_FLAG_NONBLOCK
0098 } GIOFlags;
0099
0100 struct _GIOChannel
0101 {
0102   /*< private >*/
0103   gint ref_count;
0104   GIOFuncs *funcs;
0105
0106   gchar *encoding;
0107   GIConv read_cd;
0108   GIConv write_cd;
0109   gchar *line_term;     /* String which indicates the end of a line of text */
0110   guint line_term_len;      /* So we can have null in the line term */
0111
0112   gsize buf_size;
0113   GString *read_buf;        /* Raw data from the channel */
0114   GString *encoded_read_buf;    /* Channel data converted to UTF-8 */
0115   GString *write_buf;       /* Data ready to be written to the file */
0116   gchar partial_write_buf[6];   /* UTF-8 partial characters, null terminated */
0117
0118   /* Group the flags together, immediately after partial_write_buf, to save memory */
0119
0120   guint use_buffer     : 1; /* The encoding uses the buffers */
0121   guint do_encode      : 1; /* The encoding uses the GIConv converters */
0122   guint close_on_unref : 1; /* Close the channel on final unref */
0123   guint is_readable    : 1; /* Cached GIOFlag */
0124   guint is_writeable   : 1; /* ditto */
0125   guint is_seekable    : 1; /* ditto */
0126
0127   gpointer reserved1;
0128   gpointer reserved2;
0129 };
0130
0131 typedef gboolean (*GIOFunc) (GIOChannel   *source,
0132                  GIOCondition  condition,
0133                  gpointer      data);
0134 struct _GIOFuncs
0135 {
0136   GIOStatus (*io_read)           (GIOChannel   *channel,
0137                       gchar        *buf,
0138                   gsize         count,
0139                   gsize        *bytes_read,
0140                   GError      **err);
0141   GIOStatus (*io_write)          (GIOChannel   *channel,
0142                   const gchar  *buf,
0143                   gsize         count,
0144                   gsize        *bytes_written,
0145                   GError      **err);
0146   GIOStatus (*io_seek)           (GIOChannel   *channel,
0147                   gint64        offset,
0148                   GSeekType     type,
0149                   GError      **err);
0150   GIOStatus  (*io_close)         (GIOChannel   *channel,
0151                   GError      **err);
0152   GSource*   (*io_create_watch)  (GIOChannel   *channel,
0153                   GIOCondition  condition);
0154   void       (*io_free)          (GIOChannel   *channel);
0155   GIOStatus  (*io_set_flags)     (GIOChannel   *channel,
0156                                   GIOFlags      flags,
0157                   GError      **err);
0158   GIOFlags   (*io_get_flags)     (GIOChannel   *channel);
0159 };
0160
0161 GLIB_AVAILABLE_IN_ALL
0162 void        g_io_channel_init   (GIOChannel    *channel);
0163 GLIB_AVAILABLE_IN_ALL
0164 GIOChannel *g_io_channel_ref    (GIOChannel    *channel);
0165 GLIB_AVAILABLE_IN_ALL
0166 void        g_io_channel_unref  (GIOChannel    *channel);
0167
0168 GLIB_DEPRECATED_FOR(g_io_channel_read_chars)
0169 GIOError    g_io_channel_read   (GIOChannel    *channel,
0170                                  gchar         *buf,
0171                                  gsize          count,
0172                                  gsize         *bytes_read);
0173
0174 GLIB_DEPRECATED_FOR(g_io_channel_write_chars)
0175 GIOError  g_io_channel_write    (GIOChannel    *channel,
0176                                  const gchar   *buf,
0177                                  gsize          count,
0178                                  gsize         *bytes_written);
0179
0180 GLIB_DEPRECATED_FOR(g_io_channel_seek_position)
0181 GIOError  g_io_channel_seek     (GIOChannel    *channel,
0182                                  gint64         offset,
0183                                  GSeekType      type);
0184
0185 GLIB_DEPRECATED_FOR(g_io_channel_shutdown)
0186 void      g_io_channel_close    (GIOChannel    *channel);
0187
0188 GLIB_AVAILABLE_IN_ALL
0189 GIOStatus g_io_channel_shutdown (GIOChannel      *channel,
0190                  gboolean         flush,
0191                  GError         **err);
0192 GLIB_AVAILABLE_IN_ALL
0193 guint     g_io_add_watch_full   (GIOChannel      *channel,
0194                  gint             priority,
0195                  GIOCondition     condition,
0196                  GIOFunc          func,
0197                  gpointer         user_data,
0198                  GDestroyNotify   notify);
0199 GLIB_AVAILABLE_IN_ALL
0200 GSource * g_io_create_watch     (GIOChannel      *channel,
0201                  GIOCondition     condition);
0202 GLIB_AVAILABLE_IN_ALL
0203 guint     g_io_add_watch        (GIOChannel      *channel,
0204                  GIOCondition     condition,
0205                  GIOFunc          func,
0206                  gpointer         user_data);
0207
0208 /* character encoding conversion involved functions.
0209  */
0210
0211 GLIB_AVAILABLE_IN_ALL
0212 void                  g_io_channel_set_buffer_size      (GIOChannel   *channel,
0213                              gsize         size);
0214 GLIB_AVAILABLE_IN_ALL
0215 gsize                 g_io_channel_get_buffer_size      (GIOChannel   *channel);
0216 GLIB_AVAILABLE_IN_ALL
0217 GIOCondition          g_io_channel_get_buffer_condition (GIOChannel   *channel);
0218 GLIB_AVAILABLE_IN_ALL
0219 GIOStatus             g_io_channel_set_flags            (GIOChannel   *channel,
0220                              GIOFlags      flags,
0221                              GError      **error);
0222 GLIB_AVAILABLE_IN_ALL
0223 GIOFlags              g_io_channel_get_flags            (GIOChannel   *channel);
0224 GLIB_AVAILABLE_IN_ALL
0225 void                  g_io_channel_set_line_term        (GIOChannel   *channel,
0226                              const gchar  *line_term,
0227                              gint          length);
0228 GLIB_AVAILABLE_IN_ALL
0229 const gchar *         g_io_channel_get_line_term        (GIOChannel   *channel,
0230                              gint         *length);
0231 GLIB_AVAILABLE_IN_ALL
0232 void              g_io_channel_set_buffered     (GIOChannel   *channel,
0233                              gboolean      buffered);
0234 GLIB_AVAILABLE_IN_ALL
0235 gboolean          g_io_channel_get_buffered     (GIOChannel   *channel);
0236 GLIB_AVAILABLE_IN_ALL
0237 GIOStatus             g_io_channel_set_encoding         (GIOChannel   *channel,
0238                              const gchar  *encoding,
0239                              GError      **error);
0240 GLIB_AVAILABLE_IN_ALL
0241 const gchar *         g_io_channel_get_encoding         (GIOChannel   *channel);
0242 GLIB_AVAILABLE_IN_ALL
0243 void                  g_io_channel_set_close_on_unref   (GIOChannel   *channel,
0244                              gboolean      do_close);
0245 GLIB_AVAILABLE_IN_ALL
0246 gboolean              g_io_channel_get_close_on_unref   (GIOChannel   *channel);
0247
0248
0249 GLIB_AVAILABLE_IN_ALL
0250 GIOStatus   g_io_channel_flush            (GIOChannel   *channel,
0251                        GError      **error);
0252 GLIB_AVAILABLE_IN_ALL
0253 GIOStatus   g_io_channel_read_line        (GIOChannel   *channel,
0254                        gchar       **str_return,
0255                        gsize        *length,
0256                        gsize        *terminator_pos,
0257                        GError      **error);
0258 GLIB_AVAILABLE_IN_ALL
0259 GIOStatus   g_io_channel_read_line_string (GIOChannel   *channel,
0260                        GString      *buffer,
0261                        gsize        *terminator_pos,
0262                        GError      **error);
0263 GLIB_AVAILABLE_IN_ALL
0264 GIOStatus   g_io_channel_read_to_end      (GIOChannel   *channel,
0265                        gchar       **str_return,
0266                        gsize        *length,
0267                        GError      **error);
0268 GLIB_AVAILABLE_IN_ALL
0269 GIOStatus   g_io_channel_read_chars       (GIOChannel   *channel,
0270                        gchar        *buf,
0271                        gsize         count,
0272                        gsize        *bytes_read,
0273                        GError      **error);
0274 GLIB_AVAILABLE_IN_ALL
0275 GIOStatus   g_io_channel_read_unichar     (GIOChannel   *channel,
0276                        gunichar     *thechar,
0277                        GError      **error);
0278 GLIB_AVAILABLE_IN_ALL
0279 GIOStatus   g_io_channel_write_chars      (GIOChannel   *channel,
0280                        const gchar  *buf,
0281                        gssize        count,
0282                        gsize        *bytes_written,
0283                        GError      **error);
0284 GLIB_AVAILABLE_IN_ALL
0285 GIOStatus   g_io_channel_write_unichar    (GIOChannel   *channel,
0286                        gunichar      thechar,
0287                        GError      **error);
0288 GLIB_AVAILABLE_IN_ALL
0289 GIOStatus   g_io_channel_seek_position    (GIOChannel   *channel,
0290                        gint64        offset,
0291                        GSeekType     type,
0292                        GError      **error);
0293 GLIB_AVAILABLE_IN_ALL
0294 GIOChannel* g_io_channel_new_file         (const gchar  *filename,
0295                        const gchar  *mode,
0296                        GError      **error);
0297
0298 /* Error handling */
0299
0300 GLIB_AVAILABLE_IN_ALL
0301 GQuark          g_io_channel_error_quark      (void);
0302 GLIB_AVAILABLE_IN_ALL
0303 GIOChannelError g_io_channel_error_from_errno (gint en);
0304
0305 /* On Unix, IO channels created with this function for any file
0306  * descriptor or socket.
0307  *
0308  * On Win32, this can be used either for files opened with the MSVCRT
0309  * (the Microsoft run-time C library) _open() or _pipe, including file
0310  * descriptors 0, 1 and 2 (corresponding to stdin, stdout and stderr),
0311  * or for Winsock SOCKETs. If the parameter is a legal file
0312  * descriptor, it is assumed to be such, otherwise it should be a
0313  * SOCKET. This relies on SOCKETs and file descriptors not
0314  * overlapping. If you want to be certain, call either
0315  * g_io_channel_win32_new_fd() or g_io_channel_win32_new_socket()
0316  * instead as appropriate.
0317  *
0318  * The term file descriptor as used in the context of Win32 refers to
0319  * the emulated Unix-like file descriptors MSVCRT provides. The native
0320  * corresponding concept is file HANDLE. There isn't as of yet a way to
0321  * get GIOChannels for Win32 file HANDLEs.
0322  */
0323 GLIB_AVAILABLE_IN_ALL
0324 GIOChannel* g_io_channel_unix_new    (int         fd);
0325 GLIB_AVAILABLE_IN_ALL
0326 gint        g_io_channel_unix_get_fd (GIOChannel *channel);
0327
0328
0329 /* Hook for GClosure / GSource integration. Don't touch */
0330 GLIB_VAR GSourceFuncs g_io_watch_funcs;
0331
0332 #ifdef G_OS_WIN32
0333
0334 /* You can use this "pseudo file descriptor" in a GPollFD to add
0335  * polling for Windows messages. GTK applications should not do that.
0336  */
0337
0338 #define G_WIN32_MSG_HANDLE 19981206
0339
0340 /* Use this to get a GPollFD from a GIOChannel, so that you can call
0341  * g_io_channel_win32_poll(). After calling this you should only use
0342  * g_io_channel_read() to read from the GIOChannel, i.e. never read()
0343  * from the underlying file descriptor. For SOCKETs, it is possible to call
0344  * recv().
0345  */
0346 GLIB_AVAILABLE_IN_ALL
0347 void        g_io_channel_win32_make_pollfd (GIOChannel   *channel,
0348                         GIOCondition  condition,
0349                         GPollFD      *fd);
0350
0351 /* This can be used to wait until at least one of the channels is readable.
0352  * On Unix you would do a select() on the file descriptors of the channels.
0353  */
0354 GLIB_AVAILABLE_IN_ALL
0355 gint        g_io_channel_win32_poll   (GPollFD    *fds,
0356                        gint        n_fds,
0357                        gint        timeout_);
0358
0359 /* Create an IO channel for Windows messages for window handle hwnd. */
0360 #if GLIB_SIZEOF_VOID_P == 8
0361 /* We use gsize here so that it is still an integer type and not a
0362  * pointer, like the guint in the traditional prototype. We can't use
0363  * intptr_t as that is not portable enough.
0364  */
0365 GLIB_AVAILABLE_IN_ALL
0366 GIOChannel *g_io_channel_win32_new_messages (gsize hwnd);
0367 #else
0368 GLIB_AVAILABLE_IN_ALL
0369 GIOChannel *g_io_channel_win32_new_messages (guint hwnd);
0370 #endif
0371
0372 /* Create an IO channel for C runtime (emulated Unix-like) file
0373  * descriptors. After calling g_io_add_watch() on an IO channel
0374  * returned by this function, you shouldn't call read() on the file
0375  * descriptor. This is because adding polling for a file descriptor is
0376  * implemented on Win32 by starting a thread that sits blocked in a
0377  * read() from the file descriptor most of the time. All reads from
0378  * the file descriptor should be done by this internal GLib
0379  * thread. Your code should call only g_io_channel_read_chars().
0380  */
0381 GLIB_AVAILABLE_IN_ALL
0382 GIOChannel* g_io_channel_win32_new_fd (gint         fd);
0383
0384 /* Get the C runtime file descriptor of a channel. */
0385 GLIB_AVAILABLE_IN_ALL
0386 gint        g_io_channel_win32_get_fd (GIOChannel *channel);
0387
0388 /* Create an IO channel for a winsock socket. The parameter should be
0389  * a SOCKET. Contrary to IO channels for file descriptors (on *Win32),
0390  * you can use normal recv() or recvfrom() on sockets even if GLib
0391  * is polling them.
0392  */
0393 GLIB_AVAILABLE_IN_ALL
0394 GIOChannel *g_io_channel_win32_new_socket (gint socket);
0395
0396 GLIB_DEPRECATED_FOR(g_io_channel_win32_new_socket)
0397 GIOChannel *g_io_channel_win32_new_stream_socket (gint socket);
0398
0399 GLIB_AVAILABLE_IN_ALL
0400 void        g_io_channel_win32_set_debug (GIOChannel *channel,
0401                                           gboolean    flag);
0402
0403 #endif
0404
0405 G_END_DECLS
0406
0407 #endif /* __G_IOCHANNEL_H__ */