utils: GSF Reference Manual

## utils

utils

## Functions

void | gsf_init ()
void | gsf_shutdown ()
void | gsf_init_dynamic ()
void | gsf_shutdown_dynamic ()
#define | GSF_CLASS()
#define | GSF_CLASS_FULL()
#define | GSF_CLASS_ABSTRACT()
#define | GSF_INTERFACE()
#define | GSF_INTERFACE_FULL()
#define | GSF_DYNAMIC_CLASS()
#define | GSF_DYNAMIC_CLASS_FULL()
#define | GSF_DYNAMIC_CLASS_ABSTRACT()
#define | GSF_DYNAMIC_INTERFACE()
#define | GSF_DYNAMIC_INTERFACE_FULL()
GQuark | gsf_error_quark ()
void | gsf_mem_dump ()
void | gsf_input_dump ()
gboolean | gsf_debug_flag ()
char * | gsf_filename_to_utf8 ()
void | gsf_iconv_close ()
char const * | gsf_extension_pointer ()
guint8 * | gsf_base64_encode_simple ()
size_t | gsf_base64_encode_close ()
size_t | gsf_base64_encode_step ()
size_t | gsf_base64_decode_simple ()
size_t | gsf_base64_decode_step ()
#define | GSF_LE_GET_GINT8()
#define | GSF_LE_GET_GUINT64()
#define | GSF_LE_GET_GINT16()
#define | GSF_LE_GET_GUINT8()
#define | GSF_LE_GET_GINT32()
#define | GSF_LE_GET_GUINT16()
#define | GSF_LE_GET_GUINT32()
#define | GSF_LE_GET_GINT64()
guint64 | gsf_le_get_guint64 ()
#define | GSF_LE_GET_FLOAT()
float | gsf_le_get_float ()
#define | GSF_LE_GET_DOUBLE()
double | gsf_le_get_double ()
#define | GSF_LE_SET_GUINT8()
#define | GSF_LE_SET_GUINT16()
#define | GSF_LE_SET_GUINT32()
#define | GSF_LE_SET_GINT8()
#define | GSF_LE_SET_GINT16()
#define | GSF_LE_SET_GINT32()
#define | GSF_LE_SET_GINT64()
#define | GSF_LE_SET_GUINT64()
#define | GSF_LE_SET_FLOAT()
#define | GSF_LE_SET_DOUBLE()
void | gsf_le_set_float ()
void | gsf_le_set_double ()
GsfTimestamp * | gsf_timestamp_new ()
void | gsf_timestamp_set_time ()
GsfTimestamp * | gsf_timestamp_copy ()
void | gsf_timestamp_free ()
char * | gsf_timestamp_as_string ()
int | gsf_timestamp_load_from_string ()
int | gsf_timestamp_from_string ()
guint | gsf_timestamp_hash ()
gboolean | gsf_timestamp_equal ()
void | gsf_timestamp_to_value ()
void | gsf_value_set_timestamp ()
#define | VAL_IS_GSF_TIMESTAMP()
int | gsf_timestamp_parse ()
GValue * | gsf_doc_prop_swap_val ()
void | gsf_property_settings_collect ()
void | gsf_property_settings_collect_valist ()
void | gsf_property_settings_free ()

## Types and Values

extern int | libgsf_major_version
extern int | libgsf_minor_version
extern int | libgsf_micro_version
#define | GSF_PARAM_STATIC
#define | GSF_ERROR
enum | GsfError
#define | GSF_OFF_T_FORMAT
typedef | gsf_off_t
| GsfTimestamp

## Object Hierarchy

        GBoxed
        ╰── GsfTimestamp

## Description

## Functions

### gsf_init ()

    void
    gsf_init (void);

Initializes the GSF library

### gsf_shutdown ()

    void
    gsf_shutdown (void);

De-intializes the GSF library Currently does nothing.

### gsf_init_dynamic ()

    void
    gsf_init_dynamic (GTypeModule *module);

Initializes the GSF library and associates it with a type module `mod` .

#### Parameters

module | GTypeModule. |

### gsf_shutdown_dynamic ()

    void
    gsf_shutdown_dynamic (GTypeModule *module);

De-intializes the GSF library from a type module. Currently does nothing.

#### Parameters

module | currently unused |

### GSF_CLASS()

    #define             GSF_CLASS(name, prefix, class_init, instance_init, parent)

