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