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.
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.
Constructor & Destructor Documentation
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.
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.
Open a file filename as an I/O channel using mode 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).
The name of the file to open.
One of "r", "w", "a", "r+", "w+", "a+". These have the same meaning as in fopen().
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().
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.
The condition to watch for.
An IOSource object that can be polled from a MainContext's event loop.
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.
Bitwise combination of the flags set on the 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.
Whether to set the channel buffered or unbuffered.
Setting this flag to true for a channel you have already closed can cause problems.
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.
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.