Метод IVdsSubSystem::CreateLun (vds.h)

Статья
03/08/2023

[Начиная с Windows 8 и Windows Server 2012, COM-интерфейс службы виртуальных дисков замечается API управления хранилищем Windows.]

Метод 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

Значение перечисления VDS_LUN_TYPE , указывающее тип LUN. Новый LUN может быть автоматическим или определенным типом RAID, но не обоими. Если вызывающий объект указывает автоматический тип, в параметре pHints должно быть указано одно или несколько автоматических указаний.

Указатель интерфейса для нового объекта LUN можно получить, вызвав метод IVdsAsync::Wait для указателя интерфейса, возвращаемого в параметре ppAsync . Структура VDS_ASYNC_OUTPUT , возвращаемая wait , содержит указатель интерфейса объекта LUN в элементе cl.pLunUnk .

[in] ullSizeInBytes

Размер нового LUN в байтах. Поставщик может округлить размер вверх или вниз в соответствии с требованиями выравнивания или другими ограничениями. (В большинстве случаев поставщик округляет вверх, гарантируя, что, за редкими исключениями, ЗНАЧЕНИЕ LUN по крайней мере равно требуемому.)

После создания LUN вызывающий объект может определить фактический размер LUN, вызвав метод IVdsLun::GetProperties .

[in] pDriveIdArray

Указатель на массив, содержащий VDS_OBJECT_ID для каждого диска, используемого для создания LUN. Указывая для этого параметра значение, отличное от NULL , вызывающий объект запрашивает, чтобы поставщик использовал все диски в указанном порядке, используя все экстенты на одном диске перед переходом к следующему, и останавливается, когда LUN достигнет запрошенного размера.

Кроме того, вызывающий объект может направить поставщика на автоматический выбор дисков, передав значение NULL в этом параметре и 0 в lNumberOfDrives. (Передайте значение NULL , если и только в том случае, если lNumberOfDrives имеет значение 0.)

Если параметр type задает автоматический тип, этот параметр должен иметь значение NULL.

[in] lNumberOfDrives

Количество дисков, указанное в pDriveIdArray. Если вызывающий объект передает значение 0, поставщик выбирает диски.

Если параметр type задает автоматический тип, этот параметр должен иметь значение 0.

После создания LUN вызывающий объект может определить, какие диски используются, вызвав метод IVdsLunPlex::QueryExtents .

[in] pwszUnmaskingList

Список, указывающий компьютеры, которым будет предоставлен доступ к LUN. Список представляет собой удобочитаемую строку с разделителями с запятой, заканчивающейся null.

Если значение равно "", всем компьютерам с портом HBA, подключенным к подсистеме хранения, предоставляется доступ к LUN. Если значение равно "", компьютеры не должны предоставлять доступ к LUN.

Примечание На практике, если значение равно "", большинство поставщиков оборудования предоставляют доступ к LUN только портам и инициаторам на локальном компьютере.

Если указано "*" или "", другое значение не может быть указано.

Для сетей Fibre Channel и сетей SCSI (SAS) с последовательным подключением каждая запись представляет собой 64-разрядное имя (WWN) каждого порта, для которого luN не маскируется, отформатированная в виде шестнадцатеричной строки (длиной 16 символов), в первую очередь наиболее значимого байта. Например, WWN-адрес 01:23:45:67:89:AB:CD:EF представлен как "0123456789ABCDEF". Дополнительные сведения см. в спецификациях T10 для Fibre Channel и SAS.

Для сетей iSCSI каждая запись представляет собой полное имя iSCSI (IQN) каждого инициатора, для которого не маскируется LUN. Считается, что luN, не маски для определенного инициатора, связан с этим инициатором.

Примечание Список unmasking может содержать один и тот же WWN или IQN несколько раз. Вызывающий объект не должен удалять дубликаты из списка или проверять формат WWN или IQN.

После создания LUN вызывающий объект может определить фактический список, вызвав метод IVdsLun::GetProperties .

[in] pHints

Указатель на структуру VDS_HINTS , указывающую указания, которые будут использоваться при создании LUN. Поставщик не обязан применять указания к LUN. Указания, указанные в структуре VDS_HINTS, являются только запросом к поставщику.

После создания LUN вызывающий объект может определить указания, примененные поставщиком, путем вызова метода IVdsLun::QueryHints или метода IVdsLunPlex::QueryHints .

Если параметр type указывает неавтомагический тип, этот параметр должен иметь значение NULL.

[out] ppAsync

Адрес указателя интерфейса IVdsAsync , который VDS инициализирует при возврате. Вызывающие стороны должны освободить интерфейс. Используйте этот интерфейс для отмены, ожидания или запроса состояния операции.

Если метод IVdsAsync::Wait вызывается для возвращаемого указателя интерфейса и возвращается успешное значение HRESULT, интерфейсы, возвращаемые в структуре VDS_ASYNC_OUTPUT , должны быть освобождены путем вызова метода IUnknown::Release для каждого указателя интерфейса. Однако если функция Wait возвращает значение HRESULT сбоя или параметр pHrResultобъекта Wait получает значение HRESULT сбоя, указатели интерфейса в структуре VDS_ASYNC_OUTPUT имеют значение NULL и не должны освобождаться. Вы можете проверить наличие значений HRESULT успешного или неудачного выполнения с помощью макросов SUCCEEDED и FAILED , определенных в Winerror.h.

Возвращаемое значение

Этот метод может возвращать стандартные значения 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	В подсистеме слишком мало свободных дисков для выполнения этой операции.

Выбрав соответствующие значения для параметров типа и pHints , вызывающий объект может указать атрибуты LUN полностью, частично или минимально. Поставщик может автоматически включать неопределенные атрибуты на основе автоматических указаний, указанных в структуре VDS_HINTS , на которую указывает параметр pHints .

Если поставщик VDS поддерживает только простые целевые конфигурации, подсистема должна автоматически связать созданный объект LUN с целевым объектом iSCSI. См . VDS_SF_SUPPORTS_SIMPLE_TARGET_CONFIG значение перечисления VDS_SUB_SYSTEM_FLAG .

Список WWN и IQN в параметре pwszUnmaskingList может содержать повторяющиеся имена. Поставщик несет ответственность за проверку всех имен в списке и удаление дубликатов при необходимости.

Поставщик оборудования отвечает за удаление сведений о секции LUN, чтобы можно было повторно использовать LUN. Если LUN является диском MBR, это достигается путем записи нули в первый и последний 1 МБ диска. Для диска GPT нули должны быть записаны в первый и последний 16 КБ диска.

Существует небольшое различие между E_INVALIDARG и VDS_E_NOT_SUPPORTED возвращаемыми значениями. Поставщики не должны реализовывать все функции, которые API VDS может представить клиенту. Например, метод CreateLun предоставляет возможность создавать множество различных типов LUN (например, простые, зеркало, чередуемые и четные). Однако поставщики не обязаны поддерживать все типы LUN. Если вызывающий объект задает значение для параметра типа , которое не является допустимым значением перечисления VDS_LUN_TYPE , поставщик должен вернуть E_INVALIDARG. Если вызывающий объект указывает допустимое значение типа , которое поставщик не поддерживает, поставщик должен вернуть VDS_E_NOT_SUPPORTED.

Примечания для разработчиков: Поставщик должен возвращать указатель интерфейса IVdsAsync в параметре ppAsync , даже если вызов этого метода не инициирует асинхронную операцию.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	vds.h
Библиотека	Uuid.lib