Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::G::IOChannel Class Reference

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

`#include <inti/glib/iochannel.h>`

Inheritance diagram for Inti::G::IOChannel:

List of all members.

## Public Types

- typedef Slot2< bool, IOChannel &,
  IOConditionField > IOSlot
    Signature of the callback slot to be called when the requested condition on a IOChannel is satisfied.

## Public Member Functions

Constructors

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

Accessors

- GIOChannel * g_io_channel () const
    Get a pointer to the GIOChannel structure.
- 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)
    Close an IO channel.
- unsigned int add_watch (IOConditionField condition, const IOSlot *slot, int priority=G_PRIORITY_DEFAULT, GDestroyNotify notify=0)
    Adds the channel into the main event loop with the given priority.
- void set_buffer_size (size_t size)
    Sets the buffer size.
- IOStatus set_flags (IOFlagsField flags, G::Error *error)
    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)
    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)
    Flushes the write buffer for the channel.
- IOStatus read_line (String &str, G::Error *error)
    Reads a line, including the terminating character(s), from a channel into String.
- IOStatus read_to_end (String &str, G::Error *error)
    Reads data from a channel.
- IOStatus read (char *buffer, size_t count, size_t *bytes_read, G::Error *error)
    Reads data from a channel.
- IOStatus read (String &str, size_t count, G::Error *error)
    Reads at most count data from a channel into a String.
- IOStatus read (G::Unichar &unichar, G::Error *error)
    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)
    Writes data to a channel.
- IOStatus write (const String &str, G::Error *error)
    Writes a String to a channel.
- IOStatus write (G::Unichar unichar, G::Error *error)
    This method cannot be called on a channel with a null encoding.
- IOStatus seek (gint64 offset, SeekType type, G::Error *error)
    Sets the current position in the channel, similar to the standard library function fseek().

## Static Public Member Functions

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

## Member Typedef Documentation

typedef Slot2<bool, IOChannel&, IOConditionField> Inti::G::IOChannel::IOSlot

Signature of the callback slot to be called when the requested condition on a IOChannel is satisfied.

Example: Method signature for IOSlot.

                 bool method(IOChannel& source, IOConditionField condition);

                 // source: The IOChannel event source.
                 // condition: The condition which has been satisfied.
                 // return: The slot should return false if the event source should be removed.

## Constructor & Destructor Documentation

Inti::G::IOChannel::IOChannel | ( | GIOChannel * | channel,
|  | bool | reference = true
| ) | `[explicit]`

Construct a IO channel from an existing GIOChannel.

Parameters:

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

unsigned int Inti::G::IOChannel::add_watch | ( | IOConditionField | condition,
|  | const IOSlot * | slot,
|  | int | priority = G_PRIORITY_DEFAULT,
|  | GDestroyNotify | notify = 0
| ) |

Adds the channel into the main event loop with the given priority.

Parameters:

  condition | The condition to watch for.
  slot | The IOSlot to call when the condition is satisfied.
  priority | The priority of the IOChannel source.
  notify | The function to call when the source is removed, or null.

Returns:
  The event source id.

IOStatus Inti::G::IOChannel::close | ( | bool | flush,
|  | G::Error * | error
| ) |

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> Inti::G::IOChannel::create | ( | int | fd | ) | `[static]`

Create a new channel for the file descriptor fd.

Parameters:

  fd | A file descriptor.

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> Inti::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 Inti::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 Inti::G::IOChannel::flush | ( | G::Error * | error | ) |

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 Inti::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:
  An IOCondition.

Note only the flags IO_IN and IO_OUT may be set.

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

Gets the buffer size.

Returns:
  The size of the buffer.

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

Returns whether the channel is buffered.

Returns:
  true if the channel is buffered.

bool Inti::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 Inti::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 Inti::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 Inti::G::IOChannel::get_flags | ( |  | ) | const

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

Returns:
  The flags 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 Inti::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 Inti::G::IOChannel::read | ( | G::Unichar & | unichar,
|  | G::Error * | error
| ) |

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 Inti::G::IOChannel::read | ( | String & | str,
|  | size_t | count,
|  | G::Error * | error
| ) |

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

Parameters:

  str | A String to read the data into.
  count | The maximum size of the data to 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 Inti::G::IOChannel::read | ( | char * | buffer,
|  | size_t | count,
|  | size_t * | bytes_read,
|  | G::Error * | error
| ) |

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 Inti::G::IOChannel::read_line | ( | String & | str,
|  | G::Error * | error
| ) |

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.
  error | A location to return an error of type GConvertError or IOChannelError.

Returns:
  The status of the operation.

IOStatus Inti::G::IOChannel::read_to_end | ( | String & | str,
|  | G::Error * | error
| ) |

Reads data from a channel.

Parameters:

  str | A String to read the data into.
  error | A location to return an error of type GConvertError or G::IOChannelError.

Returns:
  The status of the operation.

IOStatus Inti::G::IOChannel::seek | ( | gint64 | offset,
|  | SeekType | type,
|  | G::Error * | error
| ) |

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 Inti::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 Inti::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 Inti::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 IOChannel data structure.

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

IOStatus Inti::G::IOChannel::set_encoding | ( | const char * | encoding,
|  | G::Error * | error
| ) |

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 Inti::G::IOChannel::set_flags | ( | IOFlagsField | flags,
|  | G::Error * | error
| ) |

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

Parameters:

  flags | The flags to set on the IO channel.
  error | The location to store an error of type IOChannelErro.

Returns:
  The status of the operation.

void Inti::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 Inti::G::IOChannel::unref | ( |  | ) | `[virtual]`

Decrease an IO channel's reference count by one.

When the reference count becomes zero delete is called. Remember, as with all Inti 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 must also call unref() on an IOChannel allocated on the stack because IOChannels don't get passed on to owner objects that manage their reference count (like widgets in a container).

Reimplemented from Inti::ReferencedObject.

IOStatus Inti::G::IOChannel::write | ( | G::Unichar | unichar,
|  | G::Error * | error
| ) |

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 Inti::G::IOChannel::write | ( | const String & | str,
|  | G::Error * | error
| ) |

Writes a String to a channel.

Parameters:

  str | A String to write from.
  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 Inti::G::IOChannel::write | ( | const char * | buffer,
|  | size_t | count,
|  | size_t * | bytes_written,
|  | G::Error * | error
| ) |

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

Main Page - Footer