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 SYNOPSIS 43.In libprop/proplib.h 44.Ft prop_ingest_context_t 45.Fn prop_ingest_context_alloc "void *private" 46.Ft void 47.Fn prop_ingest_context_free "prop_ingest_context_t ctx" 48.Ft prop_ingest_error_t 49.Fn prop_ingest_context_error "prop_ingest_context_t ctx" 50.Ft prop_type_t 51.Fn prop_ingest_context_type "prop_ingest_context_t ctx" 52.Ft const char * 53.Fn prop_ingest_context_key "prop_ingest_context_t ctx" 54.Ft void * 55.Fn prop_ingest_context_private "prop_ingest_context_t ctx" 56.Ft bool 57.Fn prop_dictionary_ingest "prop_dictionary_t dict" \ 58 "const prop_ingest_table_entry rules[]" \ 59 "prop_ingest_context_t ctx" 60.Pp 61.Ft typedef bool 62.Fn (*prop_ingest_handler_t) "prop_ingest_context_t" "prop_object_t" 63.Sh DESCRIPTION 64The 65.Nm prop_dictionary_ingest 66function provides a convenient way to convert a property list into 67an arbitrary binary format or to extract values from dictionaries in a 68way that is convenient to an application 69.Pq for configuration files, for example . 70.Pp 71.Nm prop_dictionary_ingest 72is driven by a table of rules provided by the application. 73Each rule consists of three items: 74.Bl -bullet 75.It 76A C string containing a key to be looked up in the dictionary. 77.It 78The expected property type of the object associated with the key 79(or 80.Dv PROP_TYPE_UNKNOWN 81to specify that any type is allowed). 82.It 83A callback function of type 84.Dv prop_ingest_handler_t 85that will perform the translation for the application. 86.El 87.Pp 88The table is constructed using a series of macros as follows: 89.Bd -literal 90static const prop_ingest_table_entry ingest_rules[] = { 91 PROP_INGEST("file-name", PROP_TYPE_STRING, ingest_filename), 92 PROP_INGEST("count", PROP_TYPE_NUMBER, ingest_count), 93 PROP_INGEST_OPTIONAL("required", PROP_TYPE_BOOL, ingest_required), 94 PROP_INGEST_OPTIONAL("extra", PROP_TYPE_UNKNOWN, ingest_extra), 95 PROP_INGEST_END 96}; 97.Ed 98.Pp 99The 100.Dv PROP_INGEST 101macro specifies that the key is required to be present in the dictionary. 102The 103.Dv PROP_INGEST_OPTIONAL 104macro specifies that the presence of the key in the dictionary is optional. 105The 106.Dv PROP_INGEST_END 107macro marks the end of the rules table. 108.Pp 109In each case, 110.Nm prop_dictionary_ingest 111looks up the rule's key in the dictionary. 112If an object is present in the dictionary at that key, its type is checked 113against the type specified in the rule. 114A type specification of 115.Dv PROP_TYPE_UNKNOWN 116allows the object to be of any type. 117If the object does not exist and the rule is not marked as optional, then 118an error is returned. 119Otherwise, the handler specified in the rule is invoked with the ingest 120context and the object 121(or 122.Dv NULL 123if the key does not exist in the dictionary). 124The handler should return 125.Dv false 126if the value of the object is invalid to indicate failure and 127.Dv true 128otherwise. 129.Pp 130The ingest context contains several pieces of information that are 131useful during the ingest process. 132The context also provides specific error information should the ingest 133fail. 134.Bl -tag -width "xxxxx" 135.It Fn prop_ingest_context_alloc "void *private" 136Allocate an ingest context. 137The argument 138.Fa private 139may be used to pass application-specific context to the ingest handlers. 140Note that an ingest context can be re-used to perform multiple ingests. 141Returns 142.Dv NULL 143on failure. 144.It Fn prop_ingest_context_free "prop_ingest_context_t ctx" 145Free an ingest context. 146.It Fn prop_ingest_context_error "prop_ingest_context_t ctx" 147Returns the code indicating the error encountered during ingest. 148The following error codes are defined: 149.Pp 150.Bl -tag -width "PROP_INGEST_ERROR_HANDLER_FAILED" -compact 151.It Dv PROP_INGEST_ERROR_NO_ERROR 152No error was encountered during ingest. 153.It Dv PROP_INGEST_ERROR_NO_KEY 154A non-optional key was not found in the dictionary. 155.It Dv PROP_INGEST_ERROR_WRONG_TYPE 156An object in the dictionary was not the same type specified in the rules. 157.It Dv PROP_INGEST_ERROR_HANDLER_FAILED 158An object's handler returned 159.Dv false . 160.El 161.Pp 162.It Fn prop_ingest_context_type "prop_ingest_context_t ctx" 163Returns the type of the last object visited during an ingest. 164When called by an ingest handler, it returns the type of the object 165currently being processed. 166.It Fn prop_ingest_context_key "prop_ingest_context_t ctx" 167Returns the last dictionary key looked up during an ingest. 168When called by an ingest handler, it returns the dictionary key corresponding 169to the object currently being processed. 170.It Fn prop_ingest_context_private "prop_ingest_context_t ctx" 171Returns the private data set when the context was allocated with 172.Fn prop_ingest_context_alloc . 173.El 174.Sh SEE ALSO 175.Xr prop_dictionary 3 , 176.Xr proplib 3 177.Sh HISTORY 178The 179.Nm proplib 180property container object library first appeared in 181.Nx 4.0 . 182