StgCreateDocfileOnILockBytes-Funktion (coml2api.h)
Die Funktion StgCreateDocfileOnILockBytes erstellt und öffnet ein neues zusammengesetztes Dateispeicherobjekt oben in einem Byte-Array-Objekt, das vom Aufrufer bereitgestellt wird. Das Speicherobjekt unterstützt die com-bereitgestellte, zusammengesetzte Dateiimplementierung 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 auf dem zugrunde liegenden Byte-Array-Objekt, auf dem eine zusammengesetzte Datei erstellt werden soll.
[in] grfMode
Gibt den Zugriffsmodus an, der beim Öffnen der neuen Zusammengesetzten Datei verwendet werden soll. Weitere Informationen finden Sie unter STGM-Konstanten und im Abschnitt "Hinweise" unten.
[in] reserved
Für die zukünftige Verwendung reserviert. Muss 0 (null) sein.
[out] ppstgOpen
Ein Zeiger auf den Speicherort des IStorage-Zeigers auf dem neuen Speicherobjekt.
Rückgabewert
Die Funktion StgCreateDocfileOnILockBytes kann auch alle Dateisystemfehler oder Systemfehler zurückgeben, die in eine HRESULT- oder ILockBytes-Schnittstelle eingeschlossen sind. Weitere Informationen finden Sie unter "Fehlerbehandlungsstrategien " und "Behandeln unbekannter Fehler".
Bemerkungen
Die Funktion StgCreateDocfileOnILockBytes erstellt ein Speicherobjekt oben auf einem Byte-Arrayobjekt mithilfe der com-bereitgestellten, zusammengesetzten Dateiimplementierung der IStorage-Schnittstelle . StgCreateDocfileOnILockBytes können verwendet werden, um ein Dokument in einem beliebigen Datenspeicher zu speichern, z. B. Arbeitsspeicher oder eine relationale Datenbank. Das Bytearray (angegeben durch den pLkbyt-Parameter , der auf die ILockBytes-Schnittstelle auf dem Objekt verweist) wird für den zugrunde liegenden Speicher anstelle einer Datenträgerdatei verwendet.
Mit Ausnahme der Angabe eines vom Programmprogramm bereitgestellten Byte-Array-Objekts ist StgCreateDocfileOnILockBytes ähnlich wie die StgCreateDocfile-Funktion .
Die neu erstellte Zusammengesetzte Datei wird gemäß den Zugriffsmodi im grfMode-Parameter geöffnet, die den folgenden Einschränkungen unterliegen:
Das Freigabemodusverhalten und die Transaktionsisolation hängen von der ILockBytes-Implementierung ab, die LockRegion und UnlockRegion mit LOCK_ONLYONCE Semantik unterstützt. Implementierungen können den strukturierten Speicher angeben, den sie 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 transaktionsbasierte Commits auf Stammebene werden nicht ordnungsgemäß mit anderen Transaktionsinstanzen koordiniert, die auf demselben Bytearray geöffnet wurden. Anwendungen, die eine ILockBytes-Implementierung verwenden, die die Bereichssperre nicht unterstützt, z. B. die CreateStreamOnHGlobal-Implementierung , sollten vermeiden, mehrere gleichzeitige Instanzen auf dem gleichen Bytearray zu öffnen.
StgCreateDocfileOnILockBytes unterstützt keinen einfachen Modus. Das STGM_SIMPLE-Flag , falls vorhanden, wird ignoriert.
Für Konvertierungszwecke gilt die Datei als bereits vorhanden. Daher ist es nicht nützlich, den STGM_FAILIFTHERE Wert zu verwenden, da ein Fehler zurückgegeben wird. Sowohl STGM_CREATE als auch STGM_CONVERT bleiben jedoch nützlich.
Die Möglichkeit, eine zusammengesetzte Datei oben in einem Byte-Array-Objekt zu erstellen, wird bereitgestellt, um die Daten (unter einer IStorage - und IStream-Struktur ) in einem nichtpersistenten Raum zu unterstützen. Angesichts dieser Funktion gibt es nichts, was verhindert, dass ein Dokument, das in einer Datei gespeichert wird, diese Einrichtung verwendet. Beispielsweise kann ein Container dazu führen, dass die Auswirkungen auf das Dateiformat minimiert werden, die durch die Annahme von COM verursacht werden. Es wird jedoch empfohlen, dass COM-Dokumente die IStorage-Schnittstelle für den eigenen externen Speicher ü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 die Anwendung behandeln muss.
- Man kann Tools schreiben, um auf die eingebetteten und verknüpften OLE-Objekte im Dokument zuzugreifen, ohne spezielle Kenntnisse des Dateiformats des Dokuments. 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 Kopierprogramm wie diese 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 vorgenommen werden. Eine Anwendung mit der ILockBytes-Schnittstelle muss diese Probleme selbst behandeln.
Anforderungen
| 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 (einschließlich Objbase.h) |
| Bibliothek | Ole32.lib |
| DLL | Ole32.dll |