summaryrefslogtreecommitdiff
path: root/glib/src/iochannel.hg
blob: f04a14b9dab550f82aceb1ee2999f7123886a207 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
/* Copyright (C) 2002 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

_DEFS(glibmm,glib)

#include <glibmmconfig.h>
#include <glib.h> //For the GIOChannel enum values.
#include <glibmm/error.h>
#include <glibmm/refptr.h>
#include <glibmm/ustring.h>
#include <sigc++/sigc++.h>
#include <string>

#ifndef DOXYGEN_SHOULD_SKIP_THIS
extern "C" { typedef struct _GIOChannel GIOChannel; }
#endif

namespace Glib
{

class Source;
class IOSource;

_WRAP_ENUM(SeekType, GSeekType, NO_GTYPE, s#^SEEK_#SEEK_TYPE_#)
_WRAP_ENUM(IOStatus, GIOStatus, NO_GTYPE)
_WRAP_ENUM(IOFlags, GIOFlags, NO_GTYPE)


/** A bitwise combination representing an I/O condition to watch for on an
 * event source.
 * The flags correspond to those used by the <tt>%poll()</tt> system call
 * on UNIX (see <tt>man 2 poll</tt>).  To test for individual flags, do
 * something like this:
 * @code
 * if((condition & Glib::IO_OUT) != 0)
 *   do_some_output();
 * @endcode
 */
_WRAP_ENUM(IOCondition, GIOCondition, NO_GTYPE)

/** Exception class for IOChannel errors.
 */
