IVdsLun::SetMask method (vds.h)
[Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage Management API.]
Specifies the unmasking list, which is the list of computers to be granted access to the LUN.
Syntax
HRESULT SetMask(
[in] LPWSTR pwszUnmaskingList
);
Parameters
[in] pwszUnmaskingList
A list specifying the computers to be granted access to the LUN. The list is a semicolon-delimited, NULL-terminated, human-readable string.
If the value is "", all computers that have an HBA port attached to the storage subsystem are to be granted access to the LUN.
If the value is "", access is revoked for all computers that were previously granted access to the LUN.
If "*" or "" is specified, no other value can be specified.
For Fibre Channel networks and serial attached SCSI (SAS) networks, each entry is a 64-bit World-Wide Name (WWN) of each port to which the LUN is unmasked, formatted as a hexadecimal string (16 characters long), most significant byte first. For example, a WWN address of 01:23:45:67:89:AB:CD:EF is represented as "0123456789ABCDEF". For more information, see the T10 specifications for Fibre Channel and SAS.
For iSCSI networks, each entry is an iSCSI qualified name (IQN) of each initiator to which the LUN is unmasked. A LUN unmasked to a particular initiator is considered to be associated with that initiator.
Return value
This method can return standard HRESULT values, such as E_INVALIDARG or E_OUTOFMEMORY, and VDS-specific return values. It can also return converted system error codes using the HRESULT_FROM_WIN32 macro. Errors can originate from VDS itself or from the underlying VDS provider that is being used. Possible return values include the following.
| Return code/value | Description |
|---|---|
|
This return value signals a software or communication problem inside a provider that caches information about the array. Use the IVdsHwProvider::Reenumerate method followed by the IVdsHwProvider::Refresh method to restore the cache. |
|
The LUN object is no longer present. |
|
The LUN is in a failed state, and is unable to perform the requested operation. |
|
Another operation is in progress; this operation cannot proceed until the previous operation or operations are complete. |
Remarks
Before calling the SetMask method to mask a LUN, the caller should uninstall the corresponding disks as follows. First, retrieve the VDS object ID of the disk that corresponds to the LUN being masked by calling IVdsServiceUninstallDisk::GetDiskIdFromLunInfo. Then call IVdsServiceUninstallDisk::UninstallDisks with the VDS object ID of the disk.
Windows Server 2003 and Windows Server 2003 with SP1: To uninstall the corresponding disks, perform the following steps. Note that these steps became obsolete with Windows Server 2003 R2.
- Locate the volumes on the disks to be masked as follows:
- For each disk, call the IVdsDisk::QueryExtents method to enumerate the disk extents. This method returns a list of VDS_DISK_EXTENT structures. The volumeId member of this structure contains the volume GUID.
- Enumerate the volumes managed by the software provider by calling the IVdsSwProvider::QueryPacks method to enumerate the packs and calling IVdsPack::QueryVolumes to enumerate the volumes in each pack. Call IVdsVolume::GetProperties to obtain the VDS_VOLUME_PROP structure for each volume. The id member of this structure contains the volume GUID. The pwszName member contains the volume name to be passed to CreateFile to obtain a volume handle.
- Use the volume GUIDs that were obtained by calling IVdsDisk::QueryExtents to determine which of the volume names you will need from the list of enumerated volumes.
- Lock each volume by using the FSCTL_LOCK_VOLUME
control code. If the LUN is being moved to another machine as an intact volume, and another application holds a
volume lock, you should retry the FSCTL_LOCK_VOLUME
operation if possible before continuing on to the next step. However, if the volume is only being locked and
dismounted because it is being deleted, there is no need to retry the
FSCTL_LOCK_VOLUME operation.
Note This step is optional. The purpose of this step is to allow other applications that may hold locks to release them. Even if the lock operation fails, you should continue on to the next step.
- Dismount each volume by using the FSCTL_DISMOUNT_VOLUME control code.
- If the volumes are on basic disks, take them offline by using the IOCTL_VOLUME_OFFLINE control code.
- Uninstall each volume using the SetupDiCallClassInstaller function, passing DIF_REMOVE for the InstallFunction parameter.
- Uninstall each disk using the SetupDiCallClassInstaller function, passing DIF_REMOVE for the InstallFunction parameter.
- Remove user-mode paths, such as mounted folders and drive-letter assignments, from the registry by calling the IVdsService::CleanupObsoleteMountPoints method.
After a LUN is unmasked to a target machine or masked from a target machine, the LUN's visibility on that machine may not change until a bus rescan is performed. The VDS application on the target machine initiates the bus rescan by calling IVdsService::Reenumerate. The initiating of the bus rescan is the responsibility of the VDS application, not the hardware provider.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | vds.h |
| Library | Uuid.lib |