/* 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 Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 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
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see .
*/
_DEFS(glibmm,glib)
#include
#include //For the GIOCondition enum values.
#include
#include
#include
#include
#include
#ifndef DOXYGEN_SHOULD_SKIP_THIS
extern "C" { typedef struct _GIOChannel GIOChannel; }
#endif
namespace Glib
{
class Source;
class IOSource;
_WRAP_ENUM(SeekType, GSeekType, NO_GTYPE, decl_prefix GLIBMM_API)
_WRAP_ENUM(IOStatus, GIOStatus, NO_GTYPE, s#^EOF$#ENDOFFILE#, decl_prefix GLIBMM_API)
_WRAP_ENUM(IOFlags, GIOFlags, NO_GTYPE, decl_prefix GLIBMM_API)
// Glib::IOCondition::IN and Glib::IOCondition::OUT would be problematic.
// IN and OUT can be preprocessor macros.
// See https://bugzilla.gnome.org/show_bug.cgi?id=786717
/** @enum IOCondition
* A bitwise combination representing an I/O condition to watch for on an
* event source.
* The flags correspond to those used by the %poll() system call
* on UNIX (see man 2 poll). To test for individual flags, do
* something like this:
* @code
* if ((condition & Glib::IOCondition::IO_OUT) == Glib::IOCondition::IO_OUT)
* do_some_output();
* @endcode
*/
_WRAP_ENUM(IOCondition, GIOCondition, NO_GTYPE,
s#^IN$#IO_IN#,
s#^OUT$#IO_OUT#,
s#^PRI$#IO_PRI#,
s#^ERR$#IO_ERR#,
s#^HUP$#IO_HUP#,
s#^NVAL$#IO_NVAL#,
decl_prefix GLIBMM_API)
/** 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#,
decl_prefix GLIBMM_API)
#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.
*/
class GLIBMM_API IOChannel : public sigc::trackable
{
_CLASS_GENERIC(IOChannel, GIOChannel)
IOChannel(IOChannel&& other) noexcept;
IOChannel& operator=(IOChannel&& other) noexcept;
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
*/
static Glib::RefPtr 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) _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)
#ifdef G_OS_WIN32
/** 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 /* G_OS_WIN32 */
/** Read a single UCS-4 character.
* @param[out] 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.
* @param[out] 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[out] str The characters that have been read.
* @param count The maximum number of bytes to 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.
* @param[out] 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.
* @param[out] str The resulting string.
* @return Glib::IOStatus::NORMAL on success. This function never
* returns Glib::IOStatus::ENDOFFILE.
* @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::IOStatus::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.
* @param[out] 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::SeekType::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 = SeekType::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_pending Whether to flush() pending data before closing the channel.
* @return The status of the operation.
* @throw Glib::IOChannelError
*/
_WRAP_METHOD(IOStatus close(bool flush_pending = 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::IOFlags::IS_READABLE.
*
* The values of the flags Glib::IOFlags::IS_READABLE and
* Glib::IOFlags::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::IOStatus::ENDOFFILE 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::SeekType::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::IOCondition::IO_IN and Glib::IOCondition::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::IOStatus::ENDOFFILE (or, in
* the case of read_to_end(), Glib::IOStatus::NORMAL).
* -# The read() method has returned Glib::IOStatus::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::SeekType::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::IOStatus::NORMAL if the encoding was successfully set.
* @throw Glib::IOChannelError
*/
IOStatus set_encoding(const std::string& encoding = {});
_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 = {});
_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);
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_;
_IGNORE(g_io_channel_init)
#ifndef DOXYGEN_SHOULD_SKIP_THIS
IOChannel(GIOChannel* gobject, bool take_copy);
#endif
private:
void release_gobject();
};
GLIBMM_API Glib::RefPtr wrap(GIOChannel* gobject, bool take_copy = false);
} // namespace Glib