glibmm 2.80.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Symbols | List of all members
Gio::Converter Class Reference

Converter - Data conversion interface. More...

#include <giomm/converter.h>

Inheritance diagram for Gio::Converter:
Inheritance graph
[legend]

Public Types

enum class  Result {
  ERROR ,
  CONVERTED ,
  FINISHED ,
  FLUSHED
}
 
enum class  Flags {
  NO_FLAGS = 0x0 ,
  INPUT_AT_END = (1 << 0) ,
  FLUSH = (1 << 1)
}
 

Public Member Functions

 Converter (Converter &&src) noexcept
 
Converteroperator= (Converter &&src) noexcept
 
 ~Converter () noexcept override
 
GConvertergobj ()
 Provides access to the underlying C GObject.
 
const GConvertergobj () const
 Provides access to the underlying C GObject.
 
Result convert (const void *inbuf, gsize inbuf_size, void *outbuf, gsize outbuf_size, Flags flags, gsize &bytes_read, gsize &bytes_written)
 This is the main operation used when converting data.
 
void reset ()
 Resets all internal state in the converter, making it behave as if it was just created.
 
- Public Member Functions inherited from Glib::Interface
 Interface ()
 A Default constructor.
 
 Interface (Interface &&src) noexcept
 
Interfaceoperator= (Interface &&src) noexcept
 
 Interface (const Glib::Interface_Class &interface_class)
 Called by constructors of derived classes.
 
 Interface (GObject *castitem)
 Called by constructors of derived classes.
 
 ~Interface () noexcept override
 
 Interface (const Interface &)=delete
 
Interfaceoperator= (const Interface &)=delete
 
GObject * gobj ()
 
const GObject * gobj () const
 
- Public Member Functions inherited from Glib::ObjectBase
 ObjectBase (const ObjectBase &)=delete
 
ObjectBaseoperator= (const ObjectBase &)=delete
 
void set_property_value (const Glib::ustring & property_name, const Glib::ValueBase & value)
 You probably want to use a specific property_*() accessor method instead.
 
void get_property_value (const Glib::ustring & property_name, Glib::ValueBase & value) const
 You probably want to use a specific property_*() accessor method instead.
 
template<class PropertyType >
void set_property (const Glib::ustring & property_name, const PropertyType & value)
 You probably want to use a specific property_*() accessor method instead.
 
template<class PropertyType >
void get_property (const Glib::ustring & property_name, PropertyType & value) const
 You probably want to use a specific property_*() accessor method instead.
 
template<class PropertyType >
PropertyType get_property (const Glib::ustring & property_name) const
 You probably want to use a specific property_*() accessor method instead.
 
sigc::connection connect_property_changed (const Glib::ustring & property_name, const sigc::slot< void()> &slot)
 You can use the signal_changed() signal of the property proxy instead.
 
sigc::connection connect_property_changed (const Glib::ustring & property_name, sigc::slot< void()> &&slot)
 You can use the signal_changed() signal of the property proxy instead.
 
void freeze_notify ()
 Increases the freeze count on object.
 
void thaw_notify ()
 Reverts the effect of a previous call to freeze_notify().
 
virtual void reference () const
 Increment the reference count for this object.
 
virtual void unreference () const
 Decrement the reference count for this object.
 
GObject * gobj ()
 Provides access to the underlying C GObject.
 
const GObject * gobj () const
 Provides access to the underlying C GObject.
 
GObject * gobj_copy () const
 Give a ref-ed copy to someone. Use for direct struct access.
 

Static Public Member Functions

static void add_interface (GType gtype_implementer)
 
static GType get_type ()
 Get the GType for this class, for use with the underlying GObject type system.
 

Protected Member Functions

 Converter ()
 You should derive from this class to use it.
 
virtual Result convert_vfunc (const void *inbuf, gsize inbuf_size, void *outbuf, gsize outbuf_size, Flags flags, gsize &bytes_read, gsize &bytes_written)
 
virtual void reset_vfunc ()
 
- Protected Member Functions inherited from Glib::ObjectBase
 ObjectBase ()
 This default constructor is called implicitly from the constructor of user-derived classes, even if, for instance, Gtk::Button calls a different ObjectBase constructor.
 
 ObjectBase (const char *custom_type_name)
 A derived constructor always overrides this choice.
 
 ObjectBase (const std::type_info &custom_type_info)
 This constructor is a special feature to allow creation of derived types on the fly, without having to use g_object_new() manually.
 
 ObjectBase (ObjectBase &&src) noexcept
 
ObjectBaseoperator= (ObjectBase &&src) noexcept
 
virtual ~ObjectBase () noexcept=0
 
void initialize (GObject *castitem)
 
void initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)
 

Related Symbols

(Note that these are not member symbols.)

Glib::RefPtr< Gio::Converterwrap (GConverter *object, bool take_copy=false)
 A Glib::wrap() method for this object.
 

Detailed Description

Converter - Data conversion interface.

Converter is implemented by objects that convert binary data in various ways. The conversion can be stateful and may fail at any place.

Some example conversions are: character set conversion, compression, decompression and regular expression replace.

Since glibmm 2.34:

Member Enumeration Documentation

◆ Flags

Enumerator
NO_FLAGS 

No flags.

INPUT_AT_END 

At end of input data.

FLUSH 

Flush data.

◆ Result

Enumerator
ERROR 

There was an error during conversion.

CONVERTED 

Some data was consumed or produced.

FINISHED 

The conversion is finished.

FLUSHED 

Flushing is finished.

Constructor & Destructor Documentation

◆ Converter() [1/2]

Gio::Converter::Converter ( )
protected

You should derive from this class to use it.

◆ Converter() [2/2]

Gio::Converter::Converter ( Converter &&  src)
noexcept

◆ ~Converter()

Gio::Converter::~Converter ( )
overridenoexcept

Member Function Documentation

◆ add_interface()

static void Gio::Converter::add_interface ( GType  gtype_implementer)
static

◆ convert()

Result Gio::Converter::convert ( const void inbuf,
gsize  inbuf_size,
void outbuf,
gsize  outbuf_size,
Flags  flags,
gsize bytes_read,
gsize bytes_written 
)

This is the main operation used when converting data.

It is to be called multiple times in a loop, and each time it will do some work, i.e. producing some output (in outbuf) or consuming some input (from inbuf) or both. If its not possible to do any work an error is returned.

Note that a single call may not consume all input (or any input at all). Also a call may produce output even if given no input, due to state stored in the converter producing output.

If any data was either produced or consumed, and then an error happens, then only the successful conversion is reported and the error is returned on the next call.

A full conversion loop involves calling this method repeatedly, each time giving it new input and space output space. When there is no more input data after the data in inbuf, the flag Gio::Converter::Flags::INPUT_AT_END must be set. The loop will be (unless some error happens) returning Gio::Converter::Result::CONVERTED each time until all data is consumed and all output is produced, then Gio::Converter::Result::FINISHED is returned instead. Note, that Gio::Converter::Result::FINISHED may be returned even if Gio::Converter::Flags::INPUT_AT_END is not set, for instance in a decompression converter where the end of data is detectable from the data (and there might even be other data after the end of the compressed data).

When some data has successfully been converted bytes_read and is set to the number of bytes read from inbuf, and bytes_written is set to indicate how many bytes was written to outbuf. If there are more data to output or consume (i.e. unless the Gio::Converter::Flags::INPUT_AT_END is specified) then Gio::Converter::Result::CONVERTED is returned, and if no more data is to be output then Gio::Converter::Result::FINISHED is returned.

On error Gio::Converter::Result::ERROR is returned and error is set accordingly. Some errors need special handling:

Gio::Error::NO_SPACE is returned if there is not enough space to write the resulting converted data, the application should call the function again with a larger outbuf to continue.

