1/*
2 * Copyright 2016-2018 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 BeOS R4
86*/
87
88
89/*!
90	\var property_info::ctypes
91	\brief Type chunks?
92
93		\since BeOS R4
94*/
95
96
97/*!
98	\var property_info::_reserved
99	\brief Reserved for future expansion, do not use.
100
101	\since BeOS R5
102*/
103
104
105/*!
106	\enum value_kind
107	\brief Enumerates value types.
108
109	\since BeOS R4
110*/
111
112
113/*!
114	\var value_kind B_COMMAND_KIND
115	\brief Command value.
116
117	\since BeOS R4
118*/
119
120
121/*!
122	\var value_kind B_TYPE_CODE_KIND
123	\brief Type code value.
124
125	\since BeOS R4
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 R4
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 BeOS R4
256*/
257
258
259/*!
260	\fn int32 BPropertyInfo::CountProperties() const
261	\brief Returns The number of properties specified as an int32.
262
263	\since BeOS R4
264*/
265
266
267/*!
268	\fn int32 BPropertyInfo::CountValues() const
269	\brief Returns The number of values specified as an int32.
270
271	\since BeOS R4
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 BeOS R4
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 BeOS R4
308*/
309