Data container general functions

Functions
int	cif_container_create_frame (cif_container_tp container, const UChar code, cif_frame_tp **frame)
	Creates a new save frame bearing the specified frame code in the specified container.
void	cif_container_free (cif_container_tp *container)
	Frees any resources associated with the specified container handle without modifying the associated managed CIF.
int	cif_container_destroy (cif_container_tp *container)
	Frees any resources associated with the specified container handle, and furthermore removes the associated container and all its contents from its managed CIF.
int	cif_container_get_frame (cif_container_tp container, const UChar code, cif_frame_tp **frame)
	Looks up and optionally returns the save frame bearing the specified code, if any, in the specified data block or save frame.
int	cif_container_get_all_frames (cif_container_tp container, cif_frame_tp **frames)
	Provides a null-terminated array of save frame handles, one for each frame in the specified data block or save frame.
int	cif_container_get_code (cif_container_tp container, UChar *code)
	Retrieves the identifying code (block code or frame code) of the specified container.
int	cif_container_assert_block (cif_container_tp *container)
	Asserts that the specified container represents a data block, as opposed to a save frame.
int	cif_container_create_loop (cif_container_tp container, const UChar category, UChar names[], cif_loop_tp *loop)
	Creates a new loop in the specified container, and optionally returns a handle on it.
int	cif_container_get_category_loop (cif_container_tp container, const UChar category, cif_loop_tp **loop)
	Looks up the loop in the specified container that is assigned to the specified category.
int	cif_container_get_item_loop (cif_container_tp container, const UChar item_name, cif_loop_tp **loop)
	Looks up the loop in the specified container that contains the specified item, and optionally returns a handle on it.
int	cif_container_get_all_loops (cif_container_tp container, cif_loop_tp **loops)
	Provides a null-terminated array of loop handles, one for each loop in the specified container.
int	cif_container_prune (cif_container_tp *container)
	Removes all data-less loops from the specified container.
int	cif_container_get_value (cif_container_tp container, const UChar item_name, cif_value_tp **val)
	Looks up an item by name in a data block or save frame, and optionally returns (one of) its value(s).
int	cif_container_set_value (cif_container_tp container, const UChar item_name, cif_value_tp *val)
	Sets the value of the specified item in the specified container, or adds it as a scalar if it's not already present in the container.
int	cif_container_remove_item (cif_container_tp container, const UChar item_name)
	Removes the specified item and all its values from the specified container.

Function Documentation

int cif_container_assert_block ( cif_container_tp * container )

Asserts that the specified container represents a data block, as opposed to a save frame.

Parameters:

[in] container a handle on the container that is asserted to be a data block

Returns:: CIF_OK if the container is a data block, CIF_ARGUMENT_ERROR if it is a save frame, or CIF_ERROR if it is NULL

int cif_container_create_frame	(	cif_container_tp *	container,
		const UChar *	code,
		cif_frame_tp **	frame
	)

Creates a new save frame bearing the specified frame code in the specified container.

This function can optionally return a handle on the new frame via the frame 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 frame from the managed CIF).

Note that this function exhibits an extension to the CIF 2.0 data model in that CIF 2.0 does not permit save frames to contain other save frames, whereas this function will happily create just such nested frames if asked to do so.

Parameters:

`[in]`	container	a handle on the managed data block (or save frame) object to which a new block should be added; must be non-NULL and valid.
`[in]`	code	the frame code of the frame to add, as a NUL-terminated Unicode string; the frame code must comply with CIF constraints on frame codes.
`[in,out]`	frame	if not NULL, then a location where a handle on the new frame should be recorded.

Returns:

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

CIF_INVALID_FRAMECODE if the provided frame code is invalid
CIF_DUP_FRAMECODE if the specified data block already contains a frame having the given code (note that frame codes are compared in a Unicode-normalized and caseless form)
CIF_ERROR for most other failures

int cif_container_create_loop	(	cif_container_tp *	container,
		const UChar *	category,
		UChar *	names[],
		cif_loop_tp **	loop
	)

Creates a new loop in the specified container, and optionally returns a handle on it.

There must be at least one item name, and all item names given must initially be absent from the container. All item names must be valid, per the CIF specifications.

