IVdsSubSystem2：：CreateLun2 方法 (vdshwprv.h)

项目
03/03/2024

[从 Windows 8 和 Windows Server 2012 开始，虚拟磁盘服务 COM 接口由 Windows 存储管理 API 取代。]

创建 LUN。此方法与 IVdsSubSystem：：CreateLun 方法相同，只是使用 VDS_HINTS2 结构而不是 VDS_HINTS 结构提供自动提示。

语法

HRESULT CreateLun2(
  [in]  VDS_LUN_TYPE  type,
  [in]  ULONGLONG     ullSizeInBytes,
  [in]  VDS_OBJECT_ID *pDriveIdArray,
  [in]  LONG          lNumberOfDrives,
  [in]  LPWSTR        pwszUnmaskingList,
  [in]  VDS_HINTS2    *pHints2,
  [out] IVdsAsync     **ppAsync
);

参数

[in] type

指定 LUN 类型的 VDS_LUN_TYPE 枚举值。新 LUN 可以是 automagic 类型或特定的 RAID 类型，但不能同时是这两者。如果调用方指定了 automagic 类型，则应在 pHints 参数中指定一个或多个 automagic 提示。

可以通过对 ppAsync 参数中返回的接口指针调用 IVdsAsync：：Wait 方法来检索新 LUN 对象的接口指针。 Wait 返回的 VDS_ASYNC_OUTPUT 结构包含 cl.pLunUnk 成员中的 LUN 对象接口指针。

[in] ullSizeInBytes

新 LUN 的大小（以字节为单位）。提供程序可以向上或向下舍入大小，以满足对齐要求或其他限制。 (在大多数情况下，提供程序会向上舍入，确保 LUN 在极少数情况下至少与请求的大小一样大。)

创建 LUN 后，调用方可以通过调用 IVdsLun：：GetProperties 方法来确定 LUN 的实际大小。

[in] pDriveIdArray

指向数组的指针，该数组包含用于创建 LUN 的每个驱动器的 VDS_OBJECT_ID 。通过为此参数指定非 NULL 值，调用方请求提供程序按提供的顺序使用所有驱动器，在移动到下一个驱动器之前使用一个驱动器上的所有盘区，并在 LUN 达到请求的大小时停止。

或者，调用方可以通过在此参数中传递 NULL 和 lNumberOfDrives 中的 0 来指示提供程序自动选择驱动器。 (当且仅当 lNumberOfDrives 为 0.) 时传递 NULL

如果类型参数指定了 automagic 类型，则此参数应为 NULL。

[in] lNumberOfDrives

pDriveIdArray 中指定的驱动器数。如果调用方通过 0，则提供程序会选择驱动器。

如果类型参数指定了 automagic 类型，则此参数应为 0。

创建 LUN 后，调用方可以通过调用 IVdsLunPlex：：QueryExtents 方法来确定正在使用的驱动器。

[in] pwszUnmaskingList

指定要授予 LUN 访问权限的计算机的列表。该列表是一个以分号分隔、 以 NULL 结尾、用户可读的字符串。

如果值为“”，则向连接到存储子系统的 HBA 端口的所有计算机授予对 LUN 的访问权限。如果值为“”，则不向任何计算机授予对 LUN 的访问权限。

注意实际上，如果值为“”，则大多数硬件提供程序仅授予本地计算机上的端口和发起程序访问 LUN 的权限。

如果指定了“*”或“”，则不能指定其他值。

对于光纤通道网络和串行附加的 SCSI (SAS) 网络，每个条目都是一个 64 位 World-Wide Name (WWN) ，该端口已取消屏蔽 LUN，格式为十六进制字符串， (长度为 16 个字符，) ，最重要的字节优先。例如，01：23：45：67：89：AB：CD：EF 的 WWN 地址表示为“0123456789ABCDEF”。有关详细信息，请参阅光纤通道和 SAS 的 T10 规范。

对于 iSCSI 网络，每个条目都是一个 iSCSI 限定名称 (IQN) ，该发起程序已取消屏蔽 LUN。取消屏蔽到特定发起程序的 LUN 被视为与该发起程序相关联。

注意取消屏蔽列表可以多次包含相同的 WWN 或 IQN。调用方不应从列表中删除重复项或验证 WWN 或 IQN 的格式。

创建 LUN 后，调用方可以通过调用 IVdsLun：：GetProperties 方法来确定实际的取消屏蔽列表。

