Retrieve the value of a variable.
bool CExtAPI::var_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 var_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 var_GetValueEx function, which includes a test of the variable type.
The following variable types are not compatible with var_GetValue (and var_SetValue, var_GetValueEx and var_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 str API functions to read/write the values. |
VarID_map | Maps do not contain a single value. Use the map API functions instead. |
VarID_varlist | Lists do not (necessarily) contain a single value. Use the list API functions instead. |
VarID_format | Formats do not contain a single value. Use the format API functions instead. |
VarID_buffer | Buffers do not (necessarily) contain a single value. Use the buffer API functions instead. |
VarID_ComboSelector | ComboSelector dialogs do not (necessarily) contain a single value. Use the combosel API functions instead. |
VarID_ProgBox | Progress dialogs do not contain a single value. Use the progbox API functions instead. |
VarID_ZeoFunc | Zeolite extension functions do not contain a single value. Use the zeofunc API functions instead. |
// get a variable called 'radius' ZVAR hVar = theAPI.var_GetVar("radius"); // check it is the correct type (a double, in this example) if(!theAPI.var_IsType(hVar, VarID_double)) { ReportError("Incorrect variable type!"); return false; } // get the value using var_GetValue double radius; if(!theAPI.var_GetValue(hVar, &radius)) { ReportError("Cannot retrieve variable data!"); return false; } // now use radius for something...