The category name may be NULL, in which case the loop has no explicit category, but the empty category name is reserved for the loop containing all the scalar data in the container. The preprocessor macro CIF_SCALARS expands to that category name; it is provided to make the meaning clearer. Other categories are not required to be unique, but they are less useful when there are duplicates in the same container.

New loops initially contain zero packets, which is acceptable only as a transient state.

Parameters:

`[in]`	container	a handle on the container in which to create a loop.
`[in]`	category	the loop's category, as a NUL-terminated Unicode string. May be NULL.
`[in]`	names	an array of pointers to the item names that should appear in the loop, as NUL-terminated Unicode strings, with the end of the list indicated by a NULL pointer; ownership of the array and its contents does not transfer
`[in,out]`	loop	if not NULL, points to the location where a handle on the newly-created loop should be recorded.

Returns:

Returns CIF_OK on success, or an error code on failure, among them:

CIF_NULL_LOOP if an empty list of item names is specified
CIF_INVALID_ITEMNAME if one or more of the provided item names does not satisfy CIF's criteria
CIF_DUP_ITEMNAME if one or more of the item names is already present in the target container
CIF_ERROR in most other failure cases

int cif_container_destroy ( cif_container_tp * container )

Frees any resources associated with the specified container handle, and furthermore removes the associated container and all its contents from its managed CIF.

Parameters:

[in,out] container a handle on the container to destroy; must be non-NULL and valid on entry, but is invalidated by this function

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

void cif_container_free ( cif_container_tp * container )

Frees any resources associated with the specified container handle without modifying the associated managed CIF.

Parameters:

[in] container a handle on the container object to free; must be non-NULL and valid on entry, but is invalidated by this function

int cif_container_get_all_frames	(	cif_container_tp *	container,
		cif_frame_tp ***	frames
	)

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

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

Parameters:

`[in]`	container	a handle on the managed data block or save frame object from which to draw save frame handles; must be non-NULL and valid.
`[in,out]`	frames	a pointer to the location where a pointer to the resulting array of frame handles should be recorded. Must not be NULL.

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

int cif_container_get_all_loops	(	cif_container_tp *	container,
		cif_loop_tp ***	loops
	)

Provides a null-terminated array of loop handles, one for each loop in the specified container.

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

Parameters:

`[in]`	container	a handle on the managed container object from which to draw loop handles; must be non-NULL and valid.
`[in,out]`	loops	a pointer to the location where a pointer to the resulting array of loop handles should be recorded. Must not be NULL.

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

int cif_container_get_category_loop	(	cif_container_tp *	container,
		const UChar *	category,
		cif_loop_tp **	loop
	)

Looks up the loop in the specified container that is assigned to the specified category.

Unlike block code, frame code, or item name lookup, category lookup works by exact, character-by-character matching.

Parameters:

`[in]`	container	a handle on the data block or save frame in which to look for a loop, must be non-NULL and valid
`[in]`	category	the category to look up, as a NUL-terminated Unicode string; must not be NULL
`[in,out]`	loop	if not NULL, the location where a handle on the discovered loop, if any, should be written; in that case, the caller is responsible for cleaning up the returned handle

Returns:

a status code indicating the nature of the result:

CIF_OK if a single matching loop was found; only in this case can a handle be returned
CIF_INVALID_CATEGORY if the specified category name is invalid (primarily, if it is NULL)
CIF_NOSUCH_LOOP if no loop having the specified category is found
CIF_CAT_NOT_UNIQUE if multiple loops having the specified category are found
CIF_ERROR in most other cases

int cif_container_get_code	(	cif_container_tp *	container,
		UChar **	code
	)

Retrieves the identifying code (block code or frame code) of the specified container.

Responsibility for cleaning up the block or frame codes retrieved via this function belongs to the caller.

Parameters:

`[in]`	container	a handle on the container whose code is requested
`[in,out]`	code	a pointer to the location where a pointer to a NUL-terminated Unicode string containing the requested code should be recorded

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

int cif_container_get_frame	(	cif_container_tp *	container,
		const UChar *	code,
		cif_frame_tp **	frame
	)

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

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

Parameters:

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

Returns:: CIF_OK on a successful lookup (even if frame is NULL), CIF_NOSUCH_FRAME if there is no save frame bearing the given code in the given CIF, or an error code (typically CIF_ERROR ) if an error occurs.

