Retrieve the value of a variable.
Declaration | Zeolite.h |
---|---|
Implementation | Zeolite.cpp |
bool zvar_GetValue(ZVAR hVar, void* pValue);
Name | Type | Comment |
---|---|---|
hVar | ZVAR | A ZVAR handle to a variable, the value of which is to be retrieved. |
pValue | void* | A user-supplied handle to an allocated block of memory for the appropriate data type, ready to receive the value from the ZVAR. |
False if:
True otherwise.
Before retrieving the value of a variable it is strongly recommended that you check the type using zvar_IsType (see example below.) This is to ensure that the variable type is what you think it is, so that your pValue handle is the correct storage type. If, for instance, you don't check the variable type and provide a pValue handle to a char data type (1 byte) when the variable is actually a long (4 bytes), you will have corrupted memory somewhere and the world may end.
Alternatively, you can use the zvar_GetValueEx function, which includes a test of the variable type.
The following variable types are not compatible with zvar_GetValue
(and zvar_SetValue, var_GetValueEx and zvar_SetValueEx):
Type | Reason |
---|---|
VarID_void | Voids contain no data, and hence no value to retrieve. |
VarID_string | Strings are stored in a funny way. Use the 'zstr_' API functions to read/write the values. |
All class types. | Class objects do not necessarily contain a single value. Use the relevant API functions to access member data instead (i.g. 'zmap_', 'zvar_', etc.). |
// get a variable called 'radius' ZVAR hVar = zvar_GetSharedVar("radius"); // check it is the correct type (a double, in this example) if(!zvar_IsType(hVar, VarID_double)) { zeoReportError("Incorrect variable type!"); return false; } // get the value using zvar_GetValue double radius; if(!zvar_GetValue(hVar, &radius)) { ReportError("Cannot retrieve variable data!"); return false; } // now use radius for something...