====== zvar_GetValue ======

===== Description =====

Retrieve the value of a variable.

===== Files =====

^ Declaration | ''Zeolite.h'' |
^ Implementation | ''Zeolite.cpp'' |

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

<code="C">bool zvar_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: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 [[zeolite:functions:zvar_GetValueEx]] function, which includes a test of the variable type. 


==== Incompatible types ====

The following [[zeolite:varID|variable types]] are not compatible with ''zvar_GetValue'' (and [[zeolite:functions:zvar_SetValue]], [[zeolite:functions:var_GetValueEx]] and [[zeolite:functions: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_' [[zeolite:functions|API functions]] to read/write the values. |
| All [[zeolite:varid#classes|class]] types. | Class objects do not necessarily contain a single value. Use the relevant [[zeolite:functions|API functions]] to access member data instead (i.g. 'zmap_', 'zvar_', etc.). |

===== Example =====

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