This document describes the BPropertyInfo interface and some basics of how it is implemented. The document has the following sections:
The BPropertyInfo class is a simple class for describing the scripting interface which a BHandler provides. It makes implementing the ResolveSpecifier() hook function easier to implement. One source of information for the BPropertyInfo interface can be found here in the Be Book. Unfortunately, details of some changes to this interface introduced in BeOS 4 does not seem to have made it into the BeBook. For the latest, refer to the PropertyInfo.h header file or the BeOS 4 Developer Release Notes.
The following use cases cover the BPropertyInfo functionality:
Construction 1: A BPropertyInfo can be created with 0 arguments. In this case, it will not have any property_info or value_info structures associated with it. The only way to initialize it would be to Unflatten() a flattened BPropertyInfo instance (see Unflatten use cases).
Construction 2: A BPropertyInfo can be created with a single property_info argument. In this case, there will be no value_info structure associated with it and the BPropertyInfo will assume it does not need to de-allocate the property_info structure itself on destruction.
Construction 3: A BPropertyInfo can be created with a property_info argument and a value_info argument. In this case, the BPropertyInfo will use both of these arguments to determine its future behaviour. It will assume it does not need to de-allocate the property_info structure or the value_info structure itself on destruction.
Construction 4: A BPropertyInfo can be created with a property_info argument and a value_info argument and a flag to indicate whether these structres were allocated on the heap. If the flag is false, it will assume it does not need to de-allocate the property_info structure or the value_info structure itself on destruction. If the flag is true, it will assume that the property_info pointer and the value_info pointer and all pointers contained within them (ie const char * instances) need to be free()'d when the BPropertyInfo is destructed.
Destruction: On destruction, a BPropertyInfo class does nothing unless the third argument (free_on_delete flag) at construction was true. If this argument was true, the BPropertyInfo class performs a "free()" on the pointers passed in at construction time and all pointers contained within these structures.
Properties: The Properties() member function returns the first argument passed in at construction time of the BPropertyInfo or NULL if it was constructed with no arguments.
Values: The Values() member function returns the second argument passed in at construction time of the BPropertyInfo or NULL if it was constructed with one or fewer arguments.
Count Properties: The CountProperties() member function returns the number of elements in the NULL terminated array of property_info structures passed in as the first argument at construction time. If the BPropertyInfo class was constructed with no arguments, 0 is returned.
Count Values: The CountValues() member function returns the number of elements in the NULL terminated array of value_info structures passed in as the second argument at construction time. If the BPropertyInfo class was constructed with one or fewer arguments, 0 is returned.
Fixed Size: The IsFixedSize() method always returns false indicating that a BPropertyInfo class instance can be flattened but the size of that flattened instance depends on the state of the BPropertyInfo class itself.
Type Code: The TypeCode() method always returns B_PROPERTY_INFO_TYPE ('SCTD') regardless of the state of the BPropertyInfo class instance indicating that the flattened instance is of type B_PROPERTY_INFO_TYPE.
Allows Type Code: The AllowsTypeCode() method returns false for all passed in type codes unless B_PROPERTY_INFO_TYPE ('SCTD') is passed in when this method returns true. This implies that a BPropertyInfo class instance can be unflattened from flattened data of B_PROPERTY_INFO_TYPE only (NOTE: the Be implementation seems to return true for all values passed in although that doesn't seem to make much sense).
Flattened Size: The FlattenedSize() member function retures the number of bytes required to store a flattened version of the BPropertyInfo instance. The size will be determined by the description of the flattened data structure described in the "implementation" section below.
Flatten: The Flatten() member function turns the current BPropertyInfo instance into a series of bytes which completely describes its state so it can be recreated from it later. The actual description of this byte representation of BPropertyInfo is described in the "implementation" section below.
Unflatten: The Unflatten() member function takes a passed in series of bytes and sets the current BPropertyInfo instance into a copy of the BPropertyInfo described by those bytes (ie a flattened version of a previous BPropertyInfo). The old state of the current BPropertyInfo is replaced by that described by the flattened representation. The actual description of this byte representation of BPropertyInfo is described in the "implemenation" section below.
Print To Stream: The PrintToStream() member function sends the current state of the BPropertyInfo instance to standard out for debugging purpose. The actual format of this output isn't critical but it should describe the state of the object and be easy for a developer to understand.
Find Match: The FindMatch() member function takes a BMessage, a specifier (in the form of a BMessage), a specifier type (called form, ie B_DIRECT_SPECIFIER), property name and an index. The member returns -1 if no match can be found. A match will have the "what" code of the message (not the specifier message) in its command list or have a wildcard command. It will also have the property name as its property name. And, the specifier type will be listed as a valid specifier, or the property will have a wildcard specifier. Note, if the index is non-zero, then only properties with command wildcards will be a match (a wildcard is an empty list of commands, similarly for specifier type). On a match, the result is a 0 based offset into the array of properties.
There is a key difference between the OpenBeOS BPropertyInfo class and the Be implementation is support for BeOS R3 compiled executables. The elements in the property_info structure changed in R4 versus the one which was used in R3. Be did the following to handle this:
For the OpenBeOS implementation, we have decided not to implement this R3 compatibility at this time but we are not going to rule it out. The header file for BPropertyInfo will be changed to "remove" the R3 compatibility interfaces using an "ifdef R3_compatible". The interfaces will still appear to the human reader but not be there as far as the compiler is concerned. If we revise out decision in the future, it will be a simple matter of removing the ifdefs and implement these R3 compatibility interfaces. For now, we have decided not to do this because:
The flattened format of BPropertyInfo looks like the following:
| Section | Size | Description |
|---|---|---|
| Header | 1 | Endian flag, 1 for big endian, 0 for little endian |
| 4 | Number of property_info elements in the flattened data. | |
| 4 | Set to 3 if there are value_info in the flattened data, 1 otherwise | |
| property_info main section, one per property_info element | 1 to n | NULL terminated property_name |
| 1 to n | NULL terminated usage string. | |
| 4 | The extra_data value | |
| 4 to 40 | Up to 10 commands, each 4 bytes in size. A zero command indicates the end of the commands. | |
| 4 to 40 | Up to 10 specifiers, each 4 bytes in size. A zero specifier indicates the end of the specifiers. | |
| property_info types section, one per property_info element | 4 to 40 | Up to 10 types, each 4 bytes in size. A zero type indicates the end of the types. |
| 4 to n | A series of 0 to 15 name and type pairs from the "compound types" or ctypes section of the property_info structure. Each is made up of a null terminated name followed by a 4 byte type. There are up to 15 because there is a three element array of five name/type pairs. If fewer than 5 elements appear in any one set of the the three elements, four zero bytes are in the stream where the "name" would be. Also, to indicate that there are fewer than three compound types, four zero bytes are in the stream where the first name would be. | |
| value_info header, only appears if the flag in the header is set to "3" | 2 | Number of value_info elements in the flattened data. |
| value_info section, one per value_info element | 4 | The "kind" of this value_info element. |
| 4 | The "value" of this value_info element | |
| 1 to n | A NULL terminated name string | |
| 1 to n | A NULL terminated usage string | |
| 4 | The "extra_data" of this value_info element |
The following is some information from Marc Flerackers sent in a series of emails which describes his investigation into how BPropertyInfo instances are flattened. Note that the implementation is very much based Marc's implementation elluded to in these messages, although you will see some differences between the above description and Marc's messages. The above table describes the actual format as it is implemented today and seems to match Be's implementation. However, Marc's investigation, implementation and emails were critical to getting this information and is therefore included here in this document:
I spend this morning some time to check how a BPropertyInfo is flattened, here's the result for BControl (not such a good choice as there are no compound types, however I added at the bottom how the layout looks if there are). I'm implementing this now in my own BPropertyInfo class. How is the OBOS BPropertyInfo class going BTW?
// Header
4 6 chunk count
4 1 version
// Start of property_info chunks, without types
8 "Enabled" name
58 "" usage ("Returns whether or not the BControl is currently enabled.")
4 0 extra_data
4 PGET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
8 "Enabled" name
34 "" usage ("Enables or disables the BControl.")
4 0 extra_data
4 PSET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
6 "Label" name
30 "" usage ("Returns the BControl's label.")
4 0 extra_data
4 PGET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
6 "Label" name
32 "" usage ("Sets the label of the BControl.")
4 0 extra_data
4 PSET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
6 "Value" name
30 "" usage ("Returns the BControl's value.")
4 0 extra_data
4 PGET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
6 "Value" name
32 "" usage ("Sets the value of the BControl.")
4 0 extra_data
4 PSET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
// Start of property_info chunks, only types
4 BOOL type
4 0 end type list
4 0 end compound list
4 BOOL type
4 0 end type list
4 0 end compound list
4 CSTR type
4 0 end type list
4 0 end compound list
4 LONG type
4 0 end type list
4 0 end compound list
4 LONG type
4 0 end type list
4 0 end compound list
If there would have been compound types, the layout of the type chunks would be like this
4 BOOL type 4 0 end type list 5 "name" compound name 4 LONG compound type 4 0 end compound list
Layout of a flattened BPropertyInfo with compound members. Value info is still missing, I will look at it when I implement support for it in my BPropertyInfo class. BTabView and BRadioButton are coming to cvs soon BTW, I only have to find some time to write decent Draw functions ^_^.
// Header 4 3 chunk count 4 1 version // Start of property_info chunks, without types 7 "Suites" name 1 0 usage 4 0 extra_data 4 PGET commands 4 0 end commands list 4 1 specifiers 4 0 end specifiers list 10 "Messenger" name 1 0 usage 4 0 extra_data 4 PGET commands 4 0 end commands list 4 1 specifiers 4 0 end specifiers list 13 "InternalName" name 1 0 usage 4 0 extra_data 4 PGET commands 4 0 end commands list 4 1 specifiers 4 0 end specifiers list // Start of property_info chunks, only types 4 0 end type list 7 "suites" compound name 4 CSTR compound type 4 0 end compound sub list 9 "messages" compound name 4 SCTD compound type 4 0 end compound sub list 4 0 end compound list 4 MSNG type 4 0 end type list 4 0 end compound list 4 CSTR type 4 0 end type list 4 0 end compound list
Some updated information about the flattened BPropertyInfo layout for people who are interested ^_^.
The header contains flags, not a version flattened header 4 count 4 flags 0x1 : property_info structs are present 0x2 : value_info structs are present flattened value_info chunks are appended at the end as follows a small header 4 count for every value_info 2 kind 4 value x name x usage 4 extra_data where x is strlen + 1 of course.
Value info structs are used to publish information about non-Be types and scripting commands btw.
I tested my code against the Be implementation, and the flattened data matches.