Méthode IPersistStorage ::InitNew (objidl.h)

  • Article

Initialise un nouvel objet de stockage.

Syntaxe

HRESULT InitNew(
  [in] IStorage *pStg
);

Paramètres

[in] pStg

Pointeur IStorage vers le nouvel objet de stockage à initialiser. Le conteneur crée un objet de stockage imbriqué dans son objet de stockage (voir IStorage ::CreateStorage). Ensuite, le conteneur appelle la fonction WriteClassStg pour initialiser le nouvel objet de stockage avec l’identificateur de classe d’objet (CLSID).

Valeur retournée

Cette méthode peut retourner les valeurs suivantes.

Code de retour Description
S_OK
 La commande s'est correctement terminée.
CO_E_ALREADYINITIALIZED
 L’objet a déjà été initialisé par un appel précédent à la méthode IPersistStorage ::Load ou À la méthode IPersistStorage ::InitNew .
E_OUTOFMEMORY
 L’objet de stockage n’a pas été initialisé en raison d’un manque de mémoire.
E_FAIL
 L’objet de stockage n’a pas été initialisé pour une raison autre qu’un manque de mémoire.

Remarques

Une application conteneur peut appeler cette méthode lorsqu’elle doit initialiser un nouvel objet, par exemple avec une commande InsertObject.

Un objet qui prend en charge l’interface IPersistStorage doit avoir accès à tout moment à un objet de stockage valide pendant son exécution. Cela inclut le temps juste après la création de l’objet, mais avant qu’il ne soit rendu persistant. Le conteneur de l’objet doit fournir à l’objet un pointeur IStorage valide vers le stockage pendant ce temps via l’appel à IPersistStorage ::InitNew. Selon l’état du conteneur, un fichier temporaire peut être créé à cet effet.

Si l’objet souhaite conserver le instance IStorage, il doit appeler AddRef pour incrémenter son nombre de références.

Après l’appel à IPersistStorage ::InitNew, l’objet est à l’état chargé ou en cours d’exécution. Par exemple, si la classe d’objet a un serveur in-process, l’objet est à l’état en cours d’exécution. Toutefois, si l’objet utilise le gestionnaire par défaut, l’appel du conteneur à InitNew appelle uniquement l’implémentation du gestionnaire qui n’exécute pas l’objet. Plus tard, si le conteneur exécute l’objet, le gestionnaire appelle la méthode InitNew pour l’objet .

Remarques aux appelants

Au lieu d’appeler IPersistStorage ::InitNew directement, vous appelez généralement la fonction d’assistance OleCreate qui effectue les opérations suivantes :
  1. Appelle la fonction CoCreateInstance pour créer un instance de la classe d’objet.
  2. Interroge la nouvelle instance pour l’interface IPersistStorage.
  3. Appelle la méthode InitNew pour initialiser l’objet .
L’application conteneur doit mettre en cache le pointeur IPersistStorage vers l’objet pour une utilisation dans des opérations ultérieures sur l’objet.

Remarques aux implémenteurs

Une implémentation de IPersistStorage ::InitNew doit initialiser l’objet à son état par défaut, en procédant comme suit :
  1. Pré-ouvrir et mettre en cache les pointeurs vers tous les flux ou stockages dont l’objet a besoin pour s’enregistrer dans ce stockage.
  2. Appelez AddRef et mettez en cache le pointeur de stockage passé.
  3. Appelez la fonction WriteFmtUserTypeStg pour écrire le format natif du Presse-papiers et la chaîne de type utilisateur de l’objet dans l’objet de stockage.
  4. Définissez l’indicateur sale pour l’objet .
Les deux premières étapes sont particulièrement importantes pour s’assurer que l’objet peut s’enregistrer dans des situations de mémoire insuffisante. La pré-ouverture et la conservation des pointeurs vers les interfaces de flux et de stockage garantissent qu’une opération d’enregistrement dans ce stockage n’échouera pas en raison d’une mémoire insuffisante.

Votre implémentation de cette méthode doit retourner le code d’erreur CO_E_ALREADYINITIALIZED si elle reçoit un appel à la méthode IPersistStorage ::InitNew ou À la méthode IPersistStorage ::Load après son initialisation.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête objidl.h

Voir aussi

IPersistStorage