StgCreateStorageEx-Funktion (coml2api.h)

Artikel
11/20/2024

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

Für Windows 2000 geschriebene Anwendungen, Windows Server 2003 und Windows XP müssen StgCreateStorageEx- anstelle StgCreateDocfile- verwenden, um die erweiterten Windows 2000- und Windows XP Structured Storage-Features nutzen zu können.

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 nicht interpretiert an das Dateisystem übergeben. Dies kann ein relativer Name oder NULL-sein. Wenn NULL-, wird eine temporäre Datei mit einem eindeutigen Namen zugewiesen. Wenn nicht-NULL-, darf die Zeichenfolgengröße MAX_PATH Zeichen nicht überschreiten.

Windows 2000: Im Gegensatz zur CreateFile--Funktion können Sie die MAX_PATH Grenze 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, wird die Überschreibung oder Konvertierung ausgeführt, wenn der Commitvorgang für den Stammspeicher aufgerufen wird. Wenn IStorage::Commit nicht für das Stammspeicherobjekt aufgerufen wird, werden vorherige Inhalte der Datei wiederhergestellt. STGM_CREATE und STGM_CONVERT können nicht mit dem STGM_NOSNAPSHOT-Flag kombiniert werden, da eine Momentaufnahmekopie 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 -Enumeration STGFMT.

[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 Sektorgröße der Datei, die in pStgOptionsangegeben ist, kein ganzzahliges Vielfaches der physischen Größe des zugrunde liegenden Datenträgers ist, schlägt dieser Vorgang fehl.
Alle anderen Werte von stgfmt	Muss 0 sein.

[in] pStgOptions

Der pStgOptions-parameter ist nur gültig, wenn der stgfmt-parameter auf STGFMT_DOCFILE festgelegt ist. Wenn der parameter stgfmt 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 das ulSectorSize Member entweder auf 512 oder 4096 festgelegt werden. Bei Festlegung auf 4096 kann STGM_SIMPLE im grfMode--Parameter nicht angegeben werden. Das usVersion Member muss festgelegt werden, bevor StgCreateStorageEx-aufgerufen wird. Weitere Informationen finden Sie unter STGOPTIONS.

[in] pSecurityDescriptor

Aktiviert das Festlegen der ACLs, wenn die Datei erstellt wird. Wenn NULL-nicht, muss es sich um einen 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: Wert muss NULL-sein.

[in] riid

Ein Wert, der den schnittstellenbezeichner (IID) des zurückzugebenden Schnittstellenzeigers angibt. Diese IID kann für die IStorage Schnittstelle oder die IPropertySetStorage Schnittstelle verwendet werden.

[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 einem HRESULT-eingeschlossen sind. Weitere Informationen finden Sie unter Strategien zur Fehlerbehandlung und Behandlung unbekannter Fehler.

Bemerkungen

Wenn eine Anwendung die Datei ändert, erstellt sie in der Regel eine Kopie des Originals. Die funktion StgCreateStorageEx 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 funktion StgCreateDocfile und sollte von neuem Code verwendet werden. Zukünftige Verbesserungen an strukturiertem Speicher werden über die funktion StgCreateStorageEx 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 Compound File Implementation, eine IPropertySetStorage compound file implementation, oder um eine IPropertySetStorage NTFS-Implementierungabzurufen.

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

StgCreateStorageEx erstellt die Datei, wenn sie nicht vorhanden ist. Falls vorhanden, geben die Verwendung der STGM_CREATE, STGM_CONVERT und STGM_FAILIFTHERE Flags im grfMode Parameter an, wie der Vorgang fortgesetzt werden soll. Weitere Informationen zu diesen Werten finden Sie unter STGM-Konstanten. Es ist im direkten Modus ungültig, um den STGM_READ Modus im grfMode Parameter anzugeben (der direkte Modus wird durch angabe des STGM_TRANSACTED Flags angegeben). Diese Funktion kann nicht zum Öffnen einer vorhandenen Datei verwendet werden. verwenden Sie stattdessen die funktion StgOpenStorageEx.

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

Wenn eine Datei mit dieser Funktion erstellt wird, um auf die NTFS-Eigenschaftensatzimplementierung zuzugreifen, gelten spezielle Freigaberegeln. Weitere Informationen finden Sie unter IPropertySetStorage-NTFS Implementierung.

Wenn eine Verbunddatei im Transacted-Modus (durch Angeben von STGM_TRANSACTED) und schreibgeschützten Modus (durch Angeben von 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::Commitzu übernehmen. Daher gehen solche Änderungen verloren.

Das Angeben von STGM_SIMPLE bietet eine wesentlich schnellere Implementierung eines zusammengesetzten Dateiobjekts in einem begrenzten, aber häufig verwendeten Fall mit Anwendungen, die eine zusammengesetzte Dateiimplementierung mit mehreren Datenströmen und keine Speicher erfordern. Weitere Informationen finden Sie unter STGM-Konstanten. Es ist ungültig, um anzugeben, dass STGM_TRANSACTED, wenn STGM_SIMPLE angegeben ist.

Der einfache Modus unterstützt nicht alle Methoden für IStorage. Im einfachen Modus werden unterstützte IStorage- Methoden CreateStream, Commitund SetClass sowie die COM-IUnknown Methoden von QueryInterface, AddRef und Release. 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 STG_E_INVALIDFUNCTION zurückgeben.

Wenn der parameter grfMode STGM_TRANSACTED angibt und noch keine Datei mit dem Namen vorhanden ist, der durch den parameter pwcsName angegeben ist, wird die Datei sofort erstellt. In einem zugriffsgesteuerten Dateisystem muss der Aufrufer Schreibberechtigungen für das Dateisystemverzeichnis besitzen, in dem die Verbunddatei erstellt wird. Wenn STGM_TRANSACTED nicht angegeben ist und STGM_CREATE angegeben wird, wird vor dem Erstellen der neuen Datei eine vorhandene Datei mit demselben Namen 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 über einen eindeutigen vom System bereitgestellten Namen verfügen – einer, der dem Benutzer wahrscheinlich bedeutungslos ist. Der Aufrufer ist dafür verantwortlich, die temporäre Datei zu löschen, wenn sie fertig ist, es sei denn, STGM_DELETEONRELEASE für den parameter grfMode angegeben wurde. Weitere Informationen zu diesen Flags finden Sie unter STGM-Konstanten.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows 2000 Server [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	coml2api.h (include Objbase.h)
Library	Ole32.lib
DLL-	Ole32.dll