Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Public Member Functions | Static Public Member Functions
Xfc::G::IOChannel Class Reference

A GIOChannel C++ wrapper class. More...

#include <xfc/glib/iochannel.hh>

Inheritance diagram for Xfc::G::IOChannel:
Xfc::Trackable

List of all members.

Public Member Functions

Constructors

Static Public Member Functions


Detailed Description

A GIOChannel C++ wrapper class.

The IOChannel object provides a portable method for using file descriptors, pipes, and sockets, and integrating them into the main event loop. Currently full support is available on UNIX platforms, support for Windows is only partially complete.

To create a new IOChannel on UNIX systems use the create() 'file descriptor' method. This works for plain file descriptors, pipes and sockets. Alternatively, a channel can be opened for a file in a system independent manner using open_file(). Once an IOChannel has been created, it can be used in a generic manner with the methods read(), write(), seek(), and close().

To add an IOChannel to the main event loop use add_watch(). Here you specify which events you are interested in watching on the IOChannel, and provide a slot to be called whenever these events occur.

IOChannel instances are created with an initial reference count of 1. ref() and unref() can be used to increment or decrement the reference count respectively. When the reference count falls to 0, the IOChannel is freed. (Though it isn't closed automatically, unless it was opened using open_file().) Using add_watch() increments a channel's reference count.


Constructor & Destructor Documentation

Xfc::G::IOChannel::IOChannel ( GIOChannel *  channel,
bool  owns_reference = true 
) [explicit]

Construct a IO channel from an existing GIOChannel.

Parameters:
channelA pointer to a GIOChannel.
owns_referenceSet true if the initial reference count is owned by this object.

The IOChannel object takes over the ownership of the GIOChannel and unreferences it when the destructor is called.


Member Function Documentation

IOStatus Xfc::G::IOChannel::close ( bool  flush,
G::Error error = 0 
)

Close an IO channel.

Parameters:
flushSet true to flush pending data.
errorThe location to store an IOChannelError
Returns:
The status of the operation.

Any pending data to be written will be flushed if flush is true. The channel will not be freed until the last reference is dropped using unref(). Note that you don't need top call unref() with smart pointers, the smart pointer does that for you.

static Pointer<IOChannel> Xfc::G::IOChannel::create ( const String filename,
const char *  mode,
G::Error error 
) [static]

Create a new channel for the file filename using the mode mode.

Parameters:
filenameA string containing the name of a file.
modeOne of "r", "w", "a", "r+", "w+", "a+". These have the same meaning as in fopen().
errorA location to return an error of type G_FILE_ERROR.
Returns:
A smart pointer to a new IOChannel on success, or null on failure.

This channel will be closed automatically when the last reference to it is dropped.

static Pointer<IOChannel> Xfc::G::IOChannel::create ( int  fd,
bool  close_on_unref = false 
) [static]

Create a new channel for the file descriptor fd.

Parameters:
fdA file descriptor.
close_on_unrefWhether to close the channel on the final unref of the GIOChannel data structure.
Returns:
A smart pointer to a new IOChannel.

On UNIX systems this works for plain files, pipes, and sockets. The default encoding for an IOChannel is UTF-8. If your application is reading output from a command using via pipe, you may need to set the encoding to the encoding of the current locale (see g_get_charset()) with the IOChannel::set_encoding() method.

static IOChannelError Xfc::G::IOChannel::error_from_errno ( int  errno_number) [static]

Converts an errno error number to a IOChannelError.

Parameters:
errno_numberAn errno error number, e.g. EINVAL.
Returns:
An IOChannelError error number, e.g. IO_CHANNEL_ERROR_INVAL.

Flushes the write buffer for the channel.

Parameters:
errorThe location to store an error of type G::IOChannelError.
Returns:
The status of the operation: One of IO_CHANNEL_NORMAL, IO_CHANNEL_AGAIN, or IO_CHANNEL_ERROR.

Gets an IOCondition depending on whether there is data to be read/space to write data in the internal buffers in the IOChannel.

Returns:
A G::IOCondition.

Note only the flags IO_IN and IO_OUT may be set.

Gets the buffer size.

Returns:
The size of the buffer.

Returns whether the channel is buffered.

Returns:
true if the channel is buffered.

Returns whether the file/socket/whatever associated with the channel will be closed when the channel receives its final unref and is destroyed.

Returns:
Whether the channel will be closed on the final unref of the IOChannel data structure.

The return value is true for channels created from a filename, and false for all other channels.

Gets the encoding for the input/output of the channel.

Returns:
A string containing the encoding.

The internal encoding is always UTF-8. The encoding null makes the channel safe for binary data.

Returns the file descriptor of the UNIX channel created by the create() file descriptor method.

Returns:
The file descriptor of the channel.

Gets the current flags for the channel, including read-only flags such as IO_FLAG_IS_READABLE.

Returns:
The G::IOFlags which are set on the channel.

The values of the flags IO_FLAG_IS_READABLE and 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.

Gets the string that the channel uses to determine where in the file a line break occurs.

Returns:
The line termination string (a null String indicates auto detection).
IOStatus Xfc::G::IOChannel::read ( char *  buffer,
size_t  count,
size_t *  bytes_read,
G::Error error = 0 
)

Reads data from a channel.

Parameters:
bufferA buffer to read data into.
countThe size of the buffer.
bytes_readThe number of bytes read.
errorA location to return an error of type GConvertError or G::IOChannelError.
Returns:
The status of the operation.

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. The bytes_read may be zero even on success if count < 6 and the channel's encoding is non-null. This indicates that the next UTF-8 character is too wide for the buffer.

IOStatus Xfc::G::IOChannel::read ( String str,
size_t *  bytes_read,
G::Error error = 0 
)

Reads at most count data from a channel into a String.

Parameters:
strA String to read the data into.
bytes_readThe number of bytes read.
errorA location to return an error of type GConvertError or G::IOChannelError.
Returns:
The status of the operation.

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.

IOStatus Xfc::G::IOChannel::read ( G::Unichar unichar,
G::Error error = 0 
)

This method cannot be called on a channel with a null encoding.

Parameters:
unicharA location to return a unicode character.
errorA location to return an error of type GConvertError or G::IOChannelError.
Returns:
The status of the operation.
IOStatus Xfc::G::IOChannel::read_line ( String str,
size_t *  bytes_read,
G::Error error = 0 
)

Reads a line, including the terminating character(s), from a channel into String.

Parameters:
strThe line read from the IOChannel, including the line terminator.
bytes_readThe number of bytes read.
errorA location to return an error of type GConvertError or IOChannelError.
Returns:
The status of the operation.
IOStatus Xfc::G::IOChannel::read_to_end ( String str,
size_t *  bytes_read,
G::Error error = 0 
)

Reads data from a channel.

Parameters:
strA String to read the data into.
bytes_readThe number of bytes read.
errorA location to return an error of type GConvertError or G::IOChannelError.
Returns:
The status of the operation.
IOStatus Xfc::G::IOChannel::seek ( gint64  offset,
SeekType  type,
G::Error error = 0 
)

Sets the current position in the channel, similar to the standard library function fseek().

Parameters:
offsetThe offset in bytes from the position specified by type.
typeA SeekType.
errorA location to return an error of type G::IOChannelError.
Returns:
The status of the operation.

The G::SeekType IO_SEEK_CUR is only allowed in those cases where a call to set_encoding() is allowed. See the documentation for set_encoding() for details.

void Xfc::G::IOChannel::set_buffer_size ( size_t  size)

Sets the buffer size.

Parameters:
sizeThe size of the buffer (0 == pick a good size).
void Xfc::G::IOChannel::set_buffered ( bool  buffered)

Set the buffering state of the channel (the default state is buffered).

Parameters:
bufferedWhether to set the channel buffered or unbuffered.

The buffering state can only be set if the channel's encoding is null. 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 IO_STATUS_EOF do 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 IO_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.

void Xfc::G::IOChannel::set_close_on_unref ( bool  do_close)

Setting this flag to true for a channel you have already closed can cause problems.

Parameters:
do_closeWhether to close the channel on the final unref of the GIOChannel data structure.

The default value is true for channels created by the create() filename method, and false for all other channels.

IOStatus Xfc::G::IOChannel::set_encoding ( const char *  encoding,
G::Error error = 0 
)

Sets the encoding for the input/output of the channel.

Parameters:
encodingThe encoding type.
errorThe location to store an error of type GConvertError.
Returns:
IO_STATUS_NORMAL if the encoding was successfully set.

The internal encoding is always UTF-8. The default encoding for the external file is UTF-8. The encoding 'null' is safe to use with binary data. The encoding can only be set if one of the following conditions is true:

  1. The channel was just created, and has not been written to or read from yet.
  2. The channel is write-only.
  3. The channel is a file, and the file pointer was just repositioned by a call to seek() (this flushes all the internal buffers).
  4. The current encoding is NULL or UTF-8.
  5. One of the read functions has just returned IO_STATUS_EOF (or, in the case of read_to_end(), IO_STATUS_NORMAL).
  6. One of the read() methods has returned IO_STATUS_AGAIN or IO_STATUS_ERROR. This may be useful in the case of G_CONVERT_ERROR_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 with an offset of IO_SEEK_CUR, and, if they are "seekable", cannot call write after calling one of the read() methods.

Sets the (writeable) flags in the channel to (flags & IO_CHANNEL_SET_MASK).

Parameters:
flagsThe G::IOFlags to set on the IO channel.
errorThe location to store an error of type IOChannelErro.
Returns:
The status of the operation.
void Xfc::G::IOChannel::set_line_term ( const String line_term)

This sets the string that the channel uses to determine where in the file a line break occurs.

Parameters:
line_termThe line termination string (use null for auto detect).

Auto detection breaks on "\n", "\r\n", "\r", "\0", and the Unicode paragraph separator. Auto detection should not be used for anything other than file-based channels.

virtual void Xfc::G::IOChannel::unref ( ) [virtual]

Decrease an IO channel's reference count by one.

When the reference count becomes zero for a heap object delete is called. Remember, as with all XFC Objects you must call unref() on a dynamically allocated IOChannel, not delete. If you use a smart you don't need to call unref(), the smart pointer will do that for you. You don't need to call unref() on an IOChannel allocated on the stack unless you first called ref().

Reimplemented from Xfc::Trackable.

IOStatus Xfc::G::IOChannel::write ( const char *  buffer,
size_t  count,
size_t *  bytes_written,
G::Error error = 0 
)

Writes data to a channel.

Parameters:
bufferA buffer to write data from.
countThe size of the buffer. If -1, the buffer is taken to be a null-terminated string.
bytes_writtenThe location to store the number of bytes written.
errorA location to return an error of type GConvertError or G::IOChannelError
Returns:
The status of the operation.

On seekable channels with encodings other than null or UTF-8, generic mixing of reading and writing is not allowed. A call to write() may only be made on a channel from which data has been read in the cases described in the documentation for set_encoding().

The bytes_read 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, bytes_read will always be equal to count if count >= 0.

IOStatus Xfc::G::IOChannel::write ( const String str,
size_t *  bytes_written,
G::Error error = 0 
)

Writes a String to a channel.

Parameters:
strA String to write from.
bytes_writtenThe location to store the number of bytes written.
errorA location to return an error of type GConvertError or G::IOChannelError
Returns:
The status of the operation.

On seekable channels with encodings other than null or UTF-8, generic mixing of reading and writing is not allowed. A call to write() may only be made on a channel from which the String has been read in the cases described in the documentation for set_encoding().

IOStatus Xfc::G::IOChannel::write ( G::Unichar  unichar,
G::Error error = 0 
)

This method cannot be called on a channel with a null encoding.

Parameters:
unicharA unicode character.
errorA location to return an error of type GConvertError or G::IOChannelError.
Returns:
The status of the operation.

The documentation for this class was generated from the following file:
Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC