|
Packit |
ae235b |
|
|
Packit |
ae235b |
<html>
|
|
Packit |
ae235b |
<head>
|
|
Packit |
ae235b |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
Packit |
ae235b |
<title>GConverter: GIO Reference Manual</title>
|
|
Packit |
ae235b |
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
|
Packit |
ae235b |
<link rel="home" href="index.html" title="GIO Reference Manual">
|
|
Packit |
ae235b |
<link rel="up" href="conversion.html" title="Data conversion">
|
|
Packit |
ae235b |
<link rel="prev" href="conversion.html" title="Data conversion">
|
|
Packit |
ae235b |
<link rel="next" href="GCharsetConverter.html" title="GCharsetConverter">
|
|
Packit |
ae235b |
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
|
|
Packit |
ae235b |
<link rel="stylesheet" href="style.css" type="text/css">
|
|
Packit |
ae235b |
</head>
|
|
Packit |
ae235b |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Top |
|
|
Packit |
ae235b |
Description |
|
|
Packit |
ae235b |
Object Hierarchy |
|
|
Packit |
ae235b |
Prerequisites |
|
|
Packit |
ae235b |
Known Implementations
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GConverter
|
|
Packit |
ae235b |
GConverter — Data conversion interface
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Functions
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GConverterResult
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_converter_convert ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
void
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_converter_reset ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Types and Values
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GConverter
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
struct
|
|
Packit |
ae235b |
GConverterIface
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
enum
|
|
Packit |
ae235b |
GConverterResult
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
enum
|
|
Packit |
ae235b |
GConverterFlags
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Object Hierarchy
|
|
Packit |
ae235b |
GInterface
|
|
Packit |
ae235b |
╰── GConverter
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Prerequisites
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GConverter requires
|
|
Packit |
ae235b |
GObject.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Known Implementations
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GConverter is implemented by
|
|
Packit |
ae235b |
GCharsetConverter, GZlibCompressor and GZlibDecompressor.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Includes
|
|
Packit |
ae235b |
#include <gio/gio.h>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Description
|
|
Packit |
ae235b |
GConverter is implemented by objects that convert
|
|
Packit |
ae235b |
binary data in various ways. The conversion can be
|
|
Packit |
ae235b |
stateful and may fail at any place.
|
|
Packit |
ae235b |
Some example conversions are: character set conversion,
|
|
Packit |
ae235b |
compression, decompression and regular expression
|
|
Packit |
ae235b |
replace.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Functions
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_converter_convert ()
|
|
Packit |
ae235b |
GConverterResult
|
|
Packit |
ae235b |
g_converter_convert (GConverter *converter,
|
|
Packit |
ae235b |
const void *inbuf,
|
|
Packit |
ae235b |
gsize inbuf_size,
|
|
Packit |
ae235b |
void *outbuf,
|
|
Packit |
ae235b |
gsize outbuf_size,
|
|
Packit |
ae235b |
GConverterFlags flags,
|
|
Packit |
ae235b |
gsize *bytes_read,
|
|
Packit |
ae235b |
gsize *bytes_written,
|
|
Packit |
ae235b |
GError **error);
|
|
Packit |
ae235b |
This is the main operation used when converting data. It is to be called
|
|
Packit |
ae235b |
multiple times in a loop, and each time it will do some work, i.e.
|
|
Packit |
ae235b |
producing some output (in outbuf
|
|
Packit |
ae235b |
) or consuming some input (from inbuf
|
|
Packit |
ae235b |
) or
|
|
Packit |
ae235b |
both. If its not possible to do any work an error is returned.
|
|
Packit |
ae235b |
Note that a single call may not consume all input (or any input at all).
|
|
Packit |
ae235b |
Also a call may produce output even if given no input, due to state stored
|
|
Packit |
ae235b |
in the converter producing output.
|
|
Packit |
ae235b |
If any data was either produced or consumed, and then an error happens, then
|
|
Packit |
ae235b |
only the successful conversion is reported and the error is returned on the
|
|
Packit |
ae235b |
next call.
|
|
Packit |
ae235b |
A full conversion loop involves calling this method repeatedly, each time
|
|
Packit |
ae235b |
giving it new input and space output space. When there is no more input
|
|
Packit |
ae235b |
data after the data in inbuf
|
|
Packit |
ae235b |
, the flag G_CONVERTER_INPUT_AT_END must be set.
|
|
Packit |
ae235b |
The loop will be (unless some error happens) returning G_CONVERTER_CONVERTED
|
|
Packit |
ae235b |
each time until all data is consumed and all output is produced, then
|
|
Packit |
ae235b |
G_CONVERTER_FINISHED is returned instead. Note, that G_CONVERTER_FINISHED
|
|
Packit |
ae235b |
may be returned even if G_CONVERTER_INPUT_AT_END is not set, for instance
|
|
Packit |
ae235b |
in a decompression converter where the end of data is detectable from the
|
|
Packit |
ae235b |
data (and there might even be other data after the end of the compressed data).
|
|
Packit |
ae235b |
When some data has successfully been converted bytes_read
|
|
Packit |
ae235b |
and is set to
|
|
Packit |
ae235b |
the number of bytes read from inbuf
|
|
Packit |
ae235b |
, and bytes_written
|
|
Packit |
ae235b |
is set to indicate
|
|
Packit |
ae235b |
how many bytes was written to outbuf
|
|
Packit |
ae235b |
. If there are more data to output
|
|
Packit |
ae235b |
or consume (i.e. unless the G_CONVERTER_INPUT_AT_END is specified) then
|
|
Packit |
ae235b |
G_CONVERTER_CONVERTED is returned, and if no more data is to be output
|
|
Packit |
ae235b |
then G_CONVERTER_FINISHED is returned.
|
|
Packit |
ae235b |
On error G_CONVERTER_ERROR is returned and error
|
|
Packit |
ae235b |
is set accordingly.
|
|
Packit |
ae235b |
Some errors need special handling:
|
|
Packit |
ae235b |
G_IO_ERROR_NO_SPACE is returned if there is not enough space
|
|
Packit |
ae235b |
to write the resulting converted data, the application should
|
|
Packit |
ae235b |
call the function again with a larger outbuf
|
|
Packit |
ae235b |
to continue.
|
|
Packit |
ae235b |
G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
|
|
Packit |
ae235b |
input to fully determine what the conversion should produce,
|
|
Packit |
ae235b |
and the G_CONVERTER_INPUT_AT_END flag is not set. This happens for
|
|
Packit |
ae235b |
example with an incomplete multibyte sequence when converting text,
|
|
Packit |
ae235b |
or when a regexp matches up to the end of the input (and may match
|
|
Packit |
ae235b |
further input). It may also happen when inbuf_size
|
|
Packit |
ae235b |
is zero and
|
|
Packit |
ae235b |
there is no more data to produce.
|
|
Packit |
ae235b |
When this happens the application should read more input and then
|
|
Packit |
ae235b |
call the function again. If further input shows that there is no
|
|
Packit |
ae235b |
more data call the function again with the same data but with
|
|
Packit |
ae235b |
the G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
|
|
Packit |
ae235b |
to finish as e.g. in the regexp match case (or, to fail again with
|
|
Packit |
ae235b |
G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
|
|
Packit |
ae235b |
input is actually partial).
|
|
Packit |
ae235b |
After g_converter_convert() has returned G_CONVERTER_FINISHED the
|
|
Packit |
ae235b |
converter object is in an invalid state where its not allowed
|
|
Packit |
ae235b |
to call g_converter_convert() anymore. At this time you can only
|
|
Packit |
ae235b |
free the object or call g_converter_reset() to reset it to the
|
|
Packit |
ae235b |
initial state.
|
|
Packit |
ae235b |
If the flag G_CONVERTER_FLUSH is set then conversion is modified
|
|
Packit |
ae235b |
to try to write out all internal state to the output. The application
|
|
Packit |
ae235b |
has to call the function multiple times with the flag set, and when
|
|
Packit |
ae235b |
the available input has been consumed and all internal state has
|
|
Packit |
ae235b |
been produced then G_CONVERTER_FLUSHED (or G_CONVERTER_FINISHED if
|
|
Packit |
ae235b |
really at the end) is returned instead of G_CONVERTER_CONVERTED.
|
|
Packit |
ae235b |
This is somewhat similar to what happens at the end of the input stream,
|
|
Packit |
ae235b |
but done in the middle of the data.
|
|
Packit |
ae235b |
This has different meanings for different conversions. For instance
|
|
Packit |
ae235b |
in a compression converter it would mean that we flush all the
|
|
Packit |
ae235b |
compression state into output such that if you uncompress the
|
|
Packit |
ae235b |
compressed data you get back all the input data. Doing this may
|
|
Packit |
ae235b |
make the final file larger due to padding though. Another example
|
|
Packit |
ae235b |
is a regexp conversion, where if you at the end of the flushed data
|
|
Packit |
ae235b |
have a match, but there is also a potential longer match. In the
|
|
Packit |
ae235b |
non-flushed case we would ask for more input, but when flushing we
|
|
Packit |
ae235b |
treat this as the end of input and do the match.
|
|
Packit |
ae235b |
Flushing is not always possible (like if a charset converter flushes
|
|
Packit |
ae235b |
at a partial multibyte sequence). Converters are supposed to try
|
|
Packit |
ae235b |
to produce as much output as possible and then return an error
|
|
Packit |
ae235b |
(typically G_IO_ERROR_PARTIAL_INPUT).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
converter
|
|
Packit |
ae235b |
a GConverter.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
inbuf
|
|
Packit |
ae235b |
the buffer
|
|
Packit |
ae235b |
containing the data to convert.
|
|
Packit |
ae235b |
[array length=inbuf_size][element-type guint8]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
inbuf_size
|
|
Packit |
ae235b |
the number of bytes in inbuf
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
outbuf
|
|
Packit |
ae235b |
a buffer to write
|
|
Packit |
ae235b |
converted data in.
|
|
Packit |
ae235b |
[element-type guint8][array length=outbuf_size]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
outbuf_size
|
|
Packit |
ae235b |
the number of bytes in outbuf
|
|
Packit |
ae235b |
, must be at least one
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
flags
|
|
Packit |
ae235b |
a GConverterFlags controlling the conversion details
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
bytes_read
|
|
Packit |
ae235b |
will be set to the number of bytes read from inbuf
|
|
Packit |
ae235b |
on success.
|
|
Packit |
ae235b |
[out]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
bytes_written
|
|
Packit |
ae235b |
will be set to the number of bytes written to outbuf
|
|
Packit |
ae235b |
on success.
|
|
Packit |
ae235b |
[out]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
error
|
|
Packit |
ae235b |
location to store the error occurring, or NULL to ignore
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
a GConverterResult, G_CONVERTER_ERROR on error.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.24
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_converter_reset ()
|
|
Packit |
ae235b |
void
|
|
Packit |
ae235b |
g_converter_reset (GConverter *converter);
|
|
Packit |
ae235b |
Resets all internal state in the converter, making it behave
|
|
Packit |
ae235b |
as if it was just created. If the converter has any internal
|
|
Packit |
ae235b |
state that would produce output then that output is lost.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
converter
|
|
Packit |
ae235b |
a GConverter.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.24
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Types and Values
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GConverter
|
|
Packit |
ae235b |
typedef struct _GConverter GConverter;
|
|
Packit |
ae235b |
Seek object for streaming operations.
|
|
Packit |
ae235b |
Since: 2.24
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
struct GConverterIface
|
|
Packit |
ae235b |
struct GConverterIface {
|
|
Packit |
ae235b |
GTypeInterface g_iface;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
/* Virtual Table */
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GConverterResult (* convert) (GConverter *converter,
|
|
Packit |
ae235b |
const void *inbuf,
|
|
Packit |
ae235b |
gsize inbuf_size,
|
|
Packit |
ae235b |
void *outbuf,
|
|
Packit |
ae235b |
gsize outbuf_size,
|
|
Packit |
ae235b |
GConverterFlags flags,
|
|
Packit |
ae235b |
gsize *bytes_read,
|
|
Packit |
ae235b |
gsize *bytes_written,
|
|
Packit |
ae235b |
GError **error);
|
|
Packit |
ae235b |
void (* reset) (GConverter *converter);
|
|
Packit |
ae235b |
};
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Provides an interface for converting data from one type
|
|
Packit |
ae235b |
to another type. The conversion can be stateful
|
|
Packit |
ae235b |
and may fail at any place.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Members
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
convert ()
|
|
Packit |
ae235b |
Converts data.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
reset ()
|
|
Packit |
ae235b |
Reverts the internal state of the converter to its initial state.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.24
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
enum GConverterResult
|
|
Packit |
ae235b |
Results returned from g_converter_convert().
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Members
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
G_CONVERTER_ERROR
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
There was an error during conversion.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
G_CONVERTER_CONVERTED
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Some data was consumed or produced
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
G_CONVERTER_FINISHED
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The conversion is finished
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
G_CONVERTER_FLUSHED
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Flushing is finished
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.24
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
enum GConverterFlags
|
|
Packit |
ae235b |
Flags used when calling a g_converter_convert().
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Members
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
G_CONVERTER_NO_FLAGS
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
No flags.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
G_CONVERTER_INPUT_AT_END
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
At end of input data
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
G_CONVERTER_FLUSH
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Flush data
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.24
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
See Also
|
|
Packit |
ae235b |
GInputStream, GOutputStream
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Generated by GTK-Doc V1.27
|
|
Packit |
ae235b |
</body>
|
|
Packit |
ae235b |
</html>
|