StgOpenStorageEx 함수(coml2api.h)

아티클
08/22/2023

StgOpenStorageEx 함수는 파일 시스템에서 기존 루트 스토리지 개체를 엽니다. 이 함수를 사용하여 복합 파일 및 일반 파일을 엽니다. 새 파일을 만들려면 StgCreateStorageEx 함수를 사용합니다.

참고 향상된 기능을 사용하려면 모든 Windows 2000, Windows XP 및 Windows Server 2003 애플리케이션에서 StgOpenStorage 대신 StgOpenStorageEx를 호출해야 합니다. StgOpenStorage 함수는 Windows 2000 및 이전 애플리케이션과의 호환성을 위해 사용됩니다.

구문

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

매개 변수

[in] pwcsName

스토리지 개체를 포함하는 null로 종료된 유니코드 문자열 파일의 경로에 대한 포인터입니다. 이 문자열 크기는 MAX_PATH 문자를 초과할 수 없습니다.

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

[in] grfMode

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

스토리지 개체가 STGM_WRITE또는 STGM_READWRITE 대한 액세스 권한으로 직접 모드(STGM_DIRECT)로 열리는 경우 STGM_DIRECT_SWMR 모드를 지정하지 않는 한 공유 모드를 STGM_SHARE_EXCLUSIVE 합니다. 자세한 내용은 주의 섹션을 참조하세요. 스토리지 개체가 STGM_READ 대한 액세스 권한이 있는 직접 모드로 열리는 경우 STGM_PRIORITY 또는 STGM_DIRECT_SWMR 지정하지 않는 한 공유 모드는 STGM_SHARE_EXCLUSIVE 또는 STGM_SHARE_DENY_WRITE 있어야 합니다. 자세한 내용은 주의 섹션을 참조하세요.

파일이 열리는 모드는 구현 성능에 영향을 줄 수 있습니다. 자세한 내용은 복합 파일 구현 제한을 참조하세요.

[in] stgfmt

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

[in] grfAttrs

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

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

[in, out] pStgOptions

열린 스토리지 개체에 대한 데이터를 포함하는 STGOPTIONS 구조체에 대한 포인터입니다. pStgOptions 매개 변수는 stgfmt 매개 변수가 STGFMT_DOCFILE 설정된 경우에만 유효합니다. StgOpenStorageEx를 호출하기 전에 usVersion 멤버를 설정해야 합니다. 자세한 내용은 STGOPTIONS 구조를 참조하세요.

[in] pSecurityDescriptor

예약; 0이어야 합니다.

[in] riid

반환할 인터페이스 포인터의 GUID를 지정하는 값입니다. IID_IStorage IStorage 인터페이스를 가져오거나 IPropertySetStorage 인터페이스를 가져오는 IID_IPropertySetStorage 헤더 지정 값일 수도 있습니다.

[out] ppObjectOpen

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

반환 값

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

설명

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

StgOpenStorageEx 함수는 grfMode 매개 변수의 액세스 모드에 따라 지정된 루트 스토리지 개체를 열고, 성공하면 ppObjectOpen 매개 변수에서 열린 스토리지 개체에 대한 인터페이스 포인터를 제공합니다. 이 함수는 IStorage 복합 파일 구현, IPropertySetStorage 복합 파일 구현 또는 를 가져오는 데 사용할 수 있습니다.
IPropertySetStorage의 NTFS 파일 시스템 구현.

파일을 열 때 시스템은 파일 형식 및 파일이 저장된 드라이브 유형에 대해 지정하는 STGFMT 플래그에 따라 구조화된 스토리지 구현을 선택합니다.

StgOpenStorageEx 함수를 사용하여 구조화된 스토리지 문서의 루트 스토리지 또는 속성 집합을 지원하는 파일의 속성 집합 스토리지에 액세스합니다. 다양한 STGFMT 값에 대해 지원되는 IID(인터페이스 식별자)에 대한 자세한 내용은 STGFMT를 참조하세요.

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

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

이 함수의 grfMode 매개 변수에서 STGM_CREATE, STGM_DELETEONRELEASE 또는 STGM_CONVERT 플래그를 사용하는 것은 유효하지 않습니다.

하위 저장소 없이 스토리지 개체를 저장하는 간단한 모드를 지원하기 위해 StgOpenStorageEx 함수는 grfMode 매개 변수에서 다음 두 플래그 조합 중 하나를 유효한 모드로 허용합니다.

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

단일 작성기, 멀티레더, 직접 모드를 지원하기 위해 첫 번째 플래그 조합은 작성기에 유효한 grfMode 매개 변수입니다. 두 번째 플래그 조합은 판독기에서 유효합니다.

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

단순 모드 및 단일 기록기/다중 판독기 모드에 대한 자세한 내용은 STGM 상수를 참조하세요.

참고StgOpenStorageEx 호출에서 전체 스토리지 개체의 스냅샷 복사본을 만들어야 하므로 다른 사용자에게 쓰기 권한을 거부하지 않고(예: grfMode 매개 변수가 STGM_SHARE_DENY_WRITE 지정) 트랜잭션 모드 스토리지 개체를 읽기 및/또는 쓰기 모드로 여는 것은 시간이 오래 걸릴 수 있습니다.

요구 사항

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