Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RtDict
[Dictionary Tools]


Data Structures

struct  RtDict
struct  RtDictSchema

Typedefs

typedef RtDictSchema RtDictSchema
typedef RtDict RtDict
typedef void * RtDictEntryType
typedef const void * RtDictEntryConstType
typedef void *( RtDictEntryAddRefCallBack )(RtDictEntryType entry)
typedef RwBool( RtDictEntryDestroyCallBack )(RtDictEntryType entry)
typedef const RwChar *( RtDictEntryGetNameCallBack )(RtDictEntryConstType entry)
typedef RwUInt32( RtDictEntryStreamGetSizeCallBack )(RtDictEntryConstType entry)
typedef RtDictEntryType( RtDictEntryStreamReadCallBack )(RwStream *stream)
typedef RtDict *( RtDictStreamReadCompatibilityCallBack )(RwStream *stream)
typedef const RtDictEntryType( RtDictEntryStreamWriteCallBack )(RtDictEntryConstType entry, RwStream *stream)
typedef RtDict *( RtDictCallBack )(RtDict *dictionary, void *data)
typedef RtDictEntryType( RtDictEntryCallBack )(RtDictEntryType entry, void *data)

Functions

RtDictSchema * RtDictSchemaInit (RtDictSchema *schema)
RwBool RtDictSchemaDestruct (RtDictSchema *schema)
RtDict * RtDictSchemaCreateDict (RtDictSchema *schema)
RtDictSchema * RtDictSchemaAddDict (RtDictSchema *schema, RtDict *dict)
RtDictSchema * RtDictSchemaRemoveDict (RtDictSchema *schema, RtDict *dict)
RtDict * RtDictSchemaGetCurrentDict (RtDictSchema *schema)
RtDictSchema * RtDictSchemaSetCurrentDict (RtDictSchema *schema, RtDict *dict)
RtDictEntryType RtDictAddEntry (RtDict *dictionary, RtDictEntryType entry)
RtDictEntryType RtDictFindNamedEntry (RtDict *dictionary, const RwChar *name)
const RtDict * RtDictForAllEntries (const RtDict *dict, RtDictEntryCallBack *callBack, void *data)
RtDict * RtDictRemoveEntry (RtDict *dictionary, RtDictEntryType entry)
RwBool RtDictDestroy (RtDict *dictionary)
RwUInt32 RtDictStreamGetSize (const RtDict *dictionary)
RtDict * RtDictSchemaStreamReadDict (RtDictSchema *schema, RwStream *stream)
const RtDict * RtDictStreamWrite (const RtDict *dictionary, RwStream *stream)
RwBool RtDictSchemaForAllDictionaries (RtDictSchema *schema, RtDictCallBack *callBack, void *data)

Detailed Description

Dictionary Toolkit for RenderWare Graphics.

RtDict Toolkit Overview

Requirements

Overview

RtDict is a generic dictionary toolkit, enabling you to create dictionaries of arbitrary objects that may be located by name.

The layout of a dictionary is specified by a 'layout' object, RtDictSchema. Placed within the RtDictSchema are callbacks that allow the dictionary to manage the lifetime and streaming of the contained objects. RtDictSchema also manages a reference to a 'current' dictionary.

To use dictionaries, get access to or create a schema that defines the particular kind of dictionary you require. Then, call RtDictSchema functions to perform specific operations on dictionaries of that kind. RtDictSchemaCreateDict may be used to create new dictionaries; RtDictSchemaStreamReadDict can read in a dictionary; RtDictSchemaGetCurrentDict obtains the current dictionary and \RtDictschemaSetCurrentDict sets it.

Once you have a pointer to an RtDict object, you may place entries within the dictionary (RtDictAddEntry), remove entries (RtDictRemoveEntry) or stream the dictionary (RtDictStreamWrite, RtDictStreamGetSize).

Typedef Documentation

typedef struct RtDict RtDict
 

Typedef for struct RtDict.

typedef RtDict*( RtDictCallBack)(RtDict *dictionary, void *data)
 

RtDictCallBack is to be applied to each dictionary in a RtDictSchema.

Parameters:
dictionary  The dictionary to apply the callback to
data  User supplied data
Returns:
The dictionary the callback was applied to.
See also:
RtDictSchemaForAllDictionaries

typedef void*( RtDictEntryAddRefCallBack)(RtDictEntryType entry)
 

The following callbacks are needed for each dictionary schema. See RtDictSchema.

RtDictEntryAddRefCallBack defines a callback function for registering that the caller has a reference to a particular entry.

Parameters:
Entry  the entry of which to increment the reference count
Returns:
The entry

typedef RtDictEntryType( RtDictEntryCallBack)(RtDictEntryType entry, void *data)
 

RtDictEntryCallBack is to be applied to each entry in a dictionary.

