Xfce Foundation Classes
Main Page | Index | Namespace 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:

List of all members.

## Public Member Functions

Constructors

- IOChannel (GIOChannel *channel, bool owns_reference=true)
    Construct a IO channel from an existing GIOChannel.
- ~IOChannel ()
    Destructor.

Accessors

- GIOChannel * g_io_channel () const
    Get a pointer to the GIOChannel structure.
- operator GIOChannel * () const
    Conversion operator; Safely converts a G::IOChannel object into a GIOChannel pointer.
- size_t get_buffer_size () const
    Gets the buffer size.
- IOConditionField 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.
- IOFlagsField get_flags () const
    Gets the current flags for the channel, including read-only flags such as IO_FLAG_IS_READABLE.
- String get_line_term () const
    Gets the string that the channel uses to determine where in the file a line break occurs.
- bool get_buffered () const
    Returns whether the channel is buffered.
- String get_encoding () const
    Gets the encoding for the input/output of the channel.
- bool 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.
- int get_fd () const
    Returns the file descriptor of the UNIX channel created by the create() file descriptor method.

Methods

- virtual void ref ()
    Increase an IO channel's reference count by one.
- virtual void unref ()
    Decrease an IO channel's reference count by one.
- IOStatus close (bool flush, G::Error *error=0)
    Close an IO channel.
- void set_buffer_size (size_t size)
    Sets the buffer size.
- IOStatus set_flags (IOFlagsField flags, G::Error *error=0)
    Sets the (writeable) flags in the channel to (flags & IO_CHANNEL_SET_MASK).
- void 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.
- void set_buffered (bool buffered)
    Set the buffering state of the channel (the default state is buffered).
- IOStatus set_encoding (const char *encoding, G::Error *error=0)
    Sets the encoding for the input/output of the channel.
- void set_close_on_unref (bool do_close)
    Setting this flag to true for a channel you have already closed can cause problems.
- IOStatus flush (G::Error *error=0)
    Flushes the write buffer for the channel.
- IOStatus 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.
- IOStatus read_to_end (String &str, size_t *bytes_read, G::Error *error=0)
    Reads data from a channel.
- IOStatus read (char *buffer, size_t count, size_t *bytes_read, G::Error *error=0)
    Reads data from a channel.
- IOStatus read (String &str, size_t *bytes_read, G::Error *error=0)
    Reads at most count data from a channel into a String.
- IOStatus read (G::Unichar &unichar, G::Error *error=0)
    This method cannot be called on a channel with a null encoding.
- IOStatus write (const char *buffer, size_t count, size_t *bytes_written, G::Error *error=0)
    Writes data to a channel.
- IOStatus write (const String &str, size_t *bytes_written, G::Error *error=0)
    Writes a String to a channel.
- IOStatus write (G::Unichar unichar, G::Error *error=0)
    This method cannot be called on a channel with a null encoding.
- IOStatus seek (gint64 offset, SeekType type, G::Error *error=0)
    Sets the current position in the channel, similar to the standard library function fseek().

## Static Public Member Functions

Accessors

- Pointer< IOChannel > create (const String &filename, const char *mode, G::Error *error)
    Create a new channel for the file filename using the mode mode.
- Pointer< IOChannel > create (int fd, bool close_on_unref=false)
    Create a new channel for the file descriptor fd.
- IOChannelError error_from_errno (int errno_number)
    Converts an errno error number to a IOChannelError.

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

## Member Function Documentation

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.

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.

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.

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.

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.

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.

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

Gets the buffer size.

Returns:
  The size of the buffer.

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

Returns whether the channel is buffered.

Returns:
  true if the channel is buffered.

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.

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.

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.

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

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::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 | ( | 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_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::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.

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

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.

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

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.

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 | ( | 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::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 | ( | 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.

The documentation for this class was generated from the following file:

- iochannel.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3