51Degrees Common C/C++  4.1

A shared functionality library that is used by 51Degrees products
Search

Properties

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.

  1. Separated string of property names. Valid separators include space, comma and pipe.
  2. An array of strings.
  3. 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.

Structs

struct  fiftyoneDegreesPropertyAvailable
Used to access the property item quickly without the need to search. More...
struct  fiftyoneDegreesPropertyAvailableArray
Array of items of type fiftyoneDegreesPropertyAvailable used to easily access and track the size of the array. More...
struct  fiftyoneDegreesPropertiesRequired
Defines a set of properties which are required by a caller. More...

Typedefs

typedef fiftyoneDegreesPropertyAvailableArray  fiftyoneDegreesPropertiesAvailable
Array of properties which are available in a data set. More...
typedef fiftyoneDegreesString *(*  fiftyoneDegreesPropertiesGetMethod) (void *state, uint32_t index, fiftyoneDegreesCollectionItem *item)
Returns a string for the property at the index provided or NULL if there is no property available at the index. More...

Functions

EXTERNAL fiftyoneDegreesPropertiesAvailable *  fiftyoneDegreesPropertiesCreate (fiftyoneDegreesPropertiesRequired *properties, void *state, fiftyoneDegreesPropertiesGetMethod getPropertyMethod)
Creates a properties result instance for use with future property operations. More...
EXTERNAL int  fiftyoneDegreesPropertiesGetPropertyIndexFromName (fiftyoneDegreesPropertiesAvailable *available, const char *propertyName)
Gets the index of the property in the source data structure from the name. More...
EXTERNAL int  fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName (fiftyoneDegreesPropertiesAvailable *available, const char *propertyName)
Gets the required property index in the list of all required properties from the name. More...
EXTERNAL int  fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex (fiftyoneDegreesPropertiesAvailable *available, int requiredPropertyIndex)
Maps the required property index to the index in the source data structure. More...
EXTERNAL fiftyoneDegreesString *  fiftyoneDegreesPropertiesGetNameFromRequiredIndex (fiftyoneDegreesPropertiesAvailable *available, int requiredPropertyIndex)
Gets the name as a string from the required property index. More...
EXTERNAL void  fiftyoneDegreesPropertiesFree (fiftyoneDegreesPropertiesAvailable *available)
Frees the memory and resources used by the properties results previously created using the fiftyoneDegreesPropertiesCreate method. More...

Variables

EXTERNAL fiftyoneDegreesPropertiesRequired  fiftyoneDegreesPropertiesDefault
The default properties required to make all possible properties available. More...

Typedef Documentation

◆ fiftyoneDegreesPropertiesGetMethod

typedef fiftyoneDegreesString*(* fiftyoneDegreesPropertiesGetMethod) (void *state, uint32_t index, fiftyoneDegreesCollectionItem *item)

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()

EXTERNAL fiftyoneDegreesPropertiesAvailable* fiftyoneDegreesPropertiesCreate ( fiftyoneDegreesPropertiesRequired *   properties,
void *   state,
fiftyoneDegreesPropertiesGetMethod   getPropertyMethod  
)

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
Returns
instance of a properties result for use with future properties methods

◆ fiftyoneDegreesPropertiesGetNameFromRequiredIndex()

EXTERNAL fiftyoneDegreesString* fiftyoneDegreesPropertiesGetNameFromRequiredIndex ( fiftyoneDegreesPropertiesAvailable *   available,
int   requiredPropertyIndex  
)

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()

EXTERNAL int fiftyoneDegreesPropertiesGetPropertyIndexFromName ( fiftyoneDegreesPropertiesAvailable *   available,
const char *   propertyName  
)

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()

EXTERNAL int fiftyoneDegreesPropertiesGetPropertyIndexFromRequiredIndex ( fiftyoneDegreesPropertiesAvailable *   available,
int   requiredPropertyIndex  
)

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()

EXTERNAL int fiftyoneDegreesPropertiesGetRequiredPropertyIndexFromName ( fiftyoneDegreesPropertiesAvailable *   available,
const char *   propertyName  
)

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

Variable Documentation

On This Page

Generated by doxygen 1.8.15