January 21, 2008 PROP_INGEST 3

### NAME

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

```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 specifed 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 property container object library first appeared in NetBSD4.0.