utils

utils

Synopsis




void                gsf_init                            (void);
void                gsf_shutdown                        (void);
void                gsf_init_dynamic                    (GTypeModule *module);
void                gsf_shutdown_dynamic                (GTypeModule *module);
extern              int libgsf_major_version;
extern              int libgsf_minor_version;
extern              int libgsf_micro_version;

#define             GSF_CLASS                           (name, prefix, class_init, instance_init, parent)
#define             GSF_CLASS_FULL                      (name, prefix, base_init, base_finalize,
                                                         		       class_init, class_finalize, instance_init, parent_type,
                                                         		       abstract, interface_decl)
#define             GSF_CLASS_ABSTRACT                  (name, prefix, class_init, instance_init, parent)
#define             GSF_INTERFACE                       (init_func, iface_type)
#define             GSF_INTERFACE_FULL                  (type, init_func, iface_type)
#define             GSF_DYNAMIC_CLASS                   (name, prefix, class_init, instance_init, parent)
#define             GSF_DYNAMIC_CLASS_FULL              (name, prefix, base_init, base_finalize,
                                                         				   class_init,  class_finalize, instance_init, parent_type,
                                                         			       abstract, interface_decl)
#define             GSF_DYNAMIC_CLASS_ABSTRACT          (name, prefix, class_init, instance_init, parent)
#define             GSF_DYNAMIC_INTERFACE               (init_func, iface_type, module)
#define             GSF_DYNAMIC_INTERFACE_FULL          (type, init_func, iface_type, module)
#define             GSF_PARAM_STATIC

#define             GSF_ERROR
enum                GsfError;
GQuark              gsf_error_quark                     (void);

void                gsf_mem_dump                        (guint8 const *ptr,
                                                         size_t len);
void                gsf_input_dump                      (GsfInput *input,
                                                         gboolean dump_as_hex);

#define             GSF_OFF_T_FORMAT
typedef             gsf_off_t;
char*               gsf_filename_to_utf8                (char const *filename,
                                                         gboolean quoted);
void                gsf_iconv_close                     (GIConv handle);
charconst *         gsf_extension_pointer               (char const *path);

guint8*             gsf_base64_encode_simple            (guint8 const *data,
                                                         size_t len);
size_t              gsf_base64_encode_close             (guint8 const *in,
                                                         size_t inlen,
                                                         gboolean break_lines,
                                                         guint8 *out,
                                                         int *state,
                                                         guint *save);
size_t              gsf_base64_encode_step              (guint8 const *in,
                                                         size_t len,
                                                         gboolean break_lines,
                                                         guint8 *out,
                                                         int *state,
                                                         guint *save);
size_t              gsf_base64_decode_simple            (guint8 *data,
                                                         size_t len);
size_t              gsf_base64_decode_step              (guint8 const *in,
                                                         size_t len,
                                                         guint8 *out,
                                                         int *state,
                                                         guint *save);
#define             GSF_LE_GET_GINT8                    (p)
#define             GSF_LE_GET_GUINT64                  (p)
#define             GSF_LE_GET_GINT16                   (p)
#define             GSF_LE_GET_GUINT8                   (p)
#define             GSF_LE_GET_GINT32                   (p)
#define             GSF_LE_GET_GUINT16                  (p)
#define             GSF_LE_GET_GUINT32                  (p)
#define             GSF_LE_GET_GINT64                   (p)
guint64             gsf_le_get_guint64                  (void const *p);
#define             GSF_LE_GET_FLOAT                    (p)
float               gsf_le_get_float                    (void const *p);
#define             GSF_LE_GET_DOUBLE                   (p)
double              gsf_le_get_double                   (void const *p);
#define             GSF_LE_SET_GUINT8                   (p, dat)
#define             GSF_LE_SET_GUINT16                  (p, dat)
#define             GSF_LE_SET_GUINT32                  (p, dat)
#define             GSF_LE_SET_GINT8                    (p,dat)
#define             GSF_LE_SET_GINT16                   (p,dat)
#define             GSF_LE_SET_GINT32                   (p,dat)
#define             GSF_LE_SET_GINT64                   (p,dat)
#define             GSF_LE_SET_GUINT64                  (p, dat)
#define             GSF_LE_SET_FLOAT                    (p,dat)
#define             GSF_LE_SET_DOUBLE                   (p,dat)
void                gsf_le_set_float                    (void *p,
                                                         float f);
void                gsf_le_set_double                   (void *p,
                                                         double d);

                    GsfTimestamp;
GsfTimestamp*       gsf_timestamp_copy                  (GsfTimestamp const *stamp);
void                gsf_timestamp_free                  (GsfTimestamp *stamp);
char*               gsf_timestamp_as_string             (GsfTimestamp const *stamp);
int                 gsf_timestamp_parse                 (char const *spec,
                                                         GsfTimestamp *stamp);
guint               gsf_timestamp_hash                  (GsfTimestamp const *stamp);
gboolean            gsf_timestamp_equal                 (GsfTimestamp const *a,
                                                         GsfTimestamp const *b);
void                gsf_value_set_timestamp             (GValue *value,
                                                         GsfTimestamp const *stamp);
#define             VAL_IS_GSF_TIMESTAMP                (v)