_WRAP_GERROR(IOChannelError, GIOChannelError, G_IO_CHANNEL_ERROR, NO_GTYPE,
    s#^INVAL$#INVALID_ARGUMENT#,
    s#^ISDIR$#IS_DIRECTORY#,
    s#^PIPE$#BROKEN_PIPE#,
    s#^NOSPC$#NO_SPACE_LEFT#,
    s#^NXIO$#NO_SUCH_DEVICE#,
    s#^ACCES$#ACCESS_DENIED#,
    s#^FBIG$#FILE_TOO_BIG#,
    s#^IO$#IO_ERROR#,
    s#^OVERFLOW$#OVERFLOWN#)

#ifndef DOXYGEN_SHOULD_SKIP_THIS
class GlibmmIOChannel;
#endif

/** IOChannel aims to provide portable I/O support for files, pipes
 * and sockets, and to integrate them with the GLib main event loop.
 *
 * Note that IOChannels implement an automatic implicit character set
 * conversion to the data stream, and usually will not pass by default
 * binary data unchanged.  To set the encoding of the channel, use e.g.
 * set_encoding("ISO-8859-15"). To set the channel to no encoding, use
 * set_encoding() without any arguments.
 *
 * You can create an IOChannel with one of the static create methods, or
 * implement one yourself, in which case you have to 1)&nbsp;override all
 * _vfunc() members. 2)&nbsp;set the GIOChannel flags in your constructor.
 *
 * @note This feature of being able to implement a custom Glib::IOChannel is
 * deprecated in glibmm&nbsp;2.2.  The vfunc interface has not yet stabilized
 * enough to allow that -- the C++ wrapper went in by pure accident.  Besides,
 * it isn't terribly useful either.  Thus please refrain from overriding any
 * IOChannel vfuncs.
 */
class IOChannel : public sigc::trackable
{
  _CLASS_GENERIC(IOChannel, GIOChannel)

  dnl // We can't support get_fd() properly because it is impossible
  dnl // to detect the specific GIOChannel type at runtime.
  _IGNORE(g_io_channel_unix_get_fd, g_io_channel_win32_get_fd)

  dnl // deprecated or internal
  _IGNORE(g_io_channel_seek, g_io_channel_close, g_io_channel_read,
          g_io_channel_write, g_io_channel_win32_make_pollfd)

public:
  virtual ~IOChannel();

  /** Open a file @a filename as an I/O channel using mode @a mode.
   * This channel will be closed when the last reference to it is dropped,
   * so there is no need to call close() (though doing so will not cause
   * problems, as long as no attempt is made to access the channel after
   * it is closed).
   * @param filename The name of the file to open.
   * @param mode One of <tt>"r"</tt>, <tt>"w"</tt>, <tt>"a"</tt>,
   *  <tt>"r+"</tt>, <tt>"w+"</tt>, <tt>"a+"</tt>. These have the
   *  same meaning as in <tt>fopen()</tt>.
   * @return An IOChannel for the opened file.
   * @throw Glib::FileError
   */
  static Glib::RefPtr<IOChannel> create_from_file(const std::string& filename, const std::string& mode);
  _IGNORE(g_io_channel_new_file)

  /** Creates an I/O channel from a file descriptor.
   * On Unix, IOChannels created with this function work for any file
   * descriptor or socket.
   *
   * On Win32, this can be used either for files opened with the MSVCRT (the
   * Microsoft run-time C library) <tt>_open()</tt> or <tt>_pipe()</tt>,
   * including file descriptors 0, 1 and 2 (corresponding to <tt>stdin</tt>,
   * <tt>stdout</tt> and <tt>stderr</tt>), or for Winsock <tt>SOCKET</tt>s. If
   * the parameter is a legal file descriptor, it is assumed to be such,
   * otherwise it should be a <tt>SOCKET</tt>. This relies on <tt>SOCKET</tt>s
   * and file descriptors not overlapping. If you want to be certain, call
   * either create_from_win32_fd() or create_from_win32_socket() instead as
   * appropriate.
   *
   * The term file descriptor as used in the context of Win32 refers to the
   * emulated Unix-like file descriptors MSVCRT provides. The native
   * corresponding concept is file <tt>HANDLE</tt>. There isn't as of yet
   * a way to get IOChannels for Win32 file <tt>HANDLE</tt>s.
   */
  static Glib::RefPtr<IOChannel> create_from_fd(int fd);
  _IGNORE(g_io_channel_unix_new)

/* defined(DOXYGEN_SHOULD_SKIP_THIS) actually does the opposite of what it looks like... */
#if defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS)

  /** Create an I/O channel for C runtime (emulated Unix-like) file descriptors.
   * After calling add_watch() on a I/O channel returned by this function, you
   * shouldn't call read() on the file descriptor. This is because adding
   * polling for a file descriptor is implemented on Win32 by starting a thread
   * that sits blocked in a <tt>%read()</tt> from the file descriptor most of
   * the time.  All reads from the file descriptor should be done by this
   * internal GLib thread. Your code should call only IOChannel::read().
   */
  static Glib::RefPtr<IOChannel> create_from_win32_fd(int fd);
  _IGNORE(g_io_channel_win32_new_fd)

  /** Create an I/O channel for a winsock socket. The parameter should be a
   * <tt>SOCKET</tt>. Contrary to I/O channels for file descriptors (on Win32),
   * you can use normal <tt>recv()</tt> or <tt>recvfrom()</tt> on sockets even
   * if GLib is polling them.
   */
  static Glib::RefPtr<IOChannel> create_from_win32_socket(int socket);
  _IGNORE(g_io_channel_win32_new_socket)

#endif /* defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS) */

  /** Read a single UCS-4 character.
   * @retval thechar The Unicode character.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  _WRAP_METHOD(IOStatus read(gunichar& thechar), g_io_channel_read_unichar, errthrow)

  /** Read a character sequence into memory.
   * @param buf A buffer to read data into.
   * @param count The size of the buffer in bytes.  Note that the buffer may
   * not be complelely filled even if there is data in the buffer if the
   * remaining data is not a complete character.
   * @retval bytes_read The number of bytes read.  This may be zero even on
   * success if @a count < 6 and the channel's encoding is not <tt>""</tt>.
   * This indicates that the next UTF-8 character is too wide for the buffer.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  _WRAP_METHOD(IOStatus read(char* buf, gsize count, gsize& bytes_read),
               g_io_channel_read_chars, errthrow)

  /** Read a maximum of @a count bytes into @a str.
   * @param count The maximum number of bytes to read.
   * @retval str The characters that have been read.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  IOStatus read(Glib::ustring& str, gsize count);

  /** Read a whole line.
   * Reads until the line separator is found, which is included
   * in the result string.
   * @retval line The line that was read.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  IOStatus read_line(Glib::ustring& line);
  _IGNORE(g_io_channel_read_line, g_io_channel_read_line_string)

  /** Reads all the remaining data from the file.
   * @retval str The resulting string.
   * @return Glib::IO_STATUS_NORMAL on success. This function never
   *  returns Glib::IO_STATUS_EOF.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  IOStatus read_to_end(Glib::ustring& str);
  _IGNORE(g_io_channel_read_to_end)

  /** Write a string to the I/O channel.
   * Note that this method does not return the number of characters written.
   * If the channel is blocking and the returned value is
   * Glib::IO_STATUS_NORMAL, the whole string was written.
   * @param str the string to write.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  IOStatus write(const Glib::ustring& str);

  /** Write a memory area of @a count bytes to the I/O channel.
   * @param buf The start of the memory area.
   * @param count The number of bytes to write.
   * @retval bytes_written The number of bytes written to the channel.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  _WRAP_METHOD(IOStatus write(const char* buf, gssize count, gsize& bytes_written),
               g_io_channel_write_chars, errthrow)

  /** Write a single UCS-4 character to the I/O channel.
   * @param unichar The character to write.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  _WRAP_METHOD(IOStatus write(gunichar unichar), g_io_channel_write_unichar, errthrow)

  /** Seek the I/O channel to a specific position.
   * @param offset The offset in bytes from the position specified by @a type.
   * @param type A SeekType. The type Glib::SEEK_TYPE_CUR is only allowed in
   * those cases where a call to set_encoding() is allowed. See the
   * documentation for set_encoding() for details.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  _WRAP_METHOD(IOStatus seek(gint64 offset, SeekType type = SEEK_TYPE_SET),
               g_io_channel_seek_position, errthrow)

  /** Flush the buffers of the I/O channel.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   * @throw Glib::ConvertError
   */
  _WRAP_METHOD(IOStatus flush(), g_io_channel_flush, errthrow)

  /** Close the I/O channel.
   * Any pending data to be written will be flushed if @a flush is <tt>true</tt>.
   * The channel will not be freed until the last reference is dropped.
   * Accessing the channel after closing it is considered an error.
   * @param flush Whether to flush() pending data before closing the channel.
   * @return The status of the operation.
   * @throw Glib::IOChannelError
   */
  _WRAP_METHOD(IOStatus close(bool flush = true), g_io_channel_shutdown, errthrow)

  /** Get the IOChannel internal buffer size.
   * @return The buffer size.
   */
  _WRAP_METHOD(gsize get_buffer_size() const, g_io_channel_get_buffer_size)

  /** Set the internal IOChannel buffer size.
   * @param size The buffer size the IOChannel should use.
   */
  _WRAP_METHOD(void set_buffer_size(gsize size), g_io_channel_set_buffer_size)

  /** Get the current flags for a IOChannel, including read-only
   * flags such as Glib::IO_FLAG_IS_READABLE.
   *
   * The values of the flags Glib::IO_FLAG_IS_READABLE and
   * Glib::IO_FLAG_IS_WRITEABLE are cached for internal use by the channel when
   * it is created.  If they should change at some later point (e.g. partial
   * shutdown of a socket with the UNIX <tt>shutdown()</tt> function), the user
   * should immediately call get_flags() to update the internal values of these
   * flags.
   * @return Bitwise combination of the flags set on the channel.
   */
  _WRAP_METHOD(IOFlags get_flags() const, g_io_channel_get_flags)

  /** Set flags on the IOChannel.
   * @param flags Bitwise combination of the flags to set.
   * @return The operation result code.
   * @throw Glib::IOChannelError
   */
  _WRAP_METHOD(IOStatus set_flags(IOFlags flags), g_io_channel_set_flags, errthrow)

  /** Set the buffering status of the I/O channel.
   * The buffering state can only be set if the channel's encoding is
   * <tt>""</tt>. For any other encoding, the channel must be buffered.
   *
   * A buffered channel can only be set unbuffered if the channel's internal
   * buffers have been flushed. Newly created channels or channels which have
   * returned Glib::IO_STATUS_EOF not require such a flush. For write-only
   * channels, a call to flush() is sufficient. For all other channels, the
   * buffers may be flushed by a call to seek().  This includes the possibility
   * of seeking with seek type Glib::SEEK_TYPE_CUR and an offset of zero. Note
   * that this means that socket-based channels cannot be set unbuffered once
   * they have had data read from them.
   *
   * The default state of the channel is buffered.
   *
   * @param buffered Whether to set the channel buffered or unbuffered.
   */
  _WRAP_METHOD(void set_buffered(bool buffered), g_io_channel_set_buffered)

  /** Get the buffering status of the I/O channel.
   * @return The buffering status of the channel.
   */
  _WRAP_METHOD(bool get_buffered() const, g_io_channel_get_buffered)

  /** Returns an IOCondition depending on whether there is data to be
   * read/space to write data in the internal buffers in the I/O channel.
   * Only the flags Glib::IO_IN and Glib::IO_OUT may be set.
   * @return Bitwise combination of Glib::IOCondition flags.
   */
  _WRAP_METHOD(IOCondition get_buffer_condition() const, g_io_channel_get_buffer_condition)

  /** Returns whether the file/socket/whatever associated with the I/O channel
   * will be closed when the channel receives its final unref and is destroyed.
   * The default value of this is <tt>true</tt> for channels created by
   * create_from_file(), and <tt>false</tt> for all other channels.
   * @return Whether the channel will be closed on the final unref of the
   * IOChannel object.
   */
  _WRAP_METHOD(bool get_close_on_unref() const, g_io_channel_get_close_on_unref)

  /** Setting this flag to <tt>true</tt> for a channel you have already closed
   * can cause problems.
   * @param do_close Whether to close the channel on the final unref of the
   * IOChannel object.  The default value of this is <tt>true</tt> for channels
   * created by create_from_file(), and <tt>false</tt> for all other channels.
   */
  _WRAP_METHOD(void set_close_on_unref(bool do_close), g_io_channel_set_close_on_unref)

  /** Sets the encoding for the input/output of the channel.
   * The internal encoding is always UTF-8.  The default encoding for the
   * external file is UTF-8.  The encoding <tt>""</tt> is safe to use with
   * binary data.
   *
   * The encoding can only be set if one of the following conditions
   * is true:
   *
   * -# The channel was just created, and has not been written to or read from
   *  yet.
   * -# The channel is write-only.
   * -# The channel is a file, and the file pointer was just repositioned by a
   *  call to seek_position().  (This flushes all the internal buffers.)
   * -# The current encoding is <tt>""</tt> or UTF-8.
   * -# One of the read methods has just returned Glib::IO_STATUS_EOF (or, in
   *  the case of read_to_end(), Glib::IO_STATUS_NORMAL).
   * -# The read() method has returned Glib::IO_STATUS_AGAIN or thrown
   *  a Glib::Error exception.  This may be useful in the case of
   *  ConvertError::ILLEGAL_SEQUENCE.  Returning one of these statuses
   *  from read_line() or read_to_end() does <em>not</em> guarantee that
   *  the encoding can be changed.
   *
   * Channels which do not meet one of the above conditions cannot call
   * seek_position() with a seek type of Glib::SEEK_TYPE_CUR and, if they
   * are "seekable", cannot call write() after calling one of the API
   * "read" methods.
   *
   * @param encoding The encoding name, or <tt>""</tt> for binary.
   * @return Glib::IO_STATUS_NORMAL if the encoding was successfully set.
   * @throw Glib::IOChannelError
   */
  IOStatus set_encoding(const std::string& encoding = std::string());
  _IGNORE(g_io_channel_set_encoding)

  /** Get the encoding of the I/O channel.
   * @return The current encoding of the channel.
   */
  std::string get_encoding() const;
  _IGNORE(g_io_channel_get_encoding)

  void set_line_term(const std::string& term = std::string());
  _IGNORE(g_io_channel_set_line_term)

  std::string get_line_term() const;
  _IGNORE(g_io_channel_get_line_term)

  /** Creates an IOSource object.
   * Create a slot from a function to be called when condition is met
   * for the channel with sigc::ptr_fun() or sigc::mem_fun() and pass
   * it into the connect() function of the returned IOSource object.
   * Polling of the channel will start when you attach a MainContext
   * object to the returned IOSource object using its attach() function.
   *
   * Glib::signal_io().connect() is a simpler interface to the same
   * functionality, for the case where you want to add the source to the
   * default main context.
   * @param condition The condition to watch for.
   * @return An IOSource object that can be polled from a MainContext's event loop.
   */
  Glib::RefPtr<IOSource> create_watch(IOCondition condition);
  _IGNORE(g_io_channel_create_watch)

  virtual void reference()   const;
  virtual void unreference() const;
  _IGNORE(g_io_channel_ref, g_io_channel_unref)

  GIOChannel*       gobj()       { return gobject_; }
  const GIOChannel* gobj() const { return gobject_; }

protected:
  GIOChannel* gobject_;

  /** Constructor that should be used by derived classes.
   * Use this constructor if you want to inherit from IOChannel.
   * It will set up a GIOChannel that will call the vfuncs of your 
   * class even if it is being used from C code, and it will keep
   * a reference to the C++ code while the GIOChannel exists.
   */
  IOChannel();
  _IGNORE(g_io_channel_init)

#ifndef DOXYGEN_SHOULD_SKIP_THIS
  IOChannel(GIOChannel* gobject, bool take_copy);
#endif

  virtual IOStatus read_vfunc(char* buf, gsize count, gsize& bytes_read);
  virtual IOStatus write_vfunc(const char* buf, gsize count, gsize& bytes_written);
  virtual IOStatus seek_vfunc(gint64 offset, SeekType type);
  virtual IOStatus close_vfunc();
  virtual IOStatus set_flags_vfunc(IOFlags flags);
  virtual IOFlags  get_flags_vfunc();
  virtual Glib::RefPtr<Glib::Source> create_watch_vfunc(IOCondition cond);

#ifndef DOXYGEN_SHOULD_SKIP_THIS
  friend class Glib::GlibmmIOChannel;
#endif
};

Glib::RefPtr<IOChannel> wrap(GIOChannel* gobject, bool take_copy = false);

} // namespace Glib