Metodo IPersistStorage::InitNew (objidl.h)

  • Articolo

Inizializza un nuovo oggetto di archiviazione.

Sintassi

HRESULT InitNew(
  [in] IStorage *pStg
);

Parametri

[in] pStg

Puntatore IStorage al nuovo oggetto di archiviazione da inizializzare. Il contenitore crea un oggetto di archiviazione annidato nel relativo oggetto di archiviazione (vedere IStorage::CreateStorage). Il contenitore chiama quindi la funzione WriteClassStg per inizializzare il nuovo oggetto di archiviazione con l'identificatore di classe oggetto (CLSID).

Valore restituito

Questo metodo può restituire i valori seguenti.

Codice restituito Descrizione
S_OK
 Metodo completato correttamente.
CO_E_ALREADYINITIALIZED
 L'oggetto è già stato inizializzato da una chiamata precedente al metodo IPersistStorage::Load o al metodo IPersistStorage::InitNew .
E_OUTOFMEMORY
 L'oggetto di archiviazione non è stato inizializzato a causa di una mancanza di memoria.
E_FAIL
 L'oggetto di archiviazione non è stato inizializzato per qualche motivo diverso da una mancanza di memoria.

Commenti

Un'applicazione contenitore può chiamare questo metodo quando deve inizializzare un nuovo oggetto, ad esempio con un comando InsertObject.

Un oggetto che supporta l'interfaccia IPersistStorage deve avere accesso a un oggetto di archiviazione valido in ogni momento durante l'esecuzione. Ciò include il tempo appena dopo la creazione dell'oggetto, ma prima che sia stato reso persistente. Il contenitore dell'oggetto deve fornire all'oggetto un puntatore IStorage valido all'archiviazione durante questa volta tramite la chiamata a IPersistStorage::InitNew. A seconda dello stato del contenitore, potrebbe essere necessario creare un file temporaneo per questo scopo.

Se l'oggetto vuole conservare l'istanza di IStorage , deve chiamare AddRef per aumentare il numero di riferimenti.

Dopo la chiamata a IPersistStorage::InitNew, l'oggetto si trova nello stato caricato o in esecuzione. Ad esempio, se la classe oggetto ha un server in-process, l'oggetto sarà nello stato in esecuzione. Tuttavia, se l'oggetto usa il gestore predefinito, la chiamata del contenitore a InitNew richiama solo l'implementazione del gestore che non esegue l'oggetto. In seguito, se il contenitore esegue l'oggetto, il gestore chiama il metodo InitNew per l'oggetto.

Note ai chiamanti

Anziché chiamare direttamente IPersistStorage::InitNew , si chiama in genere la funzione helper OleCreate che esegue le operazioni seguenti:
  1. Chiama la funzione CoCreateInstance per creare un'istanza della classe oggetto.
  2. Esegue una query sulla nuova istanza per l'interfaccia IPersistStorage .
  3. Chiama il metodo InitNew per inizializzare l'oggetto.
L'applicazione contenitore deve memorizzare nella cache il puntatore IPersistStorage all'oggetto da usare nelle operazioni successive sull'oggetto.

Note per gli implementatori

Un'implementazione di IPersistStorage::InitNew deve inizializzare l'oggetto allo stato predefinito, seguendo questa procedura:
  1. Pre-aprire e memorizzare nella cache i puntatori a qualsiasi flusso o archiviazione che l'oggetto dovrà salvare in questa risorsa di archiviazione.
  2. Chiamare AddRef e memorizzare nella cache il puntatore di archiviazione passato.
  3. Chiamare la funzione WriteFmtUserTypeStg per scrivere il formato nativo degli Appunti e la stringa di tipo utente per l'oggetto nell'oggetto di archiviazione.
  4. Impostare il flag sporco per l'oggetto.
I primi due passaggi sono particolarmente importanti per garantire che l'oggetto possa salvarsi in situazioni di memoria ridotta. La pre-apertura e l'accesso ai puntatori alle interfacce di flusso e archiviazione garantiscono che un'operazione di salvataggio in questa risorsa di archiviazione non avrà esito negativo a causa di memoria insufficiente.

L'implementazione di questo metodo deve restituire il codice di errore CO_E_ALREADYINITIALIZED se riceve una chiamata al metodo IPersistStorage::InitNew o al metodo IPersistStorage::Load dopo l'inizializzazione.

Requisiti

Requisito Valore
Client minimo supportato Windows 2000 Professional [solo app desktop]
Server minimo supportato Windows 2000 Server [solo app desktop]
Piattaforma di destinazione Windows
Intestazione objidl.h

Vedi anche

IPersistStorage