Set up a GSF class.

#### Parameters

name | Name of the class. |
prefix | Symbol prefix designating the namespace to be used for implementing the class. |
class_init | Initialisation function of type GClassInitFunc for the class. |
instance_init | Initialisation function of type GInstanceInitFunc for an instance of the class. |
parent | Parent class to this class. |

### GSF_CLASS_FULL()

    #define             GSF_CLASS_FULL(name, prefix, base_init, base_finalize, \
                		       class_init, class_finalize, instance_init, parent_type, \
                		       abstract, interface_decl)

### GSF_CLASS_ABSTRACT()

    #define             GSF_CLASS_ABSTRACT(name, prefix, class_init, instance_init, parent)

### GSF_INTERFACE()

    #define             GSF_INTERFACE(init_func, iface_type)

### GSF_INTERFACE_FULL()

    #define             GSF_INTERFACE_FULL(type, init_func, iface_type)

### GSF_DYNAMIC_CLASS()

    #define             GSF_DYNAMIC_CLASS(name, prefix, class_init, instance_init, parent)

### GSF_DYNAMIC_CLASS_FULL()

    #define             GSF_DYNAMIC_CLASS_FULL(name, prefix, base_init, base_finalize, \
                				   class_init,  class_finalize, instance_init, parent_type, \
                			       abstract, interface_decl)

### GSF_DYNAMIC_CLASS_ABSTRACT()

    #define             GSF_DYNAMIC_CLASS_ABSTRACT(name, prefix, class_init, instance_init, parent)

### GSF_DYNAMIC_INTERFACE()

    #define             GSF_DYNAMIC_INTERFACE(init_func, iface_type, module)

### GSF_DYNAMIC_INTERFACE_FULL()

    #define             GSF_DYNAMIC_INTERFACE_FULL(type, init_func, iface_type, module)

### gsf_error_quark ()

    GQuark
    gsf_error_quark (void);

#### Returns

the GQuark used to identify libgsf errors in GError structures. Specific error codes come from the GsfError enumeration.

### gsf_mem_dump ()

    void
    gsf_mem_dump (guint8 const *ptr,
                  size_t len);

Dump `len` bytes from the memory location given by `ptr` .

#### Parameters

ptr | memory area to be dumped. |
len | how many bytes will be dumped. |

### gsf_input_dump ()

    void
    gsf_input_dump (GsfInput *input,
                    gboolean dump_as_hex);

Dumps `input` 's contents to STDOUT, optionally in hex format.

#### Parameters

input | a GsfInput |
dump_as_hex | If `TRUE`, dump in hexidecmal format |

### gsf_debug_flag ()

    gboolean
    gsf_debug_flag (const char *flag);

### gsf_filename_to_utf8 ()

    char *
    gsf_filename_to_utf8 (char const *filename,
                          gboolean quoted);

A utility wrapper to make sure filenames are valid utf8. Caller must g_free the result.

#### Parameters

filename | file name suitable for open(2). |
quoted | if `TRUE`, the resulting utf8 file name will be quoted (unless it is invalid). |

#### Returns

`filename` using utf-8 encoding for display

### gsf_iconv_close ()

    void
    gsf_iconv_close (GIConv handle);

A utility wrapper to safely close an iconv handle.

#### Parameters

handle | handle to be closed. |

### gsf_extension_pointer ()

    char const *
    gsf_extension_pointer (char const *path);

Extracts the extension from the end of a filename (the part after the final '.' in the filename).

#### Parameters

path | A filename or file path. |

#### Returns

A pointer to the extension part of the filename, or a pointer to the end of the string if the filename does not have an extension.

[transfer none]

### gsf_base64_encode_simple ()

    guint8 *
    gsf_base64_encode_simple (guint8 const *data,
                              size_t len);

Encodes data from `data` back into `data` using base64 encoding.

#### Parameters

data | data stream. | [array]
len | max length of data to encode |

#### Returns

the number of bytes encoded

### gsf_base64_encode_close ()

    size_t
    gsf_base64_encode_close (guint8 const *in,
                             size_t inlen,
                             gboolean break_lines,
                             guint8 *out,
                             int *state,
                             guint *save);

This funcion should be called to when finished encoding everything, to flush off the last little bit.

#### Parameters

