Csound and CsoundAC API  5.17
Data Structures | Macros | Typedefs | Functions
cfgvar.h File Reference

Data Structures

union  csCfgVariable_u
struct  csCfgVariableBoolean_s
struct  csCfgVariableDouble_s
struct  csCfgVariableFloat_s
struct  csCfgVariableHead_s
struct  csCfgVariableInt_s
struct  csCfgVariableMYFLT_s
struct  csCfgVariableString_s

Macros

#define CSOUNDCFG_BOOLEAN   2
#define CSOUNDCFG_DOUBLE   4
#define CSOUNDCFG_FLOAT   3
#define CSOUNDCFG_INTEGER   1
#define CSOUNDCFG_INVALID_BOOLEAN   -8
#define CSOUNDCFG_INVALID_FLAG   -3
#define CSOUNDCFG_INVALID_NAME   -1
#define CSOUNDCFG_INVALID_TYPE   -2
#define CSOUNDCFG_LASTERROR   -10
#define CSOUNDCFG_MEMORY   -9
#define CSOUNDCFG_MYFLT   5
#define CSOUNDCFG_NOT_POWOFTWO   -7
#define CSOUNDCFG_NULL_POINTER   -4
#define CSOUNDCFG_POWOFTWO   0x00000001
#define CSOUNDCFG_STRING   6
#define CSOUNDCFG_STRING_LENGTH   -10
#define CSOUNDCFG_SUCCESS   0
#define CSOUNDCFG_TOO_HIGH   -5
#define CSOUNDCFG_TOO_LOW   -6

Typedefs

typedef union csCfgVariable_u csCfgVariable_t
typedef struct
csCfgVariableBoolean_s 
csCfgVariableBoolean_t
typedef struct
csCfgVariableDouble_s 
csCfgVariableDouble_t
typedef struct csCfgVariableFloat_s csCfgVariableFloat_t
typedef struct csCfgVariableHead_s csCfgVariableHead_t
typedef struct csCfgVariableInt_s csCfgVariableInt_t
typedef struct csCfgVariableMYFLT_s csCfgVariableMYFLT_t
typedef struct
csCfgVariableString_s 
csCfgVariableString_t

Functions

PUBLIC const char * csoundCfgErrorCodeToString (int errcode)
 Remove all global configuration variables and free database.
PUBLIC int csoundCreateConfigurationVariable (CSOUND *csound, const char *name, void *p, int type, int flags, void *min, void *max, const char *shortDesc, const char *longDesc)
 Create global configuration variable with the specified parameters.
PUBLIC void csoundDeleteCfgVarList (csCfgVariable_t **lst)
 Release a configuration variable list previously returned by csoundListGlobalConfigurationVariables() or csoundListConfigurationVariables().
PUBLIC int csoundDeleteConfigurationVariable (CSOUND *csound, const char *name)
 Remove the global configuration variable with the specified name from the database.
PUBLIC csCfgVariable_t ** csoundListConfigurationVariables (CSOUND *csound)
 Create an alphabetically sorted list of all global configuration variables.
PUBLIC int csoundParseConfigurationVariable (CSOUND *csound, const char *name, const char *value)
 Set the value of a global configuration variable, by parsing a string; should be called by the host application only.
PUBLIC csCfgVariable_tcsoundQueryConfigurationVariable (CSOUND *csound, const char *name)
 Return pointer to the global configuration variable with the specified name.
PUBLIC int csoundSetConfigurationVariable (CSOUND *csound, const char *name, void *value)
 Copy a global configuration variable to a Csound instance.

Macro Definition Documentation

#define CSOUNDCFG_BOOLEAN   2
#define CSOUNDCFG_DOUBLE   4
#define CSOUNDCFG_FLOAT   3
#define CSOUNDCFG_INTEGER   1
#define CSOUNDCFG_INVALID_BOOLEAN   -8
#define CSOUNDCFG_INVALID_FLAG   -3
#define CSOUNDCFG_INVALID_NAME   -1
#define CSOUNDCFG_INVALID_TYPE   -2
#define CSOUNDCFG_LASTERROR   -10
#define CSOUNDCFG_MEMORY   -9
#define CSOUNDCFG_MYFLT   5
#define CSOUNDCFG_NOT_POWOFTWO   -7
#define CSOUNDCFG_NULL_POINTER   -4
#define CSOUNDCFG_POWOFTWO   0x00000001
#define CSOUNDCFG_STRING   6
#define CSOUNDCFG_STRING_LENGTH   -10
#define CSOUNDCFG_SUCCESS   0
#define CSOUNDCFG_TOO_HIGH   -5
#define CSOUNDCFG_TOO_LOW   -6

Typedef Documentation

Function Documentation

PUBLIC const char* csoundCfgErrorCodeToString ( int  errcode)

Remove all global configuration variables and free database.

Should be called by the host application only, and never by the Csound library or plugins. Return value is CSOUNDCFG_SUCCESS in case of success. Returns pointer to an error string constant for the specified CSOUNDCFG error code. The string is not translated.

PUBLIC int csoundCreateConfigurationVariable ( CSOUND csound,
const char *  name,
void *  p,
int  type,
int  flags,
void *  min,
void *  max,
const char *  shortDesc,
const char *  longDesc 
)

Create global configuration variable with the specified parameters.

