docs/user/app/PropertyInfo.dox

   1 /*
   2  * Copyright 2016 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              John Scipione, jscpione@gmail.com
   7  *
   8  * Corresponds to:
   9  *              headers/os/app/PropertyInfo.h   hrev50253
  10  *              src/kits/app/PropertyInfo.cpp   hrev50253
  11  */
  12
  13
  14 /*!
  15         \file PropertyInfo.h
  16         \ingroup app
  17         \ingroup libbe
  18         \brief Provides the BPropertyInfo class and support structures.
  19 */
  20
  21
  22 /*!
  23         \struct property_info
  24         \ingroup app
  25         \ingroup libbe
  26         \brief Property info struct containing lists of commands and specifiers.
  27
  28         \since BeOS R3
  29 */
  30
  31
  32 /*!
  33         \var property_info::name
  34         \brief The name of the property.
  35
  36         \since BeOS R3
  37 */
  38
  39
  40 /*!
  41         \var property_info::commands
  42         \brief Zero-terminated array of commands understood by the property
  43                e.g. \c B_GET_PROPERTY.
  44
  45         If the first element is 0 it is treated as a wildcard matching all
  46         supported commands.
  47
  48         \since BeOS R3
  49 */
  50
  51
  52 /*!
  53         \var property_info::specifiers
  54         \brief Zero-terminated array of the specifiers understood by the property
  55                e.g. \c B_DIRECT_SPECIFIER.
  56
  57         If the first element is 0 it is treated as a wildcard matching all
  58         supported specifiers.
  59
  60         \since BeOS R3
  61 */
  62
  63
  64 /*!
  65         \var property_info::usage
  66         \brief Human-readable string describing the property and its supported
  67                commands and specifiers.
  68
  69         \since BeOS R3
  70 */
  71
  72
  73 /*!
  74         \var property_info::extra_data
  75         \brief Place to specify freeform data, it is not used by the OS.
  76
  77         \since BeOS R3
  78 */
  79
  80
  81 /*!
  82         \var property_info::types
  83         \brief Type chunks?
  84
  85         \since Haiku R1
  86 */
  87
  88
  89 /*!
  90         \var property_info::ctypes
  91         \brief Type chunks?
  92
  93         \since Haiku R1
  94 */
  95
  96
  97 /*!
  98         \var property_info::_reserved
  99         \brief Reserved for future expansion, do not use.
 100
 101         \since Haiku R1
 102 */
 103
 104
 105 /*!
 106         \enum value_kind
 107         \brief Enumerates value types.
 108
 109         \since Haiku R1
 110 */
 111
 112
 113 /*!
 114         \var value_kind B_COMMAND_KIND
 115         \brief Command value.
 116
 117         \since Haiku R1
 118 */
 119
 120
 121 /*!
 122         \var value_kind B_TYPE_CODE_KIND
 123         \brief Type code value.
 124
 125         \since Haiku R1
 126 */
 127
 128
 129 /*!
 130         \class BPropertyInfo
 131         \ingroup app
 132         \ingroup libbe
 133         \brief Class used to manage scripting.
 134
 135         \since BeOS R3
 136 */
 137
 138
 139
 140 /*!
 141         \fn BPropertyInfo::BPropertyInfo(property_info* propertyInfo,
 142                 value_info* valueInfo, bool freeOnDelete)
 143         \brief Initializes the object with the specified NULL-terminated arrays
 144                \a propertyInfo and \a valueInfo.
 145
 146         The arrays are not copied so do not modify or delete the arrays while
 147         they are in use by BPropertyInfo.
 148
 149         \param propertyInfo The NULL-terminated properties array.
 150         \param valueInfo The NULL-terminated values array.
 151         \param freeOnDelete if \c true, free the memory associated with
 152            \a propertyInfo and \a valueInfo when the object is destroyed.
 153
 154         \since BeOS R3
 155 */
 156
 157
 158 /*!
 159         \fn BPropertyInfo::~BPropertyInfo()
 160         \brief Destructor method.
 161
 162         If \a freeOnDelete is set to \c true in the constructor this method
 163         frees all memory associated with \a propertyInfo and \a valueInfo.
 164
 165         \since BeOS R3
 166 */
 167
 168
 169 /*!
 170         \fn int32 BPropertyInfo::FindMatch(BMessage* message, int32 index,
 171                 BMessage* specifier, int32 form, const char* property, void* data) const
 172
 173         \since BeOS R3
 174 */
 175
 176
 177 /*!
 178         \fn bool BPropertyInfo::IsFixedSize() const
 179         \brief Always returns \c false.
 180
 181         \see BFlattenable::IsFixedSize()
 182
 183         \since BeOS R4
 184 */
 185
 186
 187 /*!
 188         \fn type_code BPropertyInfo::TypeCode() const
 189         \brief Always returns \c B_PROPERTY_INFO_TYPE.
 190
 191         \see BFlattenable::TypeCode()
 192
 193         \since BeOS R4
 194 */
 195
 196
 197 /*!
 198         \fn ssize_t BPropertyInfo::FlattenedSize() const
 199         \brief Returns the size of the flattened object in bytes.
 200
 201         \see BFlattenable::FlattenedSize()
 202
 203         \since BeOS R4
 204 */
 205
 206
 207 /*!
 208         \fn status_t BPropertyInfo::Flatten(void* buffer, ssize_t numBytes) const
 209
 210         \see BFlattenable::Flatten()
 211
 212         \since BeOS R4
 213 */
 214
 215
 216 /*!
 217         \fn bool BPropertyInfo::AllowsTypeCode(type_code code) const
 218         \brief Returns \c true if \a code is B_PROPERTY_INFO_TYPE,
 219                \c false otherwise.
 220
 221         \see BFlattenable::AllowsTypeCode()
 222
 223         \since BeOS R4
 224 */
 225
 226
 227 /*!
 228         \fn status_t BPropertyInfo::Unflatten(type_code code, const void* buffer,
 229                 ssize_t numBytes)
 230
 231         \see BFlattenable::Unflatten()
 232
 233         \since BeOS R4
 234 */
 235
 236
 237 /*!
 238         \fn const property_info* BPropertyInfo::Properties() const
 239         \brief Returns the properties as a \c property_info pointer.
 240
 241         Returns the pointer directly, does not make copy.
 242
 243         Called PropertyInfo() in the BeBook.
 244
 245         \since BeOS R4
 246 */
 247
 248
 249 /*!
 250         \fn const value_info* BPropertyInfo::Values() const
 251         \brief Returns the values as a \c value_info pointer.
 252
 253         Returns the pointer directly, does not make copy.
 254
 255         \since Haiku R1
 256 */
 257
 258
 259 /*!
 260         \fn int32 BPropertyInfo::CountProperties() const
 261         \brief Returns The number of properties specified as an int32.
 262
 263         \since Haiku R1
 264 */
 265
 266
 267 /*!
 268         \fn int32 BPropertyInfo::CountValues() const
 269         \brief Returns The number of values specified as an int32.
 270
 271         \since Haiku R1
 272 */
 273
 274
 275 /*!
 276         \fn void BPropertyInfo::PrintToStream() const
 277         \brief Prints each property, command, type, and specifier to standard
 278                 output.
 279
 280         \since BeOS R4
 281 */
 282
 283
 284 /*!
 285         \fn bool BPropertyInfo::FindCommand(uint32 what, int32 index,
 286                 property_info* propertyInfo)
 287         \brief Find the command inside of \a propertyInfo matching \a what and
 288               \a index.
 289
 290         You may want to override this method in derived classes.
 291
 292         \returns \c true if the command was found, \c false otherwise.
 293
 294         \since Haiku R1
 295 */
 296
 297
 298 /*!
 299         \fn bool BPropertyInfo::FindSpecifier(uint32 form,
 300                 property_info* propertyInfo)
 301         \brief Find the specifier inside of \a propertyInfo matching \a form.
 302
 303         You may want to override this method in derived classes.
 304
 305         \returns \c true if the specifier was found, \c false otherwise.
 306
 307         \since Haiku R1
 308 */