in | Data to be encoded. | [array length=inlen]
inlen | Length of data to be encoded |
break_lines | Whether to use line breaks |
out | Encoded data. | [array]
state | holds the number of bits that are stored in `save` . | [inout]
save | leftover bits that have not yet been decoded. | [inout]

#### Returns

a count of the number of bytes in the final block.

### gsf_base64_encode_step ()

    size_t
    gsf_base64_encode_step (guint8 const *in,
                            size_t len,
                            gboolean break_lines,
                            guint8 *out,
                            int *state,
                            guint *save);

Performs an 'encode step', only encodes blocks of 3 characters from `in` into the output `out` at a time, saves left-over state in `state` and `save` (initialise to 0 on first invocation).

#### Parameters

in | input stream. | [array]
len | max length of data to decode |
break_lines | Whether to use line breaks |
out | output stream. | [array]
state | holds the number of bits that are stored in `save` . | [inout]
save | leftover bits that have not yet been decoded. | [inout]

#### Returns

the number of bytes encoded

### gsf_base64_decode_simple ()

    size_t
    gsf_base64_decode_simple (guint8 *data,
                              size_t len);

Decodes a chunk of base64 encoded data from `data` back into `data` .

#### Parameters

data | data stream. | [array]
len | max length of data to decode |

#### Returns

the number of bytes converted

### gsf_base64_decode_step ()

    size_t
    gsf_base64_decode_step (guint8 const *in,
                            size_t len,
                            guint8 *out,
                            int *state,
                            guint *save);

Decodes a chunk of base64 encoded data

#### Parameters

in | input stream. | [array]
len | max length of data to decode |
out | output stream. | [array]
state | holds the number of bits that are stored in `save` . | [inout]
save | leftover bits that have not yet been decoded. | [inout]

#### Returns

the number of bytes converted

### GSF_LE_GET_GINT8()

    #define GSF_LE_GET_GINT8(p) ((gint8)GSF_LE_GET_GUINT8(p))

Interpret binary data as a signed 8-bit integer in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_GET_GUINT64()

    #define GSF_LE_GET_GUINT64(p) (gsf_le_get_guint64 (p))

Interpret binary data as an unsigned 64-bit integer in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_GET_GINT16()

    #define GSF_LE_GET_GINT16(p) ((gint16)GSF_LE_GET_GUINT16(p))

Interpret binary data as a signed 16-bit integer in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_GET_GUINT8()

    #define GSF_LE_GET_GUINT8(p) (*(guint8 const *)(p))

Interpret binary data as an unsigned 8-bit integer in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_GET_GINT32()

    #define GSF_LE_GET_GINT32(p) ((gint32)GSF_LE_GET_GUINT32(p))

Interpret binary data as a signed 32-bit integer in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_GET_GUINT16()

    #define             GSF_LE_GET_GUINT16(p)

Interpret binary data as an unsigned 16-bit integer in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_GET_GUINT32()

    #define             GSF_LE_GET_GUINT32(p)

Interpret binary data as an unsigned 32-bit integer in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_GET_GINT64()

    #define GSF_LE_GET_GINT64(p) ((gint64)GSF_LE_GET_GUINT64(p))

Interpret binary data as a signed 64-bit integer in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### gsf_le_get_guint64 ()

    guint64
    gsf_le_get_guint64 (void const *p);

Interpret binary data as a guint64 (8 byte unsigned integer type) in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_GET_FLOAT()

    #define GSF_LE_GET_FLOAT(p) (gsf_le_get_float (p))

Interpret binary data as a float in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### gsf_le_get_float ()

    float
    gsf_le_get_float (void const *p);

Interpret binary data as a float in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_GET_DOUBLE()

    #define GSF_LE_GET_DOUBLE(p) (gsf_le_get_double (p))

Interpret binary data as a double in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### gsf_le_get_double ()

    double
    gsf_le_get_double (void const *p);

Interpret binary data as a double in little endian order.

#### Parameters

p | pointer to storage |

#### Returns

interpreted data

### GSF_LE_SET_GUINT8()

    #define             GSF_LE_SET_GUINT8(p, dat)

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | 8-bit unsigned integer |

### GSF_LE_SET_GUINT16()

    #define             GSF_LE_SET_GUINT16(p, dat)

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | 16-bit unsigned integer |

### GSF_LE_SET_GUINT32()

    #define             GSF_LE_SET_GUINT32(p, dat)

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | 32-bit unsigned integer |

