StgOpenStorageOnILockBytes-Funktion (coml2api.h)

Die StgOpenStorageOnILockBytes-Funktion öffnet ein vorhandenes Speicherobjekt, das sich nicht in einer Datenträgerdatei befindet, sondern stattdessen über ein vom Aufrufer bereitgestelltes zugrunde liegendes Bytearray verfügt.

Syntax

HRESULT StgOpenStorageOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  IStorage   *pstgPriority,
  [in]  DWORD      grfMode,
  [in]  SNB        snbExclude,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parameter

[in] plkbyt

ILockBytes-Zeiger auf das zugrunde liegende Bytearrayobjekt, das das zu öffnende Speicherobjekt enthält.

[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 StgOpenStorageOnILockBytes zurückgegeben wurde , wurde das in pStgPriority angegebene Speicherobjekt möglicherweise freigegeben und sollte nicht mehr verwendet werden.

[in] grfMode

Gibt den Zugriffsmodus an, der zum Öffnen des Speicherobjekts verwendet werden soll. Weitere Informationen finden Sie unter STGM-Konstanten und weiter unten im Abschnitt Hinweise.

[in] snbExclude

Kann NULL sein. Wenn nicht NULL, verweist dieser Parameter auf einen Block von Elementen in diesem Speicher, die beim Öffnen des Speicherobjekts ausgeschlossen werden sollen. Dieser Ausschluss erfolgt unabhängig davon, ob eine Momentaufnahme Kopie auf dem geöffneten erfolgt.

[in] reserved

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

[out] ppstgOpen

Zeigt auf den Speicherort eines IStorage-Zeigers auf den geöffneten Speicher bei erfolgreicher Rückgabe.

Rückgabewert

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

Hinweise

StgOpenStorageOnILockBytes öffnet das angegebene Stammspeicherobjekt. Ein Zeiger auf die IStorage-Schnittstelle für das geöffnete Speicherobjekt wird über den ppstgOpen-Parameter bereitgestellt.

Das Speicherobjekt muss zuvor von der Funktion StgCreateDocfileOnILockBytes erstellt worden sein.

Mit Ausnahme der Angabe eines vom Programmierer bereitgestellten Bytearrayobjekts ähnelt StgOpenStorageOnILockBytes der StgOpenStorage-Funktion . Das Speicherobjekt wird gemäß den Zugriffsmodi im GrfMode-Parameter geöffnet, vorbehaltlich der folgenden Einschränkungen:

Das Verhalten im Freigabemodus und die Transaktionsisolation hängen von der ILockBytes-Implementierung ab, die LockRegion und UnlockRegion mit LOCK_ONLYONCE Semantik unterstützt. Implementierungen können dem strukturierten Speicher angeben, dass sie diese Funktionalität unterstützen, indem sie das LOCK_ONLYONCE Bit im grfLocksSupported-Member von STATSTG festlegen. Wenn eine ILockBytes-Implementierung diese Funktionalität nicht unterstützt, werden Freigabemodi nicht erzwungen, und Transaktionscommits auf Stammebene stimmen nicht ordnungsgemäß mit anderen Transaktionsinstanzen überein, die im gleichen Bytearray geöffnet werden. Anwendungen, die eine ILockBytes-Implementierung verwenden, die keine Regionssperrung unterstützt, z. B. die CreateStreamOnHGlobal-Implementierung , sollten das Öffnen mehrerer gleichzeitiger Instanzen in demselben Bytearray vermeiden.

StgOpenStorageOnILockBytes unterstützt den einfachen Modus nicht. Das STGM_SIMPLE-Flag wird ignoriert, sofern vorhanden.

Der pStgPriority-Parameter dient als Benutzerfreundlichkeit für Aufrufer, die ein vorhandenes Speicherobjekt ersetzen, das häufig im Prioritätsmodus geöffnet wird, durch ein neues Speicherobjekt, das auf demselben Bytearray geöffnet wird. Im Gegensatz zum pStgPriority-Parameter von StgOpenStorage wirkt sich dieser Parameter nicht auf den von StgOpenStorageOnILockBytes ausgeführten Open-Vorgang aus und ist einfach ein vorhandenes Speicherobjekt, das der Aufrufer loslassen möchte. Aufrufer sollten für diesen Parameter immer NULL übergeben, da StgOpenStorageOnILockBytes das Objekt unter bestimmten Umständen freigibt und es unter anderen Umständen nicht freigibt. Die Verwendung des pStgPriority-Parameters kann vom Aufrufer auf sicherere Weise dupliziert werden, indem das Objekt stattdessen vor dem Aufruf von StgOpenStorageOnILockBytes freigegeben wird, wie im folgenden Beispiel gezeigt:

// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &pstgNew);

pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);
    

Weitere Informationen finden Sie unter StgOpenStorage.

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

StgCreateDocfileOnILockBytes

StgOpenStorage