This function should be called by the host application only. name: name of the variable (may contain letters, digits, and _) p: pointer to variable type: type of variable, determines how 'p' is interpreted CSOUNDCFG_INTEGER: int* CSOUNDCFG_BOOLEAN: int* (value may be 0 or 1) CSOUNDCFG_FLOAT: float* CSOUNDCFG_DOUBLE: double* CSOUNDCFG_MYFLT: MYFLT* CSOUNDCFG_STRING: char* (should have enough space) flags: bitwise OR of flag values, currently only CSOUNDCFG_POWOFTWO is available, which requests CSOUNDCFG_INTEGER values to be power of two min: for CSOUNDCFG_INTEGER, CSOUNDCFG_FLOAT, CSOUNDCFG_DOUBLE, and CSOUNDCFG_MYFLT, a pointer to a variable of the type selected by 'type' that specifies the minimum allowed value. If 'min' is NULL, there is no minimum value. max: similar to 'min', except it sets the maximum allowed value. For CSOUNDCFG_STRING, it is a pointer to an int variable that defines the maximum length of the string (including the null character at the end) in bytes. This value is limited to the range 8 to 16384, and if max is NULL, it defaults to 256. shortDesc: a short description of the variable (may be NULL or an empty string if a description is not available) longDesc: a long description of the variable (may be NULL or an empty string if a description is not available) Return value is CSOUNDCFG_SUCCESS, or one of the following error codes: CSOUNDCFG_INVALID_NAME the specified name is invalid or is already in use CSOUNDCFG_MEMORY a memory allocation failure occured CSOUNDCFG_NULL_POINTER the 'p' pointer was NULL CSOUNDCFG_INVALID_TYPE CSOUNDCFG_INVALID_FLAG an invalid variable type was specified, or the flags value had unknown bits set This function is similar to csoundCreateGlobalConfigurationVariable(), except it creates a configuration variable specific to Csound instance 'csound', and is suitable for calling from the Csound library (in csoundPreCompile()) or plugins (in csoundModuleCreate()). The other parameters and return value are the same as in the case of csoundCreateGlobalConfigurationVariable().

PUBLIC void csoundDeleteCfgVarList ( csCfgVariable_t **  lst)

Release a configuration variable list previously returned by csoundListGlobalConfigurationVariables() or csoundListConfigurationVariables().

PUBLIC int csoundDeleteConfigurationVariable ( CSOUND csound,
const char *  name 
)

Remove the global configuration variable with the specified name from the database.

Should be called by the host application only, and never by the Csound library or plugins. Return value is CSOUNDCFG_SUCCESS in case of success, or CSOUNDCFG_INVALID_NAME if the variable was not found. Remove the configuration variable of Csound instance 'csound' with the specified name from the database. Plugins need not call this, as all configuration variables are automatically deleted by csoundReset(). Return value is CSOUNDCFG_SUCCESS in case of success, or CSOUNDCFG_INVALID_NAME if the variable was not found.

PUBLIC csCfgVariable_t** csoundListConfigurationVariables ( CSOUND csound)

Create an alphabetically sorted list of all global configuration variables.

Returns a pointer to a NULL terminated array of configuration variable pointers, or NULL on error. The caller is responsible for freeing the returned list with csoundDeleteCfgVarList(), however, the variable pointers in the list should not be freed. Create an alphabetically sorted list of all configuration variables of Csound instance 'csound'. Returns a pointer to a NULL terminated array of configuration variable pointers, or NULL on error. The caller is responsible for freeing the returned list with csoundDeleteCfgVarList(), however, the variable pointers in the list should not be freed.

PUBLIC int csoundParseConfigurationVariable ( CSOUND csound,
const char *  name,
const char *  value 
)

Set the value of a global configuration variable, by parsing a string; should be called by the host application only.

For boolean variables, any of the strings "0", "no", "off", and "false" will set the value to 0, and any of "1", "yes", "on", and "true" means a value of 1. Return value is CSOUNDCFG_SUCCESS in case of success, or one of the following error codes: CSOUNDCFG_INVALID_NAME no configuration variable was found with the specified name CSOUNDCFG_NULL_POINTER the 'value' pointer was NULL CSOUNDCFG_TOO_LOW CSOUNDCFG_TOO_HIGH CSOUNDCFG_NOT_POWOFTWO CSOUNDCFG_INVALID_BOOLEAN CSOUNDCFG_STRING_LENGTH the specified value was invalid in some way Set the value of a configuration variable of Csound instance 'csound', by parsing a string. The 'name' and 'value' parameters, and return value are the same as in the case of csoundParseGlobalConfigurationVariable().

PUBLIC csCfgVariable_t* csoundQueryConfigurationVariable ( CSOUND csound,
const char *  name 
)

Return pointer to the global configuration variable with the specified name.

The return value may be NULL if the variable is not found in the database. Return pointer to the configuration variable of Csound instace 'csound' with the specified name. The return value may be NULL if the variable is not found in the database.

PUBLIC int csoundSetConfigurationVariable ( CSOUND csound,
const char *  name,
void *  value 
)

Copy a global configuration variable to a Csound instance.

This function is experimental and may be subject to changes in future releases of the Csound library. Copy all global configuration variables to the specified Csound instance. This function is experimental and may be subject to changes in future releases of the Csound library. Set the value of a global configuration variable; should be called by the host application only. 'value' is a pointer of the same type as the 'p' pointer that was passed to csoundCreateGlobalConfigurationVariable(), depending on the type of the variable (integer, float, etc.). Return value is CSOUNDCFG_SUCCESS in case of success, or one of the following error codes: CSOUNDCFG_INVALID_NAME no configuration variable was found with the specified name CSOUNDCFG_NULL_POINTER the 'value' pointer was NULL CSOUNDCFG_TOO_LOW CSOUNDCFG_TOO_HIGH CSOUNDCFG_NOT_POWOFTWO CSOUNDCFG_INVALID_BOOLEAN CSOUNDCFG_STRING_LENGTH the specified value was invalid in some way Set the value of a configuration variable of Csound instance 'csound'. The 'name' and 'value' parameters, and return value are the same as in the case of csoundSetGlobalConfigurationVariable().