Método IRootStorage::SwitchToFile (objidl.h)

O método SwitchToFile copia o arquivo atual associado ao objeto de armazenamento para um novo arquivo. Em seguida, o novo arquivo é usado para o objeto de armazenamento e quaisquer alterações não confirmadas.

Sintaxe

HRESULT SwitchToFile(
  LPOLESTR pszFile
);

Parâmetros

pszFile

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do arquivo para o novo arquivo. Não pode ser o nome de um arquivo existente. Se NULL, esse método criará um arquivo temporário com um nome exclusivo e você poderá chamar IStorage::Stat para recuperar o nome do arquivo temporário.

Retornar valor

Esse método pode retornar um desses valores.

Código de retorno	Descrição
S_OK	O arquivo foi copiado com êxito.
STG_E_MEDIUMFULL	O arquivo não foi copiado devido a espaço insuficiente no dispositivo de armazenamento.
STG_E_ACCESSDENIED	O arquivo não foi copiado porque o chamador não tem permissão para acessar o dispositivo de armazenamento.
STG_E_INVALIDPOINTER	O arquivo não foi copiado porque o ponteiro pszFile não é válido.
STG_E_FILEALREADYEXISTS	O arquivo não foi copiado porque o novo nome de arquivo (pszFile) aponta para um arquivo existente.

Comentários

O método IRootStorage::SwitchToFile copia o arquivo associado ao objeto de armazenamento. Um contêiner COM chama SwitchToFile para executar um salvamento completo em um arquivo em uma situação de baixa memória. Normalmente, isso é feito somente após uma operação normal de salvamento completo (ou seja, salvar em arquivo temporário, excluir arquivo original, renomear arquivo temporário) falhar com um erro de E_OUTOFMEMORY.

É errado chamar o método SwitchToFile se o objeto de armazenamento ou qualquer coisa contida nele tiver sido empacotado para outro processo. Antes de chamar SwitchToFile, o contêiner deve chamar o método IPersistStorage::HandsOffStorage para qualquer elemento dentro do objeto de armazenamento carregado ou em execução. O método HandsOffStorage força o elemento a liberar seus ponteiros de armazenamento e entrar no modo de armazenamento prático. O contêiner também deve liberar todos os ponteiros para fluxos ou armazenamentos contidos nesse armazenamento raiz. Depois que a operação de salvamento completo for concluída, o contêiner retornará os elementos contidos para o modo de armazenamento normal.

Anotações aos implementadores

Se você estiver implementando seus próprios objetos de armazenamento, os métodos IRootStorage (incluindo QueryInterface, AddRef e Release) não deverão consumir identificadores de arquivo ou memória adicionais.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	objidl.h
Biblioteca	Uuid.lib
DLL	Ole32.dll

Confira também

IPersistStorage::HandsOffStorage

IPersistStorage::SaveCompleted

IStorage::Commit

IStorage::Stat