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

  • Artigo

Inicializa um novo objeto de armazenamento.

Sintaxe

HRESULT InitNew(
  [in] IStorage *pStg
);

Parâmetros

[in] pStg

Um ponteiro IStorage para o novo objeto de armazenamento a ser inicializado. O contêiner cria um objeto de armazenamento aninhado em seu objeto de armazenamento (consulte IStorage::CreateStorage). Em seguida, o contêiner chama a função WriteClassStg para inicializar o novo objeto de armazenamento com o CLSID (identificador de classe de objeto).

Retornar valor

Esse método pode retornar os valores a seguir.

Código de retorno Descrição
S_OK
 O método foi concluído com sucesso.
CO_E_ALREADYINITIALIZED
 O objeto já foi inicializado por uma chamada anterior para o método IPersistStorage::Load ou o método IPersistStorage::InitNew .
E_OUTOFMEMORY
 O objeto de armazenamento não foi inicializado devido à falta de memória.
E_FAIL
 O objeto de armazenamento não foi inicializado por algum motivo diferente da falta de memória.

Comentários

Um aplicativo de contêiner pode chamar esse método quando precisa inicializar um novo objeto, por exemplo, com um comando InsertObject.

Um objeto que dá suporte à interface IPersistStorage deve ter acesso a um objeto de armazenamento válido o tempo todo enquanto ele está em execução. Isso inclui o tempo logo após a criação do objeto, mas antes de se tornar persistente. O contêiner do objeto deve fornecer ao objeto um ponteiro IStorage válido para o armazenamento durante esse tempo por meio da chamada para IPersistStorage::InitNew. Dependendo do estado do contêiner, um arquivo temporário pode ter que ser criado para essa finalidade.

Se o objeto quiser manter a instância do IStorage , ele deverá chamar AddRef para incrementar sua contagem de referência.

Após a chamada para IPersistStorage::InitNew, o objeto está no estado carregado ou em execução. Por exemplo, se a classe de objeto tiver um servidor em processo, o objeto estará no estado em execução. No entanto, se o objeto usar o manipulador padrão, a chamada do contêiner para InitNew invocará apenas a implementação do manipulador que não executa o objeto. Posteriormente, se o contêiner executar o objeto , o manipulador chamará o método InitNew para o objeto .

Anotações para chamadores

Em vez de chamar IPersistStorage::InitNew diretamente, você normalmente chama a função auxiliar OleCreate , que faz o seguinte:
  1. Chama a função CoCreateInstance para criar uma instância da classe de objeto.
  2. Consulta a nova instância da interface IPersistStorage .
  3. Chama o método InitNew para inicializar o objeto.
O aplicativo de contêiner deve armazenar em cache o ponteiro IPersistStorage para o objeto a ser usado em operações posteriores no objeto .

Anotações aos implementadores

Uma implementação de IPersistStorage::InitNew deve inicializar o objeto para seu estado padrão, seguindo as seguintes etapas:
  1. Abra previamente e armazene os ponteiros em cache para quaisquer fluxos ou armazenamentos que o objeto precisará para se salvar nesse armazenamento.
  2. Chame AddRef e armazene em cache o ponteiro de armazenamento que é passado.
  3. Chame a função WriteFmtUserTypeStg para gravar o formato nativo da área de transferência e a cadeia de caracteres de tipo de usuário do objeto no objeto de armazenamento.
  4. Defina o sinalizador sujo para o objeto .
As duas primeiras etapas são particularmente importantes para garantir que o objeto possa se salvar em situações de memória baixa. A pré-abertura e a espera de ponteiros para o fluxo e as interfaces de armazenamento garantem que uma operação de salvamento nesse armazenamento não falhará devido à memória insuficiente.

Sua implementação desse método deverá retornar o código de erro CO_E_ALREADYINITIALIZED se ele receber uma chamada para o método IPersistStorage::InitNew ou o método IPersistStorage::Load depois que ele já estiver inicializado.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho objidl.h

Confira também

Ipersiststorage