// -*- c++ -*- /* $Id: iochannel.hg,v 1.8 2006/05/12 08:08:44 murrayc Exp $ */ /* Copyright (C) 2002 The gtkmm Development Team * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the Free * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ _DEFS(glibmm,glib) #include #include #include #include #include #include #include GLIBMM_USING_STD(string) #ifndef DOXYGEN_SHOULD_SKIP_THIS extern "C" { typedef struct _GIOChannel GIOChannel; } #endif namespace Glib { class Source; class IOSource; _WRAP_ENUM(SeekType, GSeekType, NO_GTYPE, s#^SEEK_#SEEK_TYPE_#) _WRAP_ENUM(IOStatus, GIOStatus, NO_GTYPE) _WRAP_ENUM(IOFlags, GIOFlags, NO_GTYPE) /** Exception class for IOChannel errors. */ _WRAP_GERROR(IOChannelError, GIOChannelError, G_IO_CHANNEL_ERROR, NO_GTYPE, s#^INVAL$#INVALID_ARGUMENT#, s#^ISDIR$#IS_DIRECTORY#, s#^PIPE$#BROKEN_PIPE#, s#^NOSPC$#NO_SPACE_LEFT#, s#^NXIO$#NO_SUCH_DEVICE#, s#^ACCES$#ACCESS_DENIED#, s#^FBIG$#FILE_TOO_BIG#, s#^IO$#IO_ERROR#, s#^OVERFLOW$#OVERFLOWN#) #ifndef DOXYGEN_SHOULD_SKIP_THIS class GlibmmIOChannel; #endif /** IOChannel aims to provide portable I/O support for files, pipes * and sockets, and to integrate them with the GLib main event loop. * * Note that IOChannels implement an automatic implicit character set * conversion to the data stream, and usually will not pass by default * binary data unchanged. To set the encoding of the channel, use e.g. * set_encoding("ISO-8859-15"). To set the channel to no encoding, use * set_encoding() without any arguments. * * You can create an IOChannel with one of the static create methods, or * implement one yourself, in which case you have to 1) override all * _vfunc() members. 2) set the GIOChannel flags in your constructor. * * @note This feature of being able to implement a custom Glib::IOChannel is * deprecated in glibmm 2.2. The vfunc interface has not yet stabilized * enough to allow that -- the C++ wrapper went in by pure accident. Besides, * it isn't terribly useful either. Thus please refrain from overriding any * IOChannel vfuncs. */ class IOChannel : public sigc::trackable { _CLASS_GENERIC(IOChannel, GIOChannel) dnl // We can't support get_fd() properly because it is impossible dnl // to detect the specific GIOChannel type at runtime. _IGNORE(g_io_channel_unix_get_fd, g_io_channel_win32_get_fd) dnl // deprecated or internal _IGNORE(g_io_channel_seek, g_io_channel_close, g_io_channel_read, g_io_channel_write, g_io_channel_win32_make_pollfd) public: virtual ~IOChannel(); /** Open a file @a filename as an I/O channel using mode @a mode. * This channel will be closed when the last reference to it is dropped, * so there is no need to call close() (though doing so will not cause * problems, as long as no attempt is made to access the channel after * it is closed). * @param filename The name of the file to open. * @param mode One of "r", "w", "a", * "r+", "w+", "a+". These have the * same meaning as in fopen(). * @return An IOChannel for the opened file. * @throw Glib::FileError */ #ifdef GLIBMM_EXCEPTIONS_ENABLED static Glib::RefPtr create_from_file(const std::string& filename, const std::string& mode); #else static Glib::RefPtr create_from_file(const std::string& filename, const std::string& mode, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED _IGNORE(g_io_channel_new_file) /** Creates an I/O channel from a file descriptor. * On Unix, IOChannels created with this function work for any file * descriptor or socket. * * On Win32, this can be used either for files opened with the MSVCRT (the * Microsoft run-time C library) _open() or _pipe(), * including file descriptors 0, 1 and 2 (corresponding to stdin, * stdout and stderr), or for Winsock SOCKETs. If * the parameter is a legal file descriptor, it is assumed to be such, * otherwise it should be a SOCKET. This relies on SOCKETs * and file descriptors not overlapping. If you want to be certain, call * either create_from_win32_fd() or create_from_win32_socket() instead as * appropriate. * * The term file descriptor as used in the context of Win32 refers to the * emulated Unix-like file descriptors MSVCRT provides. The native * corresponding concept is file HANDLE. There isn't as of yet * a way to get IOChannels for Win32 file HANDLEs. */ static Glib::RefPtr create_from_fd(int fd); _IGNORE(g_io_channel_unix_new) /* defined(DOXYGEN_SHOULD_SKIP_THIS) actually does the opposite of what it looks like... */ #if defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS) /** Create an I/O channel for C runtime (emulated Unix-like) file descriptors. * After calling add_watch() on a I/O channel returned by this function, you * shouldn't call read() on the file descriptor. This is because adding * polling for a file descriptor is implemented on Win32 by starting a thread * that sits blocked in a %read() from the file descriptor most of * the time. All reads from the file descriptor should be done by this * internal GLib thread. Your code should call only IOChannel::read(). */ static Glib::RefPtr create_from_win32_fd(int fd); _IGNORE(g_io_channel_win32_new_fd) /** Create an I/O channel for a winsock socket. The parameter should be a * SOCKET. Contrary to I/O channels for file descriptors (on Win32), * you can use normal recv() or recvfrom() on sockets even * if GLib is polling them. */ static Glib::RefPtr create_from_win32_socket(int socket); _IGNORE(g_io_channel_win32_new_socket) #endif /* defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS) */ /** Read a single UCS-4 character. * @retval thechar The Unicode character. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ _WRAP_METHOD(IOStatus read(gunichar& thechar), g_io_channel_read_unichar, errthrow) /** Read a character sequence into memory. * @param buf A buffer to read data into. * @param count The size of the buffer in bytes. Note that the buffer may * not be complelely filled even if there is data in the buffer if the * remaining data is not a complete character. * @retval bytes_read The number of bytes read. This may be zero even on * success if @a count < 6 and the channel's encoding is not "". * This indicates that the next UTF-8 character is too wide for the buffer. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ _WRAP_METHOD(IOStatus read(char* buf, gsize count, gsize& bytes_read), g_io_channel_read_chars, errthrow) /** Read a maximum of @a count bytes into @a str. * @param count The maximum number of bytes to read. * @retval str The characters that have been read. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ #ifdef GLIBMM_EXCEPTIONS_ENABLED IOStatus read(Glib::ustring& str, gsize count); #else IOStatus read(Glib::ustring& str, gsize count, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED /** Read a whole line. * Reads until the line separator is found, which is included * in the result string. * @retval line The line that was read. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ #ifdef GLIBMM_EXCEPTIONS_ENABLED IOStatus read_line(Glib::ustring& line); #else IOStatus read_line(Glib::ustring& line, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED _IGNORE(g_io_channel_read_line, g_io_channel_read_line_string) /** Reads all the remaining data from the file. * @retval str The resulting string. * @return Glib::IO_STATUS_NORMAL on success. This function never * returns Glib::IO_STATUS_EOF. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ #ifdef GLIBMM_EXCEPTIONS_ENABLED IOStatus read_to_end(Glib::ustring& str); #else IOStatus read_to_end(Glib::ustring& str, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED _IGNORE(g_io_channel_read_to_end) /** Write a string to the I/O channel. * Note that this method does not return the number of characters written. * If the channel is blocking and the returned value is * Glib::IO_STATUS_NORMAL, the whole string was written. * @param str the string to write. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ #ifdef GLIBMM_EXCEPTIONS_ENABLED IOStatus write(const Glib::ustring& str); #else IOStatus write(const Glib::ustring& str, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED /** Write a memory area of @a count bytes to the I/O channel. * @param buf The start of the memory area. * @param count The number of bytes to write. * @retval bytes_written The number of bytes written to the channel. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ _WRAP_METHOD(IOStatus write(const char* buf, gssize count, gsize& bytes_written), g_io_channel_write_chars, errthrow) /** Write a single UCS-4 character to the I/O channel. * @param unichar The character to write. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ _WRAP_METHOD(IOStatus write(gunichar unichar), g_io_channel_write_unichar, errthrow) /** Seek the I/O channel to a specific position. * @param offset The offset in bytes from the position specified by @a type. * @param type A SeekType. The type Glib::SEEK_TYPE_CUR is only allowed in * those cases where a call to set_encoding() is allowed. See the * documentation for set_encoding() for details. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ _WRAP_METHOD(IOStatus seek(gint64 offset, SeekType type = SEEK_TYPE_SET), g_io_channel_seek_position, errthrow) /** Flush the buffers of the I/O channel. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ _WRAP_METHOD(IOStatus flush(), g_io_channel_flush, errthrow) /** Close the I/O channel. * Any pending data to be written will be flushed if @a flush is true. * The channel will not be freed until the last reference is dropped. * Accessing the channel after closing it is considered an error. * @param flush Whether to flush() pending data before closing the channel. * @return The status of the operation. * @throw Glib::IOChannelError */ _WRAP_METHOD(IOStatus close(bool flush = true), g_io_channel_shutdown, errthrow) /** Get the IOChannel internal buffer size. * @return The buffer size. */ _WRAP_METHOD(gsize get_buffer_size() const, g_io_channel_get_buffer_size) /** Set the internal IOChannel buffer size. * @param size The buffer size the IOChannel should use. */ _WRAP_METHOD(void set_buffer_size(gsize size), g_io_channel_set_buffer_size) /** Get the current flags for a IOChannel, including read-only * flags such as Glib::IO_FLAG_IS_READABLE. * * The values of the flags Glib::IO_FLAG_IS_READABLE and * Glib::IO_FLAG_IS_WRITEABLE are cached for internal use by the channel when * it is created. If they should change at some later point (e.g. partial * shutdown of a socket with the UNIX shutdown() function), the user * should immediately call get_flags() to update the internal values of these * flags. * @return Bitwise combination of the flags set on the channel. */ _WRAP_METHOD(IOFlags get_flags() const, g_io_channel_get_flags) /** Set flags on the IOChannel. * @param flags Bitwise combination of the flags to set. * @return The operation result code. * @throw Glib::IOChannelError */ _WRAP_METHOD(IOStatus set_flags(IOFlags flags), g_io_channel_set_flags, errthrow) /** Set the buffering status of the I/O channel. * The buffering state can only be set if the channel's encoding is * "". For any other encoding, the channel must be buffered. * * A buffered channel can only be set unbuffered if the channel's internal * buffers have been flushed. Newly created channels or channels which have * returned Glib::IO_STATUS_EOF not require such a flush. For write-only * channels, a call to flush() is sufficient. For all other channels, the * buffers may be flushed by a call to seek(). This includes the possibility * of seeking with seek type Glib::SEEK_TYPE_CUR and an offset of zero. Note * that this means that socket-based channels cannot be set unbuffered once * they have had data read from them. * * The default state of the channel is buffered. * * @param buffered Whether to set the channel buffered or unbuffered. */ _WRAP_METHOD(void set_buffered(bool buffered), g_io_channel_set_buffered) /** Get the buffering status of the I/O channel. * @return The buffering status of the channel. */ _WRAP_METHOD(bool get_buffered() const, g_io_channel_get_buffered) /** Returns an IOCondition depending on whether there is data to be * read/space to write data in the internal buffers in the I/O channel. * Only the flags Glib::IO_IN and Glib::IO_OUT may be set. * @return Bitwise combination of Glib::IOCondition flags. */ _WRAP_METHOD(IOCondition get_buffer_condition() const, g_io_channel_get_buffer_condition) /** Returns whether the file/socket/whatever associated with the I/O channel * will be closed when the channel receives its final unref and is destroyed. * The default value of this is true for channels created by * create_from_file(), and false for all other channels. * @return Whether the channel will be closed on the final unref of the * IOChannel object. */ _WRAP_METHOD(bool get_close_on_unref() const, g_io_channel_get_close_on_unref) /** Setting this flag to true for a channel you have already closed * can cause problems. * @param do_close Whether to close the channel on the final unref of the * IOChannel object. The default value of this is true for channels * created by create_from_file(), and false for all other channels. */ _WRAP_METHOD(void set_close_on_unref(bool do_close), g_io_channel_set_close_on_unref) /** Sets the encoding for the input/output of the channel. * The internal encoding is always UTF-8. The default encoding for the * external file is UTF-8. The encoding "" is safe to use with * binary data. * * The encoding can only be set if one of the following conditions * is true: * * -# The channel was just created, and has not been written to or read from * yet. * -# The channel is write-only. * -# The channel is a file, and the file pointer was just repositioned by a * call to seek_position(). (This flushes all the internal buffers.) * -# The current encoding is "" or UTF-8. * -# One of the read methods has just returned Glib::IO_STATUS_EOF (or, in * the case of read_to_end(), Glib::IO_STATUS_NORMAL). * -# The read() method has returned Glib::IO_STATUS_AGAIN or thrown * a Glib::Error exception. This may be useful in the case of * ConvertError::ILLEGAL_SEQUENCE. Returning one of these statuses * from read_line() or read_to_end() does not guarantee that * the encoding can be changed. * * Channels which do not meet one of the above conditions cannot call * seek_position() with a seek type of Glib::SEEK_TYPE_CUR and, if they * are "seekable", cannot call write() after calling one of the API * "read" methods. * * @param encoding The encoding name, or "" for binary. * @return Glib::IO_STATUS_NORMAL if the encoding was successfully set. * @throw Glib::IOChannelError */ #ifdef GLIBMM_EXCEPTIONS_ENABLED IOStatus set_encoding(const std::string& encoding = std::string()); #else IOStatus set_encoding(const std::string& encoding, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED _IGNORE(g_io_channel_set_encoding) /** Get the encoding of the I/O channel. * @return The current encoding of the channel. */ std::string get_encoding() const; _IGNORE(g_io_channel_get_encoding) void set_line_term(const std::string& term = std::string()); _IGNORE(g_io_channel_set_line_term) std::string get_line_term() const; _IGNORE(g_io_channel_get_line_term) /** Creates an IOSource object. * Create a slot from a function to be called when condition is met * for the channel with sigc::ptr_fun() or sigc::mem_fun() and pass * it into the connect() function of the returned IOSource object. * Polling of the channel will start when you attach a MainContext * object to the returned IOSource object using its attach() function. * * Glib::signal_io().connect() is a simpler interface to the same * functionality, for the case where you want to add the source to the * default main context. * @param condition The condition to watch for. * @return An IOSource object that can be polled from a MainContext's event loop. */ Glib::RefPtr create_watch(IOCondition condition); _IGNORE(g_io_channel_create_watch) virtual void reference() const; virtual void unreference() const; _IGNORE(g_io_channel_ref, g_io_channel_unref) GIOChannel* gobj() { return gobject_; } const GIOChannel* gobj() const { return gobject_; } protected: GIOChannel* gobject_; /** Constructor that should be used by derived classes. * Use this constructor if you want to inherit from IOChannel. * It will set up a GIOChannel that will call the vfuncs of your * class even if it is being used from C code, and it will keep * a reference to the C++ code while the GIOChannel exists. */ IOChannel(); _IGNORE(g_io_channel_init) #ifndef DOXYGEN_SHOULD_SKIP_THIS IOChannel(GIOChannel* gobject, bool take_copy); #endif virtual IOStatus read_vfunc(char* buf, gsize count, gsize& bytes_read); virtual IOStatus write_vfunc(const char* buf, gsize count, gsize& bytes_written); virtual IOStatus seek_vfunc(gint64 offset, SeekType type); virtual IOStatus close_vfunc(); virtual IOStatus set_flags_vfunc(IOFlags flags); virtual IOFlags get_flags_vfunc(); virtual Glib::RefPtr create_watch_vfunc(IOCondition cond); #ifndef DOXYGEN_SHOULD_SKIP_THIS friend class Glib::GlibmmIOChannel; #endif }; Glib::RefPtr wrap(GIOChannel* gobject, bool take_copy = false); } // namespace Glib