AINameSpaceSuite Struct Reference
[API Suite List]

This suite provides functions that allow you to create and manage namespaces. More...

#include <AINameSpace.h>

Public Attributes
AIErr(*	AllocateNameSpace )(AIStringPool pool, AINameSpace *space)
	Creates a new namespace.
AIErr(*	DisposeNameSpace )(AINameSpace *space)
	Frees a namespace.
AIErr(*	SetValue )(const AINameSpace space, const char path, const char *type,...)
	Sets the value stored at a point in a namespace.
AIErr(*	GetValue )(const AINameSpace space, const char path, const char *type,...)
	Retrieves Sets the value stored at a point in a namespace.
AIErr(*	GetType )(const AINameSpace space, const char path, char **type)
	Retrieves the type of the value stored at a point in a namespace.
AIErr(*	GetChangeCount )(const AINameSpace space, const char path, ai::int32 *count)
	Reports the number of times the value stored at a point in a namespace has been changed.
AIErr(*	RemoveValue )(const AINameSpace space, const char path)
	Removes the value stored at a point in a namespace.
AIErr(*	CountPaths )(const AINameSpace space, const char path, ai::int32 *count)
	Reports the number of unique components that can be appended to a path to produce paths or partial paths in the namespace.
AIErr(*	GetNthPath )(const AINameSpace space, const char path, ai::int32 n, char *nthPath)
	Retrieves a unique component that can be appended to a given path to produce a new path or partial path in the namespace.
AIErr(*	ParseValue )(const AINameSpace space, const char path, AIDataFilter *filter)
	Reads namespace data that was written to a file using `FlushValue()` into a namespace, under a given base path.
AIErr(*	FlushValue )(const AINameSpace space, const char path, AIDataFilter *filter)
	Writes data from a namespace to a filter, serializing the namespace entries identified by a partial path to a data filter.

Detailed Description

This suite provides functions that allow you to create and manage namespaces.

A namespace is essentially a global dictionary that is not associated with any particular document. Its keys are strings called paths and the associated values can be of these types and values:

integer (value: long )
real (value: double )
string (value: char * )
raw (length: long, value: char * )
unicodeString (value: ai::UnicodeString *)

Unlike dictionaries, the contents of a namespace have a hierarchical organization. The hierarchy of keys is like that of directory paths in a file system, with levels divided by '/' separators. For example the key "/root/entry" has two components, "root" and "entry".

You can specify partial paths, and refer to all keys that are prefixed with that path. A partial path is specified with a trailing '/' separator. The path "/" refers to the root.

A path can contain a maximum of 505 characters. Each component of a path (excluding separators) can have a maximum of 100 characters.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAINameSpaceSuite and kAINameSpaceVersion.

Member Data Documentation

AIErr(* AINameSpaceSuite::AllocateNameSpace)(AIStringPool *pool, AINameSpace **space)

Creates a new namespace.

Parameters:

	pool	The string pool from which to allocate the path component string, or `NULL` to use the global string pool, If supplied, the caller must dispose of the string pool after freeing the namespace. See `AIStringPoolSuite`.
	space	A buffer in which to return the namespace reference.

AIErr(* AINameSpaceSuite::CountPaths)(const AINameSpace *space, const char *path, ai::int32 *count)

Reports the number of unique components that can be appended to a path to produce paths or partial paths in the namespace.

(This is like the number of entries in a directory.)

Parameters:

	The	namespace.
	path	The base path.
	count	[out] A buffer in which to return the component count.

AIErr(* AINameSpaceSuite::DisposeNameSpace)(AINameSpace *space)

Frees a namespace.

If you supplied a string pool, you must free it after freeing the namespace.

Parameters:

The

namespace. Upon return, this reference is invalid.

AIErr(* AINameSpaceSuite::FlushValue)(const AINameSpace *space, const char *path, AIDataFilter *filter)

Writes data from a namespace to a filter, serializing the namespace entries identified by a partial path to a data filter.

Writes only the path after the base and the key/value pairs, not the base path.

Use ParseValue() to read data in from the resulting file to a new path prefix.

Parameters:

	The	namespace.
	path	The base path for the data.
	filter	The file filter with which to serialize the keys.

AIErr(* AINameSpaceSuite::GetChangeCount)(const AINameSpace *space, const char *path, ai::int32 *count)

Reports the number of times the value stored at a point in a namespace has been changed.

Each time the value is set, the change count is incremented.

Parameters:

	The	namespace.
	path	The path. If this is an intermediate node in the namespace, the count is the number of times all values stored under that node have changed.
	count	[out] A buffer in which to return the change count.

AIErr(* AINameSpaceSuite::GetNthPath)(const AINameSpace *space, const char *path, ai::int32 n, char *nthPath)

Retrieves a unique component that can be appended to a given path to produce a new path or partial path in the namespace.

Parameters:

	The	namespace.
	path	The base path.
	n	The index position of the component.
	nthPath	[out] A buffer in which to return the component, which includes the trailing separator if it identifies a partial path.

AIErr(* AINameSpaceSuite::GetType)(const AINameSpace *space, const char *path, char **type)

Retrieves the type of the value stored at a point in a namespace.

Parameters:

The namespace.

path The path.

type

[out] A buffer in which to return the type. Types are:

integer (value: long )
real (value: double )
string (value: char * )
raw (length: long, value: char * )
unicodeString (value: ai::UnicodeString *)

AIErr(* AINameSpaceSuite::GetValue)(const AINameSpace *space, const char *path, const char *type,...)

Retrieves Sets the value stored at a point in a namespace.

Parameters:

	The	namespace.
	path	The path.
	type	[out] A buffer in which to return the type. Types are: `integer` (value: `long` ) `real` (value: `double` ) `string` (value: `char ` ) `raw` (length: `long`, value: `char ` ) `unicodeString` (value: `ai::UnicodeString *`)
	length	[out] For type `raw` only, a buffer in which to return the length of the value.
	value	[out] A buffer in which to return the value, of the appropriate type.

AIErr(* AINameSpaceSuite::ParseValue)(const AINameSpace *space, const char *path, AIDataFilter *filter)

Reads namespace data that was written to a file using FlushValue() into a namespace, under a given base path.

Parameters:

	The	namespace.
	path	The base path, used as a prefix.
	filter	The file filter with which to read the data. This does not need to be the same filter used to serialize the keys.

AIErr(* AINameSpaceSuite::RemoveValue)(const AINameSpace *space, const char *path)

Removes the value stored at a point in a namespace.

Parameters:

	The	namespace.
	path	The path. If this is a partial path, all values under it are removed.

AIErr(* AINameSpaceSuite::SetValue)(const AINameSpace *space, const char *path, const char *type,...)

Sets the value stored at a point in a namespace.

Parameters:

	The	namespace.
	path	The path.
	type	The new type. Types are: `integer` (value: `long` ) `real` (value: `double` ) `string` (value: `char ` ) `raw` (length: `long`, value: `char ` ) `unicodeString` (value: `ai::UnicodeString *`)
	length	For type `raw` only, the length of the value.
	value	The new value, of the appropriate type.

The documentation for this struct was generated from the following file:

AINameSpace.h

AINameSpaceSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AINameSpaceSuite Struct Reference
[API Suite List]