Enumerations
enum	GwyfileItemType { GWYFILE_ITEM_BOOL = 'b' , GWYFILE_ITEM_CHAR = 'c' , GWYFILE_ITEM_INT32 = 'i' , GWYFILE_ITEM_INT64 = 'q' , GWYFILE_ITEM_DOUBLE = 'd' , GWYFILE_ITEM_STRING = 's' , GWYFILE_ITEM_OBJECT = 'o' , GWYFILE_ITEM_CHAR_ARRAY = 'C' , GWYFILE_ITEM_INT32_ARRAY = 'I' , GWYFILE_ITEM_INT64_ARRAY = 'Q' , GWYFILE_ITEM_DOUBLE_ARRAY = 'D' , GWYFILE_ITEM_STRING_ARRAY = 'S' , GWYFILE_ITEM_OBJECT_ARRAY = 'O' }

Functions
void	gwyfile_item_free (GwyfileItem *item)
	Frees a GWY file data item. More...

GwyfileItemType	gwyfile_item_type (const GwyfileItem *item)
	Obtains the type of a GWY file data item. More...

const char *	gwyfile_item_name (const GwyfileItem *item)
	Obtains the name of a GWY file data item. More...

uint32_t	gwyfile_item_array_length (const GwyfileItem *item)
	Obtains the array length of a GWY file data item. More...

size_t	gwyfile_item_size (const GwyfileItem *item)
	Obtains the serialized total size of a GWY file data item. More...

size_t	gwyfile_item_data_size (const GwyfileItem *item)
	Obtains the serialized size of a GWY file data item data. More...

GwyfileItem *	gwyfile_item_copy (const GwyfileItem *item, GwyfileCopyMethod method)
	Creates a copy of a data item. More...

bool	gwyfile_item_fwrite (const GwyfileItem item, FILE stream, GwyfileError **error)
	Writes a GWY file data item to a stdio stream. More...

GwyfileItem *	gwyfile_item_fread (FILE stream, size_t max_size, GwyfileError *error)
	Reads a GWY file data item from a stdio stream. More...

size_t	gwyfile_item_write_memory (const GwyfileItem item, void buffer, size_t size, GwyfileError **error)
	Writes a GWY file data item to a memory buffer. More...

GwyfileItem *	gwyfile_item_read_memory (const void buffer, size_t size, size_t bytes_read, GwyfileError **error)
	Reads a GWY file data item from a memory buffer. More...

bool	gwyfile_item_owns_data (const GwyfileItem *item)
	Reports if a GWY file item owns its data. More...

Detailed Description

Item is one individual value, for instance integer, floating point number or a string. Items are contained inside objects, representing their components. Beside atomic types, items can hold arrays or nested objects.

Enumeration Type Documentation

◆ GwyfileItemType

enum GwyfileItemType

Enumerator
GWYFILE_ITEM_BOOL	Boolean (true or false).
GWYFILE_ITEM_CHAR	Single character.
GWYFILE_ITEM_INT32	32bit integer.
GWYFILE_ITEM_INT64	64bit integer.
GWYFILE_ITEM_DOUBLE	IEEE double precision floating point number. A conforming GWY file may only contain finite floating point values.
GWYFILE_ITEM_STRING	String of characters. All strings in a conforming GWY file must be UTF-8 encoded (or ASCII-encoding, since ASCII is a subset of UTF-8). See GWYFILE_ITEM_CHAR_ARRAY for a raw sequence of characters.
GWYFILE_ITEM_OBJECT	Object, i.e. a nested data structure. In libgwyfile the corresponding C data type is _GwyfileObject*. In Gwyddion, these items corresponds to actual objects in the type system.
GWYFILE_ITEM_CHAR_ARRAY	Array of characters. Unlike GWYFILE_ITEM_STRING, an array of characters is not considered text, just a sequence of bytes. There is no encoding implied.
GWYFILE_ITEM_INT32_ARRAY	Array of 32bit integers.
GWYFILE_ITEM_INT64_ARRAY	Array of 64bit integers.
GWYFILE_ITEM_DOUBLE_ARRAY	Array of IEEE double precision floating point numbers.
GWYFILE_ITEM_STRING_ARRAY	Array of character strings. All strings in a conforming GWY file must be UTF-8 encoded (or ASCII-encoding, since ASCII is a subset of UTF-8).
GWYFILE_ITEM_OBJECT_ARRAY	Array of objects, i.e. a nested data structures. See also GWYFILE_ITEM_OBJECT

Function Documentation

◆ gwyfile_item_array_length()

uint32_t gwyfile_item_array_length ( const GwyfileItem * item )