Gio::Error::PARTIAL_INPUT is returned if there is not enough input to fully determine what the conversion should produce, and the Gio::Converter::Flags::INPUT_AT_END flag is not set. This happens for example with an incomplete multibyte sequence when converting text, or when a regexp matches up to the end of the input (and may match further input). It may also happen when inbuf_size is zero and there is no more data to produce.

When this happens the application should read more input and then call the function again. If further input shows that there is no more data call the function again with the same data but with the Gio::Converter::Flags::INPUT_AT_END flag set. This may cause the conversion to finish as e.g. in the regexp match case (or, to fail again with Gio::Error::PARTIAL_INPUT in e.g. a charset conversion where the input is actually partial).

After g_converter_convert() has returned Gio::Converter::Result::FINISHED the converter object is in an invalid state where its not allowed to call g_converter_convert() anymore. At this time you can only free the object or call g_converter_reset() to reset it to the initial state.

If the flag Gio::Converter::Flags::FLUSH is set then conversion is modified to try to write out all internal state to the output. The application has to call the function multiple times with the flag set, and when the available input has been consumed and all internal state has been produced then Gio::Converter::Result::FLUSHED (or Gio::Converter::Result::FINISHED if really at the end) is returned instead of Gio::Converter::Result::CONVERTED. This is somewhat similar to what happens at the end of the input stream, but done in the middle of the data.

This has different meanings for different conversions. For instance in a compression converter it would mean that we flush all the compression state into output such that if you uncompress the compressed data you get back all the input data. Doing this may make the final file larger due to padding though. Another example is a regexp conversion, where if you at the end of the flushed data have a match, but there is also a potential longer match. In the non-flushed case we would ask for more input, but when flushing we treat this as the end of input and do the match.

Flushing is not always possible (like if a charset converter flushes at a partial multibyte sequence). Converters are supposed to try to produce as much output as possible and then return an error (typically Gio::Error::PARTIAL_INPUT).

Since glibmm 2.24:
Parameters
inbufThe buffer containing the data to convert.
inbuf_sizeThe number of bytes in inbuf.
outbufA buffer to write converted data in.
outbuf_sizeThe number of bytes in outbuf, must be at least one.
flagsA Gio::Converter::Flags controlling the conversion details.
bytes_readWill be set to the number of bytes read from inbuf on success.
bytes_writtenWill be set to the number of bytes written to outbuf on success.
Returns
A Gio::Converter::Result, Gio::Converter::Result::ERROR on error.
Exceptions
Glib::Error

◆ convert_vfunc()

virtual Result Gio::Converter::convert_vfunc ( const void inbuf,
gsize  inbuf_size,
void outbuf,
gsize  outbuf_size,
Flags  flags,
gsize bytes_read,
gsize bytes_written 
)
protectedvirtual
Exceptions
Glib::Error.

◆ get_type()

static GType Gio::Converter::get_type ( )
static

Get the GType for this class, for use with the underlying GObject type system.

◆ gobj() [1/2]

GConverter * Gio::Converter::gobj ( )
inline

Provides access to the underlying C GObject.

◆ gobj() [2/2]

const GConverter * Gio::Converter::gobj ( ) const
inline

Provides access to the underlying C GObject.

◆ operator=()

Converter & Gio::Converter::operator= ( Converter &&  src)
noexcept

◆ reset()

void Gio::Converter::reset ( )

Resets all internal state in the converter, making it behave as if it was just created.

If the converter has any internal state that would produce output then that output is lost.

Since glibmm 2.24:

◆ reset_vfunc()

virtual void Gio::Converter::reset_vfunc ( )
protectedvirtual

Friends And Related Symbol Documentation

◆ wrap()

Glib::RefPtr< Gio::Converter > wrap ( GConverter object,
bool  take_copy = false 
)
related

A Glib::wrap() method for this object.

Parameters
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns
A C++ instance that wraps this C instance.