Whole-CIF functions

Functions
int	cif_create (cif_tp **cif)
	Creates a new, empty, managed CIF.
int	cif_destroy (cif_tp *cif)
	Removes the specified managed CIF, releasing all resources it holds.
int	cif_create_block (cif_tp *cif, const UChar *code, cif_block_tp **block)
	Creates a new data block bearing the specified code in the specified CIF.
int	cif_get_block (cif_tp *cif, const UChar *code, cif_block_tp **block)
	Looks up and optionally returns the data block bearing the specified block code, if any, in the specified CIF.
int	cif_get_all_blocks (cif_tp *cif, cif_block_tp ***blocks)
	Provides a null-terminated array of data block handles, one for each block in the specified CIF.
int	cif_walk (cif_tp *cif, cif_handler_tp *handler, void *context)
	Performs a depth-first, natural-order traversal of a CIF, calling back to handler routines provided by the caller for each structural element.

---

Function Documentation

int cif_create

(

cif_tp **

cif

)

Creates a new, empty, managed CIF.

If the function succeeds then the caller assumes responsibility for releasing the resources associated with the managed CIF via the cif_destroy() function.

Parameters:

[out]

cif

a pointer to the location where a handle on the managed CIF should be recorded; must not be NULL. The initial value of *cif is ignored, and is overwritten on success.

Returns:

Returns CIF_OK on success or an error code (typically CIF_ERROR ) on failure.

int cif_create_block	(	cif_tp *	cif,
		const UChar *	code,
		cif_block_tp **	block
	)

Creates a new data block bearing the specified code in the specified CIF.

This function can optionally return a handle on the new block via the block argument. When that option is used, the caller assumes responsibility for cleaning up the provided handle via either cif_container_free() (to clean up only the handle) or cif_container_destroy() (to also remove the block from the managed CIF).

The caller retains ownership of all the arguments.

Parameters:

[in]	cif	a handle on the managed CIF object to which a new block should be added; must be non-NULL and valid.
[in]	code	the block code of the block to add, as a NUL-terminated Unicode string; the block code must comply with CIF constraints on block codes.
[in,out]	block	if not NULL, then a location where a handle on the new block should be recorded, overwriting any previous value. A handle is recorded only on success.

Returns:

CIF_OK on success or an error code on failure, normally one of:

• CIF_ARGUMENT_ERROR if the provided block code is NULL
• CIF_INVALID_BLOCKCODE if the provided block code is invalid
• CIF_DUP_BLOCKCODE if the specified CIF already contains a block having the given code (note that block codes are compared in a Unicode-normalized and caseless form)
• CIF_ERROR for most other failures

int cif_destroy

(

cif_tp *

cif

)

Removes the specified managed CIF, releasing all resources it holds.

The cif handle and any outstanding handles on its contents are invalidated by this function. The effects of any further use of them (except release via the cif_*_free() functions) are undefined, though the functions of this library may return code CIF_INVALID_HANDLE if such a handle is passed to them. Any resources belonging to the provided handle itself are also released, but not those belonging to any other handle. The original external source (if any) of the CIF data is not affected.

Parameters:

[in]

cif

the handle on the CIF to destroy; must not be NULL. On success, this handle ceases to be valid.

Returns:

Returns CIF_OK on success or an error code (typically CIF_ERROR ) on failure.

int cif_get_all_blocks	(	cif_tp *	cif,
		cif_block_tp ***	blocks
	)

Provides a null-terminated array of data block handles, one for each block in the specified CIF.

The caller takes responsibility for cleaning up the provided block handles and the dynamic array containing them.

Parameters:

[in]	cif	a handle on the managed CIF object from which to draw block handles; must be non-NULL and valid. The caller retains ownership of this argument.
[in,out]	blocks	a pointer to the location where a pointer to the resulting array of block handles should be recorded. Must not be NULL.

Returns:

CIF_OK on success, or an error code (typically CIF_ERROR ) on failure

int cif_get_block	(	cif_tp *	cif,
		const UChar *	code,
		cif_block_tp **	block
	)

Looks up and optionally returns the data block bearing the specified block code, if any, in the specified CIF.

Note that CIF block codes are matched in caseless and Unicode-normalized form.

The caller retains ownership of all arguments.

Parameters:

[in]	cif	a handle on the managed CIF object in which to look up the specified block code; must be non-NULL and valid.
[in]	code	the block code to look up, as a NUL-terminated Unicode string.
[in,out]	block	if not NULL on input, and if a block matching the specified code is found, then a handle on it is written where this argument points. The caller assumes responsibility for releasing this handle.

Returns:

CIF_OK on a successful lookup (even if block is NULL), CIF_NOSUCH_BLOCK if there is no data block bearing the given code in the given CIF, or an error code (typically CIF_ERROR ) if an error occurs.

int cif_walk	(	cif_tp *	cif,
		cif_handler_tp *	handler,
		void *	context
	)

Performs a depth-first, natural-order traversal of a CIF, calling back to handler routines provided by the caller for each structural element.

Traverses the tree structure of a CIF, invoking caller-specified handler functions for each structural element along the route. Order is block -> [frame -> ...] loop -> packet -> item, with save frames being traversed before loops within each data block. Handler callbacks can influence the walker's path via their return values, instructing it to continue as normal (CIF_TRAVERSE_CONTINUE), to avoid traversing the children of the current element (CIF_TRAVERSE_SKIP_CURRENT), to avoid traversing subsequent siblings of the current element (CIF_TRAVERSE_SKIP_SIBLINGS), or to terminate the walk altogether (CIF_TRAVERSE_END). For the purposes of this function, loops are not considered "siblings" of save frames.

Parameters:

[in]	cif	a handle on the CIF to traverse
[in]	handler	a structure containing the callback functions handling each type of CIF structural element
[in]	context	a context object to pass to each callback function; opaque to the walker itself

Returns:

Returns CIF_OK on success, or an error code (typically CIF_ERROR) on failure