1 /* GLIB - Library of useful routines for C programming 2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; if not, write to the 16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330, 17 * Boston, MA 02111-1307, USA. 18 */ 19 20 /* 21 * Modified by the GLib Team and others 1997-2000. See the AUTHORS 22 * file for a list of people on the GLib Team. See the ChangeLog 23 * files for a list of changes. These files are distributed with 24 * GLib at ftp://ftp.gtk.org/pub/gtk/. 25 */ 26 27 #if defined(G_DISABLE_SINGLE_INCLUDES) && !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) 28 #error "Only <glib.h> can be included directly." 29 #endif 30 31 #ifndef __G_IOCHANNEL_H__ 32 #define __G_IOCHANNEL_H__ 33 34 #include <glib/gconvert.h> 35 #include <glib/gmain.h> 36 #include <glib/gstring.h> 37 38 G_BEGIN_DECLS 39 40 /* GIOChannel 41 */ 42 43 typedef struct _GIOChannel GIOChannel; 44 typedef struct _GIOFuncs GIOFuncs; 45 46 typedef enum 47 { 48 G_IO_ERROR_NONE, 49 G_IO_ERROR_AGAIN, 50 G_IO_ERROR_INVAL, 51 G_IO_ERROR_UNKNOWN 52 } GIOError; 53 54 #define G_IO_CHANNEL_ERROR g_io_channel_error_quark() 55 56 typedef enum 57 { 58 /* Derived from errno */ 59 G_IO_CHANNEL_ERROR_FBIG, 60 G_IO_CHANNEL_ERROR_INVAL, 61 G_IO_CHANNEL_ERROR_IO, 62 G_IO_CHANNEL_ERROR_ISDIR, 63 G_IO_CHANNEL_ERROR_NOSPC, 64 G_IO_CHANNEL_ERROR_NXIO, 65 G_IO_CHANNEL_ERROR_OVERFLOW, 66 G_IO_CHANNEL_ERROR_PIPE, 67 /* Other */ 68 G_IO_CHANNEL_ERROR_FAILED 69 } GIOChannelError; 70 71 typedef enum 72 { 73 G_IO_STATUS_ERROR, 74 G_IO_STATUS_NORMAL, 75 G_IO_STATUS_EOF, 76 G_IO_STATUS_AGAIN 77 } GIOStatus; 78 79 typedef enum 80 { 81 G_SEEK_CUR, 82 G_SEEK_SET, 83 G_SEEK_END 84 } GSeekType; 85 86 typedef enum 87 { 88 G_IO_IN GLIB_SYSDEF_POLLIN, 89 G_IO_OUT GLIB_SYSDEF_POLLOUT, 90 G_IO_PRI GLIB_SYSDEF_POLLPRI, 91 G_IO_ERR GLIB_SYSDEF_POLLERR, 92 G_IO_HUP GLIB_SYSDEF_POLLHUP, 93 G_IO_NVAL GLIB_SYSDEF_POLLNVAL 94 } GIOCondition; 95 96 typedef enum 97 { 98 G_IO_FLAG_APPEND = 1 << 0, 99 G_IO_FLAG_NONBLOCK = 1 << 1, 100 G_IO_FLAG_IS_READABLE = 1 << 2, /* Read only flag */ 101 G_IO_FLAG_IS_WRITEABLE = 1 << 3, /* Read only flag */ 102 G_IO_FLAG_IS_SEEKABLE = 1 << 4, /* Read only flag */ 103 G_IO_FLAG_MASK = (1 << 5) - 1, 104 G_IO_FLAG_GET_MASK = G_IO_FLAG_MASK, 105 G_IO_FLAG_SET_MASK = G_IO_FLAG_APPEND | G_IO_FLAG_NONBLOCK 106 } GIOFlags; 107 108 struct _GIOChannel 109 { 110 /*< private >*/ 111 gint ref_count; 112 GIOFuncs *funcs; 113 114 gchar *encoding; 115 GIConv read_cd; 116 GIConv write_cd; 117 gchar *line_term; /* String which indicates the end of a line of text */ 118 guint line_term_len; /* So we can have null in the line term */ 119 120 gsize buf_size; 121 GString *read_buf; /* Raw data from the channel */ 122 GString *encoded_read_buf; /* Channel data converted to UTF-8 */ 123 GString *write_buf; /* Data ready to be written to the file */ 124 gchar partial_write_buf[6]; /* UTF-8 partial characters, null terminated */ 125 126 /* Group the flags together, immediately after partial_write_buf, to save memory */ 127 128 guint use_buffer : 1; /* The encoding uses the buffers */ 129 guint do_encode : 1; /* The encoding uses the GIConv coverters */ 130 guint close_on_unref : 1; /* Close the channel on final unref */ 131 guint is_readable : 1; /* Cached GIOFlag */ 132 guint is_writeable : 1; /* ditto */ 133 guint is_seekable : 1; /* ditto */ 134 135 gpointer reserved1; 136 gpointer reserved2; 137 }; 138 139 typedef gboolean (*GIOFunc) (GIOChannel *source, 140 GIOCondition condition, 141 gpointer data); 142 struct _GIOFuncs 143 { 144 GIOStatus (*io_read) (GIOChannel *channel, 145 gchar *buf, 146 gsize count, 147 gsize *bytes_read, 148 GError **err); 149 GIOStatus (*io_write) (GIOChannel *channel, 150 const gchar *buf, 151 gsize count, 152 gsize *bytes_written, 153 GError **err); 154 GIOStatus (*io_seek) (GIOChannel *channel, 155 gint64 offset, 156 GSeekType type, 157 GError **err); 158 GIOStatus (*io_close) (GIOChannel *channel, 159 GError **err); 160 GSource* (*io_create_watch) (GIOChannel *channel, 161 GIOCondition condition); 162 void (*io_free) (GIOChannel *channel); 163 GIOStatus (*io_set_flags) (GIOChannel *channel, 164 GIOFlags flags, 165 GError **err); 166 GIOFlags (*io_get_flags) (GIOChannel *channel); 167 }; 168 169 void g_io_channel_init (GIOChannel *channel); 170 GIOChannel *g_io_channel_ref (GIOChannel *channel); 171 void g_io_channel_unref (GIOChannel *channel); 172 173 #ifndef G_DISABLE_DEPRECATED 174 GIOError g_io_channel_read (GIOChannel *channel, 175 gchar *buf, 176 gsize count, 177 gsize *bytes_read); 178 GIOError g_io_channel_write (GIOChannel *channel, 179 const gchar *buf, 180 gsize count, 181 gsize *bytes_written); 182 GIOError g_io_channel_seek (GIOChannel *channel, 183 gint64 offset, 184 GSeekType type); 185 void g_io_channel_close (GIOChannel *channel); 186 #endif /* G_DISABLE_DEPRECATED */ 187 188 GIOStatus g_io_channel_shutdown (GIOChannel *channel, 189 gboolean flush, 190 GError **err); 191 guint g_io_add_watch_full (GIOChannel *channel, 192 gint priority, 193 GIOCondition condition, 194 GIOFunc func, 195 gpointer user_data, 196 GDestroyNotify notify); 197 GSource * g_io_create_watch (GIOChannel *channel, 198 GIOCondition condition); 199 guint g_io_add_watch (GIOChannel *channel, 200 GIOCondition condition, 201 GIOFunc func, 202 gpointer user_data); 203 204 /* character encoding conversion involved functions. 205 */ 206 207 void g_io_channel_set_buffer_size (GIOChannel *channel, 208 gsize size); 209 gsize g_io_channel_get_buffer_size (GIOChannel *channel); 210 GIOCondition g_io_channel_get_buffer_condition (GIOChannel *channel); 211 GIOStatus g_io_channel_set_flags (GIOChannel *channel, 212 GIOFlags flags, 213 GError **error); 214 GIOFlags g_io_channel_get_flags (GIOChannel *channel); 215 void g_io_channel_set_line_term (GIOChannel *channel, 216 const gchar *line_term, 217 gint length); 218 G_CONST_RETURN gchar* g_io_channel_get_line_term (GIOChannel *channel, 219 gint *length); 220 void g_io_channel_set_buffered (GIOChannel *channel, 221 gboolean buffered); 222 gboolean g_io_channel_get_buffered (GIOChannel *channel); 223 GIOStatus g_io_channel_set_encoding (GIOChannel *channel, 224 const gchar *encoding, 225 GError **error); 226 G_CONST_RETURN gchar* g_io_channel_get_encoding (GIOChannel *channel); 227 void g_io_channel_set_close_on_unref (GIOChannel *channel, 228 gboolean do_close); 229 gboolean g_io_channel_get_close_on_unref (GIOChannel *channel); 230 231 232 GIOStatus g_io_channel_flush (GIOChannel *channel, 233 GError **error); 234 GIOStatus g_io_channel_read_line (GIOChannel *channel, 235 gchar **str_return, 236 gsize *length, 237 gsize *terminator_pos, 238 GError **error); 239 GIOStatus g_io_channel_read_line_string (GIOChannel *channel, 240 GString *buffer, 241 gsize *terminator_pos, 242 GError **error); 243 GIOStatus g_io_channel_read_to_end (GIOChannel *channel, 244 gchar **str_return, 245 gsize *length, 246 GError **error); 247 GIOStatus g_io_channel_read_chars (GIOChannel *channel, 248 gchar *buf, 249 gsize count, 250 gsize *bytes_read, 251 GError **error); 252 GIOStatus g_io_channel_read_unichar (GIOChannel *channel, 253 gunichar *thechar, 254 GError **error); 255 GIOStatus g_io_channel_write_chars (GIOChannel *channel, 256 const gchar *buf, 257 gssize count, 258 gsize *bytes_written, 259 GError **error); 260 GIOStatus g_io_channel_write_unichar (GIOChannel *channel, 261 gunichar thechar, 262 GError **error); 263 GIOStatus g_io_channel_seek_position (GIOChannel *channel, 264 gint64 offset, 265 GSeekType type, 266 GError **error); 267 #ifdef G_OS_WIN32 268 #define g_io_channel_new_file g_io_channel_new_file_utf8 269 #endif 270 271 GIOChannel* g_io_channel_new_file (const gchar *filename, 272 const gchar *mode, 273 GError **error); 274 275 /* Error handling */ 276 277 GQuark g_io_channel_error_quark (void); 278 GIOChannelError g_io_channel_error_from_errno (gint en); 279 280 /* On Unix, IO channels created with this function for any file 281 * descriptor or socket. 282 * 283 * On Win32, this can be used either for files opened with the MSVCRT 284 * (the Microsoft run-time C library) _open() or _pipe, including file 285 * descriptors 0, 1 and 2 (corresponding to stdin, stdout and stderr), 286 * or for Winsock SOCKETs. If the parameter is a legal file 287 * descriptor, it is assumed to be such, otherwise it should be a 288 * SOCKET. This relies on SOCKETs and file descriptors not 289 * overlapping. If you want to be certain, call either 290 * g_io_channel_win32_new_fd() or g_io_channel_win32_new_socket() 291 * instead as appropriate. 292 * 293 * The term file descriptor as used in the context of Win32 refers to 294 * the emulated Unix-like file descriptors MSVCRT provides. The native 295 * corresponding concept is file HANDLE. There isn't as of yet a way to 296 * get GIOChannels for Win32 file HANDLEs. 297 */ 298 GIOChannel* g_io_channel_unix_new (int fd); 299 gint g_io_channel_unix_get_fd (GIOChannel *channel); 300 301 302 /* Hook for GClosure / GSource integration. Don't touch */ 303 GLIB_VAR GSourceFuncs g_io_watch_funcs; 304 305 #ifdef G_OS_WIN32 306 307 /* You can use this "pseudo file descriptor" in a GPollFD to add 308 * polling for Windows messages. GTK applications should not do that. 309 */ 310 311 #define G_WIN32_MSG_HANDLE 19981206 312 313 /* Use this to get a GPollFD from a GIOChannel, so that you can call 314 * g_io_channel_win32_poll(). After calling this you should only use 315 * g_io_channel_read() to read from the GIOChannel, i.e. never read() 316 * from the underlying file descriptor. For SOCKETs, it is possible to call 317 * recv(). 318 */ 319 void g_io_channel_win32_make_pollfd (GIOChannel *channel, 320 GIOCondition condition, 321 GPollFD *fd); 322 323 /* This can be used to wait a until at least one of the channels is readable. 324 * On Unix you would do a select() on the file descriptors of the channels. 325 */ 326 gint g_io_channel_win32_poll (GPollFD *fds, 327 gint n_fds, 328 gint timeout_); 329 330 /* Create an IO channel for Windows messages for window handle hwnd. */ 331 #if GLIB_SIZEOF_VOID_P == 8 332 /* We use gsize here so that it is still an integer type and not a 333 * pointer, like the guint in the traditional prototype. We can't use 334 * intptr_t as that is not portable enough. 335 */ 336 GIOChannel *g_io_channel_win32_new_messages (gsize hwnd); 337 #else 338 GIOChannel *g_io_channel_win32_new_messages (guint hwnd); 339 #endif 340 341 /* Create an IO channel for C runtime (emulated Unix-like) file 342 * descriptors. After calling g_io_add_watch() on a IO channel 343 * returned by this function, you shouldn't call read() on the file 344 * descriptor. This is because adding polling for a file descriptor is 345 * implemented on Win32 by starting a thread that sits blocked in a 346 * read() from the file descriptor most of the time. All reads from 347 * the file descriptor should be done by this internal GLib 348 * thread. Your code should call only g_io_channel_read_chars(). 349 */ 350 GIOChannel* g_io_channel_win32_new_fd (gint fd); 351 352 /* Get the C runtime file descriptor of a channel. */ 353 gint g_io_channel_win32_get_fd (GIOChannel *channel); 354 355 /* Create an IO channel for a winsock socket. The parameter should be 356 * a SOCKET. Contrary to IO channels for file descriptors (on *Win32), 357 * you can use normal recv() or recvfrom() on sockets even if GLib 358 * is polling them. 359 */ 360 GIOChannel *g_io_channel_win32_new_socket (gint socket); 361 362 #endif 363 364 G_END_DECLS 365 366 #endif /* __G_IOCHANNEL_H__ */ 367