Parameters:
entry  The entry to apply the callback to
data  User supplied data
Returns:
The entry the callback was applied to.
See also:
RtDictForAllEntries

typedef const void* RtDictEntryConstType
 

Typedef for dictionary entries

typedef RwBool( RtDictEntryDestroyCallBack)(RtDictEntryType entry)
 

RtDictEntryDestroyCallBack defines a callback function for destroying an entry in the dictionary.

Parameters:
entry  The entry to be destroyed
Returns:
Unused, RwBool to match most RenderWare object destruction functions

typedef const RwChar*( RtDictEntryGetNameCallBack)(RtDictEntryConstType entry)
 

RtDictEntryGetNameCallBack defines a callback function to get the name of an entry in the dictionary.

Parameters:
Entry  The entry
Returns:
A pointer to the name

typedef RwUInt32( RtDictEntryStreamGetSizeCallBack)(RtDictEntryConstType entry)
 

RtDictEntryStreamGetSizeCallBack gets the streamable size of an entry in the dictionary.

Parameters:
entry  The entry
Returns:
The size of the entry when streamed

typedef RtDictEntryType( RtDictEntryStreamReadCallBack)(RwStream *stream)
 

RtDictEntryStreamReadCallBack reads a new entry from a stream. This function should return a pointer to a freshly allocated and initialized entry, with a nominal reference count of 1 (which will be assigned to the dictionary).

Parameters:
stream  The stream to read from
Returns:
A pointer to the new entry on success; NULL on failure.

typedef const RtDictEntryType( RtDictEntryStreamWriteCallBack)(RtDictEntryConstType entry, RwStream *stream)
 

RtDictEntryStreamWriteCallBack writes an entry of the dictionary to a stream.

Parameters:
entry  The entry to write
stream  The stream to write to
Returns:
The entry on success; NULL on failure.

typedef void* RtDictEntryType
 

Typedef for dictionary entries

typedef struct RtDictSchema RtDictSchema
 

Typedef for struct RtDictSchema.

typedef RtDict*( RtDictStreamReadCompatibilityCallBack)(RwStream *stream)
 

RtDictStreamReadCompatibilityCallBack enables older dictionaries to be retrofitted to use the new generic dictionary code. This callback is for internal use.

Parameters:
stream  The stream to read from
Returns:
A pointer to the new dictionary on success; NULL on failure.

Function Documentation

RtDictEntryType RtDictAddEntry (  RtDict *    dict,
RtDictEntryType    entry
) 
 

RtDictAddEntry adds an entry to the dictionary, incrementing the reference count of that entry.

Parameters:
dict  The dictionary the entry will to be added to
entry  The entry to be added to the dictionary
Returns:
A valid pointer to the RtDict
See also:
RtDictForAllEntries , RtDictCreate

RwBool RtDictDestroy (  RtDict *    dict ) 
 

RtDictDestroy destroys a dictionary. The reference counts of all the entries contained in the dictionary are decreased via their destroy functions and the memory, associated with the dictionary, freed. If this dictionary is the current dictionary in its schema, the current dictionary is set to NULL.

Parameters:
dict  The dictionary to be destroyed
Returns:
TRUE if successful, FALSE otherwise
See also:
RtDictCreate , RtDictSchemaSetCurrentDict

RtDictEntryType RtDictFindNamedEntry (  RtDict *    dict,
const RwChar *    name
) 
 

RtDictFindNamedEntry finds an entry in a dictionary using the entry's name.

Parameters:
dict  The dictionary to be looked into.
name  The name of the entry to look for.
Returns:
A valid pointer to an entry if the entry is found, NULL otherwise

const RtDict* RtDictForAllEntries (  const RtDict *    dict,
RtDictEntryCallBack *    callBack,
void *    data
) 
 

RtDictForAllEntries executes a callback for every entry in the dictionary.

Parameters:
dict  A pointer to the RtDict.
callBack  The callback function to be executed for every entry
data  The user specified data passed on to the callback function for each entry.
Returns:
A valid pointer to an RtDict.
See also:
RtDictSchemaForAllDictionaries

RtDict* RtDictRemoveEntry (  RtDict *    dict,
RtDictEntryType    entry
) 
 

RtDictRemoveEntry removes an entry from the current dictionary. The entry's destroy function is called. Consequently, if you wish to retain the entry you should AddRef it prior to calling this function.

Parameters:
dict  The dictionary to remove the entry from
entry  The entry to be removed
Returns:
On success, the dictionary. NULL if the entry wasn't found in the dictionary.
See also:
RtDictAddEntry

RtDictSchema* RtDictSchemaAddDict (  RtDictSchema *    schema,
RtDict *    dict
) 
 

RtDictSchemaAddDict adds a new dictionary to the list of those managed by the schema.

