lib/libprop/prop_ingest.3

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