Gwyfile Library
Objects
typedef void(* GwyfileObjectForeachFunc) (const GwyfileItem *item, void *user_data)
 Type of function for iterating over GWY file data object items. More...
 
GwyfileObject * gwyfile_object_new (const char *name,...)
 Creates a new GWY file object. More...
 
GwyfileObject * gwyfile_object_newv (const char *name, GwyfileItem **items, unsigned int nitems)
 Creates a new GWY file object. More...
 
void gwyfile_object_free (GwyfileObject *object)
 Frees a GWY file data object. More...
 
const char * gwyfile_object_name (const GwyfileObject *object)
 Obtains the name of a GWY file data object. More...
 
size_t gwyfile_object_size (const GwyfileObject *object)
 Obtains the serialized size of a GWY file data object. More...
 
bool gwyfile_object_add (GwyfileObject *object, GwyfileItem *item)
 Adds an data item to a GWY file data object. More...
 
bool gwyfile_object_remove (GwyfileObject *object, const char *name)
 Removes an item from a GWY file data object and frees it. More...
 
GwyfileItem * gwyfile_object_get (const GwyfileObject *object, const char *name)
 Finds a data item in a GWY file object. More...
 
GwyfileItem * gwyfile_object_take (GwyfileObject *object, const char *name)
 Takes an item from a GWY file data object. More...
 
GwyfileItem * gwyfile_object_get_with_type (const GwyfileObject *object, const char *name, GwyfileItemType type)
 Finds a data item in a GWY file object, ensuring its type. More...
 
GwyfileItem * gwyfile_object_take_with_type (GwyfileObject *object, const char *name, GwyfileItemType type)
 Takes a data item from a GWY file object, ensuring its type. More...
 
size_t gwyfile_object_data_size (const GwyfileObject *object)
 Obtains the serialized data size of a GWY file data object. More...
 
GwyfileItem * gwyfile_object_get_nth (const GwyfileObject *object, unsigned int n)
 Gets n-th data item from a GWY file object. More...
 
void gwyfile_object_foreach (const GwyfileObject *object, GwyfileObjectForeachFunc function, void *user_data)
 Calls a function for each item contained in a GWY file data object. More...
 
unsigned int gwyfile_object_nitems (const GwyfileObject *object)
 Obtains the number of items in a GWY file data object. More...
 
const char ** gwyfile_object_item_names (const GwyfileObject *object)
 Constructs the list of names of all items in a GWY file data object. More...
 
GwyfileObject * gwyfile_object_copy (const GwyfileObject *object, GwyfileCopyMethod method)
 Creates a copy of a GWY file object. More...
 
bool gwyfile_object_fwrite (GwyfileObject *object, FILE *stream, GwyfileError **error)
 Writes a GWY file data object to a stdio stream. More...
 
GwyfileObject * gwyfile_object_fread (FILE *stream, size_t max_size, GwyfileError **error)
 Reads a GWY file data object from a stdio stream. More...
 
size_t gwyfile_object_write_memory (const GwyfileObject *object, void *buffer, size_t size, GwyfileError **error)
 Writes a GWY file data object to a memory buffer. More...
 
GwyfileObject * gwyfile_object_read_memory (const void *buffer, size_t size, size_t *bytes_read, GwyfileError **error)
 Reads a GWY file data object from a memory buffer. More...
 

Detailed Description

Gwyddion GWY file consists of objects. They are basic pieces of data. Each has a name and usually contains a number of _GwyfileItem items (also called components) which contain individual values – possibly including nested objects.

Typedef Documentation

◆ GwyfileObjectForeachFunc

GwyfileObjectForeachFunc

Type of function for iterating over GWY file data object items.

This function type is used for gwyfile_object_foreach().

Parameters
itemAn object GWY file data item.
user_dataData pointer passed to gwyfile_object_foreach().

Function Documentation

◆ gwyfile_object_add()

bool gwyfile_object_add ( GwyfileObject *  object,
GwyfileItem *  item 
)

Adds an data item to a GWY file data object.

If no item of the same name exists in this object, the item will be consumed by the object that will take care of freeing it later. Generally, you should not access the item after passing it to this function as there is no guarantee when it will be freed.

If an item of the same name already exists in this object, the function will return false and keep the existing item. Note this means the item may be leaked if you do not check the return value.

Parameters
objectA GWY file data object.
itemA GWY file data item that is not present in any object.
Returns
true if the item was actually added.
Examples
server.c, and writegeneric.c.

◆ gwyfile_object_copy()

GwyfileObject* gwyfile_object_copy ( const GwyfileObject *  object,
GwyfileCopyMethod  method 
)

Creates a copy of a GWY file object.

A new tree is created and returned, with copy of object as its root.

Parameter method gives some control of whether strings and arrays are copied. If they are not copied then the caller promises they will not go away during the lifetime of the newly created object.

Parameters
objectA GWY file object.
methodHow ownership of strings and atomic data arrays should be handled.
Returns
A newly created object which is a copy of object.
Since
1.4

◆ gwyfile_object_data_size()

size_t gwyfile_object_data_size ( const GwyfileObject *  object)

