libs/glibmm2/glib/src/iochannel.hg

   1 // -*- c++ -*-
   2 /* $Id: iochannel.hg,v 1.8 2006/05/12 08:08:44 murrayc Exp $ */
   3
   4 /* Copyright (C) 2002 The gtkmm Development Team
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the Free
  18  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  19  */
  20
  21 _DEFS(glibmm,glib)
  22
  23 #include <glibmm/error.h>
  24 #include <glibmm/main.h>
  25 #include <glibmm/refptr.h>
  26 #include <glibmm/ustring.h>
  27 #include <glib/gtypes.h>
  28
  29 #include <string>
  30 #include <glibmmconfig.h>
  31
  32 GLIBMM_USING_STD(string)
  33
  34 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  35 extern "C" { typedef struct _GIOChannel GIOChannel; }
  36 #endif
  37
  38
  39 namespace Glib
  40 {
  41
  42 class Source;
  43 class IOSource;
  44
  45 _WRAP_ENUM(SeekType, GSeekType, NO_GTYPE, s#^SEEK_#SEEK_TYPE_#)
  46 _WRAP_ENUM(IOStatus, GIOStatus, NO_GTYPE)
  47 _WRAP_ENUM(IOFlags, GIOFlags, NO_GTYPE)
  48
  49 /** Exception class for IOChannel errors.
  50  */
  51 _WRAP_GERROR(IOChannelError, GIOChannelError, G_IO_CHANNEL_ERROR, NO_GTYPE,
  52     s#^INVAL$#INVALID_ARGUMENT#,
  53     s#^ISDIR$#IS_DIRECTORY#,
  54     s#^PIPE$#BROKEN_PIPE#,
  55     s#^NOSPC$#NO_SPACE_LEFT#,
  56     s#^NXIO$#NO_SUCH_DEVICE#,
  57     s#^ACCES$#ACCESS_DENIED#,
  58     s#^FBIG$#FILE_TOO_BIG#,
  59     s#^IO$#IO_ERROR#,
  60     s#^OVERFLOW$#OVERFLOWN#)
  61
  62 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  63 class GlibmmIOChannel;
  64 #endif
  65
  66 /** IOChannel aims to provide portable I/O support for files, pipes
  67  * and sockets, and to integrate them with the GLib main event loop.
  68  *
  69  * Note that IOChannels implement an automatic implicit character set
  70  * conversion to the data stream, and usually will not pass by default
  71  * binary data unchanged.  To set the encoding of the channel, use e.g.
  72  * set_encoding("ISO-8859-15"). To set the channel to no encoding, use
  73  * set_encoding() without any arguments.
  74  *
  75  * You can create an IOChannel with one of the static create methods, or
  76  * implement one yourself, in which case you have to 1)&nbsp;override all
  77  * _vfunc() members. 2)&nbsp;set the GIOChannel flags in your constructor.
  78  *
  79  * @note This feature of being able to implement a custom Glib::IOChannel is
  80  * deprecated in glibmm&nbsp;2.2.  The vfunc interface has not yet stabilized
  81  * enough to allow that -- the C++ wrapper went in by pure accident.  Besides,
  82  * it isn't terribly useful either.  Thus please refrain from overriding any
  83  * IOChannel vfuncs.
  84  */
  85 class IOChannel : public sigc::trackable
  86 {
  87   _CLASS_GENERIC(IOChannel, GIOChannel)
  88
  89   dnl // We can't support get_fd() properly because it is impossible
  90   dnl // to detect the specific GIOChannel type at runtime.
  91   _IGNORE(g_io_channel_unix_get_fd, g_io_channel_win32_get_fd)
  92
  93   dnl // deprecated or internal
  94   _IGNORE(g_io_channel_seek, g_io_channel_close, g_io_channel_read,
  95           g_io_channel_write, g_io_channel_win32_make_pollfd)
  96
  97 public:
  98   virtual ~IOChannel();
  99
 100   /** Open a file @a filename as an I/O channel using mode @a mode.
 101    * This channel will be closed when the last reference to it is dropped,
 102    * so there is no need to call close() (though doing so will not cause
 103    * problems, as long as no attempt is made to access the channel after
 104    * it is closed).
 105    * @param filename The name of the file to open.
 106    * @param mode One of <tt>"r"</tt>, <tt>"w"</tt>, <tt>"a"</tt>,
 107    *  <tt>"r+"</tt>, <tt>"w+"</tt>, <tt>"a+"</tt>. These have the
 108    *  same meaning as in <tt>fopen()</tt>.
 109    * @return An IOChannel for the opened file.
 110    * @throw Glib::FileError
 111    */
 112 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 113   static Glib::RefPtr<IOChannel> create_from_file(const std::string& filename, const std::string& mode);
 114 #else
 115   static Glib::RefPtr<IOChannel> create_from_file(const std::string& filename, const std::string& mode, std::auto_ptr<Glib::Error>& error);
 116 #endif //GLIBMM_EXCEPTIONS_ENABLED
 117   _IGNORE(g_io_channel_new_file)
 118
 119   /** Creates an I/O channel from a file descriptor.
 120    * On Unix, IOChannels created with this function work for any file
 121    * descriptor or socket.
 122    *
 123    * On Win32, this can be used either for files opened with the MSVCRT (the
 124    * Microsoft run-time C library) <tt>_open()</tt> or <tt>_pipe()</tt>,
 125    * including file descriptors 0, 1 and 2 (corresponding to <tt>stdin</tt>,
 126    * <tt>stdout</tt> and <tt>stderr</tt>), or for Winsock <tt>SOCKET</tt>s. If
 127    * the parameter is a legal file descriptor, it is assumed to be such,
 128    * otherwise it should be a <tt>SOCKET</tt>. This relies on <tt>SOCKET</tt>s
 129    * and file descriptors not overlapping. If you want to be certain, call
 130    * either create_from_win32_fd() or create_from_win32_socket() instead as
 131    * appropriate.
 132    *
 133    * The term file descriptor as used in the context of Win32 refers to the
 134    * emulated Unix-like file descriptors MSVCRT provides. The native
 135    * corresponding concept is file <tt>HANDLE</tt>. There isn't as of yet
 136    * a way to get IOChannels for Win32 file <tt>HANDLE</tt>s.
 137    */
 138   static Glib::RefPtr<IOChannel> create_from_fd(int fd);
 139   _IGNORE(g_io_channel_unix_new)
 140
 141 /* defined(DOXYGEN_SHOULD_SKIP_THIS) actually does the opposite of what it looks like... */
 142 #if defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS)
 143
 144   /** Create an I/O channel for C runtime (emulated Unix-like) file descriptors.
 145    * After calling add_watch() on a I/O channel returned by this function, you
 146    * shouldn't call read() on the file descriptor. This is because adding
 147    * polling for a file descriptor is implemented on Win32 by starting a thread
 148    * that sits blocked in a <tt>%read()</tt> from the file descriptor most of
 149    * the time.  All reads from the file descriptor should be done by this
 150    * internal GLib thread. Your code should call only IOChannel::read().
 151    */
 152   static Glib::RefPtr<IOChannel> create_from_win32_fd(int fd);
 153   _IGNORE(g_io_channel_win32_new_fd)
 154
 155   /** Create an I/O channel for a winsock socket. The parameter should be a
 156    * <tt>SOCKET</tt>. Contrary to I/O channels for file descriptors (on Win32),
 157    * you can use normal <tt>recv()</tt> or <tt>recvfrom()</tt> on sockets even
 158    * if GLib is polling them.
 159    */
 160   static Glib::RefPtr<IOChannel> create_from_win32_socket(int socket);
 161   _IGNORE(g_io_channel_win32_new_socket)
 162
 163 #endif /* defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS) */
 164
 165   /** Read a single UCS-4 character.
 166    * @retval thechar The Unicode character.
 167    * @return The status of the operation.
 168    * @throw Glib::IOChannelError
 169    * @throw Glib::ConvertError
 170    */
 171   _WRAP_METHOD(IOStatus read(gunichar& thechar), g_io_channel_read_unichar, errthrow)
 172
 173   /** Read a character sequence into memory.
 174    * @param buf A buffer to read data into.
 175    * @param count The size of the buffer in bytes.  Note that the buffer may
 176    * not be complelely filled even if there is data in the buffer if the
 177    * remaining data is not a complete character.
 178    * @retval bytes_read The number of bytes read.  This may be zero even on
 179    * success if @a count < 6 and the channel's encoding is not <tt>""</tt>.
 180    * This indicates that the next UTF-8 character is too wide for the buffer.
 181    * @return The status of the operation.
 182    * @throw Glib::IOChannelError
 183    * @throw Glib::ConvertError
 184    */
 185   _WRAP_METHOD(IOStatus read(char* buf, gsize count, gsize& bytes_read),
 186                g_io_channel_read_chars, errthrow)
 187
 188   /** Read a maximum of @a count bytes into @a str.
 189    * @param count The maximum number of bytes to read.
 190    * @retval str The characters that have been read.
 191    * @return The status of the operation.
 192    * @throw Glib::IOChannelError
 193    * @throw Glib::ConvertError
 194    */
 195 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 196   IOStatus read(Glib::ustring& str, gsize count);
 197 #else
 198   IOStatus read(Glib::ustring& str, gsize count, std::auto_ptr<Glib::Error>& error);
 199 #endif //GLIBMM_EXCEPTIONS_ENABLED
 200
 201   /** Read a whole line.
 202    * Reads until the line separator is found, which is included
 203    * in the result string.
 204    * @retval line The line that was read.
 205    * @return The status of the operation.
 206    * @throw Glib::IOChannelError
 207    * @throw Glib::ConvertError
 208    */
 209 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 210   IOStatus read_line(Glib::ustring& line);
 211 #else
 212   IOStatus read_line(Glib::ustring& line, std::auto_ptr<Glib::Error>& error);
 213 #endif //GLIBMM_EXCEPTIONS_ENABLED
 214   _IGNORE(g_io_channel_read_line, g_io_channel_read_line_string)
 215
 216   /** Reads all the remaining data from the file.
 217    * @retval str The resulting string.
 218    * @return Glib::IO_STATUS_NORMAL on success. This function never
 219    *  returns Glib::IO_STATUS_EOF.
 220    * @throw Glib::IOChannelError
 221    * @throw Glib::ConvertError
 222    */
 223 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 224   IOStatus read_to_end(Glib::ustring& str);
 225 #else
 226   IOStatus read_to_end(Glib::ustring& str, std::auto_ptr<Glib::Error>& error);
 227 #endif //GLIBMM_EXCEPTIONS_ENABLED
 228   _IGNORE(g_io_channel_read_to_end)
 229
 230   /** Write a string to the I/O channel.
 231    * Note that this method does not return the number of characters written.
 232    * If the channel is blocking and the returned value is
 233    * Glib::IO_STATUS_NORMAL, the whole string was written.
 234    * @param str the string to write.
 235    * @return The status of the operation.
 236    * @throw Glib::IOChannelError
 237    * @throw Glib::ConvertError
 238    */
 239 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 240   IOStatus write(const Glib::ustring& str);
 241 #else
 242   IOStatus write(const Glib::ustring& str, std::auto_ptr<Glib::Error>& error);
 243 #endif //GLIBMM_EXCEPTIONS_ENABLED
 244
 245   /** Write a memory area of @a count bytes to the I/O channel.
 246    * @param buf The start of the memory area.
 247    * @param count The number of bytes to write.
 248    * @retval bytes_written The number of bytes written to the channel.
 249    * @return The status of the operation.
 250    * @throw Glib::IOChannelError
 251    * @throw Glib::ConvertError
 252    */
 253   _WRAP_METHOD(IOStatus write(const char* buf, gssize count, gsize& bytes_written),
 254                g_io_channel_write_chars, errthrow)
 255
 256   /** Write a single UCS-4 character to the I/O channel.
 257    * @param unichar The character to write.
 258    * @return The status of the operation.
 259    * @throw Glib::IOChannelError
 260    * @throw Glib::ConvertError
 261    */
 262   _WRAP_METHOD(IOStatus write(gunichar unichar), g_io_channel_write_unichar, errthrow)
 263
 264   /** Seek the I/O channel to a specific position.
 265    * @param offset The offset in bytes from the position specified by @a type.
 266    * @param type A SeekType. The type Glib::SEEK_TYPE_CUR is only allowed in
 267    * those cases where a call to set_encoding() is allowed. See the
 268    * documentation for set_encoding() for details.
 269    * @return The status of the operation.
 270    * @throw Glib::IOChannelError
 271    * @throw Glib::ConvertError
 272    */
 273   _WRAP_METHOD(IOStatus seek(gint64 offset, SeekType type = SEEK_TYPE_SET),
 274                g_io_channel_seek_position, errthrow)
 275
 276   /** Flush the buffers of the I/O channel.
 277    * @return The status of the operation.
 278    * @throw Glib::IOChannelError
 279    * @throw Glib::ConvertError
 280    */
 281   _WRAP_METHOD(IOStatus flush(), g_io_channel_flush, errthrow)
 282
 283   /** Close the I/O channel.
 284    * Any pending data to be written will be flushed if @a flush is <tt>true</tt>.
 285    * The channel will not be freed until the last reference is dropped.
 286    * Accessing the channel after closing it is considered an error.
 287    * @param flush Whether to flush() pending data before closing the channel.
 288    * @return The status of the operation.
 289    * @throw Glib::IOChannelError
 290    */
 291   _WRAP_METHOD(IOStatus close(bool flush = true), g_io_channel_shutdown, errthrow)
 292
 293   /** Get the IOChannel internal buffer size.
 294    * @return The buffer size.
 295    */
 296   _WRAP_METHOD(gsize get_buffer_size() const, g_io_channel_get_buffer_size)
 297
 298   /** Set the internal IOChannel buffer size.
 299    * @param size The buffer size the IOChannel should use.
 300    */
 301   _WRAP_METHOD(void set_buffer_size(gsize size), g_io_channel_set_buffer_size)
 302
 303   /** Get the current flags for a IOChannel, including read-only
 304    * flags such as Glib::IO_FLAG_IS_READABLE.
 305    *
 306    * The values of the flags Glib::IO_FLAG_IS_READABLE and
 307    * Glib::IO_FLAG_IS_WRITEABLE are cached for internal use by the channel when
 308    * it is created.  If they should change at some later point (e.g. partial
 309    * shutdown of a socket with the UNIX <tt>shutdown()</tt> function), the user
 310    * should immediately call get_flags() to update the internal values of these
 311    * flags.
 312    * @return Bitwise combination of the flags set on the channel.
 313    */
 314   _WRAP_METHOD(IOFlags get_flags() const, g_io_channel_get_flags)
 315
 316   /** Set flags on the IOChannel.
 317    * @param flags Bitwise combination of the flags to set.
 318    * @return The operation result code.
 319    * @throw Glib::IOChannelError
 320    */
 321   _WRAP_METHOD(IOStatus set_flags(IOFlags flags), g_io_channel_set_flags, errthrow)
 322
 323   /** Set the buffering status of the I/O channel.
 324    * The buffering state can only be set if the channel's encoding is
 325    * <tt>""</tt>. For any other encoding, the channel must be buffered.
 326    *
 327    * A buffered channel can only be set unbuffered if the channel's internal
 328    * buffers have been flushed. Newly created channels or channels which have
 329    * returned Glib::IO_STATUS_EOF not require such a flush. For write-only
 330    * channels, a call to flush() is sufficient. For all other channels, the
 331    * buffers may be flushed by a call to seek().  This includes the possibility
 332    * of seeking with seek type Glib::SEEK_TYPE_CUR and an offset of zero. Note
 333    * that this means that socket-based channels cannot be set unbuffered once
 334    * they have had data read from them.
 335    *
 336    * The default state of the channel is buffered.
 337    *
 338    * @param buffered Whether to set the channel buffered or unbuffered.
 339    */
 340   _WRAP_METHOD(void set_buffered(bool buffered), g_io_channel_set_buffered)
 341
 342   /** Get the buffering status of the I/O channel.
 343    * @return The buffering status of the channel.
 344    */
 345   _WRAP_METHOD(bool get_buffered() const, g_io_channel_get_buffered)
 346
 347   /** Returns an IOCondition depending on whether there is data to be
 348    * read/space to write data in the internal buffers in the I/O channel.
 349    * Only the flags Glib::IO_IN and Glib::IO_OUT may be set.
 350    * @return Bitwise combination of Glib::IOCondition flags.
 351    */
 352   _WRAP_METHOD(IOCondition get_buffer_condition() const, g_io_channel_get_buffer_condition)
 353
 354   /** Returns whether the file/socket/whatever associated with the I/O channel
 355    * will be closed when the channel receives its final unref and is destroyed.
 356    * The default value of this is <tt>true</tt> for channels created by
 357    * create_from_file(), and <tt>false</tt> for all other channels.
 358    * @return Whether the channel will be closed on the final unref of the
 359    * IOChannel object.
 360    */
 361   _WRAP_METHOD(bool get_close_on_unref() const, g_io_channel_get_close_on_unref)
 362
 363   /** Setting this flag to <tt>true</tt> for a channel you have already closed
 364    * can cause problems.
 365    * @param do_close Whether to close the channel on the final unref of the
 366    * IOChannel object.  The default value of this is <tt>true</tt> for channels
 367    * created by create_from_file(), and <tt>false</tt> for all other channels.
 368    */
 369   _WRAP_METHOD(void set_close_on_unref(bool do_close), g_io_channel_set_close_on_unref)
 370
 371   /** Sets the encoding for the input/output of the channel.
 372    * The internal encoding is always UTF-8.  The default encoding for the
 373    * external file is UTF-8.  The encoding <tt>""</tt> is safe to use with
 374    * binary data.
 375    *
 376    * The encoding can only be set if one of the following conditions
 377    * is true:
 378    *
 379    * -# The channel was just created, and has not been written to or read from
 380    *  yet.
 381    * -# The channel is write-only.
 382    * -# The channel is a file, and the file pointer was just repositioned by a
 383    *  call to seek_position().  (This flushes all the internal buffers.)
 384    * -# The current encoding is <tt>""</tt> or UTF-8.
 385    * -# One of the read methods has just returned Glib::IO_STATUS_EOF (or, in
 386    *  the case of read_to_end(), Glib::IO_STATUS_NORMAL).
 387    * -# The read() method has returned Glib::IO_STATUS_AGAIN or thrown
 388    *  a Glib::Error exception.  This may be useful in the case of
 389    *  ConvertError::ILLEGAL_SEQUENCE.  Returning one of these statuses
 390    *  from read_line() or read_to_end() does <em>not</em> guarantee that
 391    *  the encoding can be changed.
 392    *
 393    * Channels which do not meet one of the above conditions cannot call
 394    * seek_position() with a seek type of Glib::SEEK_TYPE_CUR and, if they
 395    * are "seekable", cannot call write() after calling one of the API
 396    * "read" methods.
 397    *
 398    * @param encoding The encoding name, or <tt>""</tt> for binary.
 399    * @return Glib::IO_STATUS_NORMAL if the encoding was successfully set.
 400    * @throw Glib::IOChannelError
 401    */
 402 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 403   IOStatus set_encoding(const std::string& encoding = std::string());
 404 #else
 405   IOStatus set_encoding(const std::string& encoding, std::auto_ptr<Glib::Error>& error);
 406 #endif //GLIBMM_EXCEPTIONS_ENABLED
 407   _IGNORE(g_io_channel_set_encoding)
 408
 409   /** Get the encoding of the I/O channel.
 410    * @return The current encoding of the channel.
 411    */
 412   std::string get_encoding() const;
 413   _IGNORE(g_io_channel_get_encoding)
 414
 415   void set_line_term(const std::string& term = std::string());
 416   _IGNORE(g_io_channel_set_line_term)
 417
 418   std::string get_line_term() const;
 419   _IGNORE(g_io_channel_get_line_term)
 420
 421   /** Creates an IOSource object.
 422    * Create a slot from a function to be called when condition is met
 423    * for the channel with sigc::ptr_fun() or sigc::mem_fun() and pass
 424    * it into the connect() function of the returned IOSource object.
 425    * Polling of the channel will start when you attach a MainContext
 426    * object to the returned IOSource object using its attach() function.
 427    *
 428    * Glib::signal_io().connect() is a simpler interface to the same
 429    * functionality, for the case where you want to add the source to the
 430    * default main context.
 431    * @param condition The condition to watch for.
 432    * @return An IOSource object that can be polled from a MainContext's event loop.
 433    */
 434   Glib::RefPtr<IOSource> create_watch(IOCondition condition);
 435   _IGNORE(g_io_channel_create_watch)
 436
 437   virtual void reference()   const;
 438   virtual void unreference() const;
 439   _IGNORE(g_io_channel_ref, g_io_channel_unref)
 440
 441   GIOChannel*       gobj()       { return gobject_; }
 442   const GIOChannel* gobj() const { return gobject_; }
 443
 444 protected:
 445   GIOChannel* gobject_;
 446
 447   /** Constructor that should be used by derived classes.
 448    * Use this constructor if you want to inherit from IOChannel.
 449    * It will set up a GIOChannel that will call the vfuncs of your
 450    * class even if it is being used from C code, and it will keep
 451    * a reference to the C++ code while the GIOChannel exists.
 452    */
 453   IOChannel();
 454   _IGNORE(g_io_channel_init)
 455
 456 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 457   IOChannel(GIOChannel* gobject, bool take_copy);
 458 #endif
 459
 460   virtual IOStatus read_vfunc(char* buf, gsize count, gsize& bytes_read);
 461   virtual IOStatus write_vfunc(const char* buf, gsize count, gsize& bytes_written);
 462   virtual IOStatus seek_vfunc(gint64 offset, SeekType type);
 463   virtual IOStatus close_vfunc();
 464   virtual IOStatus set_flags_vfunc(IOFlags flags);
 465   virtual IOFlags  get_flags_vfunc();
 466   virtual Glib::RefPtr<Glib::Source> create_watch_vfunc(IOCondition cond);
 467
 468 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 469   friend class Glib::GlibmmIOChannel;
 470 #endif
 471 };
 472
 473 Glib::RefPtr<IOChannel> wrap(GIOChannel* gobject, bool take_copy = false);
 474
 475 } // namespace Glib
 476