ctaGetParmInfoEx

Retrieves a parameter field definition on a particular Natural Access Server.

Prototype

DWORD ctaGetParmInfoEx ( CTAHD ctahd, unsigned parmid, char *parmname, unsigned index, CTA_PARM_INFO *buffer)

Argument	Description
ctahd	Context handle that specifies the server on which commands are executed. ctahd can be a void context handle.
parmid	Parameter structure ID.
parmname	Pointer to the parameter name (use NULL if the parmid specifies a valid parameter ID).
index	Relative field within the parameter structure.
buffer	Pointer to a buffer to receive a copy of CTA_PARM_INFO for the specified parameters. The CTA_PARM_INFO structure is: typedef struct { char structname[40]; char fieldname[40]; DWORD offset; DWORD size; DWORD format; DWORD units; } CTA_PARM_INFO; See the Details section for a description of these fields.

Return values

Return value	Description
SUCCESS
CTAERR_BAD_ARGUMENT	buffer is NULL, or parmname is NULL and parmid is zero (0).
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_NOT_FOUND	parmname is not found, parmid is invalid, or index is out of range.
CTAERR_NOT_INITIALIZED	Natural Access is not initialized. Call ctaInitialize first.
CTAERR_SVR_COMM	Server communication error.

Details

ctaGetParmInfoEx retrieves a field definition conveyed as a CTA_PARM_INFO structure. The parameter structure can be specified either by parmname or parmid.

If parmname is non-NULL, Natural Access searches for the parameter structure therein. 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 not supplied in parmname, Natural Access uses index as the field selector. The first field within the structure is indexed as zero (0), the second as one (1), and so on.

If parmname is NULL, parmid is used to retrieve the parameter structure and index is used as the field selector. The parameter IDs are defined in the service header file (for example, vcedef.h).

The IDs are usually of the following form: SERVICENAME[_X]_STRUCTNAME_PARMID.

The service name is the same name referenced in ctaInitialize and ctaOpenServices. If the structure references non-standard service extension parameters, the _X is used to distinguish these non-standard structures. An example of a standard structure parmid is VCE_PLAY_PARMID.

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.

The returned CTA_PARM_INFO structure contains the following fields:

Field	Description
structname	The parameter's structure name. Use when using parmid.
fieldname	The parameter's field name.
offset	The value's offset in the parameter structure.
size	The parameter's value size (bytes).
format	The parameter's value format. Refer to the format table.
units	The parameter's value units. Refer to the unit table.

The following formats are supported:

Format	Description
CTA_FMT_WORD	Field is a 16-bit unsigned quantity.
CTA_FMT_DWORD	Field is a 32-bit unsigned quantity.
CTA_FMT_INT16	Field is a 16-bit signed quantity.
CTA_FMT_INT32	Field is a 32-bit signed quantity.
CTA_FMT_STRING	Field is a NULL-terminated string.
CTA_FMT_UNKNOWN	Field contains an unknown format.

The following units are supported:

Format	Description
CTA_UNITS_INTERNAL	No engineering units available.
CTA_UNITS_INTEGER	Field is a count or an index.
CTA_UNITS_COUNT	Field is a number of something.
CTA_UNITS_MASK	Field is a bit mask.
CTA_UNITS_HZ	Field is a measurement of frequency, in Hz.
CTA_UNITS_MS	Field is measured in milliseconds.
CTA_UNITS_DB	Field is a relative signal level, measured in dB.
CTA_UNITS_DBM	Field is an absolute signal level.
CTA_UNITS_IDU	Field is in internal DSP units (NMS internal representation for amplitude).
CTA_UNITS_STRING	Field contains a string.
CTA_UNITS_PERCENT	Field contains a percentage (where 100 is 100 percent).

Refer to Managing parameters for more information.

Example

void myShowParmInfo( char *parmname )
{
    CTA_PARM_INFO info;
    BYTE temp[100];     /* temp storage for parm value */
    union
    {
        WORD  w;
        DWORD W;
        INT16 i;
        INT32 I;
        char  s[80];
    } *pdata =( void* ) temp;
    char *punits;

    CTAHD void_ctahd;
    /* Server name descriptor  */
    char server_desc[] = "host.nmss.com:2244";
    /* Create a void context handle */
    ctaCreateContext(NULL_CTAQUEUEHD, 0, server_desc, &void_ctahd);

    if( ctaGetParmInfoEx( void_ctahd, 0, parmname, 0, &info ) != SUCCESS
        || ctaGetParmByName(NULL_CTAHD, parmname, &temp, sizeof( temp) )
        != SUCCESS )
        {
            /* display error */
            return;
        }

    switch( info.units )
        {
        case CTA_UNITS_INTERNAL: punits = "Internal";     break;
        case CTA_UNITS_INTEGER : punits = "Integer";      break;
        case CTA_UNITS_COUNT   : punits = "Count";        break;
        case CTA_UNITS_MASK    : punits = "Mask";         break;
        case CTA_UNITS_HZ      : punits = "Hz";           break;
        case CTA_UNITS_MS      : punits = "ms";           break;
        case CTA_UNITS_DB      : punits = "dB";           break;
        case CTA_UNITS_DBM     : punits = "dBm";          break;
        case CTA_UNITS_IDU     : punits = "Internal DSP"; break;
        case CTA_UNITS_STRING  : punits = "String";       break;
        case CTA_UNITS_PERCENT : punits = "Percent";      break;
        default                : punits = "Undefined";    break;
        }

    switch( info.format )
        {
        case CTA_FMT_WORD:
            printf( "%s.%-20s = %5u\t\t# (0x%04x) WORD  (%s)\n",
                info.structname, info.fieldname, pdata->w, pdata->w, punits );
            break;
        case CTA_FMT_DWORD:
            printf( "%s.%-20s = %5u\t\t# (0x%04x) DWORD (%s)\n",
                info.structname, info.fieldname, pdata->W, pdata->W, punits );
            break;
        case CTA_FMT_INT16:
            printf( "%s.%-20s = %5d\t\t# (0x%04x) INT16 (%s)\n",
                info.structname, info.fieldname, pdata->i, pdata->i, punits );
            break;
        case CTA_FMT_INT32:
            printf( "%s.%-20s = %5d\t\t# (0x%04x) INT32 (%s)\n",
                info.structname, info.fieldname, pdata->I, pdata->I, punits );
            break;
        case CTA_FMT_STRING:
            printf( "%s.%-20s = \"%s\"\t\t# STRING[%d]\n",
                info.structname, info.fieldname, pdata->s, info.size );
            break;
        default:
            printf( "Error! Unknown data type: '%c'\n", info.format );
            break;
        }
        return;
}

Sample run

For the parameter vce.play.gain, the output is: