Retrieves the values for a given parameter from a specified Natural Access Server.
DWORD ctaGetParmByNameEx ( char addr, CTAHD ctahd, char *parmname, void *buffer, unsigned size)
|
Argument |
Description |
|
addr |
Natural Access Server address. |
|
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_IMPLEMENTED |
This function is not available in the execution mode associated with the specified context. |
|
CTAERR_NOT_INITIALIZED |
Natural Access is not initialized. Call ctaInitialize first. |
|
CTAERR_SVR_COMM |
Server communication error. |
ctaGetParmByNameEx retrieves the values for the parameter identified as parmname. If ctahd is a valid context, this function retrieves the parameters from the server associated with the context.
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 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.
If the context handle is equal to NULL_CTAHD, the function retrieves the parameters from the server specified by addr. If addr is equal to NULL or is an empty string, the function retrieves parameters from the default 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.
ctaGetParmByNameEx is intended primarily for utility applications. For example, use ctaGetParmByNameEx 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.
ctaGetParmByName, ctaGetParmID, ctaGetParmIds, ctaGetParmIdsEx, ctaGetParmInfo, ctaGetParms, ctaGetParmsEx, ctaSetParmByName, ctaSetParmByNameEx
void DemoPrintPlayGain(CTAHD ctahd)
{
INT32 playgain;
ctaGetParmByNameEx( "localhost", ctahd, "vce.play.gain",
&playgain, sizeof(playgain) );
printf( "Default vce.play.gain is %d dB\n", playgain);
}