StgCreateStorageEx-Funktion (coml2api.h)

Artikel
08/22/2023

Die StgCreateStorageEx-Funktion erstellt ein neues Speicherobjekt mithilfe einer bereitgestellten Implementierung für die IStorage - oder IPropertySetStorage-Schnittstelle . Verwenden Sie zum Öffnen einer vorhandenen Datei stattdessen die StgOpenStorageEx-Funktion .

Anwendungen, die für Windows 2000, Windows Server 2003 und Windows XP geschrieben wurden, müssen StgCreateStorageEx anstelle von StgCreateDocfile verwenden, um die erweiterten Strukturierten Speicherfunktionen von Windows 2000 und Windows XP zu nutzen.

Syntax

HRESULT StgCreateStorageEx(
  [in]  const WCHAR          *pwcsName,
  [in]  DWORD                grfMode,
  [in]  DWORD                stgfmt,
  [in]  DWORD                grfAttrs,
  [in]  STGOPTIONS           *pStgOptions,
  [in]  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]  REFIID               riid,
  [out] void                 **ppObjectOpen
);

Parameter

[in] pwcsName

Ein Zeiger auf den Pfad der zu erstellenden Datei. Es wird uninterpretiert an das Dateisystem übergeben. Dies kann ein relativer Name oder NULL sein. Wenn NULL, wird eine temporäre Datei mit einem eindeutigen Namen zugeordnet. Wenn nicht NULL, darf die Zeichenfolgengröße MAX_PATH Zeichen nicht überschreiten.

Windows 2000: Im Gegensatz zur CreateFile-Funktion können Sie den grenzwert für MAX_PATH nicht überschreiten, indem Sie das Präfix "\?" verwenden.

[in] grfMode

Ein -Wert, der den Zugriffsmodus angibt, 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] stgfmt

Ein -Wert, der das Speicherdateiformat angibt. Weitere Informationen finden Sie in der STGFMT-Enumeration .

[in] grfAttrs

Ein Wert, der vom Wert des stgfmt-Parameters abhängt.

Parameterwerte	Bedeutung
STGFMT_DOCFILE	0 oder FILE_FLAG_NO_BUFFERING. Weitere Informationen finden Sie unter CreateFile. Wenn die in pStgOptions angegebene Sektorgröße der Datei kein ganzzahliges Vielfaches der physischen Sektorgröße des zugrunde liegenden Datenträgers ist, schlägt dieser Vorgang fehl.
Alle anderen Werte von stgfmt	Muss den Wert 0 (null) haben.

[in] pStgOptions

Der pStgOptions-Parameter ist nur gültig, wenn der stgfmt-Parameter auf STGFMT_DOCFILE festgelegt ist. Wenn der stgfmt-Parameter auf STGFMT_DOCFILE festgelegt ist, verweist pStgOptions auf die STGOPTIONS-Struktur , die Features des Speicherobjekts angibt, z. B. die Sektorgröße. Dieser Parameter kann NULL sein, wodurch ein Speicherobjekt mit einer Standardsektorgröße von 512 Byte erstellt wird. Wenn nicht NULL, muss der ulSectorSize-Member entweder auf 512 oder 4096 festgelegt werden. Wenn dieser Wert auf 4096 festgelegt ist, kann STGM_SIMPLE im grfMode-Parameter nicht angegeben werden. Das usVersion-Element muss vor dem Aufrufen von StgCreateStorageEx festgelegt werden. Weitere Informationen finden Sie unter STGOPTIONS.

[in] pSecurityDescriptor

Ermöglicht das Festlegen der ACLs beim Erstellen der Datei. Wenn nicht NULL, muss ein Zeiger auf die SECURITY_ATTRIBUTES-Struktur sein. Informationen zum Festlegen von ACLs für Dateien finden Sie unter CreateFile .

Windows Server 2003, Windows 2000 Server, Windows XP und Windows 2000 Professional: Der Wert muss NULL sein.

[in] riid

Ein -Wert, der den Schnittstellenbezeichner (Interface Identifier, IID) des zurückzugebenden Schnittstellenzeigers angibt. Diese IID kann für die IStorage-Schnittstelle oder die IPropertySetStorage-Schnittstelle gelten.

[out] ppObjectOpen

Ein Zeiger auf eine Schnittstellenzeigervariable, die einen Zeiger für eine Schnittstelle im neuen Speicherobjekt empfängt; enthält NULL , wenn der Vorgang fehlgeschlagen ist.

Rückgabewert

Diese Funktion 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

Wenn eine Anwendung ihre Datei ändert, erstellt sie in der Regel eine Kopie des Originals. Die StgCreateStorageEx-Funktion ist eine Möglichkeit zum Erstellen einer Kopie. Diese Funktion funktioniert indirekt mit der EFS-Duplizierungs-API (Encrypting File System). Wenn Sie diese Funktion verwenden, müssen Sie die Optionen für den Dateispeicher in der STGOPTIONS-Struktur festlegen.

