StgOpenStorage 함수(coml2api.h)
StgOpenStorage 함수는 파일 시스템에서 기존 루트 스토리지 개체를 엽니다. 이 함수를 사용하여 복합 파일을 엽니다. 디렉터리, 파일 또는 요약 카탈로그를 여는 데 사용하지 마세요. 중첩된 스토리지 개체는 부모 IStorage::OpenStorage 메서드를 사용해야만 열 수 있습니다.
구문
HRESULT StgOpenStorage(
[in] const WCHAR *pwcsName,
[in] IStorage *pstgPriority,
[in] DWORD grfMode,
[in] SNB snbExclude,
[in] DWORD reserved,
[out] IStorage **ppstgOpen
);
매개 변수
[in] pwcsName
열 스토리지 개체가 포함된 null로 종료된 유니코드 문자열 파일의 경로에 대한 포인터입니다. pstgPriority 매개 변수가 NULL이 아닌 경우 이 매개 변수는 무시됩니다.
[in] pstgPriority
NULL이어야 하는 IStorage 인터페이스에 대한 포인터입니다. NULL이 아닌 경우 이 매개 변수는 아래 설명 섹션에 설명된 대로 사용됩니다.
StgOpenStorage가 반환된 후 pStgPriority에 지정된 스토리지 개체가 해제되어 더 이상 사용되지 않아야 합니다.
[in] grfMode
스토리지 개체를 여는 데 사용할 액세스 모드를 지정합니다.
[in] snbExclude
NULL이 아닌 경우 스토리지 개체가 열릴 때 제외할 스토리지의 요소 블록에 대한 포인터입니다. 제외는 스냅샷 복사본이 열려 있는지 여부에 관계없이 발생합니다. NULL일 수 있습니다.
[in] reserved
나중에 사용할 수 있는 예약됨을 나타냅니다. 는 0이어야 합니다.
[out] ppstgOpen
열린 스토리지에 대한 인터페이스 포인터를 수신하는 IStorage* 포인터 변수에 대한 포인터입니다.
반환 값
StgOpenStorage 함수는 HRESULT에 래핑된 파일 시스템 오류 또는 시스템 오류를 반환할 수도 있습니다. 자세한 내용은 오류 처리 전략 및 알 수 없는 오류 처리를 참조하세요.
설명
StgOpenStorage 함수는 grfMode 매개 변수의 액세스 모드에 따라 지정된 루트 스토리지 개체를 열고, 성공하면 ppstgOpen 매개 변수에서 열린 스토리지 개체에 대한 IStorage 포인터를 제공합니다.
하위 저장소 없이 스토리지 개체를 저장하는 간단한 모드를 지원하기 위해 StgOpenStorage 함수는 다음 두 플래그 조합 중 하나를 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_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE
STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE
STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE
STGM_READWRITE | STGM_SHARE_DENY_WRITE
// transacted versus direct mode omitted for exposition
애플리케이션은 이전 액세스 권한이 실패하는 경우 권한을 사용하여 되돌리기 스냅샷 복사본을 만들 수 있습니다. 애플리케이션은 시간이 많이 걸리는 복사본을 만들기 전에 사용자에게 메시지를 표시해야 합니다.
STGM_READWRITE
// transacted versus direct mode omitted for exposition
액세스 모드에 내포된 문서 공유 의미 체계가 적절한 경우 애플리케이션은 다음과 같이 스토리지를 열려고 시도할 수 있습니다. 이 경우 애플리케이션이 성공하면 스냅샷 복사본이 만들어지지 않습니다(STGM_SHARE_DENY_WRITE 지정되어 다른 사용자가 쓰기 권한을 거부했기 때문).
STGM_READ | STGM_SHARE_DENY_WRITE
// transacted versus direct mode omitted for exposition
pstgPriority 매개 변수는 호출자가 기존 스토리지 개체를 대체하기 위한 편의를 위해 고안되었으며, 종종 우선 순위 모드로 열리고 새 스토리지 개체가 동일한 파일에서 열리지만 다른 모드로 열립니다. pstgPriority가 NULL이 아닌 경우 무시되는 pwcsName 대신 파일 이름을 지정하는 데 사용됩니다. 그러나 StgOpenStorage는 경우에 따라 개체를 해제하고 다른 상황에서는 해제하지 않으므로 애플리케이션에서 항상 pstgPriority에 대해 NULL을 전달하는 것이 좋습니다. 특히 함수가 실패 결과를 반환하는 경우 호출자가 스토리지 개체가 해제되었는지 여부를 확인할 수 없습니다.
다음 예제와 같이 호출자가 pstgPriority 매개 변수의 기능을 보다 안전한 방식으로 복제할 수 있습니다.
// Replacement for:
// HRESULT hr = StgOpenStorage(
// NULL, pstgPriority, grfMode, NULL, 0, &pstgNew);
STATSTG statstg;
HRESULT hr = pstgPriority->Stat(&statstg, 0);
pStgPriority->Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &pstgNew);
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows 2000 Server [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | coml2api.h(Objbase.h 포함) |
| 라이브러리 | Ole32.lib |
| DLL | Ole32.dll |