source: trunk/third/glib2/glib/giochannel.h @ 20721

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