IVdsSubSystem::CreateLun 方法 (vdshwprv.h)
[从 Windows 8 和 Windows Server 2012 开始,虚拟磁盘服务 COM 接口由 Windows 存储管理 API 取代。]
CreateLun 方法 (LUN) 创建逻辑单元号。
语法
HRESULT CreateLun(
[in] VDS_LUN_TYPE type,
[in] ULONGLONG ullSizeInBytes,
[in] VDS_OBJECT_ID *pDriveIdArray,
[in] LONG lNumberOfDrives,
[in] LPWSTR pwszUnmaskingList,
[in] VDS_HINTS *pHints,
[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 的访问权限。
如果指定了“*”或“”,则不能指定其他值。
对于光纤通道网络和串行附加的 SCSI (SAS) 网络,每个条目都是一个 64 位 World-Wide Name (WWN) ,该端口已取消屏蔽 LUN,格式为十六进制字符串, (长度为 16 个字符,) ,最重要的字节优先。 例如,WWN 地址 01:23:45:67:89:AB:CD:EF 表示为“0123456789ABCDEF”。 有关详细信息,请参阅 光纤通道 和 SAS 的 T10 规范。
对于 iSCSI 网络,每个条目都是一个 iSCSI 限定名称 (IQN) ,该发起程序已取消屏蔽 LUN。 取消屏蔽到特定发起程序的 LUN 被视为与该发起程序相关联。
[in] pHints
指向 VDS_HINTS 结构的指针,该结构指定要在创建 LUN 时使用的提示。 提供程序不需要将提示应用到 LUN。 VDS_HINTS 结构中指定的提示只是对提供程序的请求。
创建 LUN 后,调用方可以通过调用 IVdsLun::QueryHints 方法或 IVdsLunPlex::QueryHints 方法来确定提供程序应用的提示。
如果 类型 参数指定非自动类型,则此参数应为 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 提供程序 。 可能的返回值包括以下内容。
返回代码/值 | 说明 |
---|---|
|
此返回值表示缓存有关数组信息的提供程序中的软件或通信问题。 使用 IVdsHwProvider::Reenumerate 方法,后跟 IVdsHwProvider::Refresh 方法还原缓存。 |
|
子系统对象不再存在。 |
|
子系统处于失败状态,无法执行请求的操作。 |
|
另一项操作正在进行中;在上一个操作完成之前,此操作无法继续。 |
|
可以从采用 VDS_OBJECT_ID 常量的任何方法返回。 此返回值指示标识符不引用现有对象。 |
|
此提供程序不支持此操作或参数组合。 |
|
此操作没有足够的可用空间。 |
|
子系统中存在的可用驱动器太少,无法完成此操作。 |
备注
通过为 类型和pHints 参数选择适当的值,调用方可以完全、部分或最小方式指定 LUN 的属性。 提供程序可以根据 pHints 参数指向的 VDS_HINTS 结构中指定的 automagic 提示自动包含未指定的属性。
如果 VDS 提供程序仅支持简单目标配置,则子系统应自动将新创建的 LUN 对象与 iSCSI 目标对象相关联。 请参阅 VDS_SUB_SYSTEM_FLAG 枚举的 VDS_SF_SUPPORTS_SIMPLE_TARGET_CONFIG 值。
pwszUnmaskingList 参数中的 WWN 和 IQN 列表可能包含重复的名称。 提供商负责验证列表中的所有名称,并在必要时删除重复项。
硬件提供程序负责删除 LUN 的分区信息,以便可以重复使用 LUN。 如果 LUN 是 MBR 磁盘,则通过向第一个和最后一个 1 MB 的磁盘写入零来实现此目的。 对于 GPT 磁盘,必须将零写入磁盘的第一个和最后 16 KB。
E_INVALIDARG和VDS_E_NOT_SUPPORTED返回值之间存在细微差异。 提供程序不应实现 VDS API 可以呈现给客户端的每个功能。 例如, CreateLun 方法公开了创建许多不同类型的 LUN 的功能, (例如简单、镜像、条带化和奇偶校验) 。 但是,提供程序不需要支持所有类型的 LUN。 如果调用方为 类型 参数指定的值不是有效的 VDS_LUN_TYPE 枚举值,则提供程序应返回 E_INVALIDARG。 如果调用方指定提供程序不支持的有效 类型 值,则提供程序应返回VDS_E_NOT_SUPPORTED。
实现者说明: 即使对此方法的调用未启动异步操作,提供程序也必须在 ppAsync 参数中返回 IVdsAsync 接口指针。
要求
最低受支持的客户端 | Windows Vista [仅限桌面应用] |
最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
目标平台 | Windows |
标头 | vdshwprv.h |
Library | Uuid.lib |