common/lib/libprop/prop_object.3

   1 .\"     $NetBSD: prop_object.3,v 1.8 2011/01/20 10:44:42 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 .\"
  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 August 21, 2006
  31 .Dt PROP_OBJECT 3
  32 .Os
  33 .Sh NAME
  34 .Nm prop_object ,
  35 .Nm prop_object_retain ,
  36 .Nm prop_object_release ,
  37 .Nm prop_object_type ,
  38 .Nm prop_object_equals ,
  39 .Nm prop_object_iterator_next ,
  40 .Nm prop_object_iterator_reset ,
  41 .Nm prop_object_iterator_release
  42 .Nd general property container object functions
  43 .Sh LIBRARY
  44 .Lb libprop
  45 .Sh SYNOPSIS
  46 .In prop/proplib.h
  47 .\"
  48 .Ft void
  49 .Fn prop_object_retain "prop_object_t obj"
  50 .Ft void
  51 .Fn prop_object_release "prop_object_t obj"
  52 .\"
  53 .Ft prop_type_t
  54 .Fn prop_object_type "prop_object_t obj"
  55 .Ft bool
  56 .Fn prop_object_equals "prop_object_t obj1" "prop_object_t obj2"
  57 .\"
  58 .Ft prop_object_t
  59 .Fn prop_object_iterator_next "prop_object_iterator_t iter"
  60 .Ft void
  61 .Fn prop_object_iterator_reset "prop_object_iterator_t iter"
  62 .Ft void
  63 .Fn prop_object_iterator_release "prop_object_iterator_t iter"
  64 .Sh DESCRIPTION
  65 The
  66 .Nm prop_object
  67 family of functions operate on all property container object types.
  68 .Bl -tag -width ""
  69 .It Fn prop_object_retain "prop_object_t obj"
  70 Increment the reference count on an object.
  71 .It Fn prop_object_release "prop_object_t obj"
  72 Decrement the reference count on an object.
  73 If the last reference is dropped, the object is freed.
  74 .It Fn prop_object_type "prop_object_t obj"
  75 Determine the type of the object.
  76 Objects are one of the following types:
  77 .Pp
  78 .Bl -tag -width "PROP_TYPE_DICT_KEYSYM" -compact
  79 .It Dv PROP_TYPE_BOOL
  80 Boolean value
  81 .Pq prop_bool_t
  82 .It Dv PROP_TYPE_NUMBER
  83 Number
  84 .Pq prop_number_t
  85 .It Dv PROP_TYPE_STRING
  86 String
  87 .Pq prop_string_t
  88 .It Dv PROP_TYPE_DATA
  89 Opaque data
  90 .Pq prop_data_t
  91 .It Dv PROP_TYPE_ARRAY
  92 Array
  93 .Pq prop_array_t
  94 .It Dv PROP_TYPE_DICTIONARY
  95 Dictionary
  96 .Pq prop_dictionary_t
  97 .It Dv PROP_TYPE_DICT_KEYSYM
  98 Dictionary key symbol
  99 .Pq prop_dictionary_keysym_t
 100 .El
 101 .Pp
 102 If
 103 .Fa obj
 104 is
 105 .Dv NULL ,
 106 then
 107 .Dv PROP_TYPE_UNKNOWN
 108 is returned.
 109 .It Fn prop_object_equals "prop_object_t obj1" "prop_object_t obj2"
 110 Returns
 111 .Dv true
 112 if the two objects are of the same type and are equivalent.
 113 .It Fn prop_object_iterator_next "prop_object_iterator_t iter"
 114 Return the next object in the collection
 115 .Pq array or dictionary
 116 being iterated by the iterator
 117 .Fa iter .
 118 If there are no more objects in the collection,
 119 .Dv NULL
 120 is returned.
 121 .It Fn prop_object_iterator_reset "prop_object_iterator_t iter"
 122 Reset the iterator to the first object in the collection being iterated
 123 by the iterator
 124 .Fa iter .
 125 .It Fn prop_object_iterator_release "prop_object_iterator_t iter"
 126 Release the iterator
 127 .Fa iter .
 128 .El
 129 .Sh SEE ALSO
 130 .Xr prop_array 3 ,
 131 .Xr prop_bool 3 ,
 132 .Xr prop_data 3 ,
 133 .Xr prop_dictionary 3 ,
 134 .Xr prop_number 3 ,
 135 .Xr prop_string 3 ,
 136 .Xr proplib 3
 137 .Sh HISTORY
 138 The
 139 .Nm proplib
 140 property container object library first appeared in
 141 .Nx 4.0 .