Retrieves the values for a given parameter.
DWORD ctaGetParmByName ( CTAHD ctahd, char *parmname, void *buffer, unsigned size)
|
Argument |
Description |
|
ctahd |
Context handle that specifies the server on which commands are executed. ctahd can be a void context handle. |
|
parmname |
Pointer to a string containing the parameter name to retrieve. |
|
buffer |
Pointer to a buffer to receive parameter values. |
|
size |
Size of buffer in bytes. |
|
Return value |
Description |
|
SUCCESS |
|
|
CTAERR_BAD_ARGUMENT |
buffer is NULL. |
|
CTAERR_BAD_SIZE |
buffer is not big enough to hold the parameter field data. |
|
CTAERR_INVALID_CTAHD |
An invalid context handle was passed as an argument to a function, or the context was destroyed by another thread. |
|
CTAERR_NOT_FOUND |
parmname not found. |
|
CTAERR_NOT_INITIALIZED |
Natural Access is not initialized. Call ctaInitialize first. |
|
CTAERR_SVR_COMM |
Server communication error. |
ctaGetParmByName retrieves the values for the parameter identified as parmname. If ctahd is a valid context, this function retrieves the parameters from the context defaults.
ctahd can be a void context handle. A void context handle refers only to the server on which the commands are executed and not to any real context object. Each server has a unique void context handle. If the void context handle is equal to NULL_CTAHD, it refers to the default server.
If a void context handle is used for the ctahd parameter, this function retrieves parameters from the global defaults and is executed on the server specified by the void context handle. Global defaults are either statically defined values maintained within a process or dynamically defined values maintained by the Natural Access Server.
Natural Access writes the values to the buffer. The size argument specifies the amount of available memory at the buffer and must be large enough to contain the returned parameter value.
The parmname format is svcname[.x].structname[.fieldname]. The service name and parameter structure name must be supplied, but the extension specifier and field name are optional. If the parameter or parameter structure are extensions to the standard service parameters, the literal text .x must be included in parmname. If the field name is omitted, the complete default parameter structure is returned.
An example of parmname is vce.play.gain.
This function is intended primarily for utility applications. For example, use ctaGetParmByName to display the default value of a parameter based on its name. Use ctaGetParms to retrieve default parameter structures by ID.
Refer to Managing parameters for more information.
ctaGetParmByNameEx, ctaGetParmInfo, ctaGetParms, ctaSetEventSources
void DemoPrintPlayGain(CTAHD ctahd)
{
INT32 playgain;
ctaGetParmByName( ctahd, "vce.play.gain",
&playgain, sizeof(playgain) );
printf( "Default vce.play.gain is %d dB\n", playgain);
}