var_GetValue

Retrieve the value of a variable.

bool CExtAPI::var_GetValue(ZVAR hVar, void* pValue);

False if:

1. hVar does not reference a valid variable (e.g. is null).
2. pValue is null.
3. The variable referenced by hVar is not initialised.
4. The variable type of hVar cannot be copied (see comments below.)

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):

// 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...