Detailed Description
Structures for properties which are available, or required.
Terms
Required Property Index : the 0 based index of the property in the list of required properties. Not the same as the property index.
Property Index : the 0 based index of the property in the source used to create the required properties. Not the same as the required property index.
Results : the structure used to contain the data associated with the available required properties.
Source : the source of property names. Typically a call back method to return properties from the data structure used by the aspect engine.
Introduction
Aspect engine performance can often be improved by limiting the properties that can be returned from the engine. As this is a performance feature shared across different types of aspect engine the utility functions are stored in the common C files.
Required properties could be specified at initialisation as a character separated string, as an array of strings or from an existing set of properties already obtained from these methods. In all scenarios it is desirable to be able to query the properties and find their indexes in the source data structure using a consistent set of methods.
Creation
fiftyoneDegreesPropertiesCreate is used to create a consistent set of required properties. The structure passed must have one of the follow set.
- Separated string of property names. Valid separators include space, comma and pipe.
- An array of strings.
- Existing properties results from a previous creation operation. This method is used when a data set is being reloaded due to a change in the underlying data.
Creation also requires a method to retrieve the name of the properties from the underlying data source. A method pointer conforming to fiftyoneDegreesPropertiesGetMethod must be provided to retrieve the property name string item for a given property index up to the maximum count. The call back is used to avoid any hard dependency between the data structure and the properties methods.
Unlike standard collection item retrieval the properties methods will not know the underlying collection implement or reference from which the item was obtained from. Therefore the implementation of get MUST set the collection field of the collection item.
Some, or all, of the required properties may not be present in the underlying data source. Any missing properties will be ignored in the results. The get name from required index method can be used to iterate over the available properties. The number of available properties after creation can be obtained from the count field of properties results.
Whilst the property names can be provided as string(s) the property names referenced from the properties results are collection items from a strings collection. The properties methods are responsible for releasing the references to these strings when the properties results are freed.
The resulting require properties index will be in ascending order of the property name a string. As such the ordered list can be used with a binary search (divide and conquer) to quickly determine the required property index from the property name.
Free
When the properties results are finished with, the fiftyoneDegreesPropertiesFree method must be used. This will also free the collection items used to reference the property name strings using the collection field of the item to obtain the source collection. This collection must have been set by the get method used at creation.
Operation
Several methods are available which can be used to convert from an input such as a property name or required property index to a property index in the data structure. The method names are self-explanatory.
Where possible using integer property or required property indexes is preferable to the string representation of the property as this improves performance.
Collaboration diagram for Properties:
Structs
Typedef Documentation
◆ fiftyoneDegreesEvidencePropertiesGetMethod
Populates the evidence properties structure with the indexes of the properties required by the property provided, and returns the number of property indexes which were added.
If the evidence properties structure is null, then this method returns the count but does not populate the structure.
- Parameters
-
- state - pointer to data which the method may need to use
|
- property - pointer to the property to get the evidence properties for
|
- evidenceProperties - pointer to the pre-allocated structure to populate with the evidence property indexes
|
- Returns
- the number of property indexes added to the structure. Or the number which would have been added were it not null
◆ fiftyoneDegreesPropertiesAvailable
Array of properties which are available in a data set.
◆ fiftyoneDegreesPropertiesGetMethod
Returns a string for the property at the index provided or NULL if there is no property available at the index.
- Parameters
-
- state - resource used to obtain the string
|
- index - of the property
|
- item - used to obtain a handle to the string
|
- Returns
- pointer to the string or NULL if no property available
Function Documentation
◆ fiftyoneDegreesPropertiesCreate()
Creates a properties result instance for use with future property operations.
The resulting required properties will be provided in ascending order.
- Parameters
-
- properties - required to be available as either a separated list of property names, an array of property names or an existing properties results structure from another data set. Valid separators include pipe, comma and space. The fields are evaluated in order of existing, array and then string. the first field with a value is used.
|
- state - pointer to state used with the get method
|
- getPropertyMethod - method used to return the property name from a string collection
|
- getEvidencePropertiesMethod - method used to populate the evidence properties for a property
|
- Returns
- instance of a properties result for use with future properties methods
◆ fiftyoneDegreesPropertiesFree()
Frees the memory and resources used by the properties results previously created using the fiftyoneDegreesPropertiesCreate method.
- Parameters
-
- available - properties instance to be freed
|
◆ fiftyoneDegreesPropertiesGetNameFromRequiredIndex()
Gets the name as a string from the required property index.
- Parameters
-
- available - properties instance
|
- requiredPropertyIndex - index of the property in the required properties structure
|
- Returns
- string representation of the property
◆ fiftyoneDegreesPropertiesGetPropertyIndexFromName()
Gets the index of the property in the source data structure from the name.
- Parameters
-
- available - properties instance
|
- propertyName - string containing the property name
|
- Returns
- 0 based index of the property in the source or -1 if not available
◆ fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex()
Maps the required property index to the index in the source data structure.
- Parameters
-
- available - properties instance
|
- requiredPropertyIndex - index of the property in the required properties structure
|
- Returns
- 0 based index of the property in the source or -1 if not available
◆ fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName()
Gets the required property index in the list of all required properties from the name.
- Parameters
-
- available - properties instance
|
- propertyName - string containing the property name
|
- Returns
- 0 based index of the property in the required properties or -1 if not available
- Examples
- Hash/StronglyTyped.c.
◆ fiftyoneDegreesPropertiesIsSetHeaderAvailable()
Check if the 'SetHeader' properties are included in the available required properties.
- Parameters
-
- available - properties instance
|
- Returns
- bool whether 'SetHeader' properties are included
Variable Documentation
◆ fiftyoneDegreesPropertiesDefault
The default properties required to make all possible properties available.
Should be used to initialise a new instance of fiftyoneDegreesPropertiesRequired.
- Examples
- Hash/MatchMetrics.c, and Hash/StronglyTyped.c.
