HAM_Return_Device_Info (Function 0x02)
Mandatory function. This routine must return a DeviceInfoStruct that gives information about a single device and how it works.
This routine is identified by the following information in the HACB's command area:
If parameter0 = = -1, it means that a new find-first-find-next sequence is to be started, and the HAM must return information about the first device in its list. The structure of the return information is defined by the DeviceInfoStruct, which the HAM copies into the buffer pointed at by the HACB's vDataBufferPtr field.
One key piece of information the HAM places in the buffer is the deviceHandle. The HAM generated this deviceHandle during HAM_Scan_For_Devices (Function 0x01), and now through HAM_Return_Device_Info, NWPA passes it to the CDM. The CDM uses this deviceHandle to indicate a target device to the HAM for all subsequent device I/O.
The HAM must perpetuate the sequence until information about all of its devices are returned.
The HAM perpetuates the sequence by doing the following:
The sequence continues with the HAM receiving another HAM_Return_Device_Info request, this time with parameter0 equal to the device handle the HAM placed in the return buffer of the previous iteration of the sequence. The HAM then uses this previous device handle to locate the next device in the list and returns its information. The HAM follows this paradigm until it returns information about all the devices in its list
After the HAM returns information about the last device in its list, it receives one more HAM_Return_Device_Info request. The HAM ends the find-first-find-next sequence by placing a 0x000A0005 (NO_MORE_DEVICES_FOUND) return value in this last HACB's hacbCompletion field and completing it by calling HAI_Complete_HACB.