messiah_data.h


Provides functions for "attaching" data to messiah items.

Version:
1.1
Date:
6/07/03
Topics
Description
This component handles the attachment and retrieval of arbitrary user data to messiah objects and controls. See Data Attachment for a detailed description.


Defines



#define FX_DATAKEY_NAME
 Passed to fxDataCreate() or fxDataSet() as keyID when key is intended to be a named key.


API Functions



FXvoidfxDataCreate (FXentity item, FXvoid *key, FXint keyID, FXulong size)
 Allocate data and attach it to the specified messiah item.

FXvoidfxDataSet (FXentity item, FXvoid *key, FXint keyID, FXvoid *data)
 Attach data to the specified messiah item.

FXvoidfxDataGet (FXentity item, FXvoid *key, FXint keyID)
 Retrieve data from the specified messiah item.

FXint fxDataFree (FXentity item, FXvoid *key, FXint keyID)
 Free and/or detach data from the specified messiah item.

FXint fxDataFreeKey (FXentity item, FXvoid *key)
 Free and/or detach all data on a key from the specified messiah item.


Function Documentation

FXvoid* fxDataCreate FXentity    item,
FXvoid   key,
FXint    keyID,
FXulong    size
 

Allocate data and attach it to the specified messiah item.

Parameters:
item [in] item to attach data to
key [in] unique key value
keyID [in] key index
size [in] size in bytes to allocate
Return values:
FXvoid* to allocated data
NULL on failure
This function will allocate a block of data of the size specified. Once allocated the data will be attached to the messiah item passed as item. The data will be automatically freed when the item is deleted, however if you wish to free the data at some point prior to the object's deletion you can use the fxDataFree() function.

Attached data is identified by a key which must be unique, it is recommended that you use the address of a global variable as this will be unique to all plugins. You can store multiple pieces of data under a given key, each of these data will be identified by the keyID param. If you wish to use a name for a key, you may pass an FXchar* as key and the constant FX_DATAKEY_NAME as keyID. This will indicate that the string is to be used as the key rather than the address. Of course with this option you are limited to one entry per key.

See also:
Data Attachment, Simple Bones Tutorial

FXint fxDataFree FXentity    item,
FXvoid   key,
FXint    keyID
 

Free and/or detach data from the specified messiah item.

Parameters:
item [in] item to remove data from
key [in] unique key value
keyID [in] key index
Return values:
FXvoid* to data
NULL on failure
If the data was originally attached using fxDataCreate() then this function will cause it to be freed prior to being detached from the item. However if the data was attached using fxDataSet() it will only be detached and it is left to you to free the data yourself.

See also:
Data Attachment, Simple Bones Tutorial

FXint fxDataFreeKey FXentity    item,
FXvoid   key
 

Free and/or detach all data on a key from the specified messiah item.

Parameters:
item [in] item to remove data from
key [in] unique key value
Return values:
FXvoid* to data
NULL on failure
Unlike fxDataFree(), this function will remove all data on a given key, regardless of it's keyID. If the data was originally attached using fxDataCreate() then this function will cause it to be freed prior to being detached from the item. However if the data was attached using fxDataSet() it will only be detached and it is left to you to free the data yourself.

See also:
Data Attachment, Simple Bones Tutorial

FXvoid* fxDataGet FXentity    item,
FXvoid   key,
FXint    keyID
 

Retrieve data from the specified messiah item.

Parameters:
item [in] item to get data from
key [in] unique key value
keyID [in] key index
Return values:
FXvoid* to data
NULL on failure
Given the specified key/keyID combination the data that is stored there will be returned. If no data exists there NULL will be returned.

See also:
Data Attachment, Simple Bones Tutorial

FXvoid* fxDataSet FXentity    item,
FXvoid   key,
FXint    keyID,
FXvoid   data
 

Attach data to the specified messiah item.

Parameters:
item [in] item to attach data to
key [in] unique key value
keyID [in] key index
data [in] data to attach
Return values:
FXvoid* to attached data
NULL on failure
Unlike fxDataCreate(), this function will not allocate data, it is used for attaching existing data. The data will be attached to the messiah item passed as item. To remove the attached data from the item use fxDataFree(), since the data was attached with fxDataSet() messiah will not attampt to free the data, it will simply detach it from the item. It is your responsibility to free the data.

Attached data is identified by a key which must be unique, it is recommended that you use the address of a global variable as this will be unique to all plugins. You can store multiple pieces of data under a given key, each of these data will be identified by the keyID param. If you wish to use a name for a key, you may pass an FXchar* as key and the constant FX_DATAKEY_NAME as keyID. This will indicate that the string is to be used as the key rather than the address. Of course with this option you are limited to one entry per key.

See also:
Data Attachment, Simple Bones Tutorial


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

Last Updated on Thu Jul 10 04:49:36 2003