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 Lesser General Public
  14  * License as published by the Free Software Foundation; either
  15  * version 2.1 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  * Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser 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.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   /** Reads a Unicode character from @a channel.
 273    * This function cannot be called on a channel with <tt>0</tt> encoding.
 274    * @param thechar A location to return a character.
 275    * @return A IOStatus.
 276    */
 277 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 278   IOStatus read(gunichar& thechar);
 279 #else
 280   IOStatus read(gunichar& thechar, std::auto_ptr<Glib::Error>& error);
 281 #endif //GLIBMM_EXCEPTIONS_ENABLED
 282
 283
 284   /** Read a character sequence into memory.
 285    * @param buf A buffer to read data into.
 286    * @param count The size of the buffer in bytes.  Note that the buffer may
 287    * not be complelely filled even if there is data in the buffer if the
 288    * remaining data is not a complete character.
 289    * @retval bytes_read The number of bytes read.  This may be zero even on
 290    * success if @a count < 6 and the channel's encoding is not <tt>""</tt>.
 291    * This indicates that the next UTF-8 character is too wide for the buffer.
 292    * @return The status of the operation.
 293    * @throw Glib::IOChannelError
 294    * @throw Glib::ConvertError
 295    */
 296
 297   /** Replacement for g_io_channel_read() with the new API.
 298    * @param buf A buffer to read data into.
 299    * @param count The size of the buffer. Note that the buffer may
 300    * not be complelely filled even if there is data
 301    * in the buffer if the remaining data is not a
 302    * complete character.
 303    * @param bytes_read The number of bytes read. This may be zero even on
 304    * success if count &lt; 6 and the channel's encoding is non-<tt>0</tt>.
 305    * This indicates that the next UTF-8 character is too wide for
 306    * the buffer.
 307    * @return The status of the operation.
 308    */
 309 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 310   IOStatus read(char* buf, gsize count, gsize& bytes_read);
 311 #else
 312   IOStatus read(char* buf, gsize count, gsize& bytes_read, std::auto_ptr<Glib::Error>& error);
 313 #endif //GLIBMM_EXCEPTIONS_ENABLED
 314
 315
 316   /** Read a maximum of @a count bytes into @a str.
 317    * @param count The maximum number of bytes to read.
 318    * @retval str The characters that have been read.
 319    * @return The status of the operation.
 320    * @throw Glib::IOChannelError
 321    * @throw Glib::ConvertError
 322    */
 323 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 324   IOStatus read(Glib::ustring& str, gsize count);
 325 #else
 326   IOStatus read(Glib::ustring& str, gsize count, std::auto_ptr<Glib::Error>& error);
 327 #endif //GLIBMM_EXCEPTIONS_ENABLED
 328
 329   /** Read a whole line.
 330    * Reads until the line separator is found, which is included
 331    * in the result string.
 332    * @retval line The line that was read.
 333    * @return The status of the operation.
 334    * @throw Glib::IOChannelError
 335    * @throw Glib::ConvertError
 336    */
 337 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 338   IOStatus read_line(Glib::ustring& line);
 339 #else
 340   IOStatus read_line(Glib::ustring& line, std::auto_ptr<Glib::Error>& error);
 341 #endif //GLIBMM_EXCEPTIONS_ENABLED
 342
 343
 344   /** Reads all the remaining data from the file.
 345    * @retval str The resulting string.
 346    * @return Glib::IO_STATUS_NORMAL on success. This function never
 347    *  returns Glib::IO_STATUS_EOF.
 348    * @throw Glib::IOChannelError
 349    * @throw Glib::ConvertError
 350    */
 351 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 352   IOStatus read_to_end(Glib::ustring& str);
 353 #else
 354   IOStatus read_to_end(Glib::ustring& str, std::auto_ptr<Glib::Error>& error);
 355 #endif //GLIBMM_EXCEPTIONS_ENABLED
 356
 357
 358   /** Write a string to the I/O channel.
 359    * Note that this method does not return the number of characters written.
 360    * If the channel is blocking and the returned value is
 361    * Glib::IO_STATUS_NORMAL, the whole string was written.
 362    * @param str the string to write.
 363    * @return The status of the operation.
 364    * @throw Glib::IOChannelError
 365    * @throw Glib::ConvertError
 366    */
 367 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 368   IOStatus write(const Glib::ustring& str);
 369 #else
 370   IOStatus write(const Glib::ustring& str, std::auto_ptr<Glib::Error>& error);
 371 #endif //GLIBMM_EXCEPTIONS_ENABLED
 372
 373   /** Write a memory area of @a count bytes to the I/O channel.
 374    * @param buf The start of the memory area.
 375    * @param count The number of bytes to write.
 376    * @retval bytes_written The number of bytes written to the channel.
 377    * @return The status of the operation.
 378    * @throw Glib::IOChannelError
 379    * @throw Glib::ConvertError
 380    */
 381
 382   /** Replacement for g_io_channel_write() with the new API.
 383    *
 384    * On seekable channels with encodings other than <tt>0</tt> or UTF-8, generic
 385    * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars()
 386    * may only be made on a channel from which data has been read in the
 387    * cases described in the documentation for g_io_channel_set_encoding().
 388    * @param buf A buffer to write data from.
 389    * @param count The size of the buffer. If -1, the buffer
 390    * is taken to be a nul-terminated string.
 391    * @param bytes_written The number of bytes written. This can be nonzero
 392    * even if the return value is not IO_STATUS_NORMAL.
 393    * If the return value is IO_STATUS_NORMAL and the
 394    * channel is blocking, this will always be equal
 395    * to @a count if @a count &gt;= 0.
 396    * @return The status of the operation.
 397    */
 398 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 399   IOStatus write(const char* buf, gssize count, gsize& bytes_written);
 400 #else
 401   IOStatus write(const char* buf, gssize count, gsize& bytes_written, std::auto_ptr<Glib::Error>& error);
 402 #endif //GLIBMM_EXCEPTIONS_ENABLED
 403
 404
 405   /** Write a single UCS-4 character to the I/O channel.
 406    * @param unichar The character to write.
 407    * @return The status of the operation.
 408    * @throw Glib::IOChannelError
 409    * @throw Glib::ConvertError
 410    */
 411
 412   /** Writes a Unicode character to @a channel.
 413    * This function cannot be called on a channel with <tt>0</tt> encoding.
 414    * @param thechar A character.
 415    * @return A IOStatus.
 416    */
 417 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 418   IOStatus write(gunichar unichar);
 419 #else
 420   IOStatus write(gunichar unichar, std::auto_ptr<Glib::Error>& error);
 421 #endif //GLIBMM_EXCEPTIONS_ENABLED
 422
 423
 424   /** Seek the I/O channel to a specific position.
 425    * @param offset The offset in bytes from the position specified by @a type.
 426    * @param type A SeekType. The type Glib::SEEK_TYPE_CUR is only allowed in
 427    * those cases where a call to set_encoding() is allowed. See the
 428    * documentation for set_encoding() for details.
 429    * @return The status of the operation.
 430    * @throw Glib::IOChannelError
 431    * @throw Glib::ConvertError
 432    */
 433
 434   /** Replacement for g_io_channel_seek() with the new API.
 435    * @param offset The offset in bytes from the position specified by @a type.
 436    * @param type A SeekType. The type SEEK_CUR is only allowed in those
 437    * cases where a call to g_io_channel_set_encoding()
 438    * is allowed. See the documentation for
 439    * g_io_channel_set_encoding() for details.
 440    * @return The status of the operation.
 441    */
 442 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 443   IOStatus seek(gint64 offset, SeekType type = SEEK_TYPE_SET);
 444 #else
 445   IOStatus seek(gint64 offset, SeekType type, std::auto_ptr<Glib::Error>& error);
 446 #endif //GLIBMM_EXCEPTIONS_ENABLED
 447
 448
 449   /** Flush the buffers of the I/O channel.
 450    * @return The status of the operation.
 451    * @throw Glib::IOChannelError
 452    * @throw Glib::ConvertError
 453    */
 454
 455   /** Flushes the write buffer for the GIOChannel.
 456    * @return The status of the operation: One of
 457    * IO_CHANNEL_NORMAL, IO_CHANNEL_AGAIN, or
 458    * IO_CHANNEL_ERROR.
 459    */
 460 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 461   IOStatus flush();
 462 #else
 463   IOStatus flush(std::auto_ptr<Glib::Error>& error);
 464 #endif //GLIBMM_EXCEPTIONS_ENABLED
 465
 466
 467   /** Close the I/O channel.
 468    * Any pending data to be written will be flushed if @a flush is <tt>true</tt>.
 469    * The channel will not be freed until the last reference is dropped.
 470    * Accessing the channel after closing it is considered an error.
 471    * @param flush Whether to flush() pending data before closing the channel.
 472    * @return The status of the operation.
 473    * @throw Glib::IOChannelError
 474    */
 475
 476   /** Close an IO channel. Any pending data to be written will be
 477    * flushed if @a flush is <tt>true</tt>. The channel will not be freed until the
 478    * last reference is dropped using g_io_channel_unref().
 479    * @param flush If <tt>true</tt>, flush pending.
 480    * @param err Location to store a IOChannelError.
 481    * @return The status of the operation.
 482    */
 483 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 484   IOStatus close(bool flush = true);
 485 #else
 486   IOStatus close(bool flush, std::auto_ptr<Glib::Error>& error);
 487 #endif //GLIBMM_EXCEPTIONS_ENABLED
 488
 489
 490   /** Get the IOChannel internal buffer size.
 491    * @return The buffer size.
 492    */
 493
 494   /** Gets the buffer size.
 495    * @return The size of the buffer.
 496    */
 497   gsize get_buffer_size() const;
 498
 499   /** Set the internal IOChannel buffer size.
 500    * @param size The buffer size the IOChannel should use.
 501    */
 502
 503   /** Sets the buffer size.
 504    * @param size The size of the buffer, or 0 to let GLib pick a good size.
 505    */
 506   void set_buffer_size(gsize size);
 507
 508   /** Get the current flags for a IOChannel, including read-only
 509    * flags such as Glib::IO_FLAG_IS_READABLE.
 510    *
 511    * The values of the flags Glib::IO_FLAG_IS_READABLE and
 512    * Glib::IO_FLAG_IS_WRITEABLE are cached for internal use by the channel when
 513    * it is created.  If they should change at some later point (e.g. partial
 514    * shutdown of a socket with the UNIX <tt>shutdown()</tt> function), the user
 515    * should immediately call get_flags() to update the internal values of these
 516    * flags.
 517    * @return Bitwise combination of the flags set on the channel.
 518    */
 519
 520   /** Gets the current flags for a IOChannel, including read-only
 521    * flags such as IO_FLAG_IS_READABLE.
 522    *
 523    * The values of the flags IO_FLAG_IS_READABLE and IO_FLAG_IS_WRITEABLE
 524    * are cached for internal use by the channel when it is created.
 525    * If they should change at some later point (e.g. partial shutdown
 526    * of a socket with the UNIX shutdown() function), the user
 527    * should immediately call g_io_channel_get_flags() to update
 528    * the internal values of these flags.
 529    * @return The flags which are set on the channel.
 530    */
 531   IOFlags get_flags() const;
 532
 533   /** Set flags on the IOChannel.
 534    * @param flags Bitwise combination of the flags to set.
 535    * @return The operation result code.
 536    * @throw Glib::IOChannelError
 537    */
 538
 539   /** Sets the (writeable) flags in @a channel to ( @a flags & IO_CHANNEL_SET_MASK).
 540    * @param flags The flags to set on the IO channel.
 541    * @return The status of the operation.
 542    */
 543 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 544   IOStatus set_flags(IOFlags flags);
 545 #else
 546   IOStatus set_flags(IOFlags flags, std::auto_ptr<Glib::Error>& error);
 547 #endif //GLIBMM_EXCEPTIONS_ENABLED
 548
 549
 550   /** Set the buffering status of the I/O channel.
 551    * The buffering state can only be set if the channel's encoding is
 552    * <tt>""</tt>. For any other encoding, the channel must be buffered.
 553    *
 554    * A buffered channel can only be set unbuffered if the channel's internal
 555    * buffers have been flushed. Newly created channels or channels which have
 556    * returned Glib::IO_STATUS_EOF not require such a flush. For write-only
 557    * channels, a call to flush() is sufficient. For all other channels, the
 558    * buffers may be flushed by a call to seek().  This includes the possibility
 559    * of seeking with seek type Glib::SEEK_TYPE_CUR and an offset of zero. Note
 560    * that this means that socket-based channels cannot be set unbuffered once
 561    * they have had data read from them.
 562    *
 563    * The default state of the channel is buffered.
 564    *
 565    * @param buffered Whether to set the channel buffered or unbuffered.
 566    */
 567
 568   /** The buffering state can only be set if the channel's encoding
 569    * is <tt>0</tt>. For any other encoding, the channel must be buffered.
 570    *
 571    * A buffered channel can only be set unbuffered if the channel's
 572    * internal buffers have been flushed. Newly created channels or
 573    * channels which have returned IO_STATUS_EOF
 574    * not require such a flush. For write-only channels, a call to
 575    * g_io_channel_flush() is sufficient. For all other channels,
 576    * the buffers may be flushed by a call to g_io_channel_seek_position().
 577    * This includes the possibility of seeking with seek type SEEK_CUR
 578    * and an offset of zero. Note that this means that socket-based
 579    * channels cannot be set unbuffered once they have had data
 580    * read from them.
 581    *
 582    * On unbuffered channels, it is safe to mix read and write
 583    * calls from the new and old APIs, if this is necessary for
 584    * maintaining old code.
 585    *
 586    * The default state of the channel is buffered.
 587    * @param buffered Whether to set the channel buffered or unbuffered.
 588    */
 589   void set_buffered(bool buffered);
 590
 591   /** Get the buffering status of the I/O channel.
 592    * @return The buffering status of the channel.
 593    */
 594
 595   /** Return Value: <tt>true</tt> if the @a channel is buffered.
 596    * @return <tt>true</tt> if the @a channel is buffered.
 597    */
 598   bool get_buffered() const;
 599
 600   /** Returns an IOCondition depending on whether there is data to be
 601    * read/space to write data in the internal buffers in the I/O channel.
 602    * Only the flags Glib::IO_IN and Glib::IO_OUT may be set.
 603    * @return Bitwise combination of Glib::IOCondition flags.
 604    */
 605
 606   /** This function returns a IOCondition depending on whether there
 607    * is data to be read/space to write data in the internal buffers in
 608    * the IOChannel. Only the flags IO_IN and IO_OUT may be set.
 609    * @return A IOCondition.
 610    */
 611   IOCondition get_buffer_condition() const;
 612
 613   /** Returns whether the file/socket/whatever associated with the I/O channel
 614    * will be closed when the channel receives its final unref and is destroyed.
 615    * The default value of this is <tt>true</tt> for channels created by
 616    * create_from_file(), and <tt>false</tt> for all other channels.
 617    * @return Whether the channel will be closed on the final unref of the
 618    * IOChannel object.
 619    */
 620
 621   /** Return value: Whether the channel will be closed on the final unref of
 622    * @return Whether the channel will be closed on the final unref of
 623    * the GIOChannel data structure.
 624    */
 625   bool get_close_on_unref() const;
 626
 627   /** Setting this flag to <tt>true</tt> for a channel you have already closed
 628    * can cause problems.
 629    * @param do_close Whether to close the channel on the final unref of the
 630    * IOChannel object.  The default value of this is <tt>true</tt> for channels
 631    * created by create_from_file(), and <tt>false</tt> for all other channels.
 632    */
 633
 634   /** Setting this flag to <tt>true</tt> for a channel you have already closed
 635    * can cause problems.
 636    * @param do_close Whether to close the channel on the final unref of
 637    * the GIOChannel data structure. The default value of
 638    * this is <tt>true</tt> for channels created by g_io_channel_new_file(),
 639    * and <tt>false</tt> for all other channels.
 640    */
 641   void set_close_on_unref(bool do_close);
 642
 643   /** Sets the encoding for the input/output of the channel.
 644    * The internal encoding is always UTF-8.  The default encoding for the
 645    * external file is UTF-8.  The encoding <tt>""</tt> is safe to use with
 646    * binary data.
 647    *
 648    * The encoding can only be set if one of the following conditions
 649    * is true:
 650    *
 651    * -# The channel was just created, and has not been written to or read from
 652    *  yet.
 653    * -# The channel is write-only.
 654    * -# The channel is a file, and the file pointer was just repositioned by a
 655    *  call to seek_position().  (This flushes all the internal buffers.)
 656    * -# The current encoding is <tt>""</tt> or UTF-8.
 657    * -# One of the read methods has just returned Glib::IO_STATUS_EOF (or, in
 658    *  the case of read_to_end(), Glib::IO_STATUS_NORMAL).
 659    * -# The read() method has returned Glib::IO_STATUS_AGAIN or thrown
 660    *  a Glib::Error exception.  This may be useful in the case of
 661    *  ConvertError::ILLEGAL_SEQUENCE.  Returning one of these statuses
 662    *  from read_line() or read_to_end() does <em>not</em> guarantee that
 663    *  the encoding can be changed.
 664    *
 665    * Channels which do not meet one of the above conditions cannot call
 666    * seek_position() with a seek type of Glib::SEEK_TYPE_CUR and, if they
 667    * are "seekable", cannot call write() after calling one of the API
 668    * "read" methods.
 669    *
 670    * @param encoding The encoding name, or <tt>""</tt> for binary.
 671    * @return Glib::IO_STATUS_NORMAL if the encoding was successfully set.
 672    * @throw Glib::IOChannelError
 673    */
 674 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 675   IOStatus set_encoding(const std::string& encoding = std::string());
 676 #else
 677   IOStatus set_encoding(const std::string& encoding, std::auto_ptr<Glib::Error>& error);
 678 #endif //GLIBMM_EXCEPTIONS_ENABLED
 679
 680
 681   /** Get the encoding of the I/O channel.
 682    * @return The current encoding of the channel.
 683    */
 684   std::string get_encoding() const;
 685
 686
 687   void set_line_term(const std::string& term = std::string());
 688
 689
 690   std::string get_line_term() const;
 691
 692
 693   /** Creates an IOSource object.
 694    * Create a slot from a function to be called when condition is met
 695    * for the channel with sigc::ptr_fun() or sigc::mem_fun() and pass
 696    * it into the connect() function of the returned IOSource object.
 697    * Polling of the channel will start when you attach a MainContext
 698    * object to the returned IOSource object using its attach() function.
 699    *
 700    * Glib::signal_io().connect() is a simpler interface to the same
 701    * functionality, for the case where you want to add the source to the
 702    * default main context.
 703    * @param condition The condition to watch for.
 704    * @return An IOSource object that can be polled from a MainContext's event loop.
 705    */
 706   Glib::RefPtr<IOSource> create_watch(IOCondition condition);
 707
 708
 709   virtual void reference()   const;
 710   virtual void unreference() const;
 711
 712
 713   GIOChannel*       gobj()       { return gobject_; }
 714   const GIOChannel* gobj() const { return gobject_; }
 715
 716 protected:
 717   GIOChannel* gobject_;
 718
 719   /** Constructor that should be used by derived classes.
 720    * Use this constructor if you want to inherit from IOChannel.
 721    * It will set up a GIOChannel that will call the vfuncs of your
 722    * class even if it is being used from C code, and it will keep
 723    * a reference to the C++ code while the GIOChannel exists.
 724    */
 725   IOChannel();
 726
 727
 728 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 729   IOChannel(GIOChannel* gobject, bool take_copy);
 730 #endif
 731
 732   virtual IOStatus read_vfunc(char* buf, gsize count, gsize& bytes_read);
 733   virtual IOStatus write_vfunc(const char* buf, gsize count, gsize& bytes_written);
 734   virtual IOStatus seek_vfunc(gint64 offset, SeekType type);
 735   virtual IOStatus close_vfunc();
 736   virtual IOStatus set_flags_vfunc(IOFlags flags);
 737   virtual IOFlags  get_flags_vfunc();
 738   virtual Glib::RefPtr<Glib::Source> create_watch_vfunc(IOCondition cond);
 739
 740 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 741   friend class Glib::GlibmmIOChannel;
 742 #endif
 743
 744
 745 };
 746
 747 Glib::RefPtr<IOChannel> wrap(GIOChannel* gobject, bool take_copy = false);
 748
 749 } // namespace Glib
 750
 751
 752 #endif /* _GLIBMM_IOCHANNEL_H */
 753