3.4.4.1 CprepDiskGetUniqueIds3 (Opnum 3)

  • Article

The CprepDiskGetUniqueIds3 method returns device ID data about the ClusPrepDisk.

 HRESULT CprepDiskGetUniqueIds3(
   [in] CPREP_DISKID DiskId,
   [out, size_is(,*pcbDihSize)] BYTE** ppbDeviceIdHeader,
   [out] ULONG* pcbDihSize,
   [out, size_is(,* pcbDdSize)] BYTE** ppDeviceDescriptor,
   [out] ULONG* pcbDdSize
 );

DiskId: The identifier representing the ClusPrepDisk for which to retrieve the device ID data.

ppbDeviceIdHeader: On successful return, the address of a pointer to a *pcbDihSize-sized block of BYTEs. The server allocates and initializes the returned buffer. Callers MUST free this memory when they are finished with it. On unsuccessful return, the client MUST ignore this value.

pcbDihSize: On successful return, the number of BYTEs returned in ppbDeviceIdHeader. On unsuccessful return, the client MUST ignore this value.

ppDeviceDescriptor: On successful return, the address of a pointer to a *pcbDdSize-sized block of BYTEs. The server allocates and initializes the returned buffer. Callers MUST free this memory when they are finished with it. On unsuccessful return, the client MUST ignore this value.

pcbDdSize: On successful return, the number of BYTEs returned in ppDeviceDescriptor. On unsuccessful return, the client MUST ignore this value.

Return Values: A signed 32-bit value that indicates return status. If the method returns a negative value, it has failed. Zero or positive values indicate success, with the lower 16 bits in positive nonzero values containing warnings or flags defined in the method implementation. For more information about Win32 error codes and HRESULT values, see [MS-ERREF] sections 2.2 and 2.1.

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070057

E_INVALIDARG

One or more arguments are invalid.

0x80070032

ERROR_NOT_SUPPORTED

The disk does not support device ID data.

For any other condition, this method MUST return a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

The opnum field value for this method is 3.

When processing this call, the server MUST do the following:

  • Obtain the ClusPrepDisk identified by the DiskId parameter as described in section 3.2.4.

  • Retrieve the page 83h SCSI data described in [SPC-3] section 7.6.3.1 in an implementation-specific way for the given disk.

  • If the retrieved 83h SCSI data does not contain at least one identifier of the types SCSI name string, EUI-64 based, or NAA as described in [SPC-3] section 7.6.3.1, with device-specific association, return ERROR_NOT_SUPPORTED.

  • Allocate a block of BYTEs large enough to store the SCSI page 83h data formatted as a STORAGE_DEVICE_ID_DESCRIPTOR structure.

  • Copy the data formatted as a STORAGE_DEVICE_ID_DESCRIPTOR structure into the ppbDeviceIdHeader buffer.

  • Initialize *pcbDihSize  to the number of BYTEs being returned.

When processing this call, the server MAY do the following:

  • Retrieve the SCSI page 80h Unit Serial Number, as described in [SPC-3], in an implementation-specific way for the given disk.

  • If the retrieved 80h Unit Serial Number is available, allocate a block of BYTEs large enough to store the SCSI page 80h Unit Serial Number, formatted as a STORAGE_DEVICE_DESCRIPTOR structure (as specified in section 2.2.27).

  • Copy the data formatted as a STORAGE_DEVICE_DESCRIPTOR structure into the ppDeviceDescriptor buffer.

  • Initialize *pcbDdSize to the number of BYTEs being returned.

If no SCSI page 80h Unit Serial Number is available, the server MUST initialize *pcbDdSize to zero, and *ppDeviceDescriptor to NULL.

The server returns the following data to the client:

  • A STORAGE_DEVICE_ID_DESCRIPTOR with SCSI page 80h serial number for the disk.

  • A STORAGE_DEVICE_DESCRIPTOR with SCSI page 80h serial number for the disk.

The client is responsible for freeing the returned memory allocation.