Obtains the serialized data size of a GWY file data object.

This is the size value stored in GWY files size and does not include the size of object name and the size field itself.

Parameters
objectA GWY file data object.
Returns
The object data size, in bytes.

◆ gwyfile_object_foreach()

void gwyfile_object_foreach ( const GwyfileObject *  object,
GwyfileObjectForeachFunc  function,
void *  user_data 
)

Calls a function for each item contained in a GWY file data object.

The function must not add items to object and it must not remove items either. And, of course, it must not cause object to be freed.

Parameters
objectA GWY file data object.
functionFunction to call for each item in the object.
user_dataData passed to the function.
See also
gwyfile_object_get_nth
Examples
readgeneric.c, and readgwy.c.

◆ gwyfile_object_fread()

GwyfileObject* gwyfile_object_fread ( FILE *  stream,
size_t  max_size,
GwyfileError **  error 
)

Reads a GWY file data object from a stdio stream.

The stream does not have to be seekable.

On success, the position indicator in stream will be pointed after the end of the object.

On failure, the position indicator state in stream is undefined.

The maximum number of bytes to read is given by max_size which is of type size_t, however, be aware that sizes in GWY files are only 32bit. So any value that does not fit into a 32bit integer means the same as SIZE_MAX.

If reading more than max_size bytes would be required to reconstruct the top-level object, the function fails with GWYFILE_ERROR_TRUNCATED error in the GWYFILE_ERROR_DOMAIN_DATA domain.

Parameters
streamC stdio stream to read the GWY file from.
max_sizeMaximum number of bytes to read. Pass SIZE_MAX for unconstrained reading.
errorLocation for the error (or NULL).
Returns
The reconstructed data object, or NULL if the reading or reconstruction fails.

◆ gwyfile_object_free()

void gwyfile_object_free ( GwyfileObject *  object)

Frees a GWY file data object.

All items contained in the object are freed recursively. It is not permitted to free an object present in a data item.

You can pass NULL as object. The function is then no-op.

Parameters
objectA GWY file data object.
Examples
checkgeneric.c, client.c, readgeneric.c, readgwy.c, server.c, writegeneric.c, and writegwy.c.

◆ gwyfile_object_fwrite()

bool gwyfile_object_fwrite ( GwyfileObject *  object,
FILE *  stream,
GwyfileError **  error 
)

Writes a GWY file data object to a stdio stream.

The stream does not have to be seekable.

On success, the position indicator in stream will be pointed after the end of the written object.

On failure, the position indicator state in stream is undefined.

Parameters
objectA GWY file data object.
streamC stdio stream to write the object to.
errorLocation for the error (or NULL).
Returns
true if the writing succeeded.

◆ gwyfile_object_get()

GwyfileItem* gwyfile_object_get ( const GwyfileObject *  object,
const char *  name 
)

Finds a data item in a GWY file object.

This function looks up the item by name. If you want to ensure the item is also of a specified type, use gwyfile_object_get_with_type().

Parameters
objectA GWY file data object.
nameName of data item to find.
Returns
The item, if found. Otherwise NULL is returned.
Examples
readgwy.c.

◆ gwyfile_object_get_nth()

GwyfileItem* gwyfile_object_get_nth ( const GwyfileObject *  object,
unsigned int  n 
)

Gets n-th data item from a GWY file object.

This function simply returns the n-th item according to the internal order. It can be useful for a simple iteration over the items. Note, however, that mixing it with calls which add, remove or take items from object has undefined results.

Parameters
objectA GWY file data object.
nIndex of the object to return. It is allowed to pass a too large index; the function then returns NULL.
Returns
The item at index n, if it exists. Otherwise NULL is returned.
See also
gwyfile_object_foreach gwyfile_object_nitems
Since
1.3
Examples
client.c, and server.c.

◆ gwyfile_object_get_with_type()

GwyfileItem* gwyfile_object_get_with_type ( const GwyfileObject *  object,
const char *  name,
GwyfileItemType  type 
)

Finds a data item in a GWY file object, ensuring its type.

This function returns an item only if both its name and type match the arguments.

Parameters
objectA GWY file data object.
nameName of data item to find.
typeType of the item to find.
Returns
The item, if found. Otherwise NULL is returned.
See also
gwyfile_object_take_with_type
Examples
readgwy.c.

◆ gwyfile_object_item_names()

const char** gwyfile_object_item_names ( const GwyfileObject *  object)

Constructs the list of names of all items in a GWY file data object.

Parameters
objectA GWY file data object.

Note the called must free the array with free() when no longer needed, but the strings within remain owned by object and are generally only guaranteed to be valid until object is changed.

Returns
A newly allocated array with names of all items in object. When there are no items NULL is returned. Upon memory allocation failure NULL is returned and errno is set to ENOMEM.

◆ gwyfile_object_name()

const char* gwyfile_object_name ( const GwyfileObject *  object)

Obtains the name of a GWY file data object.

Parameters
objectA GWY file data object.
Returns
The object type name. The returned string is owned by object and must not be modified or freed.
Examples
readgeneric.c, and readgwy.c.