GValue*             gsf_doc_prop_swap_val               (GsfDocProp *prop,
                                                         GValue *val);
void                gsf_property_settings_collect       (GType object_type,
                                                         GParameter **p_params,
                                                         size_t *p_n_params,
                                                         const gchar *first_property_name,
                                                         ...);
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);
void                gsf_property_settings_free          (GParameter *params,
                                                         size_t n_params);

Description

Details

gsf_init ()

void                gsf_init                            (void);

Initializes the GSF library

gsf_shutdown ()

void                gsf_shutdown                        (void);

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

gsf_init_dynamic ()

void                gsf_init_dynamic                    (GTypeModule *module);

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

module :

 GTypeModule.

gsf_shutdown_dynamic ()

void                gsf_shutdown_dynamic                (GTypeModule *module);

module :

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_CLASS()

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

Set up a GSF class.

name :

 (string) Name of the class.

prefix :

 (string) Prefix designating the namespace to be used for implementing the class.

class_init :

 (GClassInitFunc) Initialisation function for the class.

instance_init :

 (GInstanceInitFunc) Initialisation (constructor) function 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)

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)

name :

prefix :

class_init :

instance_init :

parent :

GSF_INTERFACE()

#define             GSF_INTERFACE(init_func, iface_type)

init_func :

iface_type :

GSF_INTERFACE_FULL()

#define             GSF_INTERFACE_FULL(type, init_func, iface_type)

type :

init_func :

iface_type :

GSF_DYNAMIC_CLASS()

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

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)

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)

name :

prefix :

class_init :

instance_init :

parent :

GSF_DYNAMIC_INTERFACE()

#define             GSF_DYNAMIC_INTERFACE(init_func, iface_type, module)

init_func :

iface_type :

module :

GSF_DYNAMIC_INTERFACE_FULL()

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

type :

init_func :

iface_type :

module :

GSF_PARAM_STATIC

#define             GSF_PARAM_STATIC

GSF_ERROR

#define GSF_ERROR (gsf_error_quark ())

enum GsfError

typedef enum {
	GSF_ERROR_OUT_OF_MEMORY,
	GSF_ERROR_INVALID_DATA
} GsfError;

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.

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.

input :

 a GsfInput

dump_as_hex :

 If TRUE, dump in hexidecmal format

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

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.

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.

handle :

 handle to be closed.

gsf_extension_pointer ()

charconst *         gsf_extension_pointer               (char const *path);

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

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.

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.

data :

 data stream

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.

in :

 Data to be encoded

inlen :

 Length of data to be encoded

break_lines :

 Whether to use line breaks

out :

 Encoded data.

state :

 holds the number of bits that are stored in save

save :

 leftover bits that have not yet been decoded

Returns :

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

in :

 input stream

len :

 max length of data to decode

break_lines :

 Whether to use line breaks

out :

 output stream

state :

 holds the number of bits that are stored in save

save :

 leftover bits that have not yet been decoded

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.

data :

 data stream

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

in :

 input stream

len :

 max length of data to decode

out :

 output stream

state :

 holds the number of bits that are stored in save

save :

 leftover bits that have not yet been decoded

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.

p :

 pointer to storage

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.

p :

 pointer to storage

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.

p :

 pointer to storage

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.

p :

 pointer to storage

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.

p :

 pointer to storage

GSF_LE_GET_GUINT16()

#define             GSF_LE_GET_GUINT16(p)

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

p :

 pointer to storage

GSF_LE_GET_GUINT32()

#define             GSF_LE_GET_GUINT32(p)

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

p :

 pointer to storage

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.

p :

 pointer to storage

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.

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.

p :

 pointer to storage

gsf_le_get_float ()

float               gsf_le_get_float                    (void const *p);

Interpret binary data as a float in little endian order.

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.

p :

 pointer to storage

gsf_le_get_double ()

double              gsf_le_get_double                   (void const *p);

Interpret binary data as a double in little endian order.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

p :

 pointer to storage

d :

 double to be stored

GsfTimestamp

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

	guint32	  timet;
} GsfTimestamp;

Class representing a point in time.

gsf_timestamp_copy ()

GsfTimestamp*       gsf_timestamp_copy                  (GsfTimestamp const *stamp);

Copies a timestamp.

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

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.

stamp :

 timestamp to be converted.

Returns :

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

gsf_timestamp_parse ()

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

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

ICK ICK ICK This routine should be called _from_sting.

spec :

 The string to parse

stamp :

 GsfTimestamp

Returns :

 TRUE on success

gsf_timestamp_hash ()

guint               gsf_timestamp_hash                  (GsfTimestamp const *stamp);

stamp :

Returns :

gsf_timestamp_equal ()

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

Compare timestamps a and b.

a :

 a timestamp

b :

 another timestamp

Returns :

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

gsf_value_set_timestamp ()

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

value :

stamp :

VAL_IS_GSF_TIMESTAMP()

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

v :

gsf_doc_prop_swap_val ()

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

prop :

 GsfDocProp

val :

 GValue

Returns :

 the current value of prop, and replaces it with val Caller is responsible for unsetting and freeing the result.

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

object_type :

p_params :

p_n_params :

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.

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

params :

n_params :