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

item	An object GWY file data item.
user_data	Data 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

object	A GWY file data object.
item	A 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

object	A GWY file object.
method	How 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

object A 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

object	A GWY file data object.
function	Function to call for each item in the object.
user_data	Data 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

stream	C stdio stream to read the GWY file from.
max_size	Maximum number of bytes to read. Pass `SIZE_MAX` for unconstrained reading.
error	Location 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

object A 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

object	A GWY file data object.
stream	C stdio stream to write the object to.
error	Location 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

object	A GWY file data object.
name	Name 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

object	A GWY file data object.
n	Index 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

object	A GWY file data object.
name	Name of data item to find.
type	Type 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

object A 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

object A 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

name	Object 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

name	Object type name.
items	Array of items to add to the object.
nitems	Number 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

object A 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

buffer	Memory buffer to read the serialized representation from.
error	Location for the error (or `NULL`).
size	Size of the memory buffer.
bytes_read	Pointer 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

object	A GWY file data object.
name	Name 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

object A 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

object	A GWY file data object.
name	Name 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

object	A GWY file data object.
name	Name of data item to find.
type	Type 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

object	A GWY file data object.
buffer	Memory buffer to write the serialized representation to.
size	Size of the memory buffer.
error	Location for the error (or `NULL`).

Returns: The number of bytes written.

Since: 1.3

Examples: client.c, and server.c.