StgOpenStorage 함수(coml2api.h)

  • 아티클

StgOpenStorage 함수는 파일 시스템에서 기존 루트 스토리지 개체를 엽니다. 이 함수를 사용하여 복합 파일을 엽니다. 디렉터리, 파일 또는 요약 카탈로그를 여는 데 사용하지 마세요. 중첩된 스토리지 개체는 부모 IStorage::OpenStorage 메서드를 사용해야만 열 수 있습니다.

참고 애플리케이션은 향상된 Windows 구조적 스토리지 기능을 활용하려면 StgOpenStorage 대신 새 함수인 StgOpenStorageEx를 사용해야 합니다. 이 함수 인 StgOpenStorage는 Windows 2000에서 실행되는 애플리케이션과의 호환성을 위해 여전히 존재합니다.
 

구문

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
참고StgOpenStorage 호출이 전체 스토리지 개체의 스냅샷 만들어야 하므로 다른 사람에게 쓰기 권한을 거부하지 않고 읽기/쓰기 모드에서 스토리지 개체를 여는 것은 시간이 오래 걸릴 수 있습니다(grfMode 매개 변수는 STGM_SHARE_DENY_WRITE 지정).
 
애플리케이션은 다음과 같은 액세스 권한으로 스토리지 개체를 열려고 하는 경우가 많습니다. 애플리케이션이 성공하면 스냅샷 복사본을 만들 필요가 없습니다. 
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
참고 스냅샷 복사하는 비용을 줄이기 위해 애플리케이션은 우선 순위 모드에서 스토리지 개체를 열 수 있습니다(grfMode는 STGM_PRIORITY 지정).
 
snbExclude 매개 변수는 스토리지 개체가 열릴 때 비워야 하는 이 스토리지 개체의 요소 이름 집합을 지정합니다. 스트림은 길이가 0으로 설정됩니다. 스토리지 개체에는 모든 요소가 제거됩니다. 특정 스트림을 제외하면 스냅샷 복사본을 만드는 비용을 크게 줄일 수 있습니다. 거의 항상 이 방법은 우선 순위 모드에서 스토리지 개체를 연 다음, 이제 제외된 요소를 메모리로 완전히 읽은 후에 사용됩니다. 스토리지 개체의 이전 우선 순위 모드 열기는 pstgPriority 매개 변수를 통해 전달되어야 우선 순위 모드에 내포된 제외를 제거합니다. 호출 애플리케이션은 커밋하기 전에 제외된 항목의 콘텐츠를 다시 작성해야 합니다. 따라서 이 기술은 문서가 활성 상태일 때 스토리지 개체에 대한 지속적인 액세스가 필요하지 않은 애플리케이션에만 유용할 수 있습니다.

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

추가 정보

IStorage

StgCreateDocfile

StgOpenStorageEx