StgCreateStorageEx 함수(coml2api.h)

아티클
08/22/2023

StgCreateStorageEx 함수는 IStorage 또는 IPropertySetStorage 인터페이스에 대해 제공된 구현을 사용하여 새 스토리지 개체를 만듭니다. 기존 파일을 열려면 StgOpenStorageEx 함수를 대신 사용합니다.

Windows 2000, Windows Server 2003 및 Windows XP용으로 작성된 애플리케이션은 향상된 Windows 2000 및 Windows XP 구조적 스토리지 기능을 활용하려면 StgCreateDocfile 대신 StgCreateStorageEx를 사용해야 합니다.

구문

HRESULT StgCreateStorageEx(
  [in]  const WCHAR          *pwcsName,
  [in]  DWORD                grfMode,
  [in]  DWORD                stgfmt,
  [in]  DWORD                grfAttrs,
  [in]  STGOPTIONS           *pStgOptions,
  [in]  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]  REFIID               riid,
  [out] void                 **ppObjectOpen
);

매개 변수

[in] pwcsName

만들 파일의 경로에 대한 포인터입니다. 파일 시스템에 해석되지 않은 상태로 전달됩니다. 상대 이름 또는 NULL일 수 있습니다. NULL인 경우 임시 파일이 고유한 이름으로 할당됩니다. NULL이 아닌 경우 문자열 크기가 MAX_PATH 문자를 초과하면 안됩니다.

Windows 2000: CreateFile 함수와 달리 "\?" 접두사를 사용하여 MAX_PATH 제한을 초과할 수 없습니다.

[in] grfMode

새 스토리지 개체를 열 때 사용할 액세스 모드를 지정하는 값입니다. 자세한 내용은 STGM 상수를 참조하세요. 호출자가 STGM_CREATE 또는 STGM_CONVERT 함께 트랜잭션 모드를 지정하는 경우 루트 스토리지에 대한 커밋 작업이 호출될 때 덮어쓰기 또는 변환이 수행됩니다. 루트 스토리지 개체에 대해 IStorage::Commit 이 호출되지 않으면 파일의 이전 내용이 복원됩니다. 트랜잭션 모드에서 파일을 덮어쓰거나 변환할 때 스냅샷 복사본이 필요하므로 STGM_CREATE 및 STGM_CONVERT STGM_NOSNAPSHOT 플래그와 결합할 수 없습니다.

[in] stgfmt

스토리지 파일 형식을 지정하는 값입니다. 자세한 내용은 STGFMT 열거형을 참조하세요.

[in] grfAttrs

stgfmt 매개 변수의 값에 따라 달라지는 값입니다.

매개 변수 값	의미
STGFMT_DOCFILE	0 또는 FILE_FLAG_NO_BUFFERING. 자세한 내용은 CreateFile을 참조하세요. pStgOptions에 지정된 파일의 섹터 크기가 기본 디스크의 실제 섹터 크기의 정수 배수가 아닌 경우 이 작업이 실패합니다.
stgfmt의 다른 모든 값	0이어야 합니다.

[in] pStgOptions

pStgOptions 매개 변수는 stgfmt 매개 변수가 STGFMT_DOCFILE 설정된 경우에만 유효합니다. stgfmt 매개 변수가 STGFMT_DOCFILE 설정된 경우 pStgOptions는 섹터 크기와 같은 스토리지 개체의 기능을 지정하는 STGOPTIONS 구조를 가리킵니다. 이 매개 변수는 기본 섹터 크기가 512바이트인 스토리지 개체를 만드는 NULL일 수 있습니다. NULL이 아닌 경우 ulSectorSize 멤버를 512 또는 4096으로 설정해야 합니다. 4096으로 설정된 경우 grfMode 매개 변수에 STGM_SIMPLE 지정하지 않을 수 있습니다. StgCreateStorageEx를 호출하기 전에 usVersion 멤버를 설정해야 합니다. 자세한 내용은 STGOPTIONS를 참조하세요.

[in] pSecurityDescriptor

파일을 만들 때 ACL을 설정할 수 있습니다. NULL이 아닌 경우 SECURITY_ATTRIBUTES 구조체에 대한 포인터여야 합니다. 파일에 ACL을 설정하는 방법에 대한 자세한 내용은 CreateFile 을 참조하세요.

Windows Server 2003, Windows 2000 Server, Windows XP 및 Windows 2000 Professional: 값은 NULL이어야 합니다.

[in] riid

반환할 인터페이스 포인터의 IID(인터페이스 식별자)를 지정하는 값입니다. 이 IID는 IStorage 인터페이스 또는 IPropertySetStorage 인터페이스용일 수 있습니다.

[out] ppObjectOpen

새 스토리지 개체의 인터페이스에 대한 포인터를 수신하는 인터페이스 포인터 변수에 대한 포인터입니다. 에는 작업이 실패한 경우 NULL 이 포함됩니다.

반환 값

이 함수는 HRESULT에 래핑된 파일 시스템 오류 또는 시스템 오류를 반환할 수도 있습니다. 자세한 내용은 오류 처리 전략 및 알 수 없는 오류 처리를 참조하세요.

설명