### GSF_LE_SET_GINT8()

    #define GSF_LE_SET_GINT8(p,dat) GSF_LE_SET_GUINT8((p),(dat))

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | 8-bit signed integer |

### GSF_LE_SET_GINT16()

    #define GSF_LE_SET_GINT16(p,dat) GSF_LE_SET_GUINT16((p),(dat))

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | 16-bit signed integer |

### GSF_LE_SET_GINT32()

    #define GSF_LE_SET_GINT32(p,dat) GSF_LE_SET_GUINT32((p),(dat))

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | 32-bit signed integer |

### GSF_LE_SET_GINT64()

    #define GSF_LE_SET_GINT64(p,dat) GSF_LE_SET_GUINT64((p),(dat))

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | 64-bit signed integer |

### GSF_LE_SET_GUINT64()

    #define             GSF_LE_SET_GUINT64(p, dat)

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | 64-bit unsigned integer |

### GSF_LE_SET_FLOAT()

    #define GSF_LE_SET_FLOAT(p,dat) gsf_le_set_float((p),(dat))

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | float to be stored |

### GSF_LE_SET_DOUBLE()

    #define GSF_LE_SET_DOUBLE(p,dat) gsf_le_set_double((p),(dat))

Store `dat` in little endian order in memory pointed to by `p` .

#### Parameters

p | pointer to storage |
dat | double to be stored |

### gsf_le_set_float ()

    void
    gsf_le_set_float (void *p,
                      float f);

Store a value of type float in memory in little endian order.

#### Parameters

p | pointer to storage |
f | float to be stored |

### gsf_le_set_double ()

    void
    gsf_le_set_double (void *p,
                       double d);

Store a value of type double in memory in little endian order

#### Parameters

p | pointer to storage |
d | double to be stored |

### gsf_timestamp_new ()

    GsfTimestamp *
    gsf_timestamp_new (void);

### gsf_timestamp_set_time ()

    void
    gsf_timestamp_set_time (GsfTimestamp *stamp,
                            guint64 t);

### gsf_timestamp_copy ()

    GsfTimestamp *
    gsf_timestamp_copy (GsfTimestamp const *stamp);

Copies a timestamp.

#### Parameters

stamp | timestamp to be copied |

#### Returns

a separate copy of `stamp` .

### gsf_timestamp_free ()

    void
    gsf_timestamp_free (GsfTimestamp *stamp);

Releases the memory in use for `stamp` (if any).

#### Parameters

stamp | timestamp to be freed |

### gsf_timestamp_as_string ()

    char *
    gsf_timestamp_as_string (GsfTimestamp const *stamp);

Produce a string representation (ISO 8601 format) of `stamp` .

#### Parameters

stamp | timestamp to be converted. |

#### Returns

a string representation of `stamp` . When `stamp` is `NULL`, the representation is "<invalid>".

### gsf_timestamp_load_from_string ()

    int
    gsf_timestamp_load_from_string (GsfTimestamp *stamp,
                                    char const *spec);

Very simple parser for time stamps. Currently requires a format of 'YYYY-MM-DDThh:mm:ss' and does only rudimentary range checking

#### Parameters

stamp | GsfTimestamp |
spec | The string to parse |

#### Returns

`TRUE` on success

Since: 1.14.24

### gsf_timestamp_from_string ()

    int
    gsf_timestamp_from_string (char const *spec,
                               GsfTimestamp *stamp);

`gsf_timestamp_from_string` has been deprecated since version 1.14.24 and should not be used in newly-written code.

, use gsf_timestamp_load_from_string

Very simple parser for time stamps. Currently requires a format of 'YYYY-MM-DDThh:mm:ss' and does no bounds checking.

[skip]

#### Parameters

spec | The string to parse |
stamp | GsfTimestamp |

#### Returns

`TRUE` on success

### gsf_timestamp_hash ()

    guint
    gsf_timestamp_hash (GsfTimestamp const *stamp);

### gsf_timestamp_equal ()

    gboolean
    gsf_timestamp_equal (GsfTimestamp const *a,
                         GsfTimestamp const *b);

Compare timestamps `a` and `b` .

#### Parameters

a | a timestamp |
b | another timestamp |

#### Returns

true if `a` and `b` represent the same point in time; false otherwise.

### gsf_timestamp_to_value ()

    void
    gsf_timestamp_to_value (GsfTimestamp const *stamp,
                            GValue *value);

