Novell Documentation: Storage Architecture Components (incl. Media Manager & NWPA)

CDM_Inquiry

The CDM's entry point for querying online devices and determining whether or not it binds to the device.

Thread Context:Blocking

Syntax

    LONG CDM_Inquiry (
       LONG                     npaDeviceID,
       LONG                     npaBusID,
       struct DeviceInfoStruct *deviceInfo,
       LONG                     flag,
       LONG                     cdmHandle
       );

Parameters

npaDeviceID: (IN) NWPA passes the value of this parameter, which is the Media Manager object ID that NWPA assigned to the target device in its device database. More information on Media Manager object IDs is found in the NDK: Media Manager for NetWare 5.x and 6.x documentation, which can be obtained from the Novell Developer Support group.
npaBusID: (IN) NWPA passes the value of this parameter, which is the Media Manager object ID that NWPA assigned to the target bus (adapter) in its object database. If flag is set to 0x00000003 or 0x00000004, this is the only valid parameter for this API. All other parameters are set to 0.
deviceInfo: (IN) NWPA passes the value of this parameter, which is a pointer to a DeviceInfoStruct. The HAM supporting the target device fills in this structure with all the pertinent device information that the CDM might need to send I/O to the device and determine if it should bind to the device. Additionally, this structure has an InquiryInfoStruct as a data member that contains bus-specific inquiry information.

flag: NWPA passes the value of this parameter, which indicates the type of inquiry to perform. This parameter can have one of the following values:

Value	Description
0x00000000	Indicates a new device. The CDM should check it and bind to it if the device meets the CDM's bind conditions.
0x00000001	(Applies only to filter CDMs) Indicates that the CDM is already bound to the specified device, but device information has changed. Therefore, the CDM might need to bind again or issue an object update. To base-translator and enhancer CDMs, this constitutes a no-op.
0x00000002	Indicates to the CDM that the specified device is no longer valid; therefore, the CDM should remove the device from its list and free any local structures associated with the device.
0x00000003	Indicates to the CDM that an End of Bus condition has occurred during a Scan For New Devices. This means that there are no more public devices on this bus. The CDM can then scan for specific devices not found during the normal scan. The specific devices can become public or private devices depending on the Scan function case used. For more details, refer to HACB Type Zero Functions under HAM_Scan_For_Devices (Function 0x01) If this flag is set, npaBusID is the only valid parameter for this API. All other parameters are set to 0.
0x00000004	Indicates to the CDM that an End of Bus condition occurred when the bus is being deactivated (that is, when the HAM associated with the bus is being unloaded). The CDM must remove any private devices on this bus and all of the local structures associated with these devices from its list. This is done by using Scan case 3 of HAM_Scan_For_Devices (Function 0x01). If this flag is set, npaBusID is the only valid parameter for this API. All other parameters are set to 0.

cdmHandle: NWPA passes the value of this parameter, which is the identifier the CDM generated for itself and registered with NWPA during CDI_Register_CDM.

Return Values

The following table lists return values and descriptions.

zero	Successful
-1	No binding occurred

Remarks

CDM_Inquiry is the CDM's entry point for logically binding to a device. A logical bind means that the CDM fields message requests for the device, and indicates this to NWPA by calling CDI_Bind_CDM_To_Object and returning zero from this function. This entry point gets registered with NWPA during NPA_Register_CDM_Module. Immediately after CDM registration, NWPA calls CDM_Inquiry for each device matching the device type that the CDM registered for with CDI_Register_CDM. It receives subsequent calls each time a new device with that device type comes online. The CDM registers the device types it supports, along with the host adapter interface it supports, by placing the appropriate values in the types input parameter of CDI_Register_CDM.

CDM_Inquiry is responsible for building and maintaining a CDM's device list. It does this by binding to devices matching the device type the CDM is designed to support. To bind to a device, a CDM must generate a cdmBindHandle from which the CDM can identify the device and access essential device information, such as the device's handle and the handle of the HAM supporting the device. Next, it must create an instance of an UpdateInfoStruct for the device, fill in its fields with the appropriate information, and pass both the cdmBindHandle and a pointer to the UpdateInfoStruct to CDI_Bind_CDM_To_Object. This is all done within the context of CDM_Inquiry. CDM_Inquiry is a blocking process, and part of its purpose is to allow a CDM the opportunity to issue non-intrusive commands (such as a mode sense) to determine if it should bind to the device. These commands should be issued using CDI_Blocking_Execute_HACB. The CDM should not issue any command that might change the state of the device during the context of CDM_Inquiry.

If the CDM decides not to logically bind to a device, CDM_Inquiry must return a -1 return code.