365 lines
9.8 KiB
C
365 lines
9.8 KiB
C
/*** variable.h - Definitions for Variable Manager
|
|
*
|
|
* Microsoft Confidential
|
|
* Copyright (C) Microsoft Corporation 1993-1994
|
|
* All Rights Reserved.
|
|
*
|
|
* Author:
|
|
* Benjamin W. Slivka
|
|
*
|
|
* History:
|
|
* 10-Aug-1993 bens Initial version
|
|
* 21-Aug-1993 bens Added variable lists
|
|
* 11-Feb-1994 bens VarSet creates new VARIABLE if necessary
|
|
* 20-Apr-1994 bens Pass hvlist to variable validation functions
|
|
* 03-Jun-1994 bens Added list traversal, get/set flags, get name
|
|
*
|
|
* Exported Functions:
|
|
* VarCreateList - Create a list of variables
|
|
* VarCloneList - Create an exact copy of a variable list
|
|
* VarDestroyList - Destroy a list of variables
|
|
*
|
|
* VarCreate - Create a variable
|
|
* VarDelete - Delete existing variable
|
|
* VarFind - See if variable exists
|
|
*
|
|
* VarGetBool - Get value of boolean variable
|
|
* VarGetInt - Get value of int variable
|
|
* VarGetLong - Get value of long variable
|
|
* VarGetString - Get value of string variable
|
|
*
|
|
* VarSet - Set value of a variable (create if necessary)
|
|
* VarSetLong - Set long variable value (create if necessary)
|
|
*
|
|
* VarFirstVar - Get first variable from list
|
|
* VarGetFlags - Get variable flags
|
|
* VarSetFlags - Set variable flags
|
|
* VarGetName - Get name of variable
|
|
* VarNextVar - Get next variable
|
|
*/
|
|
|
|
#ifndef INCLUDED_VARIABLE
|
|
#define INCLUDED_VARIABLE 1
|
|
|
|
#include "types.h"
|
|
#include "asrt.h"
|
|
#include "error.h"
|
|
|
|
//** cbVAR_NAME_MAX - Maximum length of a variable name, including NULL
|
|
#define cbVAR_NAME_MAX 32
|
|
|
|
//** cbVAR_VALUE_MAX - Maximum length of a variable value, including NULL
|
|
#define cbVAR_VALUE_MAX 256
|
|
|
|
|
|
typedef void * HVARLIST; /* hvlist - list of variables */
|
|
typedef void * HVARIABLE; /* hvar - VARIABLE handle */
|
|
typedef unsigned VARFLAGS; /* vfl - VARIABLE flags */
|
|
#define vflNONE 0x00 // VARIABLE is not special
|
|
#define vflPERM 0x01 // VARIABLE cannot be deleted
|
|
#define vflDEFINE 0x02 // VARIABLE was .Defined
|
|
#define vflCOPY 0x04 // VARIABLE needs to be copied
|
|
|
|
typedef enum {
|
|
vtypeBAD, // Invalid type
|
|
vtypeCHAR, // Character type
|
|
vtypeINT, // Integer
|
|
vtypeBOOL, // Boolean
|
|
vtypeLONG, // Long
|
|
vtypeSTR, // String
|
|
} VARTYPE; /* vtype - VARIABLE type */
|
|
|
|
|
|
/*** PFNVCVALIDATE - Function type for VarCreate validation
|
|
*** FNVCVALIDATE - macro to help define VarCreate validation function
|
|
*
|
|
* Entry:
|
|
* hvlist - Variable list for this variable
|
|
* pszName - Variable name
|
|
* pszValue - Value to check for validity
|
|
* pszNewValue - Buffer to receive validated value
|
|
* perr - ERROR structure
|
|
*
|
|
* Exit-Success:
|
|
* Returns TRUE, value is valid for variable.
|
|
* pszNewValue filled in with desired value.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns FALSE, value is not valid for variable.
|
|
* ERROR structure filled in with details of error.
|
|
*
|
|
* Notes:
|
|
* (1) The validation function may reenter the Variable Manager with
|
|
* any call that does not add or remove variables.
|
|
*/
|
|
typedef BOOL (*PFNVCVALIDATE)(HVARLIST hvlist,
|
|
char *pszName,
|
|
char *pszValue,
|
|
char *pszNewValue,
|
|
PERROR perr);
|
|
#define FNVCVALIDATE(fn) BOOL fn(HVARLIST hvlist, \
|
|
char *pszName, \
|
|
char *pszValue, \
|
|
char *pszNewValue, \
|
|
PERROR perr)
|
|
|
|
|
|
/*** VarCreate - Create a variable
|
|
*
|
|
* Entry:
|
|
* hvlist - Variable list to check
|
|
* pszName - Variable name
|
|
* pszValue - Initial value
|
|
* vtype - Type of variable
|
|
* vfl - Special variable flags
|
|
* pfnvcv - Validation function
|
|
* perr - ERROR structure
|
|
*
|
|
* Exit-Success:
|
|
* Returns HVAR, variable is created.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns NULL, cannot create variable.
|
|
* ERROR structure filled in with details of error.
|
|
*/
|
|
HVARIABLE VarCreate(HVARLIST hvlist,
|
|
char *pszName,
|
|
char *pszDefaultValue,
|
|
VARTYPE vtype,
|
|
VARFLAGS vfl,
|
|
PFNVCVALIDATE pfnvcv,
|
|
PERROR perr);
|
|
|
|
|
|
/*** VarCreateList - Create a list of variables
|
|
*
|
|
* Entry:
|
|
* perr - ERROR structure
|
|
*
|
|
* Exit-Success:
|
|
* Returns HVARLIST; list is created.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns NULL, cannot create list; perror filled in with error.
|
|
*/
|
|
HVARLIST VarCreateList(PERROR perr);
|
|
|
|
|
|
/*** VarCloneList - Create an exact copy of a variable list
|
|
*
|
|
* Entry:
|
|
* hvlist - Variable list to clone
|
|
* perr - ERROR structure
|
|
*
|
|
* Exit-Success:
|
|
* Returns new HVARLIST; list was copied.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns NULL, cannot copy list; perror filled in with error.
|
|
*/
|
|
HVARLIST VarCloneList(HVARLIST hvlist, PERROR perr);
|
|
|
|
|
|
/*** VarDestroyList - Destroy a list of variables
|
|
*
|
|
* Entry:
|
|
* hvlist - Variable list to destroy
|
|
* perr - ERROR structure
|
|
*
|
|
* Exit-Success:
|
|
* Returns TRUE; list was destroyed.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns FALSE, cannot destroy list; perror filled in with error.
|
|
*/
|
|
BOOL VarDestroyList(HVARLIST hvlist, PERROR perr);
|
|
|
|
|
|
/*** VarSet - Set value of a variable (create if necessary)
|
|
*
|
|
* Entry:
|
|
* hvlist - Variable list
|
|
* pszName - Variable name
|
|
* pszValue - New value
|
|
* perr - ERROR structure
|
|
*
|
|
* Exit-Success:
|
|
* Returns HVARIABLE, variable is created (if necessary) and value set.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns NULL, cannot set variable value.
|
|
* ERROR structure filled in with details of error.
|
|
*/
|
|
HVARIABLE VarSet(HVARLIST hvlist,
|
|
char *pszName,
|
|
char *pszValue,
|
|
PERROR perr);
|
|
|
|
|
|
/*** VarSetLong - Set long variable value (create if necessary)
|
|
*
|
|
* Entry:
|
|
* hvlist - Variable list
|
|
* pszName - Variable name
|
|
* lValue - New value
|
|
* perr - ERROR structure
|
|
*
|
|
* Exit-Success:
|
|
* Returns TRUE, variable is created (if necessary) and value set.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns FALSE, cannot set variable value.
|
|
* ERROR structure filled in with details of error.
|
|
*/
|
|
BOOL VarSetLong(HVARLIST hvlist,
|
|
char *pszName,
|
|
long lValue,
|
|
PERROR perr);
|
|
|
|
|
|
/*** VarFind - See if variable exists
|
|
*
|
|
* Entry:
|
|
* hvlist - Variable list
|
|
* pszName - Variable name to look for
|
|
* perr - ERROR structure
|
|
*
|
|
* Exit-Success:
|
|
* Returns HVAR, if variable exists.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns NULL, variable does not exist.
|
|
* ERROR structure filled in with details of error.
|
|
*/
|
|
HVARIABLE VarFind(HVARLIST hvlist,
|
|
char *pszName,
|
|
PERROR perr);
|
|
|
|
|
|
/*** VarDelete - Delete existing variable
|
|
*
|
|
* Entry:
|
|
* hvar - Variable handle
|
|
*
|
|
* Exit-Success:
|
|
* Always works, since hvar is valid.
|
|
*/
|
|
void VarDelete(HVARIABLE hvar);
|
|
|
|
|
|
/*** VarGetBool - Get value of boolean variable
|
|
*
|
|
* Entry:
|
|
* hvar - Variable handle
|
|
*
|
|
* Exit-Success:
|
|
* Returns value of variable (TRUE or FALSE)
|
|
*/
|
|
BOOL VarGetBool(HVARIABLE hvar);
|
|
|
|
|
|
/*** VarGetInt - Get value of int variable
|
|
*
|
|
* Entry:
|
|
* hvar - Variable handle
|
|
*
|
|
* Exit-Success:
|
|
* Returns value of variable (int)
|
|
* NOTE: If variable is a long, return value is undefined.
|
|
* If variable is a BOOL, return value is 0 or 1.
|
|
* If variable is a string, return value is atoi(string)
|
|
*/
|
|
int VarGetInt(HVARIABLE hvar);
|
|
|
|
|
|
/*** VarGetLong - Get value of long variable
|
|
*
|
|
* Entry:
|
|
* hvar - Variable handle
|
|
*
|
|
* Exit-Success:
|
|
* Returns value of variable (long)
|
|
* NOTE: If variable is a int, return value is cast to a long
|
|
* If variable is a BOOL, return value is 0 or 1.
|
|
* If variable is a string, return value is atol(string)
|
|
*/
|
|
long VarGetLong(HVARIABLE hvar);
|
|
|
|
|
|
/*** VarGetString - Get value of string variable
|
|
*
|
|
* Entry:
|
|
* hvar - Variable handle
|
|
*
|
|
* Exit-Success:
|
|
* Returns pointer to value of variable.
|
|
* NOTE: Caller may not modify variable value directly!
|
|
*/
|
|
char *VarGetString(HVARIABLE hvar);
|
|
|
|
|
|
/*** VarSetFlags - Set variable flags
|
|
*
|
|
* Entry:
|
|
* hvar - Variable handle
|
|
* vfl - New value for variable flags
|
|
*
|
|
* Exit-Success:
|
|
* Variable flags are updated.
|
|
*/
|
|
void VarSetFlags(HVARIABLE hvar,
|
|
VARFLAGS vfl);
|
|
|
|
|
|
/*** VarGetFlags - Get variable flags
|
|
*
|
|
* Entry:
|
|
* hvar - Variable handle
|
|
*
|
|
* Exit-Success:
|
|
* Returns variable flags.
|
|
*/
|
|
VARFLAGS VarGetFlags(HVARIABLE hvar);
|
|
|
|
|
|
/*** VarFirstVar - Get first variable from list
|
|
*
|
|
* Entry:
|
|
* hvlist - Variable list
|
|
*
|
|
* Exit-Success:
|
|
* Returns HVARIABLE of first variable in list.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns NULL; hglist is bad or empty.
|
|
*/
|
|
HVARIABLE VarFirstVar(HVARLIST hvlist);
|
|
|
|
|
|
/*** VarNextVar - Get next variable
|
|
*
|
|
* Entry:
|
|
* hvar - Variable handle
|
|
*
|
|
* Exit-Success:
|
|
* Returns HVARIABLE of next variable following hvar in list.
|
|
*
|
|
* Exit-Failure:
|
|
* Returns NULL; no more variables
|
|
*/
|
|
HVARIABLE VarNextVar(HVARIABLE hvar);
|
|
|
|
|
|
/*** VarGetName - Get name of variable
|
|
*
|
|
* Entry:
|
|
* hvar - Variable handle
|
|
*
|
|
* Exit-Success:
|
|
* Returns pointer to name of variable.
|
|
* NOTE: Caller may not modify the name directly!
|
|
*/
|
|
char *VarGetName(HVARIABLE hvar);
|
|
|
|
#endif // !INCLUDED_VARIABLE
|