libs/glibmm2/glib/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: iochannel.hg,v 1.8 2006/05/12 08:08:44 murrayc Exp $ */
   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
 151 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 152   static void throw_func(GError* gobject);
 153 #else
 154   //When not using exceptions, we just pass the Exception object around without throwing it:
 155   static std::auto_ptr<Glib::Error> throw_func(GError* gobject);
 156 #endif //GLIBMM_EXCEPTIONS_ENABLED
 157
 158   friend void wrap_init(); // uses throw_func()
 159 #endif
 160 };
 161
 162
 163 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 164 class GlibmmIOChannel;
 165 #endif
 166
 167 /** IOChannel aims to provide portable I/O support for files, pipes
 168  * and sockets, and to integrate them with the GLib main event loop.
 169  *
 170  * Note that IOChannels implement an automatic implicit character set
 171  * conversion to the data stream, and usually will not pass by default
 172  * binary data unchanged.  To set the encoding of the channel, use e.g.
 173  * set_encoding("ISO-8859-15"). To set the channel to no encoding, use
 174  * set_encoding() without any arguments.
 175  *
 176  * You can create an IOChannel with one of the static create methods, or
 177  * implement one yourself, in which case you have to 1)&nbsp;override all
 178  * _vfunc() members. 2)&nbsp;set the GIOChannel flags in your constructor.
 179  *
 180  * @note This feature of being able to implement a custom Glib::IOChannel is
 181  * deprecated in glibmm&nbsp;2.2.  The vfunc interface has not yet stabilized
 182  * enough to allow that -- the C++ wrapper went in by pure accident.  Besides,
 183  * it isn't terribly useful either.  Thus please refrain from overriding any
 184  * IOChannel vfuncs.
 185  */
 186 class IOChannel : public sigc::trackable
 187 {
 188   public:
 189 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 190   typedef IOChannel CppObjectType;
 191   typedef GIOChannel BaseObjectType;
 192 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 193
 194 private:
 195
 196
 197 public:
 198   virtual ~IOChannel();
 199
 200   /** Open a file @a filename as an I/O channel using mode @a mode.
 201    * This channel will be closed when the last reference to it is dropped,
 202    * so there is no need to call close() (though doing so will not cause
 203    * problems, as long as no attempt is made to access the channel after
 204    * it is closed).
 205    * @param filename The name of the file to open.
 206    * @param mode One of <tt>"r"</tt>, <tt>"w"</tt>, <tt>"a"</tt>,
 207    *  <tt>"r+"</tt>, <tt>"w+"</tt>, <tt>"a+"</tt>. These have the
 208    *  same meaning as in <tt>fopen()</tt>.
 209    * @return An IOChannel for the opened file.
 210    * @throw Glib::FileError
 211    */
 212 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 213   static Glib::RefPtr<IOChannel> create_from_file(const std::string& filename, const std::string& mode);
 214 #else
 215   static Glib::RefPtr<IOChannel> create_from_file(const std::string& filename, const std::string& mode, std::auto_ptr<Glib::Error>& error);
 216 #endif //GLIBMM_EXCEPTIONS_ENABLED
 217
 218
 219   /** Creates an I/O channel from a file descriptor.
 220    * On Unix, IOChannels created with this function work for any file
 221    * descriptor or socket.
 222    *
 223    * On Win32, this can be used either for files opened with the MSVCRT (the
 224    * Microsoft run-time C library) <tt>_open()</tt> or <tt>_pipe()</tt>,
 225    * including file descriptors 0, 1 and 2 (corresponding to <tt>stdin</tt>,
 226    * <tt>stdout</tt> and <tt>stderr</tt>), or for Winsock <tt>SOCKET</tt>s. If
 227    * the parameter is a legal file descriptor, it is assumed to be such,
 228    * otherwise it should be a <tt>SOCKET</tt>. This relies on <tt>SOCKET</tt>s
 229    * and file descriptors not overlapping. If you want to be certain, call
 230    * either create_from_win32_fd() or create_from_win32_socket() instead as
 231    * appropriate.
 232    *
 233    * The term file descriptor as used in the context of Win32 refers to the
 234    * emulated Unix-like file descriptors MSVCRT provides. The native
 235    * corresponding concept is file <tt>HANDLE</tt>. There isn't as of yet
 236    * a way to get IOChannels for Win32 file <tt>HANDLE</tt>s.
 237    */
 238   static Glib::RefPtr<IOChannel> create_from_fd(int fd);
 239
 240
 241 /* defined(DOXYGEN_SHOULD_SKIP_THIS) actually does the opposite of what it looks like... */
 242 #if defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS)
 243
 244   /** Create an I/O channel for C runtime (emulated Unix-like) file descriptors.
 245    * After calling add_watch() on a I/O channel returned by this function, you
 246    * shouldn't call read() on the file descriptor. This is because adding
 247    * polling for a file descriptor is implemented on Win32 by starting a thread
 248    * that sits blocked in a <tt>%read()</tt> from the file descriptor most of
 249    * the time.  All reads from the file descriptor should be done by this
 250    * internal GLib thread. Your code should call only IOChannel::read().
 251    */
 252   static Glib::RefPtr<IOChannel> create_from_win32_fd(int fd);
 253
 254
 255   /** Create an I/O channel for a winsock socket. The parameter should be a
 256    * <tt>SOCKET</tt>. Contrary to I/O channels for file descriptors (on Win32),
 257    * you can use normal <tt>recv()</tt> or <tt>recvfrom()</tt> on sockets even
 258    * if GLib is polling them.
 259    */
 260   static Glib::RefPtr<IOChannel> create_from_win32_socket(int socket);
 261
 262
 263 #endif /* defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS) */
 264
 265   /** Read a single UCS-4 character.
 266    * @retval thechar The Unicode character.
 267    * @return The status of the operation.
 268    * @throw Glib::IOChannelError
 269    * @throw Glib::ConvertError
 270    */
 271
 272   /** This function cannot be called on a channel with <tt>0</tt> encoding.
 273    * @param thechar A location to return a character.
 274    * @param error A location to return an error of type G::ConvertError
 275    * or G::IOChannelError.
 276    * @return A G::IOStatus.
 277    */
 278 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 279   IOStatus read(gunichar& thechar);
 280 #else
 281   IOStatus read(gunichar& thechar, std::auto_ptr<Glib::Error>& error);
 282 #endif //GLIBMM_EXCEPTIONS_ENABLED
 283
 284
 285   /** Read a character sequence into memory.
 286    * @param buf A buffer to read data into.
 287    * @param count The size of the buffer in bytes.  Note that the buffer may
 288    * not be complelely filled even if there is data in the buffer if the
 289    * remaining data is not a complete character.
 290    * @retval bytes_read The number of bytes read.  This may be zero even on
 291    * success if @a count < 6 and the channel's encoding is not <tt>""</tt>.
 292    * This indicates that the next UTF-8 character is too wide for the buffer.
 293    * @return The status of the operation.
 294    * @throw Glib::IOChannelError
 295    * @throw Glib::ConvertError
 296    */
 297
 298   /** Replacement for g_io_channel_read() with the new API.
 299    * @param buf A buffer to read data into.
 300    * @param count The size of the buffer. Note that the buffer may
 301    * not be complelely filled even if there is data
 302    * in the buffer if the remaining data is not a
 303    * complete character.
 304    * @param bytes_read The number of bytes read. This may be zero even on
 305    * success if count &lt; 6 and the channel's encoding is non-<tt>0</tt>.
 306    * This indicates that the next UTF-8 character is too wide for
 307    * the buffer.
 308    * @param error A location to return an error of type G::ConvertError
 309    * or G::IOChannelError.
 310    * @return The status of the operation.
 311    */
 312 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 313   IOStatus read(char* buf, gsize count, gsize& bytes_read);
 314 #else
 315   IOStatus read(char* buf, gsize count, gsize& bytes_read, std::auto_ptr<Glib::Error>& error);
 316 #endif //GLIBMM_EXCEPTIONS_ENABLED
 317
 318
 319   /** Read a maximum of @a count bytes into @a str.
 320    * @param count The maximum number of bytes to read.
 321    * @retval str The characters that have been read.
 322    * @return The status of the operation.
 323    * @throw Glib::IOChannelError
 324    * @throw Glib::ConvertError
 325    */
 326 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 327   IOStatus read(Glib::ustring& str, gsize count);
 328 #else
 329   IOStatus read(Glib::ustring& str, gsize count, std::auto_ptr<Glib::Error>& error);
 330 #endif //GLIBMM_EXCEPTIONS_ENABLED
 331
 332   /** Read a whole line.
 333    * Reads until the line separator is found, which is included
 334    * in the result string.
 335    * @retval line The line that was read.
 336    * @return The status of the operation.
 337    * @throw Glib::IOChannelError
 338    * @throw Glib::ConvertError
 339    */
 340 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 341   IOStatus read_line(Glib::ustring& line);
 342 #else
 343   IOStatus read_line(Glib::ustring& line, std::auto_ptr<Glib::Error>& error);
 344 #endif //GLIBMM_EXCEPTIONS_ENABLED
 345
 346
 347   /** Reads all the remaining data from the file.
 348    * @retval str The resulting string.
 349    * @return Glib::IO_STATUS_NORMAL on success. This function never
 350    *  returns Glib::IO_STATUS_EOF.
 351    * @throw Glib::IOChannelError
 352    * @throw Glib::ConvertError
 353    */
 354 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 355   IOStatus read_to_end(Glib::ustring& str);
 356 #else
 357   IOStatus read_to_end(Glib::ustring& str, std::auto_ptr<Glib::Error>& error);
 358 #endif //GLIBMM_EXCEPTIONS_ENABLED
 359
 360
 361   /** Write a string to the I/O channel.
 362    * Note that this method does not return the number of characters written.
 363    * If the channel is blocking and the returned value is
 364    * Glib::IO_STATUS_NORMAL, the whole string was written.
 365    * @param str the string to write.
 366    * @return The status of the operation.
 367    * @throw Glib::IOChannelError
 368    * @throw Glib::ConvertError
 369    */
 370 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 371   IOStatus write(const Glib::ustring& str);
 372 #else
 373   IOStatus write(const Glib::ustring& str, std::auto_ptr<Glib::Error>& error);
 374 #endif //GLIBMM_EXCEPTIONS_ENABLED
 375
 376   /** Write a memory area of @a count bytes to the I/O channel.
 377    * @param buf The start of the memory area.
 378    * @param count The number of bytes to write.
 379    * @retval bytes_written The number of bytes written to the channel.
 380    * @return The status of the operation.
 381    * @throw Glib::IOChannelError
 382    * @throw Glib::ConvertError
 383    */
 384
 385   /** Replacement for g_io_channel_write() with the new API.
 386    *
 387    * On seekable channels with encodings other than <tt>0</tt> or UTF-8, generic
 388    * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars()
 389    * may only be made on a channel from which data has been read in the
 390    * cases described in the documentation for g_io_channel_set_encoding().
 391    * @param buf A buffer to write data from.
 392    * @param count The size of the buffer. If -1, the buffer
 393    * is taken to be a nul-terminated string.
 394    * @param bytes_written The number of bytes written. This can be nonzero
 395    * even if the return value is not G::IO_STATUS_NORMAL.
 396    * If the return value is G::IO_STATUS_NORMAL and the
 397    * channel is blocking, this will always be equal
 398    * to @a count  if @a count  &gt;= 0.
 399    * @param error A location to return an error of type G::ConvertError
 400    * or G::IOChannelError.
 401    * @return The status of the operation.
 402    */
 403 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 404   IOStatus write(const char* buf, gssize count, gsize& bytes_written);
 405 #else
 406   IOStatus write(const char* buf, gssize count, gsize& bytes_written, std::auto_ptr<Glib::Error>& error);
 407 #endif //GLIBMM_EXCEPTIONS_ENABLED
 408
 409
 410   /** Write a single UCS-4 character to the I/O channel.
 411    * @param unichar The character to write.
 412    * @return The status of the operation.
 413    * @throw Glib::IOChannelError
 414    * @throw Glib::ConvertError
 415    */
 416
 417   /** This function cannot be called on a channel with <tt>0</tt> encoding.
 418    * @param thechar A character.
 419    * @param error A location to return an error of type G::ConvertError
 420    * or G::IOChannelError.
 421    * @return A G::IOStatus.
 422    */
 423 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 424   IOStatus write(gunichar unichar);
 425 #else
 426   IOStatus write(gunichar unichar, std::auto_ptr<Glib::Error>& error);
 427 #endif //GLIBMM_EXCEPTIONS_ENABLED
 428
 429
 430   /** Seek the I/O channel to a specific position.
 431    * @param offset The offset in bytes from the position specified by @a type.
 432    * @param type A SeekType. The type Glib::SEEK_TYPE_CUR is only allowed in
 433    * those cases where a call to set_encoding() is allowed. See the
 434    * documentation for set_encoding() for details.
 435    * @return The status of the operation.
 436    * @throw Glib::IOChannelError
 437    * @throw Glib::ConvertError
 438    */
 439
 440   /** Replacement for g_io_channel_seek() with the new API.
 441    * @param offset The offset in bytes from the position specified by @a type .
 442    * @param type A G::SeekType. The type G::SEEK_CUR is only allowed in those
 443    * cases where a call to g_io_channel_set_encoding()
 444    * is allowed. See the documentation for
 445    * g_io_channel_set_encoding() for details.
 446    * @param error A location to return an error of type G::IOChannelError.
 447    * @return The status of the operation.
 448    */
 449 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 450   IOStatus seek(gint64 offset, SeekType type = SEEK_TYPE_SET);
 451 #else
 452   IOStatus seek(gint64 offset, SeekType type, std::auto_ptr<Glib::Error>& error);
 453 #endif //GLIBMM_EXCEPTIONS_ENABLED
 454
 455
 456   /** Flush the buffers of the I/O channel.
 457    * @return The status of the operation.
 458    * @throw Glib::IOChannelError
 459    * @throw Glib::ConvertError
 460    */
 461
 462   /** Flushes the write buffer for the GIOChannel.
 463    * @param error Location to store an error of type G::IOChannelError.
 464    * @return The status of the operation: One of
 465    * G::IO_CHANNEL_NORMAL, G::IO_CHANNEL_AGAIN, or
 466    * G::IO_CHANNEL_ERROR.
 467    */
 468 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 469   IOStatus flush();
 470 #else
 471   IOStatus flush(std::auto_ptr<Glib::Error>& error);
 472 #endif //GLIBMM_EXCEPTIONS_ENABLED
 473
 474
 475   /** Close the I/O channel.
 476    * Any pending data to be written will be flushed if @a flush is <tt>true</tt>.
 477    * The channel will not be freed until the last reference is dropped.
 478    * Accessing the channel after closing it is considered an error.
 479    * @param flush Whether to flush() pending data before closing the channel.
 480    * @return The status of the operation.
 481    * @throw Glib::IOChannelError
 482    */
 483
 484   /** Close an IO channel. Any pending data to be written will be
 485    * flushed if @a flush  is <tt>true</tt>. The channel will not be freed until the
 486    * last reference is dropped using g_io_channel_unref().
 487    * @param flush If <tt>true</tt>, flush pending.
 488    * @param err Location to store a G::IOChannelError.
 489    * @return The status of the operation.
 490    */
 491 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 492   IOStatus close(bool flush = true);
 493 #else
 494   IOStatus close(bool flush, std::auto_ptr<Glib::Error>& error);
 495 #endif //GLIBMM_EXCEPTIONS_ENABLED
 496
 497
 498   /** Get the IOChannel internal buffer size.
 499    * @return The buffer size.
 500    */
 501
 502   /** Gets the buffer size.
 503    * @return The size of the buffer.
 504    */
 505   gsize get_buffer_size() const;
 506
 507   /** Set the internal IOChannel buffer size.
 508    * @param size The buffer size the IOChannel should use.
 509    */
 510
 511   /** Sets the buffer size.
 512    * @param size The size of the buffer. 0 == pick a good size.
 513    */
 514   void set_buffer_size(gsize size);
 515
 516   /** Get the current flags for a IOChannel, including read-only
 517    * flags such as Glib::IO_FLAG_IS_READABLE.
 518    *
 519    * The values of the flags Glib::IO_FLAG_IS_READABLE and
 520    * Glib::IO_FLAG_IS_WRITEABLE are cached for internal use by the channel when
 521    * it is created.  If they should change at some later point (e.g. partial
 522    * shutdown of a socket with the UNIX <tt>shutdown()</tt> function), the user
 523    * should immediately call get_flags() to update the internal values of these
 524    * flags.
 525    * @return Bitwise combination of the flags set on the channel.
 526    */
 527
 528   /** Gets the current flags for a G::IOChannel, including read-only
 529    * flags such as G::IO_FLAG_IS_READABLE.
 530    *
 531    * The values of the flags G::IO_FLAG_IS_READABLE and G::IO_FLAG_IS_WRITEABLE
 532    * are cached for internal use by the channel when it is created.
 533    * If they should change at some later point (e.g. partial shutdown
 534    * of a socket with the UNIX shutdown() function), the user
 535    * should immediately call g_io_channel_get_flags() to update
 536    * the internal values of these flags.
 537    * @return The flags which are set on the channel.
 538    */
 539   IOFlags get_flags() const;
 540
 541   /** Set flags on the IOChannel.
 542    * @param flags Bitwise combination of the flags to set.
 543    * @return The operation result code.
 544    * @throw Glib::IOChannelError
 545    */
 546
 547   /** Sets the (writeable) flags in @a channel  to ( @a flags  & G::IO_CHANNEL_SET_MASK).
 548    * @param flags The flags to set on the IO channel.
 549    * @param error A location to return an error of type G::IOChannelError.
 550    * @return The status of the operation.
 551    */
 552 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 553   IOStatus set_flags(IOFlags flags);
 554 #else
 555   IOStatus set_flags(IOFlags flags, std::auto_ptr<Glib::Error>& error);
 556 #endif //GLIBMM_EXCEPTIONS_ENABLED
 557
 558
 559   /** Set the buffering status of the I/O channel.
 560    * The buffering state can only be set if the channel's encoding is
 561    * <tt>""</tt>. For any other encoding, the channel must be buffered.
 562    *
 563    * A buffered channel can only be set unbuffered if the channel's internal
 564    * buffers have been flushed. Newly created channels or channels which have
 565    * returned Glib::IO_STATUS_EOF not require such a flush. For write-only
 566    * channels, a call to flush() is sufficient. For all other channels, the
 567    * buffers may be flushed by a call to seek().  This includes the possibility
 568    * of seeking with seek type Glib::SEEK_TYPE_CUR and an offset of zero. Note
 569    * that this means that socket-based channels cannot be set unbuffered once
 570    * they have had data read from them.
 571    *
 572    * The default state of the channel is buffered.
 573    *
 574    * @param buffered Whether to set the channel buffered or unbuffered.
 575    */
 576
 577   /** The buffering state can only be set if the channel's encoding
 578    * is <tt>0</tt>. For any other encoding, the channel must be buffered.
 579    *
 580    * A buffered channel can only be set unbuffered if the channel's
 581    * internal buffers have been flushed. Newly created channels or
 582    * channels which have returned G::IO_STATUS_EOF
 583    * not require such a flush. For write-only channels, a call to
 584    * g_io_channel_flush() is sufficient. For all other channels,
 585    * the buffers may be flushed by a call to g_io_channel_seek_position().
 586    * This includes the possibility of seeking with seek type G::SEEK_CUR
 587    * and an offset of zero. Note that this means that socket-based
 588    * channels cannot be set unbuffered once they have had data
 589    * read from them.
 590    *
 591    * On unbuffered channels, it is safe to mix read and write
 592    * calls from the new and old APIs, if this is necessary for
 593    * maintaining old code.
 594    *
 595    * The default state of the channel is buffered.
 596    * @param buffered Whether to set the channel buffered or unbuffered.
 597    */
 598   void set_buffered(bool buffered);
 599
 600   /** Get the buffering status of the I/O channel.
 601    * @return The buffering status of the channel.
 602    */
 603
 604   /** Return Value: <tt>true</tt> if the @a channel  is buffered.
 605    * @return <tt>true</tt> if the @a channel  is buffered.
 606    */
 607   bool get_buffered() const;
 608
 609   /** Returns an IOCondition depending on whether there is data to be
 610    * read/space to write data in the internal buffers in the I/O channel.
 611    * Only the flags Glib::IO_IN and Glib::IO_OUT may be set.
 612    * @return Bitwise combination of Glib::IOCondition flags.
 613    */
 614
 615   /** This function returns a G::IOCondition depending on whether there
 616    * is data to be read/space to write data in the
 617    * internal buffers in the G::IOChannel. Only the flags G::IO_IN and
 618    * G::IO_OUT may be set.
 619    * @return A G::IOCondition.
 620    */
 621   IOCondition get_buffer_condition() const;
 622
 623   /** Returns whether the file/socket/whatever associated with the I/O channel
 624    * will be closed when the channel receives its final unref and is destroyed.
 625    * The default value of this is <tt>true</tt> for channels created by
 626    * create_from_file(), and <tt>false</tt> for all other channels.
 627    * @return Whether the channel will be closed on the final unref of the
 628    * IOChannel object.
 629    */
 630
 631   /** Return value: Whether the channel will be closed on the final unref of
 632    * @return Whether the channel will be closed on the final unref of
 633    * the GIOChannel data structure.
 634    */
 635   bool get_close_on_unref() const;
 636
 637   /** Setting this flag to <tt>true</tt> for a channel you have already closed
 638    * can cause problems.
 639    * @param do_close Whether to close the channel on the final unref of the
 640    * IOChannel object.  The default value of this is <tt>true</tt> for channels
 641    * created by create_from_file(), and <tt>false</tt> for all other channels.
 642    */
 643
 644   /** Setting this flag to <tt>true</tt> for a channel you have already closed
 645    * can cause problems.
 646    * @param do_close Whether to close the channel on the final unref of
 647    * the GIOChannel data structure. The default value of
 648    * this is <tt>true</tt> for channels created by g_io_channel_new_file(),
 649    * and <tt>false</tt> for all other channels.
 650    */
 651   void set_close_on_unref(bool do_close);
 652
 653   /** Sets the encoding for the input/output of the channel.
 654    * The internal encoding is always UTF-8.  The default encoding for the
 655    * external file is UTF-8.  The encoding <tt>""</tt> is safe to use with
 656    * binary data.
 657    *
 658    * The encoding can only be set if one of the following conditions
 659    * is true:
 660    *
 661    * -# The channel was just created, and has not been written to or read from
 662    *  yet.
 663    * -# The channel is write-only.
 664    * -# The channel is a file, and the file pointer was just repositioned by a
 665    *  call to seek_position().  (This flushes all the internal buffers.)
 666    * -# The current encoding is <tt>""</tt> or UTF-8.
 667    * -# One of the read methods has just returned Glib::IO_STATUS_EOF (or, in
 668    *  the case of read_to_end(), Glib::IO_STATUS_NORMAL).
 669    * -# The read() method has returned Glib::IO_STATUS_AGAIN or thrown
 670    *  a Glib::Error exception.  This may be useful in the case of
 671    *  ConvertError::ILLEGAL_SEQUENCE.  Returning one of these statuses
 672    *  from read_line() or read_to_end() does <em>not</em> guarantee that
 673    *  the encoding can be changed.
 674    *
 675    * Channels which do not meet one of the above conditions cannot call
 676    * seek_position() with a seek type of Glib::SEEK_TYPE_CUR and, if they
 677    * are "seekable", cannot call write() after calling one of the API
 678    * "read" methods.
 679    *
 680    * @param encoding The encoding name, or <tt>""</tt> for binary.
 681    * @return Glib::IO_STATUS_NORMAL if the encoding was successfully set.
 682    * @throw Glib::IOChannelError
 683    */
 684 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 685   IOStatus set_encoding(const std::string& encoding = std::string());
 686 #else
 687   IOStatus set_encoding(const std::string& encoding, std::auto_ptr<Glib::Error>& error);
 688 #endif //GLIBMM_EXCEPTIONS_ENABLED
 689
 690
 691   /** Get the encoding of the I/O channel.
 692    * @return The current encoding of the channel.
 693    */
 694   std::string get_encoding() const;
 695
 696
 697   void set_line_term(const std::string& term = std::string());
 698
 699
 700   std::string get_line_term() const;
 701
 702
 703   /** Creates an IOSource object.
 704    * Create a slot from a function to be called when condition is met
 705    * for the channel with sigc::ptr_fun() or sigc::mem_fun() and pass
 706    * it into the connect() function of the returned IOSource object.
 707    * Polling of the channel will start when you attach a MainContext
 708    * object to the returned IOSource object using its attach() function.
 709    *
 710    * Glib::signal_io().connect() is a simpler interface to the same
 711    * functionality, for the case where you want to add the source to the
 712    * default main context.
 713    * @param condition The condition to watch for.
 714    * @return An IOSource object that can be polled from a MainContext's event loop.
 715    */
 716   Glib::RefPtr<IOSource> create_watch(IOCondition condition);
 717
 718
 719   virtual void reference()   const;
 720   virtual void unreference() const;
 721
 722
 723   GIOChannel*       gobj()       { return gobject_; }
 724   const GIOChannel* gobj() const { return gobject_; }
 725
 726 protected:
 727   GIOChannel* gobject_;
 728
 729   /** Constructor that should be used by derived classes.
 730    * Use this constructor if you want to inherit from IOChannel.
 731    * It will set up a GIOChannel that will call the vfuncs of your
 732    * class even if it is being used from C code, and it will keep
 733    * a reference to the C++ code while the GIOChannel exists.
 734    */
 735   IOChannel();
 736
 737
 738 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 739   IOChannel(GIOChannel* gobject, bool take_copy);
 740 #endif
 741
 742   virtual IOStatus read_vfunc(char* buf, gsize count, gsize& bytes_read);
 743   virtual IOStatus write_vfunc(const char* buf, gsize count, gsize& bytes_written);
 744   virtual IOStatus seek_vfunc(gint64 offset, SeekType type);
 745   virtual IOStatus close_vfunc();
 746   virtual IOStatus set_flags_vfunc(IOFlags flags);
 747   virtual IOFlags  get_flags_vfunc();
 748   virtual Glib::RefPtr<Glib::Source> create_watch_vfunc(IOCondition cond);
 749
 750 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 751   friend class Glib::GlibmmIOChannel;
 752 #endif
 753
 754
 755 };
 756
 757 Glib::RefPtr<IOChannel> wrap(GIOChannel* gobject, bool take_copy = false);
 758
 759 } // namespace Glib
 760
 761
 762 #endif /* _GLIBMM_IOCHANNEL_H */
 763