Accessing property extensions
Depending on the settings for the __EXTENSIONS collection, property extensions are created explicitly (managed extensions) or on demand (automatic extensions). Automatic property extensions are created on demand, while managed property extensions have to be created explicitly.
Accessing extension properties is possible by calling Property::property() or Property::value() passing the name of the extension property. The function returns a property or value handle for the extension property, when being defined in dictionary or database. Property or value handles for property extensions may be kept as long as the parent property handle is opened. They are closed automatically when closing the parent property handle.
When trying to access an extension property by calling Property::property() or Property::value(), which also has been defined as object type property, the object type property will be returned. In order to explicitly request an extension property or value, Property::extensionProperty() or Property::extensionValue() might be called.
In order to check, whether an extension property exists, Database::extensionExist() might be called. Extension properties defined in the database or dictionary do potentially exist for all object types containing an __EXTENSIONS reference. Property extensions do exist for an instance only, when being explicitly created or when when using automatic property extension (create is true for __EXTENSIONS ).
In order to delete a property extension, Property::extensionErase() might be called, which will remove the property extension from the selected object instance.
For listing values for all existing property extensions for an instance, property extensions may be provided by position (Property::extensionProperty()). In order to avoid exceptions, Property::extensionsCount() may be called, which returns the number of property extensions stored for the instance currently selected (see example below).
In order to define managed property extensions, the create option has to be set to false in the __EXTENSIONS reference definition. Then, property extensions have to be created explicitly. For creating a property extension explicitly Property::provideExtension() has to be called from an application program or OSI script. The property name passed to the function is searched first in the database and then, when not being defined there, in the dictionary. When no such property extension exists in the property extension list of the object instance, the property extension will be created and initialized. In order to check, whether the property extension has already been created for the object instance, one may call Property::extensionExist().
When an expandable object instance selected in a property handle does not contain property extensions referenced by calling Property::property() or Property::value(), the property handle is not accessible (but valid). The state of property or value handles may, however, change when changing the selection in the parent property handle.
After removing a managed property extension from the instance by calling Property::extensionErase(), it is not accessible anymore for the instance selected.
In order to define automatic property extensions, the create option in the __EXTENSIONS reference definition has been set to true. In this case, all extension properties are considered as potential properties of each expandable object instance, i.e. object instances containing an __EXTENSIONS reference. Each defined property extension can be accessed, but will be stored only, when data has been set or created for an extension property.
Similar to managed extensions, Property::extensionExist() may be called in order to check, whether the property has already been created for an instance.
... fragment { Property &person ) { // OSI
Property extension; // property extension
int ext_count;
Property &pid = person.property("pid"); // person property
while ( person.next() ) {
ext_count = person.extensionCount();
if ( ext_count > 0 ) {
printf("Property extensiosn for %s:",pid.toString());
while ( ext_count > 0 ) {
extension = person.extensionProperty(--ext_count);
printf(" %s",extension.propertyDefinition().name());
}
}
}
}