Parameters:
schema  The schema describing the dictionary layout
dict  The dictionary to add to the list
Returns:
A valid pointer to a RtDictSchema if successful, NULL otherwise
See also:
RtDictSchemaCreateDict , RtDictSchemaRemoveDict

RtDict* RtDictSchemaCreateDict (  RtDictSchema *    schema ) 
 

RtDictSchemaCreateDict creates an empty dictionary. RtDictAddEntry can be used to add entries to the dictionary

Parameters:
schema  The schema describing the dictionary layout
Returns:
A valid pointer to a RtDict if successful, NULL otherwise
See also:
RtDictDestroy , RtDictAddEntry

RwBool RtDictSchemaDestruct (  RtDictSchema *    schema ) 
 

RtDictSchemaDestruct destructs an external schema. Destroys the internal list of all dictionaries of this schema type.

Parameters:
schema  The schema to be used
Returns:
A valid pointer to the RtDictSchema if successful, NULL otherwise
See also:
RtDictSchemaDestruct , RtDictDestroy , RtDictAddEntry

RwBool RtDictSchemaForAllDictionaries (  RtDictSchema *    schema,
RtDictCallBack *    callBack,
void *    data
) 
 

RtDictSchemaForAllDictionaries executes a callback function for all active dictionaries. The callback function can have specified user datas.

Parameters:
schema  The schema for the set of dictionaries to be iterated over
callBack  The callback function to be executed for all dictionaries.
data  The user specified data passed on to the callback function for each dictionary.
Returns:
A RwBool (always TRUE at the moment)
See also:
RtDictForAllEntries

RtDict* RtDictSchemaGetCurrentDict (  RtDictSchema *    schema ) 
 

RtDictSchemaGetCurrentDict gets the current dictionary.

Parameters:
schema  The schema for which to obtain the current dictionary of
Returns:
A pointer to the current RtDict. This is NULL if there is no current dictionary.
See also:
RtDictSetCurrent

RtDictSchema* RtDictSchemaInit (  RtDictSchema *    schema ) 
 

RtDictSchemaInit initializes an external schema and creates an internal list of all dictionaries of this schema type.

Parameters:
schema  An external schema structure already initialized with appropriate entry management callbacks.
Returns:
A valid pointer to the RtDictSchema if successful, NULL otherwise
See also:
RtDictSchemaDestruct , RtDictDestroy , RtDictAddEntry

RtDictSchema* RtDictSchemaRemoveDict (  RtDictSchema *    schema,
RtDict *    dict
) 
 

RtDictSchemaRemoveDict removes a dictionary to the list of those managed by the schema.

Parameters:
schema  The schema describing the dictionary layout
dict  The dictionary to remove from the list
Returns:
A valid pointer to a RtDictSchema if successful, NULL otherwise
See also:
RtDictDestroy , RtDictSchemaAddDict

RtDictSchema* RtDictSchemaSetCurrentDict (  RtDictSchema *    schema,
RtDict *    dict
) 
 

RtDictSchemaSetCurrentDict sets the current dictionary.

Parameters:
schema  The schema for which to set the current dictionary.
dict  The dictionary to be set as current. NULL is valid, and indicates there is no current dictionary.
Returns:
A valid pointer to the schema.
See also:
RtDictGetCurrent

RtDict* RtDictSchemaStreamReadDict (  RtDictSchema *    schema,
RwStream *    stream
) 
 

RtDictSchemaStreamReadDict reads a dictionary from a stream.

Parameters:
schema  The schema for the dictionary to be created
stream  The stream the dictionary is to be read from.
Returns:
A valid pointer to a RtDict if successful, NULL otherwise.
See also:
RtDictStreamWrite , RtDictStreamGetSize , RwStreamOpen , RwStreamClose , RwStreamFindChunk

RwUInt32 RtDictStreamGetSize (  const RtDict *    dict ) 
 

RtDictStreamGetSize gets the size of a dictionary, should it be streamed out.

Parameters:
dict  The dictionary for which to obtain the size when streamed.
Returns:
The size of the dictionary in a stream
See also:
RtDictStreamReadDict , RtDictStreamWrite , RwStreamOpen , RwStreamClose , RwStreamFindChunk

const RtDict* RtDictStreamWrite (  const RtDict *    dict,
RwStream *    stream
) 
 

RtDictStreamWrite writes a dictionary to a stream.

Parameters:
dict  The RtDict to be written to the stream.
stream  The RwStream to be written to.
Returns:
A valid RtDict pointer if successful, NULL otherwise.
See also:
RtDictSchemaStreamReadDict , RtDictStreamGetSize , RwStreamOpen , RwStreamClose

Criterion Software © 1993-2004 Criterion Software Limited. All rights reserved. Built Thu Feb 12 13:47:09 2004. Send Feedback