common/lib/libprop/prop_object.3

   1 .\"     $NetBSD: prop_object.3,v 1.7 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 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.  Objects are one of the following types:
  76 .Pp
  77 .Bl -tag -width "PROP_TYPE_DICT_KEYSYM" -compact
  78 .It Dv PROP_TYPE_BOOL
  79 Boolean value
  80 .Pq prop_bool_t
  81 .It Dv PROP_TYPE_NUMBER
  82 Number
  83 .Pq prop_number_t
  84 .It Dv PROP_TYPE_STRING
  85 String
  86 .Pq prop_string_t
  87 .It Dv PROP_TYPE_DATA
  88 Opaque data
  89 .Pq prop_data_t
  90 .It Dv PROP_TYPE_ARRAY
  91 Array
  92 .Pq prop_array_t
  93 .It Dv PROP_TYPE_DICTIONARY
  94 Dictionary
  95 .Pq prop_dictionary_t
  96 .It Dv PROP_TYPE_DICT_KEYSYM
  97 Dictionary key symbol
  98 .Pq prop_dictionary_keysym_t
  99 .El
 100 .Pp
 101 If
 102 .Fa obj
 103 is
 104 .Dv NULL ,
 105 then
 106 .Dv PROP_TYPE_UNKNOWN
 107 is returned.
 108 .It Fn prop_object_equals "prop_object_t obj1" "prop_object_t obj2"
 109 Returns
 110 .Dv true
 111 if the two objects are of the same type and are equivalent.
 112 .It Fn prop_object_iterator_next "prop_object_iterator_t iter"
 113 Return the next object in the collection
 114 .Pq array or dictionary
 115 being iterated by the iterator
 116 .Fa iter .
 117 If there are no more objects in the collection,
 118 .Dv NULL
 119 is returned.
 120 .It Fn prop_object_iterator_reset "prop_object_iterator_t iter"
 121 Reset the iterator to the first object in the collection being iterated
 122 by the iterator
 123 .Fa iter .
 124 .It Fn prop_object_iterator_release "prop_object_iterator_t iter"
 125 Release the iterator
 126 .Fa iter .
 127 .El
 128 .Sh SEE ALSO
 129 .Xr prop_array 3 ,
 130 .Xr prop_bool 3 ,
 131 .Xr prop_data 3 ,
 132 .Xr prop_dictionary 3 ,
 133 .Xr prop_number 3 ,
 134 .Xr prop_string 3 ,
 135 .Xr proplib 3
 136 .Sh HISTORY
 137 The
 138 .Nm proplib
 139 property container object library first appeared in
 140 .Nx 4.0 .