NCM_GetValue( )

---

Description | Cautions | Example | Error Codes | See Also

Name:	NCMRetCode NCM_GetValue( pncmFamily, pncmDevice, pncmProperty, pncmVariable, ppncmValue )
Inputs:	NCMFamily *pncmFamily	pointer to a structure containing a device family name
	NCMDevice *pncmDevice	pointer to a structure containing a device name
	NCMProperty *pncmProperty	pointer to a structure containing a property section
	NCMVariable *pncmVariable	pointer to a structure containing a configuration parameter
	NCMValue **ppncmValue	address of pointer where value will be output
Returns:	NCM_SUCCESS if success NCM error code if failure
Includes:	NCMApi.h
Mode:	synchronous

Description

The NCM_GetValue( ) function gets an instantiated or default parameter value. This function enables you to determine either the instantiated value of a configuration parameter in the system configuration or the default value of a configuration parameter in the DCM Catalog.

The function parameters are defined as follows:

Parameter	Description
pncmFamily	pointer to the structure containing the family name
pncmDevice	pointer to the structure containing a device name; the device name can be either a device model name or a unique device name (the unique device name must be the same name you used to add the device to the system configuration with the NCM_AddDevice( ) function)
pncmProperty	pointer to the structure containing the property name
pncmVariable	pointer to the structure containing the configuration parameter name
ppncmValue	an address of the pointer to be filled with the configuration parameter value

Whether this function gets an instantiated value from the system configuration or a default value from the DCM Catalog depends on whether pncmDevice points to a unique device name or a device model name:

• To get an instantiated configuration parameter value: pncmDevice must point to a unique device name; the unique device name must be the same name you used to add the device to the system configuration with the NCM_AddDevice( ) function.
• To get the default configuration parameter value: pncmDevice must point to an installable device model name; the device model name must be for a model that is defined in the DCM Catalog.

For more information about the distinction between device model names and unique device names, see Section 2.3.4, Device Model Names and Unique Device Names.

Cautions

The DCM API allocates memory for the data returned by this function. To avoid memory leaks, the client application must deallocate this memory by calling the NCM_Dealloc( ) or NCM_DeallocValue( ) function.

Example

#include "NCMApi.h" 
...
//
// Prepare inputs
// 
NCMFamily family;
family.name = "D/x1D";
family.next = NULL; 
NCMDevice device;
device.name = "D/41D-1";
device.next = NULL; 
NCMProperty property;
property.name = "System";
property.next = NULL; 
NCMVariable variable;
variable.name = "D41DAddress";
variable.next = NULL; 
NCMValue *     pValue = NULL; 
//
// Execute
// 
NCMRetCode     ncmRc = NCM_GetValue( &family, &device, &property,
                                         &variable, &pValue ); 
if ( ncmRc == NCM_SUCCESS )
{
     if (pValue != Null && pValue ->name ! = Null)
     //use the value
}
else
{     // Process error
     ...
} 
// Deallocate memory
NCM_Dealloc( pValue ); 
... 

Error Codes

Equate	Returned When
NCME_NO_INF	the DCM Catalog could not be found
NCME_MEM_ALLOC	memory could not be allocated to perform the function
NCME_SP	invalid state transition
NCME_GENERAL	a problem occurred retrieving the data
NCME_BAD_INF	there was an error parsing the DCM Catalog
NCME_INVALID_INPUTS	the values of the parameters supplied are invalid

See Also

• NCM_GetInstalledDevices( )
• NCM_GetInstalledFamilies( )
• NCM_GetValueEx( )
• NCM_SetValue( )
• NCM_SetValueEx( )
• NCM_Dealloc( )
• NCM_DeallocValue( )

Click here to contact Telecom Support Resources