// -*- c++ -*- // Generated by gtkmmproc -- DO NOT MODIFY! #ifndef _GLIBMM_IOCHANNEL_H #define _GLIBMM_IOCHANNEL_H // -*- c++ -*- /* $Id$ */ /* 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. */ #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; /** @addtogroup glibmmEnums Enums and Flags */ /** * @ingroup glibmmEnums */ enum SeekType { SEEK_TYPE_CUR, SEEK_TYPE_SET, SEEK_TYPE_END }; /** * @ingroup glibmmEnums */ enum IOStatus { IO_STATUS_ERROR, IO_STATUS_NORMAL, IO_STATUS_EOF, IO_STATUS_AGAIN }; /** * @ingroup glibmmEnums * @par Bitwise operators: * %IOFlags operator|(IOFlags, IOFlags)
* %IOFlags operator&(IOFlags, IOFlags)
* %IOFlags operator^(IOFlags, IOFlags)
* %IOFlags operator~(IOFlags)
* %IOFlags& operator|=(IOFlags&, IOFlags)
* %IOFlags& operator&=(IOFlags&, IOFlags)
* %IOFlags& operator^=(IOFlags&, IOFlags)
*/ enum IOFlags { IO_FLAG_APPEND = 1 << 0, IO_FLAG_NONBLOCK = 1 << 1, IO_FLAG_IS_READABLE = 1 << 2, IO_FLAG_IS_WRITEABLE = 1 << 3, IO_FLAG_IS_SEEKABLE = 1 << 4, IO_FLAG_GET_MASK = 0x0, IO_FLAG_SET_MASK = 0x1 }; /** @ingroup glibmmEnums */ inline IOFlags operator|(IOFlags lhs, IOFlags rhs) { return static_cast(static_cast(lhs) | static_cast(rhs)); } /** @ingroup glibmmEnums */ inline IOFlags operator&(IOFlags lhs, IOFlags rhs) { return static_cast(static_cast(lhs) & static_cast(rhs)); } /** @ingroup glibmmEnums */ inline IOFlags operator^(IOFlags lhs, IOFlags rhs) { return static_cast(static_cast(lhs) ^ static_cast(rhs)); } /** @ingroup glibmmEnums */ inline IOFlags operator~(IOFlags flags) { return static_cast(~static_cast(flags)); } /** @ingroup glibmmEnums */ inline IOFlags& operator|=(IOFlags& lhs, IOFlags rhs) { return (lhs = static_cast(static_cast(lhs) | static_cast(rhs))); } /** @ingroup glibmmEnums */ inline IOFlags& operator&=(IOFlags& lhs, IOFlags rhs) { return (lhs = static_cast(static_cast(lhs) & static_cast(rhs))); } /** @ingroup glibmmEnums */ inline IOFlags& operator^=(IOFlags& lhs, IOFlags rhs) { return (lhs = static_cast(static_cast(lhs) ^ static_cast(rhs))); } /** Exception class for IOChannel errors. */ class IOChannelError : public Glib::Error { public: enum Code { FILE_TOO_BIG, INVALID_ARGUMENT, IO_ERROR, IS_DIRECTORY, NO_SPACE_LEFT, NO_SUCH_DEVICE, OVERFLOWN, BROKEN_PIPE, FAILED }; IOChannelError(Code error_code, const Glib::ustring& error_message); explicit IOChannelError(GError* gobject); Code code() const; #ifndef DOXYGEN_SHOULD_SKIP_THIS private: static void throw_func(GError* gobject); friend void wrap_init(); // uses throw_func() #endif }; #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 { public: #ifndef DOXYGEN_SHOULD_SKIP_THIS typedef IOChannel CppObjectType; typedef GIOChannel BaseObjectType; #endif /* DOXYGEN_SHOULD_SKIP_THIS */ private: 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 */ static Glib::RefPtr create_from_file(const std::string& filename, const std::string& mode); /** 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); /* 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); /** 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); #endif /* defined(G_OS_WIN32) || defined(DOXYGEN_SHOULD_SKIP_THIS) */ /** Read a single UCS-4 character. * @retval unichar The Unicode character. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ /** This function cannot be called on a channel with 0 encoding. * @param thechar A location to return a character. * @param error A location to return an error of type G::ConvertError * or G::IOChannelError. * @return A G::IOStatus. */ IOStatus read(gunichar& unichar); /** 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 */ /** Replacement for g_io_channel_read() with the new API. * @param buf A buffer to read data into. * @param count The size of the buffer. 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. * @param bytes_read The number of bytes read. This may be zero even on * success if count < 6 and the channel's encoding is non-0. * This indicates that the next UTF-8 character is too wide for * the buffer. * @param error A location to return an error of type G::ConvertError * or G::IOChannelError. * @return The status of the operation. */ IOStatus read(char* buf, gsize count, gsize& bytes_read); /** 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 */ IOStatus read(Glib::ustring& str, gsize count); /** 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 */ IOStatus read_line(Glib::ustring& line); /** 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 */ IOStatus read_to_end(Glib::ustring& str); /** 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 */ IOStatus write(const Glib::ustring& str); /** 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 */ /** Replacement for g_io_channel_write() with the new API. * * On seekable channels with encodings other than 0 or UTF-8, generic * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars() * may only be made on a channel from which data has been read in the * cases described in the documentation for g_io_channel_set_encoding(). * @param buf A buffer to write data from. * @param count The size of the buffer. If -1, the buffer * is taken to be a nul-terminated string. * @param bytes_written The number of bytes written. This can be nonzero * even if the return value is not G::IO_STATUS_NORMAL. * If the return value is G::IO_STATUS_NORMAL and the * channel is blocking, this will always be equal * to @a count if @a count >= 0. * @param error A location to return an error of type G::ConvertError * or G::IOChannelError. * @return The status of the operation. */ IOStatus write(const char* buf, gssize count, gsize& bytes_written); /** 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 */ /** This function cannot be called on a channel with 0 encoding. * @param thechar A character. * @param error A location to return an error of type G::ConvertError * or G::IOChannelError. * @return A G::IOStatus. */ IOStatus write(gunichar unichar); /** 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 */ /** Replacement for g_io_channel_seek() with the new API. * @param offset The offset in bytes from the position specified by @a type . * @param type A G::SeekType. The type G::SEEK_CUR is only allowed in those * cases where a call to g_io_channel_set_encoding() * is allowed. See the documentation for * g_io_channel_set_encoding() for details. * @param error A location to return an error of type G::IOChannelError. * @return The status of the operation. */ IOStatus seek(gint64 offset, SeekType type = SEEK_TYPE_SET); /** Flush the buffers of the I/O channel. * @return The status of the operation. * @throw Glib::IOChannelError * @throw Glib::ConvertError */ /** Flushes the write buffer for the GIOChannel. * @param error Location to store an error of type G::IOChannelError. * @return The status of the operation: One of * G::IO_CHANNEL_NORMAL, G::IO_CHANNEL_AGAIN, or * G::IO_CHANNEL_ERROR. */ IOStatus flush(); /** 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 */ /** Close an IO 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 using g_io_channel_unref(). * @param flush If true, flush pending. * @param err Location to store a G::IOChannelError. * @return The status of the operation. */ IOStatus close(bool flush = true); /** Get the IOChannel internal buffer size. * @return The buffer size. */ /** Gets the buffer size. * @return The size of the buffer. */ gsize get_buffer_size() const; /** Set the internal IOChannel buffer size. * @param size The buffer size the IOChannel should use. */ /** Sets the buffer size. * @param size The size of the buffer. 0 == pick a good size. */ void set_buffer_size(gsize 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. */ /** Gets the current flags for a G::IOChannel, including read-only * flags such as G::IO_FLAG_IS_READABLE. * * The values of the flags G::IO_FLAG_IS_READABLE and G::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 g_io_channel_get_flags() to update * the internal values of these flags. * @return The flags which are set on the channel. */ IOFlags get_flags() const; /** Set flags on the IOChannel. * @param flags Bitwise combination of the flags to set. * @return The operation result code. * @throw Glib::IOChannelError */ /** Sets the (writeable) flags in @a channel to ( @a flags & G::IO_CHANNEL_SET_MASK). * @param flags The flags to set on the IO channel. * @param error A location to return an error of type G::IOChannelError. * @return The status of the operation. */ IOStatus set_flags(IOFlags flags); /** 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. */ /** The buffering state can only be set if the channel's encoding * is 0. 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 G::IO_STATUS_EOF * not require such a flush. For write-only channels, a call to * g_io_channel_flush() is sufficient. For all other channels, * the buffers may be flushed by a call to g_io_channel_seek_position(). * This includes the possibility of seeking with seek type G::SEEK_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. * * On unbuffered channels, it is safe to mix read and write * calls from the new and old APIs, if this is necessary for * maintaining old code. * * The default state of the channel is buffered. * @param buffered Whether to set the channel buffered or unbuffered. */ void set_buffered(bool buffered); /** Get the buffering status of the I/O channel. * @return The buffering status of the channel. */ /** Returns whether @a channel is buffered. * @return true if the @a channel is buffered. */ bool get_buffered() const; /** 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. */ /** This function returns a G::IOCondition depending on whether there * is data to be read/space to write data in the * internal buffers in the G::IOChannel. Only the flags G::IO_IN and * G::IO_OUT may be set. * @return A G::IOCondition. */ IOCondition get_buffer_condition() const; /** 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. */ /** Returns whether the file/socket/whatever associated with @a channel * will be closed when @a channel receives its final unref and is * destroyed. The default value of this is true for channels created * by g_io_channel_new_file(), and false for all other channels. * @return Whether the channel will be closed on the final unref of * the GIOChannel data structure. */ bool get_close_on_unref() const; /** 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. */ /** 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 GIOChannel data structure. The default value of * this is true for channels created by g_io_channel_new_file(), * and false for all other channels. */ void set_close_on_unref(bool do_close); /** 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 */ IOStatus set_encoding(const std::string& encoding = std::string()); /** Get the encoding of the I/O channel. * @return The current encoding of the channel. */ std::string get_encoding() const; void set_line_term(const std::string& term = std::string()); std::string get_line_term() const; /** 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); virtual void reference() const; virtual void unreference() const; 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(); #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 #endif /* _GLIBMM_IOCHANNEL_H */