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