StgCreateDocfileOnILockBytes-Funktion (coml2api.h)

  • Artikel

Die StgCreateDocfileOnILockBytes-Funktion erstellt und öffnet ein neues Verbunddateispeicherobjekt auf einem vom Aufrufer bereitgestellten Bytearrayobjekt. Das Speicherobjekt unterstützt die com-bereitgestellte Verbunddateiimplementierung für die IStorage-Schnittstelle .

Syntax

HRESULT StgCreateDocfileOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  DWORD      grfMode,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parameter

[in] plkbyt

Ein Zeiger auf die ILockBytes-Schnittstelle des zugrunde liegenden Bytearrayobjekts, für das eine Verbunddatei erstellt werden soll.

[in] grfMode

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

[in] reserved

Für die zukünftige Verwendung reserviert. Muss 0 (null) sein.

[out] ppstgOpen

Ein Zeiger auf die Position des IStorage-Zeigers für das neue Speicherobjekt.

Rückgabewert

Die StgCreateDocfileOnILockBytes-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

Die StgCreateDocfileOnILockBytes-Funktion erstellt ein Speicherobjekt über einem Bytearrayobjekt mithilfe der com-bereitgestellten Verbunddateiimplementierung der IStorage-Schnittstelle . StgCreateDocfileOnILockBytes kann verwendet werden, um ein Dokument in einem beliebigen Datenspeicher wie Arbeitsspeicher oder einer relationalen Datenbank zu speichern. Das Bytearray (angegeben durch den pLkbyt-Parameter , der auf die ILockBytes-Schnittstelle im Objekt verweist) wird für den zugrunde liegenden Speicher anstelle einer Datenträgerdatei verwendet.

Mit Ausnahme der Angabe eines vom Programmierer bereitgestellten Bytearrayobjekts ähnelt StgCreateDocfileOnILockBytes der Funktion StgCreateDocfile .

Die neu erstellte Verbunddatei 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.

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

Zu Konvertierungszwecken gilt die Datei als bereits vorhanden. Daher ist es nicht sinnvoll, den wert STGM_FAILIFTHERE zu verwenden, da dadurch ein Fehler zurückgegeben wird. Sowohl STGM_CREATE als auch STGM_CONVERT bleiben jedoch nützlich.

Die Möglichkeit, eine Verbunddatei auf einem Bytearrayobjekt zu erstellen, wird bereitgestellt, um zu unterstützen, dass sich die Daten (unterhalb einer IStorage - und IStream-Struktur ) in einem nicht permanenten Raum befinden. Angesichts dieser Funktion gibt es nichts, was ein in einer Datei gespeichertes Dokument daran hindert, diese Funktion zu verwenden. Ein Container kann dies beispielsweise tun, um die Auswirkungen auf sein Dateiformat zu minimieren, die durch die Einführung von COM verursacht werden. Es wird jedoch empfohlen, dass COM-Dokumente die IStorage-Schnittstelle für ihren eigenen Speicher auf äußerer Ebene übernehmen. Dies bietet die folgenden Vorteile:

  • Die Speicherstruktur des Dokuments entspricht der Speicherstruktur, wenn es sich um ein eingebettetes Objekt handelt, wodurch die Anzahl der Fälle reduziert wird, die von der Anwendung behandelt werden müssen.
  • Sie können Tools schreiben, um auf die eingebetteten und verknüpften OLE-Objekte im Dokument zuzugreifen, ohne besondere Kenntnisse des Dateiformats des Dokuments zu haben. Ein Beispiel für ein solches Tool ist ein Kopierprogramm, das alle Dokumente kopiert, die in einem Container enthalten sind, der verknüpfte Objekte enthält. Ein solches Kopierprogramm benötigt Zugriff auf die enthaltenen Links, um den Umfang der zu kopierenden Dateien zu bestimmen.
  • Die IStorage-Implementierung behebt das Problem, wie die Änderungen an der Datei committet werden. Eine Anwendung, die die ILockBytes-Schnittstelle verwendet, muss diese Probleme selbst behandeln.

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

StgCreateDocfile