Obtains the array length of a GWY file data item.

This function may be called on non-array data items. Zero is returned as the length in this case.

Parameters

item	A GWY file data item.

Returns: The number of items of the contained array.

◆ gwyfile_item_copy()

GwyfileItem* gwyfile_item_copy	(	const GwyfileItem *	item,
		GwyfileCopyMethod	method
	)

Creates a copy of a data item.

A new tree is created and returned, with copy of item as its root. If item is atomic then just this one item is copied, but if it contains objects the entire tree is duplicated.

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

Parameters

item	A GWY file data item.
method	How ownership of strings and atomic data arrays should be handled.

Returns: A newly created item which is a copy of item.

Since: 1.4

◆ gwyfile_item_data_size()

size_t gwyfile_item_data_size ( const GwyfileItem * item )

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

The size is the number of bytes the item data would occupy in a GWY file. It includes the size of all contained data, in particular contained objects and object arrays.

The returned size does not include the item type and name (see gwyfile_item_size() for that). It is the pure data size.

Parameters

item	A GWY file data item.

Returns: The item data size, in bytes.

◆ gwyfile_item_fread()

GwyfileItem* gwyfile_item_fread	(	FILE *	stream,
		size_t	max_size,
		GwyfileError **	error
	)

Reads a GWY file data item 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 item.

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, i.e. unconstrained reading.

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.
error	Location for the error (or `NULL`).
max_size	Maximum number of bytes to read. Pass `SIZE_MAX` for unconstrained reading.

Returns: The reconstructed data item. NULL is returned upon I/O failure.

◆ gwyfile_item_free()

void gwyfile_item_free ( GwyfileItem * item )

Frees a GWY file data item.

All item data, including contained arrays, strings and objects, are freed recursively. It is not permitted to free an item present in a data object.

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

Parameters

item	A GWY file data item.

See also: gwyfile_item_release_object

◆ gwyfile_item_fwrite()

bool gwyfile_item_fwrite	(	const GwyfileItem *	item,
		FILE *	stream,
		GwyfileError **	error
	)

Writes a GWY file data item to a stdio stream.

The stream does not have to be seekable.

Parameters

item	A GWY file data item.
stream	C stdio stream to write the item to.
error	Location for the error (or `NULL`).

Returns: true if the writing succeeded.

◆ gwyfile_item_name()

const char* gwyfile_item_name ( const GwyfileItem * item )

Obtains the name of a GWY file data item.

Parameters

item	A GWY file data item.

Returns: The object type name. The returned string is owned by item and must not be modified or freed.

◆ gwyfile_item_owns_data()

bool gwyfile_item_owns_data ( const GwyfileItem * item )

Reports if a GWY file item owns its data.

It is possible to pass any type of data item to this function. It returns true for data that cannot be taken from the item.

You should rarely need this function.

Parameters

item	A GWY file data item.

Returns: true if item owns its data.

◆ gwyfile_item_read_memory()

GwyfileItem* gwyfile_item_read_memory	(	const void *	buffer,
		size_t	size,
		size_t *	bytes_read,
		GwyfileError **	error
	)

Reads a GWY file data item 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 item. NULL is returned upon failure.

Since: 1.3

◆ gwyfile_item_size()

size_t gwyfile_item_size ( const GwyfileItem * item )

Obtains the serialized total size of a GWY file data item.

The size is the number of bytes the data would occupy in a GWY file. It is equal to the value returned by gwyfile_item_data_size() plus the size of item type and name. For array types, it includes the array length record.

Parameters

item	A GWY file data item.

Returns: The item size, in bytes.

◆ gwyfile_item_type()

GwyfileItemType gwyfile_item_type ( const GwyfileItem * item )

Obtains the type of a GWY file data item.

Parameters

item	A GWY file data item.

Returns: The item type.

◆ gwyfile_item_write_memory()

size_t gwyfile_item_write_memory	(	const GwyfileItem *	item,
		void *	buffer,
		size_t	size,
		GwyfileError **	error
	)

Writes a GWY file data item to a memory buffer.

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

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

Parameters

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

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ GwyfileItemType

Function Documentation

◆ gwyfile_item_array_length()

◆ gwyfile_item_copy()

◆ gwyfile_item_data_size()

◆ gwyfile_item_fread()

◆ gwyfile_item_free()

◆ gwyfile_item_fwrite()

◆ gwyfile_item_name()

◆ gwyfile_item_owns_data()

◆ gwyfile_item_read_memory()

◆ gwyfile_item_size()

◆ gwyfile_item_type()

◆ gwyfile_item_write_memory()