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

  • Artigo

Carrega um objeto de seu armazenamento existente.

Sintaxe

HRESULT Load(
  [in] IStorage *pStg
);

Parâmetros

[in] pStg

Um ponteiro IStorage para o armazenamento existente do qual o objeto deve ser carregado.

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 não foi carregado devido à falta de memória.
E_FAIL
 O objeto não foi carregado devido a algum motivo que não seja a falta de memória.

Comentários

Esse método inicializa um objeto de um armazenamento existente. O objeto será colocado no estado carregado se esse método for chamado pelo aplicativo de contêiner. Se chamado pelo manipulador padrão, esse método coloca o objeto no estado em execução.

O manipulador padrão ou o próprio objeto pode manter o ponteiro IStorage enquanto o objeto está carregado ou em execução.

Anotações aos Chamadores

Em vez de chamar IPersistStorage::Load diretamente, você normalmente chama a função auxiliar OleLoad , que faz o seguinte:
  1. Crie uma instância não inicializada da classe de objeto .
  2. Consulte a nova instância para a interface IPersistStorage .
  3. Chame Load para inicializar o objeto do armazenamento existente.
Você também chama esse método indiretamente quando chama a função OleCreateFromData ou a função OleCreateFromFile para inserir um objeto em um arquivo composto (como em uma operação de colagem de arrastar e soltar ou de área de transferência).

O contêiner deve armazenar em cache o ponteiro IPersistStorage para uso em operações posteriores no objeto .

Observações aos implementadores

Sua implementação deve executar as seguintes etapas para carregar um objeto:
  1. Abra os fluxos do objeto no objeto de armazenamento e leia os dados necessários nas estruturas de dados internas do objeto.
  2. Limpe o sinalizador de sujo do objeto.
  3. Chame o método AddRef e armazene em cache o ponteiro de armazenamento passado.
  4. Mantenha aberto e armazene em cache os ponteiros para quaisquer fluxos ou armazenamentos que o objeto precisará para se salvar nesse armazenamento.
  5. Execute qualquer outra inicialização padrão necessária para o objeto .
As etapas 3 e 4 são particularmente importantes para garantir que o objeto possa se salvar em situações de memória insuficiente. Manter em ponteiros para as interfaces de armazenamento e fluxo garante 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

OleLoad