int cif_container_get_item_loop	(	cif_container_tp *	container,
		const UChar *	item_name,
		cif_loop_tp **	loop
	)

Looks up the loop in the specified container that contains the specified item, and optionally returns a handle on it.

Note that in the underlying data model, all items belong to loops. To determine whether an item is logically a scalar, either count the packets in its loop, or check whether the loop's category is CIF_SCALARS (depending on what, exactly, you mean by "scalar").

Parameters:

`[in]`	container	a handle on the container in which to look up the item's loop
`[in]`	item_name	the item name to look up, as a NUL-terminated Unicode string. Matching is performed via a caseless, Unicode-normalized algorithm.
`[in,out]`	loop	if not NULL, the location where a handle on the discovered loop, if any, is written

Returns:

Returns a status code indicating the nature of the result:

CIF_OK if the item was found; only in this case can a handle be returned
CIF_NOSUCH_ITEM if the item is not present in the container
CIF_ERROR in most other cases The return code does not depend on whether loop is NULL.

int cif_container_get_value	(	cif_container_tp *	container,
		const UChar *	item_name,
		cif_value_tp **	val
	)

Looks up an item by name in a data block or save frame, and optionally returns (one of) its value(s).

The return value indicates whether the item is present with a single value (CIF_OK), present with multiple values (CIF_AMBIGUOUS_ITEM), or absent (CIF_NOSUCH_ITEM). Being present in a zero-packet loop is treated the same as being absent altogether. If there are any values for the item and the val parameter is non-NULL, then one of the values is returned via val. Name matching is performed via a caseless, Unicode-normalized algorithm, and invalid names are handled as absent.

Parameters:

`[in]`	container	a handle on the data block or save frame in which to look up the item; must be non-NULL and valid
`[in]`	item_name	the name of the item to look up, as a NUL-terminated Unicode string; must not be NULL
`[in,out]`	val	if non-NULL then the location where a pointer to (one of) the item's value(s) should be written. If a non-NULL pointer is already at the referenced location then its contents are cleaned as if by `cif_value_clean()` and then overwritten; otherwise a new value object is created and a pointer to it provided.

Returns:: Returns a result code as described above, or CIF_ERROR if an error occurs

int cif_container_prune ( cif_container_tp * container )

Removes all data-less loops from the specified container.

The cif_container_create_loop() function creates loops that initially contain no data (which is intended to be a transitory state), and it is possible via the packet iterator interface to remove all packets from a previously non-empty loop. The CIF data model does not accommodate loops without data, so by whatever path they are introduced, empty loops must be removed or filled in order to achieve a valid CIF. This convenience function serves that purpose by efficiently removing all empty loops belonging directly to the specified container.

Parameters:

[in] container a handle on the data block or save frame from which to prune empty loops

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

int cif_container_remove_item	(	cif_container_tp *	container,
		const UChar *	item_name
	)

Removes the specified item and all its values from the specified container.

If the removed item was the last in its loop, then the whole loop is removed, invalidating any outstanding handle on it.

Parameters:

`[in]`	container	a handle on the container from which to remove the item
`[in]`	item_name	the name of the item to set, as a NUL-terminated Unicode string; must not be NULL

Returns:: Returns CIF_OK if the item was successfully removed, CIF_NOSUCH_ITEM if it was not present in the container, or an error code (typically CIF_ERROR ) on failure

int cif_container_set_value	(	cif_container_tp *	container,
		const UChar *	item_name,
		cif_value_tp *	val
	)

Sets the value of the specified item in the specified container, or adds it as a scalar if it's not already present in the container.

The given value is set for the item in every packet of the loop to which it belongs. To set a value in just one packet of a multi-packet loop, use a packet iterator. Note that zero-packet loops are no exception: if an item belongs to a zero-packet loop, then setting its value(s) via this method updates all zero packets for no net effect.

Parameters:

`[in]`	container	a handle on the container to modify; must be non-NULL and valid
`[in]`	item_name	the name of the item to set, as a NUL-terminated Unicode string; must be a valid item name
`[in]`	val	a pointer to the value to set for the specified item; if NULL then a value of kind `CIF_UNK_KIND` is set

Returns:: CIF_OK on success, CIF_INVALID_ITEMNAME if the item name is invalid, or another error code (typically CIF_ERROR ) on failure

Data container general functions

Functions

Function Documentation