StgOpenStorageEx-Funktion (coml2api.h)

Artikel
08/22/2023

Die StgOpenStorageEx-Funktion öffnet ein vorhandenes Stammspeicherobjekt im Dateisystem. Verwenden Sie diese Funktion, um zusammengesetzte Dateien und reguläre Dateien zu öffnen. Verwenden Sie zum Erstellen einer neuen Datei die Funktion StgCreateStorageEx .

Hinweis Um Verbesserungen zu verwenden, sollten alle Windows 2000-, Windows XP- und Windows Server 2003-Anwendungen StgOpenStorageEx anstelle von StgOpenStorageEx aufrufen. Die StgOpenStorage-Funktion wird aus Gründen der Kompatibilität mit Windows 2000- und früheren Anwendungen verwendet.

Syntax

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
);

Parameter

[in] pwcsName

Ein Zeiger auf den Pfad der Unicode-Zeichenfolgendatei mit NULL-Beendigung, die das Speicherobjekt enthält. Diese Zeichenfolgengröße darf MAX_PATH Zeichen nicht überschreiten.

Windows Server 2003 und Windows XP/2000: Im Gegensatz zur CreateFile-Funktion kann der MAX_PATH Grenzwert nicht überschritten werden, indem das Präfix "\?" verwendet wird.

[in] grfMode

Ein Wert, der den Zugriffsmodus zum Öffnen des neuen Speicherobjekts angibt. Weitere Informationen finden Sie unter STGM-Konstanten. Wenn der Aufrufer den Transaktionsmodus zusammen mit STGM_CREATE oder STGM_CONVERT angibt, erfolgt die Überschreibung oder Konvertierung, wenn der Commitvorgang für den Stammspeicher aufgerufen wird. Wenn IStorage::Commit nicht für das Stammspeicherobjekt aufgerufen wird, wird der vorherige Inhalt der Datei wiederhergestellt. STGM_CREATE und STGM_CONVERT können nicht mit dem STGM_NOSNAPSHOT-Flag kombiniert werden, da eine Momentaufnahme Kopie erforderlich ist, wenn eine Datei im Transaktionsmodus überschrieben oder konvertiert wird.

Wenn das Speicherobjekt im direkten Modus (STGM_DIRECT) mit Zugriff auf STGM_WRITE oder STGM_READWRITE geöffnet wird, muss der Freigabemodus STGM_SHARE_EXCLUSIVE werden, es sei denn, der STGM_DIRECT_SWMR-Modus ist angegeben. Weitere Informationen finden Sie im Abschnitt mit Hinweisen. Wenn das Speicherobjekt im direkten Modus mit Zugriff auf STGM_READ geöffnet wird, muss der Freigabemodus entweder STGM_SHARE_EXCLUSIVE oder STGM_SHARE_DENY_WRITE sein, es sei denn, es wird STGM_PRIORITY oder STGM_DIRECT_SWMR angegeben. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

Der Modus, in dem eine Datei geöffnet wird, kann sich auf die Implementierungsleistung auswirken. Weitere Informationen finden Sie unter Grenzwerte für die Implementierung von zusammengesetzten Dateien.

[in] stgfmt

Ein Wert, der das Speicherdateiformat angibt. Weitere Informationen finden Sie in der STGFMT-Enumeration .

[in] grfAttrs

Ein Wert, der vom Wert des stgfmt-Parameters abhängt.

STGFMT_DOCFILE muss null (0) oder FILE_FLAG_NO_BUFFERING sein. Weitere Informationen zu diesem Wert finden Sie unter CreateFile. Wenn die in pStgOptions angegebene Sektorgröße der Datei kein ganzzahliges Vielfaches der physischen Sektorgröße des zugrunde liegenden Datenträgers ist, schlägt dieser Vorgang fehl. Alle anderen Werte von stgfmt müssen null sein.

[in, out] pStgOptions

Ein Zeiger auf eine STGOPTIONS-Struktur , die Daten über das geöffnete Speicherobjekt enthält. Der pStgOptions-Parameter ist nur gültig, wenn der stgfmt-Parameter auf STGFMT_DOCFILE festgelegt ist. Das usVersion-Element muss vor dem Aufrufen von StgOpenStorageEx festgelegt werden. Weitere Informationen finden Sie in der STGOPTIONS-Struktur .

[in] pSecurityDescriptor

Reserviert; muss null sein.

[in] riid