애플리케이션은 파일을 수정할 때 일반적으로 원본의 복사본을 만듭니다. StgCreateStorageEx 함수는 복사본을 만드는 한 가지 방법입니다. 이 함수는 EFS(파일 시스템 암호화) 중복 API에서 간접적으로 작동합니다. 이 함수를 사용하는 경우 STGOPTIONS 구조에서 파일 스토리지에 대한 옵션을 설정해야 합니다.

StgCreateStorageEx 는 StgCreateDocfile 함수의 상위 집합이며 새 코드에서 사용해야 합니다. 구조적 스토리지에 대한 향후 개선 내용은 StgCreateStorageEx 함수를 통해 공개될 예정입니다. 지원되는 플랫폼에 대한 자세한 내용은 다음 요구 사항 섹션을 참조하세요.

StgCreateStorageEx 함수는 시스템에서 제공하는 구조적 스토리지 구현 중 하나를 사용하여 새 스토리지 개체를 만듭니다. 이 함수를 사용하여
IStorage 복합 파일 구현, IPropertySetStorage 복합 파일 구현 또는 IPropertySetStorage NTFS 구현을 가져옵니다.

새 파일을 만들 때 사용되는 스토리지 구현은 사용자가 지정한 플래그와 파일이 저장되는 드라이브 유형에 따라 달라집니다. 자세한 내용은 STGFMT 열거형을 참조하세요.

StgCreateStorageEx 가 없는 경우 파일을 만듭니다. 있는 경우 grfMode 매개 변수에서 STGM_CREATE, STGM_CONVERT 및 STGM_FAILIFTHERE 플래그를 사용하면 진행 방법이 표시됩니다. 이러한 값에 대한 자세한 내용은 STGM 상수를 참조하세요. grfMode 매개 변수에서 STGM_READ 모드를 지정하는 것은 직접 모드에서 유효하지 않습니다(직접 모드는 STGM_TRANSACTED 플래그를 지정하지 않음으로써 표시됨). 이 함수는 기존 파일을 여는 데 사용할 수 없습니다. 대신 StgOpenStorageEx 함수를 사용합니다.

StgCreateStorageEx 함수를 사용하여 구조적 스토리지 문서의 루트 스토리지 또는 속성 집합을 지원하는 파일의 속성 집합 스토리지에 액세스할 수 있습니다. 다양한 STGFMT 값에 대해 지원되는 IID에 대한 자세한 내용은 STGFMT 설명서를 참조하세요.

NTFS 속성 집합 구현에 액세스하기 위해 이 함수를 사용하여 파일을 만들면 특수 공유 규칙이 적용됩니다. 자세한 내용은 IPropertySetStorage-NTFS 구현을 참조하세요.

복합 파일을 트랜잭션 모드(STGM_TRANSACTED 지정)와 읽기 전용 모드(STGM_READ 지정)로 만든 경우 반환된 스토리지 개체를 변경할 수 있습니다. 예를 들어 IStorage::CreateStream을 호출할 수 있습니다. 그러나 IStorage::Commit을 호출하여 이러한 변경 내용을 커밋할 수 없습니다. 따라서 이러한 변경 내용은 손실됩니다.

STGM_SIMPLE 지정하면 여러 스트림이 있고 스토리지가 없는 복합 파일 구현이 필요한 애플리케이션과 관련된 제한된 경우에 복합 파일 개체를 훨씬 더 빠르게 구현할 수 있습니다. 자세한 내용은 STGM 상수를 참조하세요. STGM_SIMPLE 지정된 경우 해당 STGM_TRANSACTED 지정하는 것은 유효하지 않습니다.

단순 모드는 IStorage의 모든 메서드를 지원하지 않습니다. 특히 단순 모드에서 지원되는 IStorage 메서드는 CreateStream, Commit 및 SetClass뿐만 아니라 QueryInterface, AddRef 및 Release의 COM IUnknown 메서드입니다. 또한 SetElementTimes 는 NULL 이름으로 지원되므로 애플리케이션이 루트 스토리지에서 시간을 설정할 수 있습니다. IStorage의 다른 모든 메서드는 STG_E_INVALIDFUNCTION 반환합니다.

grfMode 매개 변수가 STGM_TRANSACTED 지정하고 pwcsName 매개 변수로 지정된 이름을 가진 파일이 아직 없는 경우 파일이 즉시 만들어집니다. 액세스 제어 파일 시스템에서 호출자는 복합 파일이 만들어지는 파일 시스템 디렉터리에 대한 쓰기 권한이 있어야 합니다. STGM_TRANSACTED 지정하지 않고 STGM_CREATE 지정한 경우 새 파일을 만들기 전에 이름이 같은 기존 파일이 제거됩니다.

또한 StgCreateStorageEx를 사용하여 pwcsName 매개 변수에 대한 NULL 값을 전달하여 임시 복합 파일을 만들 수도 있습니다. 그러나 이러한 파일은 사용자에게 의미가 없는 고유한 시스템 제공 이름을 가지고 있다는 점에서만 일시적일 수 있습니다. 호출자는 grfMode 매개 변수에 대해 STGM_DELETEONRELEASE 지정하지 않은 한 임시 파일을 완료할 때 삭제할 책임이 있습니다. 이러한 플래그에 대한 자세한 내용은 STGM 상수를 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows 2000 Server [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	coml2api.h(Objbase.h 포함)
라이브러리	Ole32.lib
DLL	Ole32.dll