IVdsSubSystem2::CreateLun2 메서드(vdshwprv.h)

아티클
03/08/2023

[Windows 8 및 Windows Server 2012 가상 디스크 서비스 COM 인터페이스는 Windows Storage 관리 API로 대체됩니다.]

LUN을 만듭니다. 이 메서드는 IVdsSubSystem::CreateLun 메서드와 동일합니다. 단, 자동 매핑 힌트는 VDS_HINTS 구조 대신 VDS_HINTS2 구조를 사용하여 제공됩니다.

구문

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은 자동 매핑 형식 또는 특정 RAID 형식일 수 있지만 둘 다 사용할 수는 없습니다. 호출자가 automagic 형식을 지정하는 경우 pHints 매개 변수에 하나 이상의 자동 매핑 힌트를 지정해야 합니다.

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을 전달합니다.)

type 매개 변수가 automagic 형식을 지정하는 경우 이 매개 변수는 NULL이어야 합니다.

[in] lNumberOfDrives

pDriveIdArray에 지정된 드라이브 수입니다. 호출자가 0을 통과하면 공급자가 드라이브를 선택합니다.

type 매개 변수가 automagic 형식을 지정하는 경우 이 매개 변수는 0이어야 합니다.

LUN을 만든 후 호출자는 IVdsLunPlex::QueryExtents 메서드를 호출하여 사용 중인 드라이브를 확인할 수 있습니다.

[in] pwszUnmaskingList

LUN에 대한 액세스 권한을 부여할 컴퓨터를 지정하는 목록입니다. 목록은 세미콜론으로 구분된 NULL로 종료되고 사람이 읽을 수 있는 문자열입니다.

값이 ""인 경우 스토리지 하위 시스템에 연결된 HBA 포트가 있는 모든 컴퓨터에 LUN에 대한 액세스 권한이 부여됩니다. 값이 ""인 경우 LUN에 대한 액세스 권한을 부여할 컴퓨터가 없습니다.

참고 실제로 값이 ""인 경우 대부분의 하드웨어 공급자는 로컬 컴퓨터의 포트 및 초기자만 LUN에 대한 액세스 권한을 부여합니다.

"*" 또는 ""을 지정하면 다른 값을 지정할 수 없습니다.

파이버 채널 네트워크 및 SAS(직렬 연결 SCSI) 네트워크의 경우 각 항목은 LUN이 마스크되지 않은 각 포트의 64비트 WWN(World-Wide Name)이며 16진수 문자열(16자 길이)로 가장 중요한 바이트입니다. 예를 들어 01:23:45:67:89:AB:CD:EF의 WWN 주소는 "0123456789ABCDEF"로 표시됩니다. 자세한 내용은 파이버 채널 및 SAS에 대한 T10 사양을 참조하세요.

iSCSI 네트워크의 경우 각 항목은 LUN이 마스크 해제된 각 초기자의 iSCSI 정규화된 이름(IQN)입니다. 특정 초기자에 매핑되지 않은 LUN은 해당 초기자와 연결된 것으로 간주됩니다.

참고 마스킹 해제 목록에는 동일한 WWN 또는 IQN이 두 번 이상 포함될 수 있습니다. 호출자는 목록에서 중복 항목을 제거하거나 WWN 또는 IQN 형식의 유효성을 검사할 필요가 없습니다.

LUN을 만든 후 호출자는 IVdsLun::GetProperties 메서드를 호출하여 실제 마스킹 해제 목록을 확인할 수 있습니다.

[in] pHints2

LUN을 만드는 데 사용할 힌트를 지정하는 VDS_HINTS2 구조체에 대한 포인터입니다. 공급자는 LUN에 힌트를 적용할 필요가 없습니다. VDS_HINTS2 구조에 지정된 힌트는 공급자에 대한 요청일 뿐입니다.

LUN을 만든 후 호출자는 IVdsLun2::QueryHints2 메서드를 호출하여 공급자가 적용한 힌트를 확인할 수 있습니다.

type 매개 변수가 자동 형식이 아닌 형식을 지정하는 경우 이 매개 변수는 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 값을 테스트할 수 있습니다.

반환 값

이 메서드는 E_INVALIDARG 또는 E_OUTOFMEMORY 같은 표준 HRESULT 값과 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 구조에 지정된 자동 매핑 힌트에 따라 지정되지 않은 특성을 자동으로 포함할 수 있습니다.

구현자에 대한 참고 사항: 이 메서드에 대한 호출이 비동기 작업을 시작하지 않더라도 공급자는 ppAsync 매개 변수에서 IVdsAsync 인터페이스 포인터를 반환해야 합니다.

pwszUnmaskingList 매개 변수의 WWN 및 IQN 목록에는 중복된 이름이 포함될 수 있습니다. 필요한 경우 목록의 모든 이름의 유효성을 검사하고 중복 항목을 제거하는 것은 공급자의 책임입니다.

CreateLun2 메서드에 대한 응답으로 새 LUN을 호스트에 마스킹 해제하기 전에 공급자는 첫 번째 및 마지막 메가바이트에 0을 채우고 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
라이브러리	Uuid.lib