libs/glibmm2/glibmm/iochannel.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GLIBMM_IOCHANNEL_H
   4 #define _GLIBMM_IOCHANNEL_H
   5
   6
   7 // -*- c++ -*-
   8 /* $Id$ */
   9
  10 /* Copyright (C) 2002 The gtkmm Development Team
  11  *
  12  * This library is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Library General Public
  14  * License as published by the Free Software Foundation; either
  15  * version 2 of the License, or (at your option) any later version.
  16  *
  17  * This library is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with this library; if not, write to the Free
  24  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25  */
  26
  27
  28 #include <glibmm/error.h>
  29 #include <glibmm/main.h>
  30 #include <glibmm/refptr.h>
  31 #include <glibmm/ustring.h>
  32 #include <glib/gtypes.h>
  33
  34 #include <string>
  35 #include <glibmmconfig.h>
  36
  37 GLIBMM_USING_STD(string)
  38
  39 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  40 extern "C" { typedef struct _GIOChannel GIOChannel; }
  41 #endif
  42
  43
  44 namespace Glib
  45 {
  46
  47 class Source;
  48 class IOSource;
  49
  50 /** @addtogroup glibmmEnums Enums and Flags */
  51
  52 /**
  53  * @ingroup glibmmEnums
  54  */
  55 enum SeekType
  56 {
  57   SEEK_TYPE_CUR,
  58   SEEK_TYPE_SET,
  59   SEEK_TYPE_END
  60 };
  61
  62
  63 /**
  64  * @ingroup glibmmEnums
  65  */
  66 enum IOStatus
  67 {
  68   IO_STATUS_ERROR,
  69   IO_STATUS_NORMAL,
  70   IO_STATUS_EOF,
  71   IO_STATUS_AGAIN
  72 };
  73
  74
  75 /**
  76  * @ingroup glibmmEnums
  77  * @par Bitwise operators:
  78  * <tt>%IOFlags operator|(IOFlags, IOFlags)</tt><br>
  79  * <tt>%IOFlags operator&(IOFlags, IOFlags)</tt><br>
  80  * <tt>%IOFlags operator^(IOFlags, IOFlags)</tt><br>
  81  * <tt>%IOFlags operator~(IOFlags)</tt><br>
  82  * <tt>%IOFlags& operator|=(IOFlags&, IOFlags)</tt><br>
  83  * <tt>%IOFlags& operator&=(IOFlags&, IOFlags)</tt><br>
  84  * <tt>%IOFlags& operator^=(IOFlags&, IOFlags)</tt><br>
  85  */
  86 enum IOFlags
  87 {
  88   IO_FLAG_APPEND = 1 << 0,
  89   IO_FLAG_NONBLOCK = 1 << 1,
  90   IO_FLAG_IS_READABLE = 1 << 2,
  91   IO_FLAG_IS_WRITEABLE = 1 << 3,
  92   IO_FLAG_IS_SEEKABLE = 1 << 4,
  93   IO_FLAG_GET_MASK = 0x0,
  94   IO_FLAG_SET_MASK = 0x1
  95 };
  96
  97 /** @ingroup glibmmEnums */
  98 inline IOFlags operator|(IOFlags lhs, IOFlags rhs)
  99   { return static_cast<IOFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
 100
 101 /** @ingroup glibmmEnums */
 102 inline IOFlags operator&(IOFlags lhs, IOFlags rhs)
 103   { return static_cast<IOFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
 104
 105 /** @ingroup glibmmEnums */
 106 inline IOFlags operator^(IOFlags lhs, IOFlags rhs)
 107   { return static_cast<IOFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
 108
 109 /** @ingroup glibmmEnums */
 110 inline IOFlags operator~(IOFlags flags)
 111   { return static_cast<IOFlags>(~static_cast<unsigned>(flags)); }
 112
 113 /** @ingroup glibmmEnums */
 114 inline IOFlags& operator|=(IOFlags& lhs, IOFlags rhs)
 115   { return (lhs = static_cast<IOFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
 116
 117 /** @ingroup glibmmEnums */
 118 inline IOFlags& operator&=(IOFlags& lhs, IOFlags rhs)
 119   { return (lhs = static_cast<IOFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
 120
 121 /** @ingroup glibmmEnums */
 122 inline IOFlags& operator^=(IOFlags& lhs, IOFlags rhs)
 123   { return (lhs = static_cast<IOFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
 124
 125
 126 /** Exception class for IOChannel errors.
 127  */
 128 class IOChannelError : public Glib::Error
 129 {
 130 public:
 131   enum Code
 132   {
 133     FILE_TOO_BIG,
 134     INVALID_ARGUMENT,
 135     IO_ERROR,
 136     IS_DIRECTORY,
 137     NO_SPACE_LEFT,
 138     NO_SUCH_DEVICE,
 139     OVERFLOWN,
 140     BROKEN_PIPE,
 141     FAILED
 142   };
 143
 144   IOChannelError(Code error_code, const Glib::ustring& error_message);
 145   explicit IOChannelError(GError* gobject);
 146   Code code() const;
 147
 148 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 149 private:
 150   static void throw_func(GError* gobject);
 151   friend void wrap_init(); // uses throw_func()
 152 #endif
 153 };
 154
 155
 156 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 157 class GlibmmIOChannel;
 158 #endif
 159
 160 /** IOChannel aims to provide portable I/O support for files, pipes
 161  * and sockets, and to integrate them with the GLib main event loop.
 162  *
 163  * Note that IOChannels implement an automatic implicit character set
 164  * conversion to the data stream, and usually will not pass by default
 165  * binary data unchanged.  To set the encoding of the channel, use e.g.
 166  * set_encoding("ISO-8859-15"). To set the channel to no encoding, use
 167  * set_encoding() without any arguments.
 168  *
 169  * You can create an IOChannel with one of the static create methods, or
 170  * implement one yourself, in which case you have to 1)&nbsp;override all
 171  * _vfunc() members. 2)&nbsp;set the GIOChannel flags in your constructor.
 172  *
 173  * @note This feature of being able to implement a custom Glib::IOChannel is
 174  * deprecated in glibmm&nbsp;2.2.  The vfunc interface has not yet stabilized
 175  * enough to allow that -- the C++ wrapper went in by pure accident.  Besides,
 176  * it isn't terribly useful either.  Thus please refrain from overriding any
 177  * IOChannel vfuncs.
 178  */
 179 class IOChannel : public sigc::trackable
 180 {
 181   public:
 182 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 183   typedef IOChannel CppObjectType;
 184   typedef GIOChannel BaseObjectType;
 185 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 186
 187 private:
 188
 189
 190 public:
 191   virtual ~IOChannel();
 192
 193   /** Open a file @a filename as an I/O channel using mode @a mode.
 194    * This channel will be closed when the last reference to it is dropped,
 195    * so there is no need to call close() (though doing so will not cause
 196    * problems, as long as no attempt is made to access the channel after
 197    * it is closed).
 198    * @param filename The name of the file to open.
 199    * @param mode One of <tt>"r"</tt>, <tt>"w"</tt>, <tt>"a"</tt>,
 200    *  <tt>"r+"</tt>, <tt>"w+"</tt>, <tt>"a+"</tt>. These have the
 201    *  same meaning as in <tt>fopen()</tt>.
 202    * @return An IOChannel for the opened file.
 203    * @throw Glib::FileError
 204    */
 205   static Glib::RefPtr<IOChannel> create_from_file(const std::string& filename, const std::string& mode);
 206
 207
 208   /** Creates an I/O channel from a file descriptor.
 209    * On Unix, IOChannels created with this function work for any file
 210    * descriptor or socket.
 211    *
 212    * On Win32, this can be used either for files opened with the MSVCRT (the
 213    * Microsoft run-time C library) <tt>_open()</tt> or <tt>_pipe()</tt>,
 214    * including file descriptors 0, 1 and 2 (corresponding to <tt>stdin</tt>,
 215    * <tt>stdout</tt> and <tt>stderr</tt>), or for Winsock <tt>SOCKET</tt>s. If
 216    * the parameter is a legal file descriptor, it is assumed to be such,
 217    * otherwise it should be a <tt>SOCKET</tt>. This relies on <tt>SOCKET</tt>s
 218    * and file descriptors not overlapping. If you want to be certain, call
 219    * either create_from_win32_fd() or create_from_win32_socket() instead as
 220    * appropriate.
 221    *
 222    * The term file descriptor as used in the context of Win32 refers to the
 223    * emulated Unix-like file descriptors MSVCRT provides. The native
 224    * corresponding concept is file <tt>HANDLE</tt>. There isn't as of yet
 225    * a way to get IOChannels for Win32 file <tt>HANDLE</tt>s.
 226    */
 227   static Glib::RefPtr<IOChannel> create_from_fd(int fd);
 228
 229
 230 /* defined(DOXYGEN_SHOULD_SKIP_THIS) actually does the opposite of what it looks like... */
 231 #if defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS)
 232
 233   /** Create an I/O channel for C runtime (emulated Unix-like) file descriptors.
 234    * After calling add_watch() on a I/O channel returned by this function, you
 235    * shouldn't call read() on the file descriptor. This is because adding
 236    * polling for a file descriptor is implemented on Win32 by starting a thread
 237    * that sits blocked in a <tt>%read()</tt> from the file descriptor most of
 238    * the time.  All reads from the file descriptor should be done by this
 239    * internal GLib thread. Your code should call only IOChannel::read().
 240    */
 241   static Glib::RefPtr<IOChannel> create_from_win32_fd(int fd);
 242
 243
 244   /** Create an I/O channel for a winsock socket. The parameter should be a
 245    * <tt>SOCKET</tt>. Contrary to I/O channels for file descriptors (on Win32),
 246    * you can use normal <tt>recv()</tt> or <tt>recvfrom()</tt> on sockets even
 247    * if GLib is polling them.
 248    */
 249   static Glib::RefPtr<IOChannel> create_from_win32_socket(int socket);
 250
 251
 252 #endif /* defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS) */
 253
 254   /** Read a single UCS-4 character.
 255    * @retval unichar The Unicode character.
 256    * @return The status of the operation.
 257    * @throw Glib::IOChannelError
 258    * @throw Glib::ConvertError
 259    */
 260
 261   /** This function cannot be called on a channel with <tt>0</tt> encoding.
 262    * @param thechar A location to return a character.
 263    * @param error A location to return an error of type G::ConvertError
 264    * or G::IOChannelError.
 265    * @return A G::IOStatus.
 266    */
 267   IOStatus read(gunichar& unichar);
 268
 269   /** Read a character sequence into memory.
 270    * @param buf A buffer to read data into.
 271    * @param count The size of the buffer in bytes.  Note that the buffer may
 272    * not be complelely filled even if there is data in the buffer if the
 273    * remaining data is not a complete character.
 274    * @retval bytes_read The number of bytes read.  This may be zero even on
 275    * success if @a count < 6 and the channel's encoding is not <tt>""</tt>.
 276    * This indicates that the next UTF-8 character is too wide for the buffer.
 277    * @return The status of the operation.
 278    * @throw Glib::IOChannelError
 279    * @throw Glib::ConvertError
 280    */
 281
 282   /** Replacement for g_io_channel_read() with the new API.
 283    * @param buf A buffer to read data into.
 284    * @param count The size of the buffer. Note that the buffer may
 285    * not be complelely filled even if there is data
 286    * in the buffer if the remaining data is not a
 287    * complete character.
 288    * @param bytes_read The number of bytes read. This may be zero even on
 289    * success if count &lt; 6 and the channel's encoding is non-<tt>0</tt>.
 290    * This indicates that the next UTF-8 character is too wide for
 291    * the buffer.
 292    * @param error A location to return an error of type G::ConvertError
 293    * or G::IOChannelError.
 294    * @return The status of the operation.
 295    */
 296   IOStatus read(char* buf, gsize count, gsize& bytes_read);
 297
 298   /** Read a maximum of @a count bytes into @a str.
 299    * @param count The maximum number of bytes to read.
 300    * @retval str The characters that have been read.
 301    * @return The status of the operation.
 302    * @throw Glib::IOChannelError
 303    * @throw Glib::ConvertError
 304    */
 305   IOStatus read(Glib::ustring& str, gsize count);
 306
 307   /** Read a whole line.
 308    * Reads until the line separator is found, which is included
 309    * in the result string.
 310    * @retval line The line that was read.
 311    * @return The status of the operation.
 312    * @throw Glib::IOChannelError
 313    * @throw Glib::ConvertError
 314    */
 315   IOStatus read_line(Glib::ustring& line);
 316
 317
 318   /** Reads all the remaining data from the file.
 319    * @retval str The resulting string.
 320    * @return Glib::IO_STATUS_NORMAL on success. This function never
 321    *  returns Glib::IO_STATUS_EOF.
 322    * @throw Glib::IOChannelError
 323    * @throw Glib::ConvertError
 324    */
 325   IOStatus read_to_end(Glib::ustring& str);
 326
 327
 328   /** Write a string to the I/O channel.
 329    * Note that this method does not return the number of characters written.
 330    * If the channel is blocking and the returned value is
 331    * Glib::IO_STATUS_NORMAL, the whole string was written.
 332    * @param str the string to write.
 333    * @return The status of the operation.
 334    * @throw Glib::IOChannelError
 335    * @throw Glib::ConvertError
 336    */
 337   IOStatus write(const Glib::ustring& str);
 338
 339   /** Write a memory area of @a count bytes to the I/O channel.
 340    * @param buf The start of the memory area.
 341    * @param count The number of bytes to write.
 342    * @retval bytes_written The number of bytes written to the channel.
 343    * @return The status of the operation.
 344    * @throw Glib::IOChannelError
 345    * @throw Glib::ConvertError
 346    */
 347
 348   /** Replacement for g_io_channel_write() with the new API.
 349    *
 350    * On seekable channels with encodings other than <tt>0</tt> or UTF-8, generic
 351    * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars()
 352    * may only be made on a channel from which data has been read in the
 353    * cases described in the documentation for g_io_channel_set_encoding().
 354    * @param buf A buffer to write data from.
 355    * @param count The size of the buffer. If -1, the buffer
 356    * is taken to be a nul-terminated string.
 357    * @param bytes_written The number of bytes written. This can be nonzero
 358    * even if the return value is not G::IO_STATUS_NORMAL.
 359    * If the return value is G::IO_STATUS_NORMAL and the
 360    * channel is blocking, this will always be equal
 361    * to @a count  if @a count  &gt;= 0.
 362    * @param error A location to return an error of type G::ConvertError
 363    * or G::IOChannelError.
 364    * @return The status of the operation.
 365    */
 366   IOStatus write(const char* buf, gssize count, gsize& bytes_written);
 367
 368   /** Write a single UCS-4 character to the I/O channel.
 369    * @param unichar The character to write.
 370    * @return The status of the operation.
 371    * @throw Glib::IOChannelError
 372    * @throw Glib::ConvertError
 373    */
 374
 375   /** This function cannot be called on a channel with <tt>0</tt> encoding.
 376    * @param thechar A character.
 377    * @param error A location to return an error of type G::ConvertError
 378    * or G::IOChannelError.
 379    * @return A G::IOStatus.
 380    */
 381   IOStatus write(gunichar unichar);
 382
 383   /** Seek the I/O channel to a specific position.
 384    * @param offset The offset in bytes from the position specified by @a type.
 385    * @param type A SeekType. The type Glib::SEEK_TYPE_CUR is only allowed in
 386    * those cases where a call to set_encoding() is allowed. See the
 387    * documentation for set_encoding() for details.
 388    * @return The status of the operation.
 389    * @throw Glib::IOChannelError
 390    * @throw Glib::ConvertError
 391    */
 392
 393   /** Replacement for g_io_channel_seek() with the new API.
 394    * @param offset The offset in bytes from the position specified by @a type .
 395    * @param type A G::SeekType. The type G::SEEK_CUR is only allowed in those
 396    * cases where a call to g_io_channel_set_encoding()
 397    * is allowed. See the documentation for
 398    * g_io_channel_set_encoding() for details.
 399    * @param error A location to return an error of type G::IOChannelError.
 400    * @return The status of the operation.
 401    */
 402   IOStatus seek(gint64 offset, SeekType type = SEEK_TYPE_SET);
 403
 404   /** Flush the buffers of the I/O channel.
 405    * @return The status of the operation.
 406    * @throw Glib::IOChannelError
 407    * @throw Glib::ConvertError
 408    */
 409
 410   /** Flushes the write buffer for the GIOChannel.
 411    * @param error Location to store an error of type G::IOChannelError.
 412    * @return The status of the operation: One of
 413    * G::IO_CHANNEL_NORMAL, G::IO_CHANNEL_AGAIN, or
 414    * G::IO_CHANNEL_ERROR.
 415    */
 416   IOStatus flush();
 417
 418   /** Close the I/O channel.
 419    * Any pending data to be written will be flushed if @a flush is <tt>true</tt>.
 420    * The channel will not be freed until the last reference is dropped.
 421    * Accessing the channel after closing it is considered an error.
 422    * @param flush Whether to flush() pending data before closing the channel.
 423    * @return The status of the operation.
 424    * @throw Glib::IOChannelError
 425    */
 426
 427   /** Close an IO channel. Any pending data to be written will be
 428    * flushed if @a flush  is <tt>true</tt>. The channel will not be freed until the
 429    * last reference is dropped using g_io_channel_unref().
 430    * @param flush If <tt>true</tt>, flush pending.
 431    * @param err Location to store a G::IOChannelError.
 432    * @return The status of the operation.
 433    */
 434   IOStatus close(bool flush = true);
 435
 436   /** Get the IOChannel internal buffer size.
 437    * @return The buffer size.
 438    */
 439
 440   /** Gets the buffer size.
 441    * @return The size of the buffer.
 442    */
 443   gsize get_buffer_size() const;
 444
 445   /** Set the internal IOChannel buffer size.
 446    * @param size The buffer size the IOChannel should use.
 447    */
 448
 449   /** Sets the buffer size.
 450    * @param size The size of the buffer. 0 == pick a good size.
 451    */
 452   void set_buffer_size(gsize size);
 453
 454   /** Get the current flags for a IOChannel, including read-only
 455    * flags such as Glib::IO_FLAG_IS_READABLE.
 456    *
 457    * The values of the flags Glib::IO_FLAG_IS_READABLE and
 458    * Glib::IO_FLAG_IS_WRITEABLE are cached for internal use by the channel when
 459    * it is created.  If they should change at some later point (e.g. partial
 460    * shutdown of a socket with the UNIX <tt>shutdown()</tt> function), the user
 461    * should immediately call get_flags() to update the internal values of these
 462    * flags.
 463    * @return Bitwise combination of the flags set on the channel.
 464    */
 465
 466   /** Gets the current flags for a G::IOChannel, including read-only
 467    * flags such as G::IO_FLAG_IS_READABLE.
 468    *
 469    * The values of the flags G::IO_FLAG_IS_READABLE and G::IO_FLAG_IS_WRITEABLE
 470    * are cached for internal use by the channel when it is created.
 471    * If they should change at some later point (e.g. partial shutdown
 472    * of a socket with the UNIX shutdown() function), the user
 473    * should immediately call g_io_channel_get_flags() to update
 474    * the internal values of these flags.
 475    * @return The flags which are set on the channel.
 476    */
 477   IOFlags get_flags() const;
 478
 479   /** Set flags on the IOChannel.
 480    * @param flags Bitwise combination of the flags to set.
 481    * @return The operation result code.
 482    * @throw Glib::IOChannelError
 483    */
 484
 485   /** Sets the (writeable) flags in @a channel  to ( @a flags  & G::IO_CHANNEL_SET_MASK).
 486    * @param flags The flags to set on the IO channel.
 487    * @param error A location to return an error of type G::IOChannelError.
 488    * @return The status of the operation.
 489    */
 490   IOStatus set_flags(IOFlags flags);
 491
 492   /** Set the buffering status of the I/O channel.
 493    * The buffering state can only be set if the channel's encoding is
 494    * <tt>""</tt>. For any other encoding, the channel must be buffered.
 495    *
 496    * A buffered channel can only be set unbuffered if the channel's internal
 497    * buffers have been flushed. Newly created channels or channels which have
 498    * returned Glib::IO_STATUS_EOF not require such a flush. For write-only
 499    * channels, a call to flush() is sufficient. For all other channels, the
 500    * buffers may be flushed by a call to seek().  This includes the possibility
 501    * of seeking with seek type Glib::SEEK_TYPE_CUR and an offset of zero. Note
 502    * that this means that socket-based channels cannot be set unbuffered once
 503    * they have had data read from them.
 504    *
 505    * The default state of the channel is buffered.
 506    *
 507    * @param buffered Whether to set the channel buffered or unbuffered.
 508    */
 509
 510   /** The buffering state can only be set if the channel's encoding
 511    * is <tt>0</tt>. For any other encoding, the channel must be buffered.
 512    *
 513    * A buffered channel can only be set unbuffered if the channel's
 514    * internal buffers have been flushed. Newly created channels or
 515    * channels which have returned G::IO_STATUS_EOF
 516    * not require such a flush. For write-only channels, a call to
 517    * g_io_channel_flush() is sufficient. For all other channels,
 518    * the buffers may be flushed by a call to g_io_channel_seek_position().
 519    * This includes the possibility of seeking with seek type G::SEEK_CUR
 520    * and an offset of zero. Note that this means that socket-based
 521    * channels cannot be set unbuffered once they have had data
 522    * read from them.
 523    *
 524    * On unbuffered channels, it is safe to mix read and write
 525    * calls from the new and old APIs, if this is necessary for
 526    * maintaining old code.
 527    *
 528    * The default state of the channel is buffered.
 529    * @param buffered Whether to set the channel buffered or unbuffered.
 530    */
 531   void set_buffered(bool buffered);
 532
 533   /** Get the buffering status of the I/O channel.
 534    * @return The buffering status of the channel.
 535    */
 536
 537   /** Returns whether @a channel  is buffered.
 538    * @return <tt>true</tt> if the @a channel  is buffered.
 539    */
 540   bool get_buffered() const;
 541
 542   /** Returns an IOCondition depending on whether there is data to be
 543    * read/space to write data in the internal buffers in the I/O channel.
 544    * Only the flags Glib::IO_IN and Glib::IO_OUT may be set.
 545    * @return Bitwise combination of Glib::IOCondition flags.
 546    */
 547
 548   /** This function returns a G::IOCondition depending on whether there
 549    * is data to be read/space to write data in the
 550    * internal buffers in the G::IOChannel. Only the flags G::IO_IN and
 551    * G::IO_OUT may be set.
 552    * @return A G::IOCondition.
 553    */
 554   IOCondition get_buffer_condition() const;
 555
 556   /** Returns whether the file/socket/whatever associated with the I/O channel
 557    * will be closed when the channel receives its final unref and is destroyed.
 558    * The default value of this is <tt>true</tt> for channels created by
 559    * create_from_file(), and <tt>false</tt> for all other channels.
 560    * @return Whether the channel will be closed on the final unref of the
 561    * IOChannel object.
 562    */
 563
 564   /** Returns whether the file/socket/whatever associated with @a channel
 565    * will be closed when @a channel  receives its final unref and is
 566    * destroyed. The default value of this is <tt>true</tt> for channels created
 567    * by g_io_channel_new_file(), and <tt>false</tt> for all other channels.
 568    * @return Whether the channel will be closed on the final unref of
 569    * the GIOChannel data structure.
 570    */
 571   bool get_close_on_unref() const;
 572
 573   /** Setting this flag to <tt>true</tt> for a channel you have already closed
 574    * can cause problems.
 575    * @param do_close Whether to close the channel on the final unref of the
 576    * IOChannel object.  The default value of this is <tt>true</tt> for channels
 577    * created by create_from_file(), and <tt>false</tt> for all other channels.
 578    */
 579
 580   /** Setting this flag to <tt>true</tt> for a channel you have already closed
 581    * can cause problems.
 582    * @param do_close Whether to close the channel on the final unref of
 583    * the GIOChannel data structure. The default value of
 584    * this is <tt>true</tt> for channels created by g_io_channel_new_file(),
 585    * and <tt>false</tt> for all other channels.
 586    */
 587   void set_close_on_unref(bool do_close);
 588
 589   /** Sets the encoding for the input/output of the channel.
 590    * The internal encoding is always UTF-8.  The default encoding for the
 591    * external file is UTF-8.  The encoding <tt>""</tt> is safe to use with
 592    * binary data.
 593    *
 594    * The encoding can only be set if one of the following conditions
 595    * is true:
 596    *
 597    * -# The channel was just created, and has not been written to or read from
 598    *  yet.
 599    * -# The channel is write-only.
 600    * -# The channel is a file, and the file pointer was just repositioned by a
 601    *  call to seek_position().  (This flushes all the internal buffers.)
 602    * -# The current encoding is <tt>""</tt> or UTF-8.
 603    * -# One of the read methods has just returned Glib::IO_STATUS_EOF (or, in
 604    *  the case of read_to_end(), Glib::IO_STATUS_NORMAL).
 605    * -# The read() method has returned Glib::IO_STATUS_AGAIN or thrown
 606    *  a Glib::Error exception.  This may be useful in the case of
 607    *  ConvertError::ILLEGAL_SEQUENCE.  Returning one of these statuses
 608    *  from read_line() or read_to_end() does <em>not</em> guarantee that
 609    *  the encoding can be changed.
 610    *
 611    * Channels which do not meet one of the above conditions cannot call
 612    * seek_position() with a seek type of Glib::SEEK_TYPE_CUR and, if they
 613    * are "seekable", cannot call write() after calling one of the API
 614    * "read" methods.
 615    *
 616    * @param encoding The encoding name, or <tt>""</tt> for binary.
 617    * @return Glib::IO_STATUS_NORMAL if the encoding was successfully set.
 618    * @throw Glib::IOChannelError
 619    */
 620   IOStatus set_encoding(const std::string& encoding = std::string());
 621
 622
 623   /** Get the encoding of the I/O channel.
 624    * @return The current encoding of the channel.
 625    */
 626   std::string get_encoding() const;
 627
 628
 629   void set_line_term(const std::string& term = std::string());
 630
 631
 632   std::string get_line_term() const;
 633
 634
 635   /** Creates an IOSource object.
 636    * Create a slot from a function to be called when condition is met
 637    * for the channel with sigc::ptr_fun() or sigc::mem_fun() and pass
 638    * it into the connect() function of the returned IOSource object.
 639    * Polling of the channel will start when you attach a MainContext
 640    * object to the returned IOSource object using its attach() function.
 641    *
 642    * Glib::signal_io().connect() is a simpler interface to the same
 643    * functionality, for the case where you want to add the source to the
 644    * default main context.
 645    * @param condition The condition to watch for.
 646    * @return An IOSource object that can be polled from a MainContext's event loop.
 647    */
 648   Glib::RefPtr<IOSource> create_watch(IOCondition condition);
 649
 650
 651   virtual void reference()   const;
 652   virtual void unreference() const;
 653
 654
 655   GIOChannel*       gobj()       { return gobject_; }
 656   const GIOChannel* gobj() const { return gobject_; }
 657
 658 protected:
 659   GIOChannel* gobject_;
 660
 661   /** Constructor that should be used by derived classes.
 662    * Use this constructor if you want to inherit from IOChannel.
 663    * It will set up a GIOChannel that will call the vfuncs of your
 664    * class even if it is being used from C code, and it will keep
 665    * a reference to the C++ code while the GIOChannel exists.
 666    */
 667   IOChannel();
 668
 669
 670 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 671   IOChannel(GIOChannel* gobject, bool take_copy);
 672 #endif
 673
 674   virtual IOStatus read_vfunc(char* buf, gsize count, gsize& bytes_read);
 675   virtual IOStatus write_vfunc(const char* buf, gsize count, gsize& bytes_written);
 676   virtual IOStatus seek_vfunc(gint64 offset, SeekType type);
 677   virtual IOStatus close_vfunc();
 678   virtual IOStatus set_flags_vfunc(IOFlags flags);
 679   virtual IOFlags  get_flags_vfunc();
 680   virtual Glib::RefPtr<Glib::Source> create_watch_vfunc(IOCondition cond);
 681
 682 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 683   friend class Glib::GlibmmIOChannel;
 684 #endif
 685
 686
 687 };
 688
 689 Glib::RefPtr<IOChannel> wrap(GIOChannel* gobject, bool take_copy = false);
 690
 691 } // namespace Glib
 692
 693
 694 #endif /* _GLIBMM_IOCHANNEL_H */
 695