StgCreateDocfile-Funktion (coml2api.h)
Die StgCreateDocfile-Funktion erstellt ein neues zusammengesetztes Dateispeicherobjekt mithilfe der com-bereitgestellten Verbunddateiimplementierung für die IStorage-Schnittstelle .
Syntax
HRESULT StgCreateDocfile(
[in] const WCHAR *pwcsName,
[in] DWORD grfMode,
[in] DWORD reserved,
[out] IStorage **ppstgOpen
);
Parameter
[in] pwcsName
Ein Zeiger auf einen Unicode-Zeichenfolgennamen mit NULL-Beendigung für die zu erstellende Verbunddatei. Es wird uninterpretiert an das Dateisystem übergeben. Dies kann ein relativer Name oder NULL sein. Wenn NULL, wird eine temporäre zusammengesetzte Datei mit einem eindeutigen Namen zugeordnet.
[in] grfMode
Gibt den Zugriffsmodus an, der beim Öffnen des neuen Speicherobjekts verwendet werden soll. 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 für das Stammspeicherobjekt nicht 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.
[in] reserved
Für die zukünftige Verwendung reserviert. Muss 0 (null) sein.
[out] ppstgOpen
Ein Zeiger auf die Position des IStorage-Zeigers auf das neue Speicherobjekt.
Rückgabewert
StgCreateDocfile 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
Die StgCreateDocfile-Funktion erstellt ein neues Speicherobjekt mithilfe der com-bereitgestellten Verbunddateiimplementierung für die IStorage-Schnittstelle . Der Name der geöffneten Verbunddatei kann durch Aufrufen der IStorage::Stat-Methode abgerufen werden.
StgCreateDocfile erstellt die Datei, wenn sie nicht vorhanden ist. Falls vorhanden, gibt die Verwendung der Flags STGM_CREATE, STGM_CONVERT und STGM_FAILIFTHERE im GrfMode-Parameter an, wie sie fortgesetzt werden soll. Weitere Informationen finden Sie unter STGM-Konstanten.
Wenn die Verbunddatei im Transaktionsmodus geöffnet wird (der grfMode-Parameter gibt STGM_TRANSACTED an) und eine Datei mit diesem Namen bereits vorhanden ist, wird die vorhandene Datei erst geändert, wenn ein Commit für alle ausstehenden Änderungen erfolgt ist. Wenn der aufrufende Prozess keinen Schreibzugriff auf die vorhandene Datei hat (aufgrund der Zugriffssteuerung im Dateisystem), kann der grfMode-Parameter nur STGM_READ und nicht STGM_WRITE oder STGM_READWRITE angeben. Die resultierende neue geöffnete Verbunddatei kann weiterhin in geschrieben werden, aber bei einem nachfolgenden Commitvorgang tritt ein Fehler auf (im Transaktionsmodus werden Schreibberechtigungen zum Commitzeitpunkt erzwungen).
Die Angabe STGM_SIMPLE ermöglicht eine viel schnellere Implementierung eines zusammengesetzten Dateiobjekts in einem begrenzten, aber häufig verwendeten Fall. Dies kann von Anwendungen verwendet werden, die eine Verbunddateiimplementierung mit mehreren Streams und ohne Speicher erfordern. Der einfache Modus unterstützt nicht alle Methoden in IStorage. Weitere Informationen finden Sie unter STGM-Konstanten.
Wenn der grfMode-Parameter STGM_TRANSACTED angibt und noch keine Datei mit dem durch den parameter pwcsName angegebenen Namen vorhanden ist, wird die Datei sofort erstellt. In einem zugriffsgesteuerten Dateisystem muss der Aufrufer über Schreibberechtigungen im Dateisystemverzeichnis verfügen, in dem die Verbunddatei erstellt wird. Wenn STGM_TRANSACTED nicht angegeben ist und STGM_CREATE angegeben ist, wird eine vorhandene Datei mit demselben Namen zerstört, bevor die neue Datei erstellt wird.
StgCreateDocfile kann verwendet werden, um eine temporäre Verbunddatei zu erstellen, indem ein NULL-Wert für den pwcsName-Parameter übergeben wird. Diese Dateien sind jedoch nur in dem Sinne temporär, dass sie über einen vom System bereitgestellten eindeutigen Namen verfügen – wahrscheinlich einen, der für den Benutzer bedeutungslos ist. Der Aufrufer ist für das Löschen der temporären Datei verantwortlich, wenn er damit fertig ist, es sei denn, STGM_DELETEONRELEASE wurde für den grfMode-Parameter angegeben.
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 |