◆ gwyfile_object_new()

GwyfileObject* gwyfile_object_new ( const char *  name,
  ... 
)

Creates a new GWY file object.

The object type name must be a valid identifier formed from ASCII letters, digits and underscores. Usually, it is the name of a serialisable Gwyddion object such as "GwyDataField". However, if you use GWY files to store other hierarchical data (not intended for Gwyddion) this does not have to hold.

Each item must have a unique name.

The created object will consume all the items and will take care of freeing them. You must not touch them any more after this function returns.

Parameters
nameObject type name. It determines what data items are expected inside.
...A NULL-terminated list of items to add to the object.
Returns
The newly created GWY file object.
See also
gwyfile_object_newv
Examples
client.c, server.c, writegeneric.c, and writegwy.c.

◆ gwyfile_object_newv()

GwyfileObject* gwyfile_object_newv ( const char *  name,
GwyfileItem **  items,
unsigned int  nitems 
)

Creates a new GWY file object.

The object type name must be a valid identifier formed from ASCII letters, digits and underscores. Usually, it is the name of a serialisable Gwyddion object such as "GwyDataField". However, if you use GWY files to store other hierarchical data (not intended for Gwyddion) this does not have to hold.

Each item must have a unique name.

The created object will consume all the items and will take care of freeing them. You must not touch them any more after this function returns.

The array items, however, remains owned by the caller.

Parameters
nameObject type name.
itemsArray of items to add to the object.
nitemsNumber of items in items.
Returns
The newly created GWY file object.
See also
gwyfile_object_new

◆ gwyfile_object_nitems()

unsigned int gwyfile_object_nitems ( const GwyfileObject *  object)

Obtains the number of items in a GWY file data object.

Parameters
objectA GWY file data object.

This function is intended to be used in conjunction with gwyfile_object_item_names(), gwyfile_object_get_nth(), or possibly gwyfile_object_foreach().

Returns
The number of items in object.
Examples
client.c, and server.c.

◆ gwyfile_object_read_memory()

GwyfileObject* gwyfile_object_read_memory ( const void *  buffer,
size_t  size,
size_t *  bytes_read,
GwyfileError **  error 
)

Reads a GWY file data object from a memory buffer.

The buffer size is given by size which is of type size_t, however, be aware that sizes in GWY files are only 32bit.

If reading more than size bytes would be required to reconstruct the top-level object, the function fails with GWYFILE_ERROR_TRUNCATED error in the GWYFILE_ERROR_DOMAIN_DATA domain.

The actual number of bytes consumed can be found by passing non-NULL bytes_read.

Parameters
bufferMemory buffer to read the serialized representation from.
errorLocation for the error (or NULL).
sizeSize of the memory buffer.
bytes_readPointer to location where the number of consumed bytes should be stored. May be NULL.
Returns
The reconstructed data object. NULL is returned upon failure.
Since
1.3
Examples
client.c, and server.c.

◆ gwyfile_object_remove()

bool gwyfile_object_remove ( GwyfileObject *  object,
const char *  name 
)

Removes an item from a GWY file data object and frees it.

Parameters
objectA GWY file data object.
nameName of data item to remove.
Returns
Whether such item was present and was removed.

◆ gwyfile_object_size()

size_t gwyfile_object_size ( const GwyfileObject *  object)

Obtains the serialized size of a GWY file data object.

The size includes the size of object name and the size field itself. See gwyfile_object_data_size() for the size of just object data.

Parameters
objectA GWY file data object.
Returns
The object size, in bytes.
Examples
client.c, and server.c.

◆ gwyfile_object_take()

GwyfileItem* gwyfile_object_take ( GwyfileObject *  object,
const char *  name 
)

Takes an item from a GWY file data object.

The caller becomes the owner of the returned item and is responsible for freeing it later.

Parameters
objectA GWY file data object.
nameName of data item to take.
Returns
The item, if found. Otherwise NULL is returned.

◆ gwyfile_object_take_with_type()

GwyfileItem* gwyfile_object_take_with_type ( GwyfileObject *  object,
const char *  name,
GwyfileItemType  type 
)

Takes a data item from a GWY file object, ensuring its type.

This function returns an item only if both its name and type match the arguments.

The caller becomes the owner of the returned item and is responsible for freeing it later.

Parameters
objectA GWY file data object.
nameName of data item to find.
typeType of the item to find.
Returns
The item, if found. Otherwise NULL is returned.
See also
gwyfile_object_get_with_type

◆ gwyfile_object_write_memory()

size_t gwyfile_object_write_memory ( const GwyfileObject *  object,
void *  buffer,
size_t  size,
GwyfileError **  error 
)

Writes a GWY file data object to a memory buffer.

The function fails if the buffer size is insufficient. Use gwyfile_object_size() to obtain a sufficient buffer size.

Zero return value indicates failure (on success something is always written to buffer).

Parameters
objectA GWY file data object.
bufferMemory buffer to write the serialized representation to.
sizeSize of the memory buffer.
errorLocation for the error (or NULL).
Returns
The number of bytes written.
Since
1.3
Examples
client.c, and server.c.