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
38G_BEGIN_DECLS
39
40/* GIOChannel
41 */
42
43typedef struct _GIOChannel	GIOChannel;
44typedef struct _GIOFuncs        GIOFuncs;
45
46typedef 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
56typedef 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
71typedef 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
79typedef enum
80{
81  G_SEEK_CUR,
82  G_SEEK_SET,
83  G_SEEK_END
84} GSeekType;
85
86typedef 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
96typedef 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
108struct _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
139typedef gboolean (*GIOFunc) (GIOChannel   *source,
140			     GIOCondition  condition,
141			     gpointer      data);
142struct _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
169void        g_io_channel_init   (GIOChannel    *channel);
170GIOChannel *g_io_channel_ref    (GIOChannel    *channel);
171void        g_io_channel_unref  (GIOChannel    *channel);
172
173#ifndef G_DISABLE_DEPRECATED
174GIOError    g_io_channel_read   (GIOChannel    *channel,
175			         gchar         *buf,
176			         gsize          count,
177			         gsize         *bytes_read);
178GIOError  g_io_channel_write    (GIOChannel    *channel,
179			         const gchar   *buf,
180			         gsize          count,
181			         gsize         *bytes_written);
182GIOError  g_io_channel_seek     (GIOChannel    *channel,
183			         gint64         offset,
184			         GSeekType      type);
185void      g_io_channel_close    (GIOChannel    *channel);
186#endif /* G_DISABLE_DEPRECATED */
187
188GIOStatus g_io_channel_shutdown (GIOChannel      *channel,
189				 gboolean         flush,
190				 GError         **err);
191guint     g_io_add_watch_full   (GIOChannel      *channel,
192				 gint             priority,
193				 GIOCondition     condition,
194				 GIOFunc          func,
195				 gpointer         user_data,
196				 GDestroyNotify   notify);
197GSource * g_io_create_watch     (GIOChannel      *channel,
198				 GIOCondition     condition);
199guint     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
207void                  g_io_channel_set_buffer_size      (GIOChannel   *channel,
208							 gsize         size);
209gsize                 g_io_channel_get_buffer_size      (GIOChannel   *channel);
210GIOCondition          g_io_channel_get_buffer_condition (GIOChannel   *channel);
211GIOStatus             g_io_channel_set_flags            (GIOChannel   *channel,
212							 GIOFlags      flags,
213							 GError      **error);
214GIOFlags              g_io_channel_get_flags            (GIOChannel   *channel);
215void                  g_io_channel_set_line_term        (GIOChannel   *channel,
216							 const gchar  *line_term,
217							 gint          length);
218G_CONST_RETURN gchar* g_io_channel_get_line_term        (GIOChannel   *channel,
219							 gint         *length);
220void		      g_io_channel_set_buffered		(GIOChannel   *channel,
221							 gboolean      buffered);
222gboolean	      g_io_channel_get_buffered		(GIOChannel   *channel);
223GIOStatus             g_io_channel_set_encoding         (GIOChannel   *channel,
224							 const gchar  *encoding,
225							 GError      **error);
226G_CONST_RETURN gchar* g_io_channel_get_encoding         (GIOChannel   *channel);
227void                  g_io_channel_set_close_on_unref	(GIOChannel   *channel,
228							 gboolean      do_close);
229gboolean              g_io_channel_get_close_on_unref	(GIOChannel   *channel);
230
231
232GIOStatus   g_io_channel_flush            (GIOChannel   *channel,
233					   GError      **error);
234GIOStatus   g_io_channel_read_line        (GIOChannel   *channel,
235					   gchar       **str_return,
236					   gsize        *length,
237					   gsize        *terminator_pos,
238					   GError      **error);
239GIOStatus   g_io_channel_read_line_string (GIOChannel   *channel,
240					   GString      *buffer,
241					   gsize        *terminator_pos,
242					   GError      **error);
243GIOStatus   g_io_channel_read_to_end      (GIOChannel   *channel,
244					   gchar       **str_return,
245					   gsize        *length,
246					   GError      **error);
247GIOStatus   g_io_channel_read_chars       (GIOChannel   *channel,
248					   gchar        *buf,
249					   gsize         count,
250					   gsize        *bytes_read,
251					   GError      **error);
252GIOStatus   g_io_channel_read_unichar     (GIOChannel   *channel,
253					   gunichar     *thechar,
254					   GError      **error);
255GIOStatus   g_io_channel_write_chars      (GIOChannel   *channel,
256					   const gchar  *buf,
257					   gssize        count,
258					   gsize        *bytes_written,
259					   GError      **error);
260GIOStatus   g_io_channel_write_unichar    (GIOChannel   *channel,
261					   gunichar      thechar,
262					   GError      **error);
263GIOStatus   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
271GIOChannel* g_io_channel_new_file         (const gchar  *filename,
272					   const gchar  *mode,
273					   GError      **error);
274
275/* Error handling */
276
277GQuark          g_io_channel_error_quark      (void);
278GIOChannelError 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 */
298GIOChannel* g_io_channel_unix_new    (int         fd);
299gint        g_io_channel_unix_get_fd (GIOChannel *channel);
300
301
302/* Hook for GClosure / GSource integration. Don't touch */
303GLIB_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 */
319void        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 */
326gint        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 */
336GIOChannel *g_io_channel_win32_new_messages (gsize hwnd);
337#else
338GIOChannel *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 */
350GIOChannel* g_io_channel_win32_new_fd (gint         fd);
351
352/* Get the C runtime file descriptor of a channel. */
353gint        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 */
360GIOChannel *g_io_channel_win32_new_socket (gint socket);
361
362#endif
363
364G_END_DECLS
365
366#endif /* __G_IOCHANNEL_H__ */
367