Construction 1: A BPropertyInfo can be created with 0 to 3 construction arguments. -With no arguments, the BPropertyInfo has no "property_info" or "value_info" structures. If one -argument is specified, it must be a pointer to the property_info structure for the BPropertyInfo. -If two arguments are specified, the first is the property_info pointer and the second is the -value_info structure. If three arguments are specified, the first two are the same as indicated -and the third is a flag which indicates that the BPropertyInfo class should "delete[]" the -passed in pointers on destruction if true.
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 "delete[]" on the pointers passed in at construction time.
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.
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.
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.