giochannel.h

00001 /* GLIB - Library of useful routines for C programming
00002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
00003  * Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.
00004  *
00005  * This library is free software; you can redistribute it and/or
00006  * modify it under the terms of the GNU Lesser General Public
00007  * License as published by the Free Software Foundation; either
00008  * version 2 of the License, or (at your option) any later version.
00009  *
00010  * This library is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013  * Lesser General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU Lesser General Public
00016  * License along with this library; if not, write to the
00017  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00018  * Boston, MA 02111-1307, USA.
00019  */
00020 
00021 /*
00022  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
00023  * file for a list of people on the GLib Team.  See the ChangeLog
00024  * files for a list of changes.  These files are distributed with
00025  * GLib at ftp://ftp.gtk.org/pub/gtk/. 
00026  */
00027 
00028 #ifndef __G_IOCHANNEL_H__
00029 #define __G_IOCHANNEL_H__
00030 
00031 #include <_ansi.h>
00032 #include <glib/gconvert.h>
00033 #include <glib/gmain.h>
00034 #include <glib/gstring.h>
00035 
00036 G_BEGIN_DECLS
00037 
00038 /* GIOChannel
00039  */
00040 
00041 typedef struct _GIOChannel      GIOChannel;
00042 typedef struct _GIOFuncs        GIOFuncs;
00043 
00044 typedef enum
00045 {
00046   G_IO_ERROR_NONE,
00047   G_IO_ERROR_AGAIN,
00048   G_IO_ERROR_INVAL,
00049   G_IO_ERROR_UNKNOWN
00050 } GIOError;
00051 
00052 #define G_IO_CHANNEL_ERROR g_io_channel_error_quark()
00053 
00054 typedef enum
00055 {
00056   /* Derived from errno */
00057   G_IO_CHANNEL_ERROR_FBIG,
00058   G_IO_CHANNEL_ERROR_INVAL,
00059   G_IO_CHANNEL_ERROR_IO,
00060   G_IO_CHANNEL_ERROR_ISDIR,
00061   G_IO_CHANNEL_ERROR_NOSPC,
00062   G_IO_CHANNEL_ERROR_NXIO,
00063   G_IO_CHANNEL_ERROR_OVERFLOW,
00064   G_IO_CHANNEL_ERROR_PIPE,
00065   /* Other */
00066   G_IO_CHANNEL_ERROR_FAILED
00067 } GIOChannelError;
00068 
00069 typedef enum
00070 {
00071   G_IO_STATUS_ERROR,
00072   G_IO_STATUS_NORMAL,
00073   G_IO_STATUS_EOF,
00074   G_IO_STATUS_AGAIN
00075 } GIOStatus;
00076 
00077 typedef enum
00078 {
00079   G_SEEK_CUR,
00080   G_SEEK_SET,
00081   G_SEEK_END
00082 } GSeekType;
00083 
00084 typedef enum
00085 {
00086   G_IO_IN       GLIB_SYSDEF_POLLIN,
00087   G_IO_OUT      GLIB_SYSDEF_POLLOUT,
00088   G_IO_PRI      GLIB_SYSDEF_POLLPRI,
00089   G_IO_ERR      GLIB_SYSDEF_POLLERR,
00090   G_IO_HUP      GLIB_SYSDEF_POLLHUP,
00091   G_IO_NVAL     GLIB_SYSDEF_POLLNVAL
00092 } GIOCondition;
00093 
00094 typedef enum
00095 {
00096   G_IO_FLAG_APPEND = 1 << 0,
00097   G_IO_FLAG_NONBLOCK = 1 << 1,
00098   G_IO_FLAG_IS_READABLE = 1 << 2,       /* Read only flag */
00099   G_IO_FLAG_IS_WRITEABLE = 1 << 3,      /* Read only flag */
00100   G_IO_FLAG_IS_SEEKABLE = 1 << 4,       /* Read only flag */
00101   G_IO_FLAG_MASK = (1 << 5) - 1,
00102   G_IO_FLAG_GET_MASK = G_IO_FLAG_MASK,
00103   G_IO_FLAG_SET_MASK = G_IO_FLAG_APPEND | G_IO_FLAG_NONBLOCK
00104 } GIOFlags;
00105 
00106 struct _GIOChannel
00107 {
00108   /*< private >*/
00109   guint ref_count;
00110   GIOFuncs *funcs;
00111 
00112   gchar *encoding;
00113   GIConv read_cd;
00114   GIConv write_cd;
00115   gchar *line_term;             /* String which indicates the end of a line of text */
00116   guint line_term_len;          /* So we can have null in the line term */
00117 
00118   gsize buf_size;
00119   GString *read_buf;            /* Raw data from the channel */
00120   GString *encoded_read_buf;    /* Channel data converted to UTF-8 */
00121   GString *write_buf;           /* Data ready to be written to the file */
00122   gchar partial_write_buf[6];   /* UTF-8 partial characters, null terminated */
00123 
00124   /* Group the flags together, immediately after partial_write_buf, to save memory */
00125 
00126   guint use_buffer     : 1;     /* The encoding uses the buffers */
00127   guint do_encode      : 1;     /* The encoding uses the GIConv coverters */
00128   guint close_on_unref : 1;     /* Close the channel on final unref */
00129   guint is_readable    : 1;     /* Cached GIOFlag */
00130   guint is_writeable   : 1;     /* ditto */
00131   guint is_seekable    : 1;     /* ditto */
00132 
00133   gpointer reserved1;   
00134   gpointer reserved2;   
00135 };
00136 
00137 typedef gboolean (*GIOFunc) (GIOChannel   *source,
00138                              GIOCondition  condition,
00139                              gpointer      data);
00140 struct _GIOFuncs
00141 {
00142   GIOStatus (*io_read)           (GIOChannel   *channel, 
00143                                   gchar        *buf, 
00144                                   gsize         count,
00145                                   gsize        *bytes_read,
00146                                   GError      **err);
00147   GIOStatus (*io_write)          (GIOChannel   *channel, 
00148                                   const gchar  *buf, 
00149                                   gsize         count,
00150                                   gsize        *bytes_written,
00151                                   GError      **err);
00152   GIOStatus (*io_seek)           (GIOChannel   *channel, 
00153                                   gint64        offset, 
00154                                   GSeekType     type,
00155                                   GError      **err);
00156   GIOStatus  (*io_close)         (GIOChannel   *channel,
00157                                   GError      **err);
00158   GSource*   (*io_create_watch)  (GIOChannel   *channel,
00159                                   GIOCondition  condition);
00160   void       (*io_free)          (GIOChannel   *channel);
00161   GIOStatus  (*io_set_flags)     (GIOChannel   *channel,
00162                                   GIOFlags      flags,
00163                                   GError      **err);
00164   GIOFlags   (*io_get_flags)     (GIOChannel   *channel);
00165 };
00166 
00167 IMPORT_C void        g_io_channel_init   (GIOChannel    *channel);
00168 IMPORT_C GIOChannel *g_io_channel_ref    (GIOChannel    *channel);
00169 IMPORT_C void        g_io_channel_unref  (GIOChannel    *channel);
00170 
00171 #ifndef G_DISABLE_DEPRECATED
00172 IMPORT_C GIOError    g_io_channel_read   (GIOChannel    *channel, 
00173                                  gchar         *buf, 
00174                                  gsize          count,
00175                                  gsize         *bytes_read);
00176 IMPORT_C GIOError  g_io_channel_write    (GIOChannel    *channel, 
00177                                  const gchar   *buf, 
00178                                  gsize          count,
00179                                  gsize         *bytes_written);
00180 IMPORT_C GIOError  g_io_channel_seek     (GIOChannel    *channel,
00181                                  gint64         offset, 
00182                                  GSeekType      type);
00183 IMPORT_C void      g_io_channel_close    (GIOChannel    *channel);
00184 #endif /* G_DISABLE_DEPRECATED */
00185 
00186 IMPORT_C GIOStatus g_io_channel_shutdown (GIOChannel      *channel,
00187                                  gboolean         flush,
00188                                  GError         **err);
00189 IMPORT_C guint     g_io_add_watch_full   (GIOChannel      *channel,
00190                                  gint             priority,
00191                                  GIOCondition     condition,
00192                                  GIOFunc          func,
00193                                  gpointer         user_data,
00194                                  GDestroyNotify   notify);
00195 IMPORT_C GSource * g_io_create_watch     (GIOChannel      *channel,
00196                                  GIOCondition     condition);
00197 IMPORT_C guint     g_io_add_watch        (GIOChannel      *channel,
00198                                  GIOCondition     condition,
00199                                  GIOFunc          func,
00200                                  gpointer         user_data);
00201 
00202 /* character encoding conversion involved functions.
00203  */
00204 
00205 IMPORT_C void                  g_io_channel_set_buffer_size      (GIOChannel   *channel,
00206                                                          gsize         size);
00207 IMPORT_C gsize                 g_io_channel_get_buffer_size      (GIOChannel   *channel);
00208 IMPORT_C GIOCondition          g_io_channel_get_buffer_condition (GIOChannel   *channel);
00209 IMPORT_C GIOStatus             g_io_channel_set_flags            (GIOChannel   *channel,
00210                                                          GIOFlags      flags,
00211                                                          GError      **error);
00212 IMPORT_C GIOFlags              g_io_channel_get_flags            (GIOChannel   *channel);
00213 IMPORT_C void                  g_io_channel_set_line_term        (GIOChannel   *channel,
00214                                                          const gchar  *line_term,
00215                                                          gint          length);
00216 IMPORT_C G_CONST_RETURN gchar* g_io_channel_get_line_term        (GIOChannel   *channel,
00217                                                          gint         *length);
00218 IMPORT_C void                 g_io_channel_set_buffered         (GIOChannel   *channel,
00219                                                          gboolean      buffered);
00220 IMPORT_C gboolean             g_io_channel_get_buffered         (GIOChannel   *channel);
00221 IMPORT_C GIOStatus             g_io_channel_set_encoding         (GIOChannel   *channel,
00222                                                          const gchar  *encoding,
00223                                                          GError      **error);
00224 IMPORT_C G_CONST_RETURN gchar* g_io_channel_get_encoding         (GIOChannel   *channel);
00225 IMPORT_C void                  g_io_channel_set_close_on_unref  (GIOChannel   *channel,
00226                                                          gboolean      do_close);
00227 IMPORT_C gboolean              g_io_channel_get_close_on_unref  (GIOChannel   *channel);
00228 
00229 
00230 IMPORT_C GIOStatus   g_io_channel_flush            (GIOChannel   *channel,
00231                                            GError      **error);
00232 IMPORT_C GIOStatus   g_io_channel_read_line        (GIOChannel   *channel,
00233                                            gchar       **str_return,
00234                                            gsize        *length,
00235                                            gsize        *terminator_pos,
00236                                            GError      **error);
00237 IMPORT_C GIOStatus   g_io_channel_read_line_string (GIOChannel   *channel,
00238                                            GString      *buffer,
00239                                            gsize        *terminator_pos,
00240                                            GError      **error);
00241 IMPORT_C GIOStatus   g_io_channel_read_to_end      (GIOChannel   *channel,
00242                                            gchar       **str_return,
00243                                            gsize        *length,
00244                                            GError      **error);
00245 IMPORT_C GIOStatus   g_io_channel_read_chars       (GIOChannel   *channel,
00246                                            gchar        *buf,
00247                                            gsize         count,
00248                                            gsize        *bytes_read,
00249                                            GError      **error);
00250 IMPORT_C GIOStatus   g_io_channel_read_unichar     (GIOChannel   *channel,
00251                                            gunichar     *thechar,
00252                                            GError      **error);
00253 IMPORT_C GIOStatus   g_io_channel_write_chars      (GIOChannel   *channel,
00254                                            const gchar  *buf,
00255                                            gssize        count,
00256                                            gsize        *bytes_written,
00257                                            GError      **error);
00258 IMPORT_C GIOStatus   g_io_channel_write_unichar    (GIOChannel   *channel,
00259                                            gunichar      thechar,
00260                                            GError      **error);
00261 IMPORT_C GIOStatus   g_io_channel_seek_position    (GIOChannel   *channel,
00262                                            gint64        offset,
00263                                            GSeekType     type,
00264                                            GError      **error);
00265 #ifdef G_OS_WIN32
00266 #define g_io_channel_new_file g_io_channel_new_file_utf8
00267 #endif
00268 
00269 IMPORT_C GIOChannel* g_io_channel_new_file         (const gchar  *filename,
00270                                            const gchar  *mode,
00271                                            GError      **error);
00272 
00273 /* Error handling */
00274 
00275 IMPORT_C GQuark          g_io_channel_error_quark      (void);
00276 IMPORT_C GIOChannelError g_io_channel_error_from_errno (gint en);
00277 
00278 /* On Unix, IO channels created with this function for any file
00279  * descriptor or socket.
00280  *
00281  * On Win32, this can be used either for files opened with the MSVCRT
00282  * (the Microsoft run-time C library) _open() or _pipe, including file
00283  * descriptors 0, 1 and 2 (corresponding to stdin, stdout and stderr),
00284  * or for Winsock SOCKETs. If the parameter is a legal file
00285  * descriptor, it is assumed to be such, otherwise it should be a
00286  * SOCKET. This relies on SOCKETs and file descriptors not
00287  * overlapping. If you want to be certain, call either
00288  * g_io_channel_win32_new_fd() or g_io_channel_win32_new_socket()
00289  * instead as appropriate.
00290  *
00291  * The term file descriptor as used in the context of Win32 refers to
00292  * the emulated Unix-like file descriptors MSVCRT provides. The native
00293  * corresponding concept is file HANDLE. There isn't as of yet a way to
00294  * get GIOChannels for Win32 file HANDLEs.
00295  */
00296 IMPORT_C GIOChannel* g_io_channel_unix_new    (int         fd);
00297 IMPORT_C gint        g_io_channel_unix_get_fd (GIOChannel *channel);
00298 
00299 
00300 /* Hook for GClosure / GSource integration. Don't touch */
00301 GLIB_VAR GSourceFuncs g_io_watch_funcs;
00302 
00303 #ifdef SYMBIAN
00304 IMPORT_C GSourceFuncs * _g_io_watch_funcs();
00305 #endif /* SYMBIAN */
00306 
00307 #ifdef G_OS_WIN32
00308 
00309 /* You can use this "pseudo file descriptor" in a GPollFD to add
00310  * polling for Windows messages. GTK applications should not do that.
00311  */
00312 
00313 #define G_WIN32_MSG_HANDLE 19981206
00314 
00315 /* Use this to get a GPollFD from a GIOChannel, so that you can call
00316  * g_io_channel_win32_poll(). After calling this you should only use
00317  * g_io_channel_read() to read from the GIOChannel, i.e. never read()
00318  * from the underlying file descriptor. For SOCKETs, it is possible to call
00319  * recv().
00320  */
00321 void        g_io_channel_win32_make_pollfd (GIOChannel   *channel,
00322                                             GIOCondition  condition,
00323                                             GPollFD      *fd);
00324 
00325 /* This can be used to wait a until at least one of the channels is readable.
00326  * On Unix you would do a select() on the file descriptors of the channels.
00327  */
00328 gint        g_io_channel_win32_poll   (GPollFD    *fds,
00329                                        gint        n_fds,
00330                                        gint        timeout_);
00331 
00332 /* Create an IO channel for Windows messages for window handle hwnd. */
00333 GIOChannel *g_io_channel_win32_new_messages (guint hwnd);
00334 
00335 /* Create an IO channel for C runtime (emulated Unix-like) file
00336  * descriptors. After calling g_io_add_watch() on a IO channel
00337  * returned by this function, you shouldn't call read() on the file
00338  * descriptor. This is because adding polling for a file descriptor is
00339  * implemented on Win32 by starting a thread that sits blocked in a
00340  * read() from the file descriptor most of the time. All reads from
00341  * the file descriptor should be done by this internal GLib
00342  * thread. Your code should call only g_io_channel_read().
00343  */
00344 GIOChannel* g_io_channel_win32_new_fd (gint         fd);
00345 
00346 /* Get the C runtime file descriptor of a channel. */
00347 gint        g_io_channel_win32_get_fd (GIOChannel *channel);
00348 
00349 /* Create an IO channel for a winsock socket. The parameter should be
00350  * a SOCKET. Contrary to IO channels for file descriptors (on *Win32),
00351  * you can use normal recv() or recvfrom() on sockets even if GLib
00352  * is polling them.
00353  */
00354 GIOChannel *g_io_channel_win32_new_socket (gint socket);
00355 
00356 #endif
00357 
00358 G_END_DECLS
00359 
00360 #endif /* __G_IOCHANNEL_H__ */