====== var_GetValue ======

===== Description =====

Retrieve the value of a variable.

===== Function prototype =====

<code>bool CExtAPI::var_GetValue(ZVAR hVar, void* pValue);</code>


===== Arguments =====

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



===== Return value =====

False if:
  - //hVar// does not reference a valid variable (e.g. is null).
  - //pValue// is null.
  - The variable referenced by //hVar// is not initialised.
  - The variable type of //hVar// cannot be copied (see comments below.)
True otherwise.

===== Comments =====

==== Check the variable type, or use var_GetValueEx ====

Before retrieving the value of a variable it is //strongly recommended// that you check the type using [[zeolite:functions: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 [[zeolite:functions:var_GetValueEx]] function, which includes a test of the variable type. 







==== Incompatible types ====

The following variable types are not compatible with var_GetValue (and [[zeolite:functions:var_SetValue]], [[zeolite:functions:var_GetValueEx]] and [[zeolite:functions:var_SetValueEx]]):

^ Type ^ Reason |
| [[zeolite:varID:void|VarID_void]] | Voids contain no data, and hence no value to retrieve. |
| [[zeolite:varID:string|VarID_string]] | Strings are stored in a funny way. Use the str [[zeolite:functions|API functions]] to read/write the values. |
| [[zeolite:varID:map|VarID_map]] | Maps do not contain a single value. Use the map [[zeolite:functions|API functions]] instead. |
| [[zeolite:varID:varlist|VarID_varlist]] | Lists do not (necessarily) contain a single value. Use the list [[zeolite:functions|API functions]] instead. |
| [[zeolite:varID:format|VarID_format]] | Formats do not contain a single value. Use the format [[zeolite:functions|API functions]] instead. |
| [[zeolite:varID:buffer|VarID_buffer]] | Buffers do not (necessarily) contain a single value. Use the buffer [[zeolite:functions|API functions]] instead. |
| [[zeolite:varID:ComboSelector|VarID_ComboSelector]] | ComboSelector dialogs do not (necessarily) contain a single value. Use the combosel [[zeolite:functions|API functions]] instead. |
| [[zeolite:varID:ProgBox|VarID_ProgBox]] | Progress dialogs do not contain a single value. Use the progbox [[zeolite:functions|API functions]] instead. |
| [[zeolite:varID:ZeoFunc|VarID_ZeoFunc]] | Zeolite extension functions do not contain a single value. Use the zeofunc [[zeolite:functions|API functions]] instead. |

===== Example =====

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