cif_handler_s Struct Reference
[Data types]

A set of functions defining a handler interface for directing and taking appropriate action in response to a traversal of a CIF. More...

#include <cif.h>

Data Fields
int(*	handle_cif_start )(cif_tp *cif, void *context)
	A handler function for the beginning of a top-level CIF object.
int(*	handle_cif_end )(cif_tp *cif, void *context)
	A handler function for the end of a top-level CIF object.
int(*	handle_block_start )(cif_container_tp *block, void *context)
	A handler function for the beginning of a data block.
int(*	handle_block_end )(cif_container_tp *block, void *context)
	A handler function for the end of a data block.
int(*	handle_frame_start )(cif_container_tp *frame, void *context)
	A handler function for the beginning of a save frame.
int(*	handle_frame_end )(cif_container_tp *frame, void *context)
	A handler function for the end of a save frame.
int(*	handle_loop_start )(cif_loop_tp *loop, void *context)
	A handler function for the beginning of a loop.
int(*	handle_loop_end )(cif_loop_tp *loop, void *context)
	A handler function for the end of a loop.
int(*	handle_packet_start )(cif_packet_tp *packet, void *context)
	A handler function for the beginning of a loop packet.
int(*	handle_packet_end )(cif_packet_tp *packet, void *context)
	A handler function for the end of a loop packet.
int(*	handle_item )(UChar *name, cif_value_tp *value, void *context)
	A handler function for data items (there are not separate beginning and end callbacks). If called with a NULL name then value is a placeholder -- this normally happens only in a parsing context, when a duplicate data name is enrolled in a loop.

---

Detailed Description

A set of functions defining a handler interface for directing and taking appropriate action in response to a traversal of a CIF.

Each structural element of the CIF being traversed will be presented to the appropriate handler function, along with the appropriate context object, if any. When traversal is performed via the cif_walk() function, the context object is the one passed to cif_walk() by its caller. The handler may perform any action it considers suitable, and it is expected to return a code influencing the traversal path, one of:

• CIF_TRAVERSE_CONTINUE for the walker to continue on its default path (for instance, to descend to the current element's first child), or
• CIF_TRAVERSE_SKIP_CURRENT for the walker to skip traversal of the current element's children, if any, and the current element itself if possible (meaningfully distinct from CIF_TRAVERSE_CONTINUE only for the *_start callbacks), or
• CIF_TRAVERSE_SKIP_SIBLINGS for the walker to skip the current element if possible, its children, and all its siblings that have not yet been traversed, or
• CIF_TRAVERSE_END for the walker to stop without traversing any more elements

A handler function may, alternatively, return a CIF API error code, which has the effect of CIF_TRAVERSE_END plus additional semantics specific to the traversal function (cif_walk() forwards the code to its caller as its return value).