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: The channel was just created, and has not been written to or read from yet. The channel is write-only. The channel is a file, and the file pointer was just repositioned by a call to seek() (this flushes all the internal buffers). The current encoding is NULL or UTF-8. One of the read functions has just returned IO_STATUS_EOF (or, in the case of read_to_end(), IO_STATUS_NORMAL). 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

---

Copyright © 2004-2005 The XFC Development Team

XFC 4.3