NCM_AddDevice( )

---

Description | Cautions | Example | Error Codes | See Also

Name:	NCMRetCode NCM_AddDevice( pncmFamily, pncm DeviceModel, pncmDeviceUnique )
Inputs:	NCMFamily* pncmFamily	pointer to a structure containing a device family name
	NCMDevice* pncmDeviceModel	pointer to a structure containing a device model name
	NCMDevice* pncmDeviceUnique	pointer to a structure containing a unique device name
Returns:	NCM_SUCCESS if success NCM error code if failure
Includes:	NCMApi.h
Mode:	synchronous

Description

The NCM_AddDevice( ) function instantiates a device in the system configuration. Upon adding the device, this function will establish default settings for all configuration parameters pertaining to the device. It also sets the device's System parameters based on the system's available resources (for more information, see Section 2.6.2, System Property Parameters).

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
pncmDeviceModel	pointer to the structure containing the device's model name; the value of the structure must be an installable device
pncmDeviceUnique	pointer to the structure containing the device's unique name, this name can be any string sufficient to distinguish multiple instantiations of the same device model

Cautions

Because devices are instantiated in the system configuration according to their unique device name, it is impossible to correlate an instantiated device with a device model name. Intel® Dialogic strongly recommends that you embed the device model name within the unique device name when you instantiate a device with the NCM_AddDevice( ) function.

The pncmFamily and pncmDeviceModel 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.

This function adds to the information instantiated in the current system configuration. It has no effect on the installable families, devices and configuration parameters defined in the DCM Catalog. For more information about the distinction between the system configuration and the DCM Catalog, see Section 2.1, The DCM API Architecture.

Example

#include "NCMApi.h" 
... 
//
// Prepare inputs
// 
NCMFamily family;
family.name = "D/x1D";
family.next = NULL; 
NCMDevice model;
model.name = "D/41D";
model.next = NULL; 
NCMDeviceUniqueName;
UniqueName.name = "D/41D at ID 0";
uniqueName.next = NULL; 
//
// Execute
// 
NCMRetCode ncmRc = NCM_AddDevice( &family, &model, &uniqueName ); 
if ( ncmRc == NCM_SUCCESS ) 
{
     ...
} 
else 
{     // Process error
     ...
}
... 

Error Codes

Equate	Returned When
NCME_NO_RESOURCES	there are no more system resources (memory, IRQ, or ports) for the device to use
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_BAD_INF	there was an error parsing the DCM Catalog
NCME_INVALID_FAMILY	the family name is invalid
NCME_INVALID_DEVICE	the device name is invalid
NCME_DUP_DEVICE	the device could not be added because a device of the same device model name and unique device name is already instantiated in the system configuration

See Also

• NCM_GetInstalledDevices( )
• NCM_GetInstalledFamilies( )
• NCM_GetValue( )
• NCM_GetValueEx( )
• NCM_SetValue( )
• NCM_SetValueEx( )

Click here to contact Telecom Support Resources