StgCreateStorageEx ist eine Obermenge der StgCreateDocfile-Funktion und sollte von neuem Code verwendet werden. Zukünftige Erweiterungen des strukturierten Speichers werden über die StgCreateStorageEx-Funktion verfügbar gemacht. Informationen zu unterstützten Plattformen finden Sie im folgenden Abschnitt "Anforderungen".

Die StgCreateStorageEx-Funktion erstellt ein neues Speicherobjekt mithilfe einer der vom System bereitgestellten, strukturierten Speicherimplementierungen. Diese Funktion kann verwendet werden, um eine
IStorage-Verbunddateiimplementierung, eine IPropertySetStorage-Verbunddateiimplementierung oder zum Abrufen einer IPropertySetStorage-NTFS-Implementierung.

Wenn eine neue Datei erstellt wird, hängt die verwendete Speicherimplementierung vom angegebenen Flag und vom Typ des Laufwerks ab, auf dem die Datei gespeichert ist. Weitere Informationen finden Sie in der STGFMT-Enumeration .

StgCreateStorageEx 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 zu diesen Werten finden Sie unter STGM-Konstanten. Im direkten Modus ist es ungültig, den STGM_READ Modus im GrfMode-Parameter anzugeben (der direkte Modus wird durch keine Angabe des flags STGM_TRANSACTED angegeben). Diese Funktion kann nicht verwendet werden, um eine vorhandene Datei zu öffnen. Verwenden Sie stattdessen die StgOpenStorageEx-Funktion .

Sie können die StgCreateStorageEx-Funktion verwenden, um Zugriff auf den Stammspeicher eines strukturierten Speicherdokuments oder auf den Eigenschaftensatzspeicher einer beliebigen Datei zu erhalten, die Eigenschaftssätze unterstützt. Informationen dazu, welche IIDs für verschiedene STGFMT-Werte unterstützt werden, finden Sie in der STGFMT-Dokumentation .

Wenn eine Datei mit dieser Funktion für den Zugriff auf die NTFS-Eigenschaftensatzimplementierung erstellt wird, gelten spezielle Freigaberegeln. Weitere Informationen finden Sie unter IPropertySetStorage-NTFS-Implementierung.

Wenn eine zusammengesetzte Datei im Transaktionsmodus (durch Angabe von STGM_TRANSACTED) und schreibgeschütztem Modus (durch Angabe STGM_READ) erstellt wird, ist es möglich, Änderungen am zurückgegebenen Speicherobjekt vorzunehmen. Beispielsweise ist es möglich, IStorage::CreateStream aufzurufen. Es ist jedoch nicht möglich, diese Änderungen durch Aufrufen von IStorage::Commit zu committen. Daher gehen solche Änderungen verloren.

Die Angabe STGM_SIMPLE ermöglicht eine viel schnellere Implementierung eines zusammengesetzten Dateiobjekts in einem begrenzten, aber häufig verwendeten Fall mit Anwendungen, die eine Verbunddateiimplementierung mit mehreren Streams und ohne Speicher erfordern. Weitere Informationen finden Sie unter STGM-Konstanten. Es ist ungültig, diese STGM_TRANSACTED anzugeben, wenn STGM_SIMPLE angegeben wird.

Der einfache Modus unterstützt nicht alle Methoden in IStorage. Insbesondere im einfachen Modus werden die IStorage-MethodenCreateStream, Commit und SetClass sowie die COM IUnknown-Methoden von QueryInterface, AddRef und Release unterstützt. Darüber hinaus wird SetElementTimes mit einem NULL-Namen unterstützt, sodass Anwendungen Zeiten für einen Stammspeicher festlegen können. Alle anderen Methoden von IStorage geben STG_E_INVALIDFUNCTION zurück.

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 für das Dateisystemverzeichnis verfügen, in dem die Verbunddatei erstellt wird. Wenn STGM_TRANSACTED nicht angegeben ist und STGM_CREATE angegeben wird, wird eine vorhandene Datei mit demselben Namen vor dem Erstellen der neuen Datei zerstört.

Sie können auch StgCreateStorageEx verwenden, um eine temporäre Verbunddatei zu erstellen, indem Sie einen NULL-Wert für den parameter pwcsName übergeben. Diese Dateien sind jedoch nur in dem Sinne temporär, dass sie einen eindeutigen, vom System bereitgestellten Namen haben , der für den Benutzer wahrscheinlich 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. Weitere Informationen zu diesen Flags finden Sie unter STGM-Konstanten.

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 (include Objbase.h)
Bibliothek	Ole32.lib
DLL	Ole32.dll