[in] pHints2

指向 VDS_HINTS2 结构的指针，该结构指定要在创建 LUN 时使用的提示。提供程序不需要将提示应用到 LUN。 VDS_HINTS2 结构中指定的提示只是对提供程序的请求。

创建 LUN 后，调用方可以通过调用 IVdsLun2：：QueryHints2 方法来确定提供程序应用的提示。

如果类型参数指定非自动类型，则此参数应为 NULL。

[out] ppAsync

VDS 在返回时初始化的 IVdsAsync 接口指针的地址。调用方必须释放接口。使用此接口可取消、等待或查询操作的状态。

如果在返回的接口指针上调用 IVdsAsync：：Wait 并返回成功的 HRESULT 值，则必须通过调用每个接口指针上的 IUnknown：：Release 方法释放VDS_ASYNC_OUTPUT结构中返回的接口。但是，如果 Wait 返回失败的 HRESULT 值，或者如果 Wait 的 pHrResult 参数收到失败的 HRESULT 值，则VDS_ASYNC_OUTPUT结构中的接口指针为 NULL，不需要释放。可以使用 Winerror.h 中定义的 SUCCEEDED 和 FAILED 宏测试成功或失败 HRESULT 值。

返回值

此方法可以返回标准 HRESULT 值，例如E_INVALIDARG或E_OUTOFMEMORY，以及特定于 VDS 的返回值。它还可以使用 HRESULT_FROM_WIN32 宏返回转换的系统错误代码。错误可能源自 VDS 本身或正在使用的基础 VDS 提供程序。可能的返回值包括以下内容。

返回代码/值	说明
VDS_E_PROVIDER_CACHE_CORRUPT 0x8004241FL	缓存有关数组的信息的提供程序内部存在软件或通信问题。使用 IVdsHwProvider：：Reenumerate 方法，后跟 IVdsHwProvider：：Refresh 方法还原缓存。
VDS_E_OBJECT_DELETED 0x8004240BL	子系统对象不再存在。
VDS_E_OBJECT_STATUS_FAILED 0x80042431L	子系统处于失败状态，无法执行请求的操作。
VDS_E_ANOTHER_CALL_IN_PROGRESS 0x80042404L	另一项操作正在进行中;在上一个操作完成之前，此操作无法继续。
VDS_E_OBJECT_NOT_FOUND 0x80042405L	标识符不引用现有对象。此值可以从采用 VDS_OBJECT_ID 常量的任何方法返回。
VDS_E_NOT_SUPPORTED 0x80042400L	此提供程序不支持此操作或参数组合。
VDS_E_NOT_ENOUGH_SPACE 0x8004240FL	此操作没有足够的可用空间。
VDS_E_NOT_ENOUGH_DRIVE 0x80042410L	子系统中存在的可用驱动器太少，无法完成此操作。

注解

通过为 类型和pHints2 参数选择适当的值，调用方可以完全、部分或最小方式指定 LUN 的属性。提供程序可以根据 pHints 参数指向的 VDS_HINTS2 结构中指定的 automagic 提示自动包含未指定的属性。

实施者注意事项： 提供程序必须在 ppAsync 参数中返回 IVdsAsync 接口指针，即使对此方法的调用未启动异步操作也是如此。

pwszUnmaskingList 参数中的 WWN 和 IQN 列表可能包含重复的名称。提供商负责验证列表中的所有名称，并在必要时删除重复项。

为了响应 CreateLun2 方法，在将新 LUN 取消屏蔽到任何主机之前，提供程序应用零填充第一个和最后一个 MB，使 LUN 保持未初始化。

E_INVALIDARG和VDS_E_NOT_SUPPORTED返回值之间存在细微差异。提供程序不应实现 VDS API 可以呈现给客户端的每个功能。例如，CreateLun2 方法公开了创建许多不同类型的 LUN 的功能， (例如简单、镜像、条带化和奇偶校验) 。但是，提供程序不需要支持所有类型的 LUN。如果调用方为类型参数指定的值不是有效的 VDS_LUN_TYPE 枚举值，则提供程序应返回 E_INVALIDARG。如果调用方指定提供程序不支持的有效类型值，则提供程序应返回VDS_E_NOT_SUPPORTED。

要求

要求	值
最低受支持的客户端	Windows 7 [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 R2 [仅限桌面应用]
目标平台	Windows
标头	vdshwprv.h
Library	Uuid.lib