NCM_GetProperties( )

---

Description | Cautions | Example | Error Codes | See Also

Name:	NCMRetCode NCM_GetProperties( pncmFamily, pncmDevice, ppncmProperties )
Inputs:	NCMFamily *pncmFamily	pointer to a structure containing a device family name
	NCMDevice *pncmDevice	pointer to a structure containing a device name
	NCMProperty **ppncmProperties	address of pointer where properties will be output
Returns:	NCM_SUCCESS if success NCM error code if failure
Includes:	NCMApi.h
Mode:	synchronous

Description

The NCM_GetProperties( ) function gets the installable properties for a device. For information about using this function to fill all the structures you need to instantiate and modify configuration parameter values, see Section 2.3.1, Populating Required Structures.

The function parameters are defined as follows:

Parameter	Description
pncmFamily	pointer to the structure containing the family name; the value of the structure must be an installable family (see Cautions below.)
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)
ppncmProperties	address of the pointer to the list to be filled with property structures

Cautions

The pncmFamily and pncmDevice pointers must reference information that is valid in the current DCM Catalog. For information about how to determine which families, devices and configuration parameters are valid in the current DCM Catalog, see Section 2.3.1, Populating Required Structures.

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 *     pProperties = NULL; 
//
// Execute
// 
NCMRetCode     ncmRc = NCM_GetProperties( &family, &device, &pProperties ); 
if ( ncmRc == NCM_SUCCESS )
{
     NCMProperty * pCurrProperties = pProperties;
     while ( pCurrProperties != NULL )
     {
          // Process list
          ...
          pCurrProperties = pCurrProperties ->next;
     }
}
else
{     // Process error
...
} 
// Deallocate memory
NCM_Dealloc( pProperties );
... 

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_GENERAL	a problem occurred retrieving the data
NCME_INVALID_INPUTS	the values of the parameters supplied are invalid

See Also

• NCM_GetAllDevices( )
• NCM_GetAllFamilies( )
• NCM_GetValueRange( )
• NCM_GetVariables( )
• NCM_Dealloc( )
• NCM_DeallocValue( )

Click here to contact Telecom Support Resources