ENV_GetXXX

# ENV_Get*

## C Specification

      #include <nitro/env.h>

      BOOL ENV_GetS8( const char* name, s8* retVal );
      BOOL ENV_GetU8( const char* name, u8* retVal );
      BOOL ENV_GetS16( const char* name, s16* retVal );
      BOOL ENV_GetU16( const char* name, u16* retVal );
      BOOL ENV_GetS32( const char* name, s32* retVal );
      BOOL ENV_GetU32( const char* name, u32* retVal );
      BOOL ENV_GetS64( const char* name, s64* retVal );
      BOOL ENV_GetU64( const char* name, u64* retVal );
      BOOL ENV_GetBOOL( const char* name, BOOL* retVal );

      BOOL ENV_GetString( const char* name, char** retPtr );
      BOOL ENV_GetStringAndLength( const char* name, char** retPtr, int* length );
      BOOL ENV_GetBinary( const char* name, void** retPtr );
      BOOL ENV_GetBinaryEAndSize( const char* name, void** retPtr, int* size );

## Arguments

name | The pointer to the resource name. If this character string begins with a "`.`" (period), the class name is considered to be omitted and the current class is filled in before that period.
length | This is the pointer used to store the character string length when getting a character string resource.
retVal | This is the pointer used to store the obtained resource.
retPtr | This is the pointer used to store the pointer to the obtained resource.
size | This is the pointer used to store the size when getting a binary resource.

## Return Values

Returns whether or not the resource was successfully obtained. Returns TRUE if successful. Returns FALSE if the specified resource does not exist.

## Description

Gets the specified resource value.

`name` is the resource name. This function searches for a resource with the same resource name defined. If `name` begins with a period ("`.`"), the current class set with `ENV_SetClass()` is filled in before that period.

> Example:
> The following two examples return the same values.
> //(1)
> ENV_GetU32( "MYCLASS.U32VALUE", &retVal );
> // (2)
> ENV_SetClass( "MYCLASS" );
> ENV_GetU32( ".U32VALUE", &retVal );

Searches are performed on all resource arrays registered in the system. If there are resources with identical resource names, the first one found according to the list order within the system is returned.

`ENV_GetS8()` gets a value of an s8 type. Be sure to define the resource with `ENV_S8()`.
`ENV_GetU8()` gets a value of a u8 type. Be sure to define the resource with `ENV_U8()`.
`ENV_GetS16()` gets a value of an s16 type. Be sure to define the resource with `ENV_S16()`.
`ENV_GetU16()` gets a value of a u16 type. Be sure to define the resource with `ENV_U16()`.
`ENV_GetS32()` gets a value of an s32 type. Be sure to define the resource with `ENV_S32()`.
`ENV_GetU32()` gets a value of a u32 type. Be sure to define the resource with `ENV_U32()`.
`ENV_GetS64()` gets a value of an s64 type. Define the resource with `ENV_S64()`.
`ENV_GetU64()` gets a value of a u64 type. Define the resource with `ENV_U64()`.
`ENV_GetBOOL()` gets a value of a BOOL type. Be sure to define the resource with `ENV_BOOL()`.
The obtained value is always either TRUE or FALSE. (In other words, the value will be TRUE even when the stored value is a non-zero value that indicates other than TRUE.)

The obtained value is stored in the place where `retVal` points to. If the value was obtained, the return value is TRUE. If the value was not obtained, the return value is FALSE and a 0 will be assigned in the place where `retVal` points to.

`ENV_GetString()` gets the pointer to the character string as a `char*` type. Be sure to define the resource with `ENV_STRING()`. The obtained pointer is stored in the the place where `retPtr` points to. If the pointer was obtained, TRUE is returned. If not, FALSE is returned. The value that is stored is a NULL value. `ENV_GetStringAndLength()` stores the same content as `ENV_GetString()` as well as the length of the string in the place where `length` points to.

`ENV_GetBinary()` gets the pointer to the binary data as a `void*` type. Be sure to define the resource with `ENV_BINARY()`. The obtained pointer is stored in the the place where `retPtr` points to. If the pointer was obtained, TRUE is returned. If not, FALSE is returned. The value that is stored is a NULL value. `ENV_GetBinaryAndSize()` stores the binary data size in `size` in addition to the content stored with `ENV_GetBinary()`.

## See Also

`ENV_Init, ENV_GetSize, ENV_GetType, ENV_SetClass`

## Revision History

08/29/2005 Revised description mistakes in function names.
08/23/2005 Changed the method for obtaining resource values.
08/16/2005 Initial version.