IPersistStorage::InitNew-Methode (objidl.h)

  • Artikel

Initialisiert ein neues Speicherobjekt.

Syntax

HRESULT InitNew(
  [in] IStorage *pStg
);

Parameter

[in] pStg

Ein IStorage-Zeiger auf das neue Speicherobjekt, das initialisiert werden soll. Der Container erstellt ein geschachteltes Speicherobjekt in seinem Speicherobjekt (siehe IStorage::CreateStorage). Anschließend ruft der Container die WriteClassStg-Funktion auf, um das neue Speicherobjekt mit dem Objektklassenbezeichner (Object Class Identifier, CLSID) zu initialisieren.

Rückgabewert

Diese Methode kann die folgenden Werte zurückgeben.

Rückgabecode BESCHREIBUNG
S_OK
 Die Methode wurde erfolgreich abgeschlossen.
CO_E_ALREADYINITIALIZED
 Das Objekt wurde bereits durch einen vorherigen Aufruf der IPersistStorage::Load-Methode oder der IPersistStorage::InitNew-Methode initialisiert.
E_OUTOFMEMORY
 Das Speicherobjekt wurde aufgrund eines Mangels an Arbeitsspeicher nicht initialisiert.
E_FAIL
 Das Speicherobjekt wurde aus einem anderen Grund als einem Mangel an Arbeitsspeicher nicht initialisiert.

Hinweise

Eine Containeranwendung kann diese Methode aufrufen, wenn sie ein neues Objekt initialisieren muss, z. B. mit einem InsertObject-Befehl.

Ein Objekt, das die IPersistStorage-Schnittstelle unterstützt, muss während der Ausführung jederzeit Zugriff auf ein gültiges Speicherobjekt haben. Dies schließt die Zeit ein, nachdem das Objekt erstellt wurde, aber bevor es dauerhaft festgelegt wurde. Der Container des Objekts muss während dieser Zeit über den Aufruf von IPersistStorage::InitNew einen gültigenIStorage-Zeiger auf den Speicher bereitstellen. Abhängig vom Status des Containers muss zu diesem Zweck möglicherweise eine temporäre Datei erstellt werden.

Wenn das Objekt die IStorage-instance beibehalten möchte, muss es AddRef aufrufen, um seine Verweisanzahl zu erhöhen.

Nach dem Aufruf von IPersistStorage::InitNew befindet sich das Objekt entweder im geladenen oder ausgeführten Zustand. Wenn die Objektklasse beispielsweise über einen prozessinternen Server verfügt, befindet sich das Objekt im Status "Wird ausgeführt". Wenn das -Objekt jedoch den Standardhandler verwendet, ruft der InitNew-Aufruf des Containers nur die Implementierung des Handlers auf, die das Objekt nicht ausführt. Wenn der Container das -Objekt später ausführt, ruft der Handler die InitNew-Methode für das -Objekt auf.

Hinweise für Anrufer

Anstatt IPersistStorage::InitNew direkt aufzurufen, rufen Sie in der Regel die OleCreate-Hilfsfunktion auf , die Folgendes ausführt:
  1. Ruft die CoCreateInstance-Funktion auf, um eine instance der Objektklasse zu erstellen.
  2. Fragt die neue instance für die IPersistStorage-Schnittstelle ab.
  3. Ruft die InitNew-Methode auf, um das -Objekt zu initialisieren.
Die Containeranwendung sollte den IPersistStorage-Zeiger auf das -Objekt zwischenspeichern, um in späteren Vorgängen für das Objekt verwendet zu werden.

Hinweise für Implementierer

Eine Implementierung von IPersistStorage::InitNew sollte das Objekt in seinen Standardzustand initialisieren und dabei die folgenden Schritte ausführen:
  1. Öffnen Und zwischenspeichern Sie die Zeiger auf alle Datenströme oder Speicher, die das Objekt benötigt, um sich selbst in diesem Speicher zu speichern.
  2. Rufen Sie AddRef auf, und speichern Sie den übergebenen Speicherzeiger zwischen.
  3. Rufen Sie die WriteFmtUserTypeStg-Funktion auf, um das native Zwischenablageformat und die Benutzertypzeichenfolge für das Objekt in das Speicherobjekt zu schreiben.
  4. Legen Sie das modifiziert-Flag für das -Objekt fest.
Die ersten beiden Schritte sind besonders wichtig, um sicherzustellen, dass sich das Objekt in Situationen mit geringem Arbeitsspeicher selbst speichern kann. Das Voraböffnen und Halten von Zeigern auf den Stream und die Speicherschnittstellen stellt sicher, dass ein Speichervorgang für diesen Speicher nicht aufgrund von unzureichendem Arbeitsspeicher fehlschlägt.

Ihre Implementierung dieser Methode sollte den CO_E_ALREADYINITIALIZED Fehlercode zurückgeben, wenn sie einen Aufruf der IPersistStorage::InitNew-Methode oder der IPersistStorage::Load-Methode empfängt, nachdem sie bereits initialisiert wurde.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile objidl.h

Weitere Informationen

IPersistStorage