StgOpenStorage-Funktion (coml2api.h)

Die StgOpenStorage-Funktion öffnet ein vorhandenes Stammspeicherobjekt im Dateisystem. Verwenden Sie diese Funktion, um zusammengesetzte Dateien zu öffnen. Verwenden Sie sie nicht zum Öffnen von Verzeichnissen, Dateien oder Zusammenfassungskatalogen. Geschachtelte Speicherobjekte können nur mit der übergeordneten IStorage::OpenStorage-Methode geöffnet werden.

Hinweis Anwendungen sollten die neue Funktion StgOpenStorageEx anstelle von StgOpenStorage verwenden, um die erweiterten Features und strukturierten Speicher von Windows zu nutzen. Diese Funktion, StgOpenStorage, ist aus Gründen der Kompatibilität mit Anwendungen, die unter Windows 2000 ausgeführt werden, weiterhin vorhanden.

 

Syntax

HRESULT StgOpenStorage(
  [in]  const WCHAR *pwcsName,
  [in]  IStorage    *pstgPriority,
  [in]  DWORD       grfMode,
  [in]  SNB         snbExclude,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Parameter

[in] pwcsName

Ein Zeiger auf den Pfad der Unicode-Zeichenfolgendatei mit NULL-Beendigung, die das zu öffnende Speicherobjekt enthält. Dieser Parameter wird ignoriert, wenn der pstgPriority-Parameter nicht NULL ist.

[in] pstgPriority

Ein Zeiger auf die IStorage-Schnittstelle , die NULL sein sollte. Wenn nicht NULL, wird dieser Parameter wie unten im Abschnitt Hinweise beschrieben verwendet.

Nachdem StgOpenStorage zurückgegeben wurde, wurde das in pStgPriority angegebene Speicherobjekt möglicherweise freigegeben und sollte nicht mehr verwendet werden.

[in] grfMode

Gibt den Zugriffsmodus an, mit dem das Speicherobjekt geöffnet werden soll.

[in] snbExclude

Wenn nicht NULL, zeiger auf einen Block von Elementen im Speicher, der beim Öffnen des Speicherobjekts ausgeschlossen werden soll. Der Ausschluss tritt unabhängig davon auf, ob eine Momentaufnahme Kopie im Geöffneten erfolgt. Kann NULL sein.

[in] reserved

Gibt an, dass für die zukünftige Verwendung reserviert ist; muss null sein.

[out] ppstgOpen

Ein Zeiger auf eine IStorage*-Zeigervariable, die den Schnittstellenzeiger auf den geöffneten Speicher empfängt.

Rückgabewert

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

Hinweise

Die StgOpenStorage-Funktion öffnet das angegebene Stammspeicherobjekt entsprechend dem Zugriffsmodus im GrfMode-Parameter und stellt bei erfolgreicher Ausführung einen IStorage-Zeiger auf das geöffnete Speicherobjekt im parameter ppstgOpen bereit.

Um den einfachen Modus zum Speichern eines Speicherobjekts ohne Unterspeicher zu unterstützen, akzeptiert die StgOpenStorage-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

Im direkten Modus ist eine der folgenden drei Kombinationen gültig.

    STGM_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE

    STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE

Hinweis Das Öffnen eines Speicherobjekts im Lese-/Schreibmodus, ohne anderen die Schreibberechtigung zu verweigern (der grfMode-Parameter gibt STGM_SHARE_DENY_WRITE an), kann zeitaufwendig sein, da der StgOpenStorage-Aufruf eine Momentaufnahme des gesamten Speicherobjekts erstellen muss.

 

Anwendungen versuchen häufig, Speicherobjekte mit den folgenden Zugriffsberechtigungen zu öffnen. Wenn die Anwendung erfolgreich ist, muss sie nie eine Momentaufnahme Kopie erstellen.

STGM_READWRITE | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition 

Die Anwendung kann rückgängig machen, die Berechtigungen zu verwenden und eine Momentaufnahme Kopie zu erstellen, wenn die vorherigen Zugriffsberechtigungen fehlschlagen. Die Anwendung sollte den Benutzer vor dem Erstellen einer zeitaufwendigen Kopie auffordern.

STGM_READWRITE 
    // transacted versus direct mode omitted for exposition 

Wenn die von den Zugriffsmodi implizierte Dokumentfreigabesemantik angemessen ist, könnte die Anwendung versuchen, den Speicher wie folgt zu öffnen. Wenn die Anwendung erfolgreich ist, wurde in diesem Fall keine Momentaufnahme Kopie erstellt (da STGM_SHARE_DENY_WRITE angegeben wurde und anderen Schreibzugriff verweigert wurde).

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition 

Hinweis Um den Aufwand für das Erstellen eines Momentaufnahme Kopierens zu reduzieren, können Anwendungen Speicherobjekte im Prioritätsmodus öffnen (grfMode gibt STGM_PRIORITY an).

 

Der snbExclude-Parameter gibt einen Satz von Elementnamen in diesem Speicherobjekt an, die beim Öffnen des Speicherobjekts geleert werden sollen: Streams werden auf eine Länge von 0 festgelegt; Bei Speicherobjekten werden alle zugehörigen Elemente entfernt. Durch das Ausschließen bestimmter Datenströme kann der Aufwand für die Erstellung einer Momentaufnahme Kopie erheblich reduziert werden. Fast immer wird dieser Ansatz verwendet, nachdem das Speicherobjekt zuerst im Prioritätsmodus geöffnet und dann die jetzt ausgeschlossenen Elemente vollständig in den Arbeitsspeicher gelesen wurde. Dieses frühere Öffnen des Prioritätsmodus des Speicherobjekts sollte über den pstgPriority-Parameter übergeben werden, um den im Prioritätsmodus implizierten Ausschluss zu entfernen. Die aufrufende Anwendung ist dafür verantwortlich, den Inhalt der ausgeschlossenen Elemente vor dem Commit neu zu schreiben. Daher ist dieses Verfahren wahrscheinlich nur für Anwendungen nützlich, deren Dokumente keinen konstanten Zugriff auf ihre Speicherobjekte benötigen, während sie aktiv sind.

Der pstgPriority-Parameter ist als Benutzerfreundlichkeit für Aufrufer gedacht, die ein vorhandenes Speicherobjekt ersetzen, das häufig im Prioritätsmodus geöffnet ist, durch ein neues Speicherobjekt, das in derselben Datei, aber in einem anderen Modus geöffnet wird. Wenn pstgPriority nicht NULL ist, wird es verwendet, um den Dateinamen anstelle von pwcsName anzugeben, der ignoriert wird. Es wird jedoch empfohlen, dass Anwendungen immer NULL für pstgPriority übergeben, da StgOpenStorage das Objekt unter bestimmten Umständen freigibt und es unter anderen Umständen nicht freigibt. Insbesondere wenn die Funktion ein Fehlerergebnis zurückgibt, ist es für den Aufrufer nicht möglich, zu bestimmen, ob das Speicherobjekt freigegeben wurde oder nicht.

Die Funktionalität des pstgPriority-Parameters kann vom Aufrufer sicherer dupliziert werden, wie im folgenden Beispiel gezeigt:

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

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

Weitere Informationen

IStorage

StgCreateDocfile

StgOpenStorageEx