diff options
Diffstat (limited to 'glib/src/iochannel.hg')
| -rw-r--r-- | glib/src/iochannel.hg | 452 |
1 files changed, 452 insertions, 0 deletions
diff --git a/glib/src/iochannel.hg b/glib/src/iochannel.hg new file mode 100644 index 00000000..ab9f4b38 --- /dev/null +++ b/glib/src/iochannel.hg @@ -0,0 +1,452 @@ +// -*- 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. + */ + +_DEFS(glibmm,glib) + +#include <glibmm/error.h> +#include <glibmm/main.h> +#include <glibmm/refptr.h> +#include <glibmm/ustring.h> +#include <glib/gtypes.h> + +#include <string> +#include <glibmmconfig.h> + +GTKMM_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::Object +{ + _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 <tt>"r"</tt>, <tt>"w"</tt>, <tt>"a"</tt>, + * <tt>"r+"</tt>, <tt>"w+"</tt>, <tt>"a+"</tt>. These have the + * same meaning as in <tt>fopen()</tt>. + * @return An IOChannel for the opened file. + * @throw Glib::FileError + */ + static Glib::RefPtr<IOChannel> create_from_file(const std::string& filename, const std::string& mode); + _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) <tt>_open()</tt> or <tt>_pipe()</tt>, + * including file descriptors 0, 1 and 2 (corresponding to <tt>stdin</tt>, + * <tt>stdout</tt> and <tt>stderr</tt>), or for Winsock <tt>SOCKET</tt>s. If + * the parameter is a legal file descriptor, it is assumed to be such, + * otherwise it should be a <tt>SOCKET</tt>. This relies on <tt>SOCKET</tt>s + * 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 <tt>HANDLE</tt>. There isn't as of yet + * a way to get IOChannels for Win32 file <tt>HANDLE</tt>s. + */ + static Glib::RefPtr<IOChannel> 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 <tt>%read()</tt> 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<IOChannel> 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 + * <tt>SOCKET</tt>. Contrary to I/O channels for file descriptors (on Win32), + * you can use normal <tt>recv()</tt> or <tt>recvfrom()</tt> on sockets even + * if GLib is polling them. + */ + static Glib::RefPtr<IOChannel> 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 unichar The Unicode character. + * @return The status of the operation. + * @throw Glib::IOChannelError + * @throw Glib::ConvertError + */ + _WRAP_METHOD(IOStatus read(gunichar& unichar), 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 <tt>""</tt>. + * 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 + */ + 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); + _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 + */ + IOStatus read_to_end(Glib::ustring& str); + _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 + */ + 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 + */ + _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 <tt>true</tt>. + * 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 <tt>shutdown()</tt> 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 + * <tt>""</tt>. 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 <tt>true</tt> for channels created by + * create_from_file(), and <tt>false</tt> 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 <tt>true</tt> 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 <tt>true</tt> for channels + * created by create_from_file(), and <tt>false</tt> 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 <tt>""</tt> 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 <tt>""</tt> 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 <em>not</em> 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 <tt>""</tt> 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()); + _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::slot() 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<IOSource> 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<Glib::Source> create_watch_vfunc(IOCondition cond); + +#ifndef DOXYGEN_SHOULD_SKIP_THIS + friend class Glib::GlibmmIOChannel; +#endif +}; + +Glib::RefPtr<IOChannel> wrap(GIOChannel* gobject, bool take_copy = false); + +} // namespace Glib + |