NPA_Return_DeviceHandle

Allows an application or utility to get the HAM-generated deviceHandle associated with a device object under NWPA.

Thread Context:Non-Blocking. SFT III in MSEngine only.

Syntax

    LONG NPA_Return_DeviceHandle (
       LONG   objectID,
       LONG  *deviceHandle
    );

Parameters

objectID
(IN) Media Manager objectID of the target device object.
deviceHandle
(OUT) Receives the object's deviceHandle as assigned by the HAM managing the device.

Return Values

The following table lists return values and descriptions.

0x00

MM_OK

Operation successful.

0x01

MM_INVALID_OBJECT

Input objectID doesn’t map to a valid object.

0x0D

MM_INVALID_OBJECT_TYPE

Input objectID doesn’t map to a device object.

0x0F

MM_NOT_NWPA_OBJECT

Corresponding device object is not under NWPA. deviceHandle is not applicable.

Remarks

NPA_Return_DeviceHandle is used by device-specific applications that send HACB messages directly to HAMs using NPA_HACB_Passthru. In general, these types of applications need to communicate directly with hardware. Some examples of these types of applications are RAID configuration/monitoring utilities, drive diagnostic utilities, and predictive failure analysis utilities.

In order for these applications to route HACBs to a target device, they need to place the corresponding, HAM-generated deviceHandle in the appropriate field of the HACB. For typical storage applications, this hardware routing and HACB message building is transparent through the Media Manager API and Media Manager assigned object IDs. However, for device-specific applications that need to build their own HACBs, this routing is not transparent.

NPA_Return_DeviceHandle provides specific applications with a mechanism to map Media Manager object IDs into deviceHandles to aid them in building HACBs.