Ein Wert, der die GUID des zurückzugebenden Schnittstellenzeigers angibt. Kann auch der vom Header angegebene Wert für IID_IStorage zum Abrufen der IStorage-Schnittstelle oder für IID_IPropertySetStorage zum Abrufen der IPropertySetStorage-Schnittstelle sein.

[out] ppObjectOpen

Die Adresse einer Schnittstellenzeigervariable, die einen Zeiger für eine Schnittstelle auf dem geöffneten Speicherobjekt empfängt; enthält NULL , wenn der Vorgang fehlgeschlagen ist.

Rückgabewert

Diese Funktion kann auch alle Dateisystemfehler oder Systemfehler zurückgeben, die in ein HRESULT umschlossen sind. Weitere Informationen finden Sie unter Strategien zur Fehlerbehandlung und Behandeln unbekannter Fehler.

Hinweise

StgOpenStorageEx ist eine Übermenge der StgOpenStorage-Funktion und sollte von neuem Code verwendet werden. Zukünftige Verbesserungen des strukturierten Speichers werden über diese Funktion verfügbar gemacht. Weitere Informationen zu unterstützten Plattformen finden Sie im Abschnitt Anforderungen.

Die StgOpenStorageEx-Funktion öffnet das angegebene Stammspeicherobjekt entsprechend dem Zugriffsmodus im GrfMode-Parameter und stellt bei erfolgreicher Ausführung einen Schnittstellenzeiger für das geöffnete Speicherobjekt im Parameter ppObjectOpen bereit. Diese Funktion kann verwendet werden, um eine IStorage-Verbunddateiimplementierung, eine IPropertySetStorage-Verbunddateiimplementierung oder eine
NTFS-Dateisystemimplementierung von IPropertySetStorage.

Wenn Sie eine Datei öffnen, wählt das System eine strukturierte Speicherimplementierung aus, je nachdem, welches STGFMT-Flag Sie für den Dateityp und den Typ des Laufwerks angeben, auf dem die Datei gespeichert ist.

Verwenden Sie die StgOpenStorageEx-Funktion , um auf den Stammspeicher eines strukturierten Speicherdokuments oder auf den Eigenschaftensatzspeicher einer beliebigen Datei zuzugreifen, die Eigenschaftensätze unterstützt. Weitere Informationen dazu, welche Schnittstellenbezeichner (INTERFACE Identifiers, IIDs) für die verschiedenen STGFMT-Werte unterstützt werden, finden Sie unter STGFMT.

Wenn eine Datei mit dieser Funktion geöffnet wird, um auf die NTFS-Eigenschaftensatzimplementierung zuzugreifen, gelten spezielle Freigaberegeln. Weitere Informationen finden Sie unter IPropertySetStorage-NTFS-Implementierung.

Wenn eine zusammengesetzte Datei im Transaktionsmodus geöffnet wird, können Sie das zurückgegebene Speicherobjekt ändern, indem Sie STGM_TRANSACTED und den schreibgeschützten Modus angeben, indem Sie STGM_READ angeben. Beispielsweise ist es möglich, IStorage::CreateStream aufzurufen. Es ist jedoch nicht möglich, diese Änderungen durch Aufrufen von IStorage::Commit zu committen. Daher gehen solche Änderungen verloren.

Es ist ungültig, die STGM_CREATE-, STGM_DELETEONRELEASE- oder STGM_CONVERT-Flags im GrfMode-Parameter für diese Funktion zu verwenden.

Um den einfachen Modus zum Speichern eines Speicherobjekts ohne Unterspeicher zu unterstützen, akzeptiert die StgOpenStorageEx-Funktion eine der folgenden beiden Flagkombinationen als gültige Modi im grfMode-Parameter :

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

Um den Modus "Single Writer", "Multireader" und "Direct" zu unterstützen, ist die erste Flagkombination der gültige grfMode-Parameter für den Writer. Die zweite Flagkombination ist für Leser gültig.

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

Weitere Informationen zu einfachen Modus und Einzelschreiber-/Mehrlesermodi finden Sie unter STGM-Konstanten.

Hinweis Das Öffnen eines Speicherobjekts im Transaktionsmodus im Lese- und/oder Schreibmodus, ohne anderen Schreibberechtigungen zu verweigern (z. B. gibt der grfMode-ParameterSTGM_SHARE_DENY_WRITE an), kann zeitaufwändig sein, da der StgOpenStorageEx-Aufruf eine Momentaufnahme Kopie des gesamten Speicherobjekts erstellen muss.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	coml2api.h (include Objbase.h)
Bibliothek	Ole32.lib
DLL	Ole32.dll