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