IVdsLun::SetMask 方法 (vds.h)

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

指定取消屏蔽列表,这是要授予对 LUN 的访问权限的计算机的列表。

语法

HRESULT SetMask(
  [in] LPWSTR pwszUnmaskingList
);

参数

[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 或 iSCSI 名称的格式。 此外,访问不是累积的。 换句话说,如果连续调用此方法两次,则只授予第二次调用中指定的计算机访问权限。
 

返回值

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

返回代码/值 说明
VDS_E_PROVIDER_CACHE_CORRUPT
0x8004241FL
此返回值表示缓存有关数组信息的提供程序中的软件或通信问题。 使用 IVdsHwProvider::Reenumerate 方法,后跟 IVdsHwProvider::Refresh 方法还原缓存。
VDS_E_OBJECT_DELETED
0x8004240BL
LUN 对象不再存在。
VDS_E_OBJECT_STATUS_FAILED
0x80042431L
LUN 处于失败状态,无法执行请求的操作。
VDS_E_ANOTHER_CALL_IN_PROGRESS
0x80042404L
另一项操作正在进行中;在上一个操作完成之前,此操作无法继续。

注解

调用 SetMask 方法以屏蔽 LUN 之前,调用方应卸载相应的磁盘,如下所示。 首先,通过调用 IVdsServiceUninstallDisk::GetDiskIdFromLunInfo 检索与被屏蔽的 LUN 对应的磁盘的 VDS 对象 ID。 然后使用磁盘 的 VDS 对象 ID 调用 IVdsServiceUninstallDisk::UninstallDisks

Windows Server 2003 和 Windows Server 2003 SP1: 若要卸载相应的磁盘,请执行以下步骤。 请注意,这些步骤在 Windows Server 2003 R2 中已过时。

  1. 在磁盘上找到要屏蔽的卷,如下所示:
    1. 对于每个磁盘,调用 IVdsDisk::QueryExtents 方法来枚举磁盘盘区。 此方法返回 VDS_DISK_EXTENT 结构的列表。 此结构的 volumeId 成员包含卷 GUID
    2. 通过调用 IVdsSwProvider::QueryPacks 方法来枚举包,并调用 IVdsPack::QueryVolumes 枚举每个包中的卷来枚举软件提供程序管理的卷。 调用 IVdsVolume::GetProperties 以获取每个卷 的 VDS_VOLUME_PROP 结构。 此结构的 id 成员包含卷 GUIDpwszName 成员包含要传递给 CreateFile 以获取卷句柄的卷名称。
    3. 使用通过调用 IVdsDisk::QueryExtents 获取的卷 GUID 来确定需要从枚举卷列表中获取的卷名称。
  2. 使用 FSCTL_LOCK_VOLUME 控制代码锁定每个卷。 如果 LUN 作为一个完整卷移动到另一台计算机,并且另一个应用程序持有卷锁,则应尽可能重试 FSCTL_LOCK_VOLUME 操作,然后再继续下一步。 但是,如果卷由于被删除而仅被锁定和卸载,则无需重试 FSCTL_LOCK_VOLUME 操作。
    注意 此步骤是可选的。 此步骤的目的是允许可能持有锁的其他应用程序释放它们。 即使锁定操作失败,也应继续执行下一步。
     
  3. 使用 FSCTL_DISMOUNT_VOLUME 控制代码卸载每个卷。
  4. 如果卷位于基本磁盘上,请使用 IOCTL_VOLUME_OFFLINE 控制代码使它们脱机。
  5. 使用 SetupDiCallClassInstaller 函数卸载每个卷,并为 InstallFunction 参数传递DIF_REMOVE
  6. 使用 SetupDiCallClassInstaller 函数卸载每个磁盘,并为 InstallFunction 参数传递DIF_REMOVE
  7. 通过调用 IVdsService::CleanupObsoleteMountPoints 方法,从注册表中删除用户模式路径,例如装载的文件夹和驱动器号分配。

将 LUN 取消到目标计算机或从目标计算机屏蔽后,该计算机上的 LUN 可见性可能不会更改,直到执行总线重新扫描。 目标计算机上的 VDS 应用程序通过调用 IVdsService::Reenumerate 启动总线重新扫描。 启动总线重新扫描由 VDS 应用程序而不是硬件提供商负责。

要求

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

另请参阅

IVdsHwProvider::Reenumerate

IVdsHwProvider::Refresh

IVdsLun