BPropertyInfo

Derived from: BFlattenable

Declared in: be/app/PropertyInfo.h

Library: libbe.so

Summary

BPropertyInfo is a simple class that manages scripting. A program describes its scripting interface to a BPropertyInfo object through an array of property_info structures, with each entry describing a piece of the scripting suite. The structure definition:

   struct 
property_info
 {
      char *name;
      uint32 commands[10];
      uint32 specifiers[10];
      char *usage;
      uint32 extra_data;
   };

• name provides the name of the property this structure describes.

• commands is a zero-terminated array of commands understood by the property, i.e. B_GET_PROPERTY. If the first element is 0, it represents a wildcard matching all possible commands.

• specifiers is a zero-terminated array of the specifiers understood by the property, i.e. B_DIRECT_SPECIFIER. If the first element is 0, it represents a wildcard matching all possible specifiers.

• usage gives a human-readable string describing the property and its allowable commands and specifiers.

• extra_data is an area free for general use; the operating system does not touch its contents.

A BPropertyInfo is instantiated by passing a zero-terminated array of property_info to its constructor. A typical initialization of BPropertyInfo looks like:

   static property_info prop_list[] = {
      { "duck", {B_GET_PROPERTY, B_SET_PROPERTY, 0}, 
      {B_DIRECT_SPECIFIER, B_INDEX_SPECIFIER, 0}, "get or set duck"},
      { "head", {B_GET_PROPERTY, 0}, {B_DIRECT_SPECIFIER, 0}, "get head"},
      { "head", {B_SET_PROPERTY, 0}, {B_DIRECT_SPECIFIER, 0}, "set head"},
      { "feet", {0}, {0}, "can do anything with his orange feet"},
      0 // terminate list
   };
   
   BPropertyInfo prop_info(prop_list);

Since BPropertyInfo only stores a pointer to the array, it is important that the life span of the array is at least as long as that of the BPropertyInfo object.

Notice that BPropertyInfo doesn't impose any particular structure upon the array; in particular, not all commands and specifiers for a given property need be placed in a single entry in the array. You are free to organize your scripting suite in whatever manner is most convenient for your particular object.

BPropertyInfo is a descendant of BFlattenable, and can therefore be used to store a description of an object's supported scripting suite. This is particularly useful when overriding GetSupportedSuites():

   status_t MyHandler::GetSupportedSuites(BMessage *msg)
   {
      msg->AddString("suites", "suite/vnd.Me-my_handler");
      BPropertyInfo prop_info(prop_list);
      msg->AddFlat("messages", &prop_info);
      return baseClass::GetSupportedSuites(msg);
   }

Naturally, BPropertyInfo is equally as useful in interpreting the results obtained from querying an object for its supported suites.

BPropertyInfo defines the FindMatch() method designed to simplify the implementation of ResolveSpecifier(). It returns the index of the property info matching the description given to it, or -1 if none match. This reduces ResolveSpecifier() in the simplest cases to:

   BHandler *MyHandler::ResolveSpecifier(BMessage *msg, int32 index,
      BMessage *spec, int32 form, const char *prop)
   {
      BPropertyInfo prop_info(prop_list);
      if (prop_info.FindMatch(msg, index, spec, form, prop) >= 0)
      return this;
      return baseClass::ResolveSpecifier(msg, index, spec, form, prop);
   }

Of course, for more complicated objects, ResolveSpecifier() may need to set the target handler to an object other than itself, so more processing may be required. In those cases, the object can use the index returned by FindMatch() to help it determine the target of the scripting message.

Constructor and Destructor

BPropertyInfo()

	BPropertyInfo(property_info *p = NULL, bool free_on_delete = false)

Initializes the object with the specified zero-terminated array p of property_info. Passing true in free_on_delete instructs the object to free the memory associated with the property_info when the object is destroyed. BPropertyInfo does not copy the array, so it is important that the array is not deleted or otherwise destroyed while the BPropertyInfo is in use.

~BPropertyInfo()

	~BPropertyInfo()

If free_on_delete set to true in the constructor, the destructor frees all memory associated with the property_info. Otherwise, does nothing.

Member Functions

AllowsTypeCode()

Implementation detail. See BFlattenable::AllowsTypeCode().

FindMatch()

	int32 FindMatch(BMessage *msg, int32 index, BMessage *spec, int32 form,       const char *prop, void *data = NULL) const

Passed a property name in prop, a specifier in form, and a command in msg->what, searches the property_info array for an item supporting the specified scripting request. If index is nonzero, then FindMatch() only searches those property_info structures with the wildcard command (first element of command array equal to 0). Otherwise, it searches through all available property_info structures for a match. If a match is found, it fills the memory at data with the contents of the extra_data field of the match and returns the index of the match in the array. Otherwise, it returns B_ERROR.

Flatten

Implementation detail. See BFlattenable::Flatten().

FlattenedSize()

Implementation detail. See BFlattenable::FlattenedSize().

IsFixedSize()

Implementation detail. See BFlattenable::IsFixedSize().

TypeCode()

Implementation detail. See BFlattenable::TypeCode().

PrintToStream()

	void PrintToStream(void) const

Prints information about the BPropertyInfo to standard output.

PropertyInfo()

	const property_info *PropertyInfo(void) const

Returns the property_info list associated with the object.

Unflatten()

Implementation detail. See BFlattenable::Unflatten().