/* 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