PathEngine home previous: Error Handlersnext: Passing Arrays
Contents, Programmers Guide, Applying the SDK, Miscellaneous API Issues, Handling Attributes

Handling Attributes

A parameter of type 'const char *const*' is used in various places to pass a set of named attributes.
(See for example Error Handlers and iPathEngine::getVersionAttributes() .)
This is essentially an array of pointers to C strings.

This mechanism enables an arbitrary set of attributes to be passed without requiring changes in linkage, and in such a way that calling code can easily parse those attributes.
You could do the same thing with a std::vector<std::string>, but this requires STL implementations to agree across the interface.

The 'const char *const*' parameter points to a null terminated sequence of C string pointers. (The sequence of C string pointers is terminated by a null pointer.)
The strings themselves are a set of name,value pairs. (So there are guaranteed to be an even number of strings in the sequence.)
Note also that the parameter itself may be a null pointer, indicating that there are no attributes. (This makes it straightforward to call an error handler when you don't want to specify any attributes.)

One way in which this might be generated is as follows:

void someFunction()
{
	char* attributes[5];
	attributes[0] = "firstAttributeName";
	attributes[1] = "firstAttributeValue";
	attributes[2] = "secondAttributeName";
	attributes[3] = "secondAttributeValue";
	attributes[4]=0;
	someFunctionThatTakesAttributes(attributes);
}

The convention is that functions taking attributes copy the attribute data if this needs to be used after the function returns.

Code such as the following can be used to parse attributes:

if(attributes)
{
	while(*attributes)
	{
		printf("attribute name = \"%s\"\n", attributes[0]);
		printf("attribute value = \"%s\"\n", attributes[1]);
		attributes += 2;
	}
}

It is important to include the check for attributes being a null pointer since this can be used to indicate that there are no attributes.


Documentation for PathEngine release 6.00 - Copyright © 2002-2016 PathEnginenext: Passing Arrays