NAME
prop_ingest,
prop_ingest_context_alloc,
prop_ingest_context_free,
prop_ingest_context_error,
prop_ingest_context_type,
prop_ingest_context_key,
prop_ingest_context_private,
prop_dictionary_ingest —
Ingest a
dictionary into an arbitrary binary format
SYNOPSIS
#include <prop/proplib.h>
prop_ingest_context_t
prop_ingest_context_alloc(
void
*private);
void
prop_ingest_context_free(
prop_ingest_context_t
ctx);
prop_ingest_error_t
prop_ingest_context_error(
prop_ingest_context_t
ctx);
prop_type_t
prop_ingest_context_type(
prop_ingest_context_t
ctx);
const char *
prop_ingest_context_key(
prop_ingest_context_t
ctx);
void *
prop_ingest_context_private(
prop_ingest_context_t
ctx);
bool
prop_dictionary_ingest(
prop_dictionary_t
dict,
const
prop_ingest_table_entry rules[],
prop_ingest_context_t ctx);
typedef bool
(*prop_ingest_handler_t)(
prop_ingest_context_t,
prop_object_t);
DESCRIPTION
The
prop_dictionary_ingest() function provides a convenient
way to convert a property list into an arbitrary binary format or to extract
values from dictionaries in a way that is convenient to an application (for
configuration files, for example).
prop_dictionary_ingest() is driven by a table of rules
provided by the application. Each rule consists of three items:
- A C string containing a key to be looked up in the
dictionary.
- The expected property type of the object associated with
the key (or
PROP_TYPE_UNKNOWN
to specify that any
type is allowed).
- A callback function of type
prop_ingest_handler_t
that will perform the
translation for the application.
The table is constructed using a series of macros as follows:
static const prop_ingest_table_entry ingest_rules[] = {
PROP_INGEST("file-name", PROP_TYPE_STRING, ingest_filename),
PROP_INGEST("count", PROP_TYPE_NUMBER, ingest_count),
PROP_INGEST_OPTIONAL("required", PROP_TYPE_BOOL, ingest_required),
PROP_INGEST_OPTIONAL("extra", PROP_TYPE_UNKNOWN, ingest_extra),
PROP_INGEST_END
};
The
PROP_INGEST
macro specifies that the key is required
to be present in the dictionary. The
PROP_INGEST_OPTIONAL
macro specifies that the presence
of the key in the dictionary is optional. The
PROP_INGEST_END
macro marks the end of the rules
table.
In each case,
prop_dictionary_ingest() looks up the rule's key
in the dictionary. If an object is present in the dictionary at that key, its
type is checked against the type specified in the rule. A type specification
of
PROP_TYPE_UNKNOWN
allows the object to be of any
type. If the object does not exist and the rule is not marked as optional,
then an error is returned. Otherwise, the handler specified in the rule is
invoked with the ingest context and the object (or
NULL
if the key does not exist in the dictionary). The
handler should return
false
if the value of the object
is invalid to indicate failure and
true
otherwise.
The ingest context contains several pieces of information that are useful during
the ingest process. The context also provides specific error information
should the ingest fail.
-
-
- prop_ingest_context_alloc(void
*private)
- Allocate an ingest context. The argument
private may be used to pass application-specific
context to the ingest handlers. Note that an ingest context can be re-used
to perform multiple ingests. Returns
NULL
on
failure.
-
-
- prop_ingest_context_free(prop_ingest_context_t
ctx)
- Free an ingest context.
-
-
- prop_ingest_context_error(prop_ingest_context_t
ctx)
- Returns the code indicating the error encountered during
ingest. The following error codes are defined:
PROP_INGEST_ERROR_NO_ERROR
- No error was encountered during ingest.
PROP_INGEST_ERROR_NO_KEY
- A non-optional key was not found in the
dictionary.
PROP_INGEST_ERROR_WRONG_TYPE
- An object in the dictionary was not the same type
specified in the rules.
PROP_INGEST_ERROR_HANDLER_FAILED
- An object's handler returned
false
.
-
-
- prop_ingest_context_type(prop_ingest_context_t
ctx)
- Returns the type of the last object visited during an
ingest. When called by an ingest handler, it returns the type of the
object currently being processed.
-
-
- prop_ingest_context_key(prop_ingest_context_t
ctx)
- Returns the last dictionary key looked up during an ingest.
When called by an ingest handler, it returns the dictionary key
corresponding to the object currently being processed.
-
-
- prop_ingest_context_private(prop_ingest_context_t
ctx)
- Returns the private data set when the context was allocated
with prop_ingest_context_alloc().
SEE ALSO
prop_dictionary(3),
proplib(3)
HISTORY
The
proplib(3) property container
object library first appeared in
NetBSD 4.0.