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


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

Accessors
Methods

Static Public Member Functions

Accessors

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:
channel A pointer to a GIOChannel.
owns_reference Set 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.

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

Construct a IO channel from an existing GIOChannel.

Parameters:
channel A pointer to a GIOChannel.
owns_reference Set 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

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:
filename A string containing the name of a file.
mode One of "r", "w", "a", "r+", "w+", "a+". These have the same meaning as in fopen().
error A 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:
fd A file descriptor.
close_on_unref Whether 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_number An errno error number, e.g. EINVAL.
Returns:
An IOChannelError error number, e.g. IO_CHANNEL_ERROR_INVAL.

size_t Xfc::G::IOChannel::get_buffer_size (  )  const

Gets the buffer size.

Returns:
The size of the buffer.

IOConditionField Xfc::G::IOChannel::get_buffer_condition (  )  const

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.

IOFlagsField Xfc::G::IOChannel::get_flags (  )  const

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.

String Xfc::G::IOChannel::get_line_term (  )  const

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).

bool Xfc::G::IOChannel::get_buffered (  )  const

Returns whether the channel is buffered.

Returns:
true if the channel is buffered.

String Xfc::G::IOChannel::get_encoding (  )  const

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.

bool Xfc::G::IOChannel::get_close_on_unref (  )  const

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.

int Xfc::G::IOChannel::get_fd (  )  const

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

Returns:
The file descriptor of the channel.

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::close ( bool  flush,
G::Error error = 0 
)

Close an IO channel.

Parameters:
flush Set true to flush pending data.
error The 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.

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

Sets the buffer size.

Parameters:
size The size of the buffer (0 == pick a good size).

IOStatus Xfc::G::IOChannel::set_flags ( IOFlagsField  flags,
G::Error error = 0 
)

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

Parameters:
flags The G::IOFlags to set on the IO channel.
error The 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_term The 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.

void Xfc::G::IOChannel::set_buffered ( bool  buffered  ) 

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

Parameters:
buffered Whether 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.

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

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

Parameters:
encoding The encoding type.
error The 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.

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_close Whether 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::flush ( G::Error error = 0  ) 

Flushes the write buffer for the channel.

Parameters:
error The 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.

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:
str The line read from the IOChannel, including the line terminator.
bytes_read The number of bytes read.
error A 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:
str A String to read the data into.
bytes_read The number of bytes read.
error A location to return an error of type GConvertError or G::IOChannelError.
Returns:
The status of the operation.

IOStatus Xfc::G::IOChannel::read ( char *  buffer,
size_t  count,
size_t *  bytes_read,
G::Error error = 0 
)

Reads data from a channel.

Parameters:
buffer A buffer to read data into.
count The size of the buffer.
bytes_read The number of bytes read.
error A 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:
str A String to read the data into.
bytes_read The number of bytes read.
error A 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:
unichar A location to return a unicode character.
error A location to return an error of type GConvertError or G::IOChannelError.
Returns:
The status of the operation.

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:
buffer A buffer to write data from.
count The size of the buffer. If -1, the buffer is taken to be a null-terminated string.
bytes_written The location to store the number of bytes written.
error A 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:
str A String to write from.
bytes_written The location to store the number of bytes written.
error A 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:
unichar A unicode character.
error A 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:
offset The offset in bytes from the position specified by type.
type A SeekType.
error A 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.


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