1.\" $NetBSD: prop_ingest.3,v 1.5 2008/04/30 13:10:46 martin Exp $ 2.\" 3.\" Copyright (c) 2006 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 21, 2008 31.Dt PROP_INGEST 3 32.Os 33.Sh NAME 34.Nm prop_ingest_context_alloc , 35.Nm prop_ingest_context_free , 36.Nm prop_ingest_context_error , 37.Nm prop_ingest_context_type , 38.Nm prop_ingest_context_key , 39.Nm prop_ingest_context_private , 40.Nm prop_dictionary_ingest 41.Nd Ingest a dictionary into an arbitrary binary format 42.Sh LIBRARY 43.Lb libprop 44.Sh SYNOPSIS 45.In libprop/proplib.h 46.Ft prop_ingest_context_t 47.Fn prop_ingest_context_alloc "void *private" 48.Ft void 49.Fn prop_ingest_context_free "prop_ingest_context_t ctx" 50.Ft prop_ingest_error_t 51.Fn prop_ingest_context_error "prop_ingest_context_t ctx" 52.Ft prop_type_t 53.Fn prop_ingest_context_type "prop_ingest_context_t ctx" 54.Ft const char * 55.Fn prop_ingest_context_key "prop_ingest_context_t ctx" 56.Ft void * 57.Fn prop_ingest_context_private "prop_ingest_context_t ctx" 58.Ft bool 59.Fn prop_dictionary_ingest "prop_dictionary_t dict" \ 60 "const prop_ingest_table_entry rules[]" \ 61 "prop_ingest_context_t ctx" 62.Pp 63.Ft typedef bool 64.Fn (*prop_ingest_handler_t) "prop_ingest_context_t" "prop_object_t" 65.Sh DESCRIPTION 66The 67.Nm prop_dictionary_ingest 68function provides a convenient way to convert a property list into 69an arbitrary binary format or to extract values from dictionaries in a 70way that is convenient to an application 71.Pq for configuration files, for example . 72.Pp 73.Nm prop_dictionary_ingest 74is driven by a table of rules provided by the application. 75Each rule consists of three items: 76.Bl -bullet 77.It 78A C string containing a key to be looked up in the dictionary. 79.It 80The expected property type of the object associated with the key 81(or 82.Dv PROP_TYPE_UNKNOWN 83to specify that any type is allowed). 84.It 85A callback function of type 86.Dv prop_ingest_handler_t 87that will perform the translation for the application. 88.El 89.Pp 90The table is constructed using a series of macros as follows: 91.Bd -literal 92static const prop_ingest_table_entry ingest_rules[] = { 93 PROP_INGEST("file-name", PROP_TYPE_STRING, ingest_filename), 94 PROP_INGEST("count", PROP_TYPE_NUMBER, ingest_count), 95 PROP_INGEST_OPTIONAL("required", PROP_TYPE_BOOL, ingest_required), 96 PROP_INGEST_OPTIONAL("extra", PROP_TYPE_UNKNOWN, ingest_extra), 97 PROP_INGEST_END 98}; 99.Ed 100.Pp 101The 102.Dv PROP_INGEST 103macro specifies that the key is required to be present in the dictionary. 104The 105.Dv PROP_INGEST_OPTIONAL 106macro specifies that the presence of the key in the dictionary is optional. 107The 108.Dv PROP_INGEST_END 109macro marks the end of the rules table. 110.Pp 111In each case, 112.Nm prop_dictionary_ingest 113looks up the rule's key in the dictionary. 114If an object is present in the dictionary at that key, its type is checked 115against the type specified in the rule. 116A type specification of 117.Dv PROP_TYPE_UNKNOWN 118allows the object to be of any type. 119If the object does not exist and the rule is not marked as optional, then 120an error is returned. 121Otherwise, the handler specified in the rule is invoked with the ingest 122context and the object 123(or 124.Dv NULL 125if the key does not exist in the dictionary). 126The handler should return 127.Dv false 128if the value of the object is invalid to indicate failure and 129.Dv true 130otherwise. 131.Pp 132The ingest context contains several pieces of information that are 133useful during the ingest process. 134The context also provides specific error information should the ingest 135fail. 136.Bl -tag -width "xxxxx" 137.It Fn prop_ingest_context_alloc "void *private" 138Allocate an ingest context. 139The argument 140.Fa private 141may be used to pass application-specific context to the ingest handlers. 142Note that an ingest context can be re-used to perform multiple ingests. 143Returns 144.Dv NULL 145on failure. 146.It Fn prop_ingest_context_free "prop_ingest_context_t ctx" 147Free an ingest context. 148.It Fn prop_ingest_context_error "prop_ingest_context_t ctx" 149Returns the code indicating the error encountered during ingest. 150The following error codes are defined: 151.Pp 152.Bl -tag -width "PROP_INGEST_ERROR_HANDLER_FAILED" -compact 153.It Dv PROP_INGEST_ERROR_NO_ERROR 154No error was encountered during ingest. 155.It Dv PROP_INGEST_ERROR_NO_KEY 156A non-optional key was not found in the dictionary. 157.It Dv PROP_INGEST_ERROR_WRONG_TYPE 158An object in the dictionary was not the same type specified in the rules. 159.It Dv PROP_INGEST_ERROR_HANDLER_FAILED 160An object's handler returned 161.Dv false . 162.El 163.It Fn prop_ingest_context_type "prop_ingest_context_t ctx" 164Returns the type of the last object visited during an ingest. 165When called by an ingest handler, it returns the type of the object 166currently being processed. 167.It Fn prop_ingest_context_key "prop_ingest_context_t ctx" 168Returns the last dictionary key looked up during an ingest. 169When called by an ingest handler, it returns the dictionary key corresponding 170to the object currently being processed. 171.It Fn prop_ingest_context_private "prop_ingest_context_t ctx" 172Returns the private data set when the context was allocated with 173.Fn prop_ingest_context_alloc . 174.El 175.Sh SEE ALSO 176.Xr prop_dictionary 3 , 177.Xr proplib 3 178.Sh HISTORY 179The 180.Nm proplib 181property container object library first appeared in 182.Nx 4.0 . 183