Calls g_value_set_box (value, stamp);

#### Parameters

stamp | GsfTimestamp |
value | GValue |

Since: 1.14.24

### gsf_value_set_timestamp ()

    void
    gsf_value_set_timestamp (GValue *value,
                             GsfTimestamp const *stamp);

`gsf_value_set_timestamp` has been deprecated since version 1.14.24 and should not be used in newly-written code.

, use gsf_timestamp_to_value.

[skip]

#### Parameters

value | GValue |
stamp | GsfTimestamp |

### VAL_IS_GSF_TIMESTAMP()

    #define VAL_IS_GSF_TIMESTAMP(v) (G_TYPE_CHECK_VALUE_TYPE((v), GSF_TIMESTAMP_TYPE))

### gsf_timestamp_parse ()

    int
    gsf_timestamp_parse (char const *spec,
                         GsfTimestamp *stamp);

`gsf_timestamp_parse` is deprecated and should not be used in newly-written code.

Use gsf_timestamp_load_from_string

Very simple parser for time stamps. Currently requires a format of 'YYYY-MM-DDThh:mm:ss' and does no bounds checking.

[skip]

#### Parameters

spec | The string to parse |
stamp | GsfTimestamp |

#### Returns

`TRUE` on success

### gsf_doc_prop_swap_val ()

    GValue *
    gsf_doc_prop_swap_val (GsfDocProp *prop,
                           GValue *val);

#### Parameters

prop | GsfDocProp |
val | GValue. | [transfer full]

#### Returns

the current value of `prop` , and replaces it with `val` .

[transfer full]

### gsf_property_settings_collect ()

    void
    gsf_property_settings_collect (GType object_type,
                                   GParameter **p_params,
                                   size_t *p_n_params,
                                   const gchar *first_property_name,
                                   ...);

### gsf_property_settings_collect_valist ()

    void
    gsf_property_settings_collect_valist (GType object_type,
                                          GParameter **p_params,
                                          size_t *p_n_params,
                                          const gchar *first_property_name,
                                          va_list var_args);

This function builds a GParameter array suitable for g_object_newv.

#### Parameters

object_type | the GType for which the properties are being set. |
p_params | a pointer to the GParameter array that holds the properties. (Used for both input and output. This may point to a `NULL` pointer if there are no properties collected yet.) |
p_n_params | a pointer to the number of properties collected. (Used for both input and output.) |
first_property_name | the name of the first property being set, or `NULL`. |
var_args | a va_list holding the remainder of the property names and values, terminated by a `NULL`. |

### gsf_property_settings_free ()

    void
    gsf_property_settings_free (GParameter *params,
                                size_t n_params);

#### Parameters

params | . | [array length=n_params][transfer full]

## Types and Values

### libgsf_major_version

    extern int libgsf_major_version;

Major version number of libgsf, indicating the ABI version.

### libgsf_minor_version

    extern int libgsf_minor_version;

Minor (secondary) version number of libgsf, indicating the API version.

### libgsf_micro_version

    extern int libgsf_micro_version;

Micro (tertiary) version number of libgsf, indicating bug fixes.

### GSF_PARAM_STATIC

    #define GSF_PARAM_STATIC (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)

### GSF_ERROR

    #define GSF_ERROR (gsf_error_quark ())

### enum GsfError

#### Members

GSF_ERROR_OUT_OF_MEMORY | Memory allocation failed |
GSF_ERROR_INVALID_DATA | Invalid data encountered (e.g. not enough data) |

### GSF_OFF_T_FORMAT

    #define GSF_OFF_T_FORMAT G_GINT64_FORMAT

The printf(3) conversion specifier to be used for printing values of type gsf_off_t.

### gsf_off_t

    typedef gint64 gsf_off_t;

Data type to represent offsets (positions) within a data stream.

FIXME: gsf_off_t is really supposed to be the widest type off_t can be configured to on the platform

### GsfTimestamp

    typedef struct {
    	GDate	  date;			/* In local timezone */
    	glong     seconds;		/* time of day */
    	GString	  time_zone;		/* possibly blank */

    	guint32	  timet;
    } GsfTimestamp;

A point in time.

#### Members

GDate `date`; | GDate in local timezone |
glong `seconds`; | glong number of seconds since `date` . |
GString `time_zone`; | possibly blank GString of the timezone |
guint32 `timet`; | as from mktime. |