Método IStorage::Commit (objidl.h)

  • Artigo

O método Commit garante que todas as alterações feitas em um objeto de armazenamento aberto no modo transacionado sejam refletidas no armazenamento pai. Para objetos de armazenamento não padrão no modo direto, esse método não tem efeito. Para um armazenamento raiz, ele reflete as alterações no dispositivo real; por exemplo, um arquivo em disco. Para um objeto de armazenamento raiz aberto no modo direto, sempre chame o método IStorage::Commit antes de Release. IStorage::Commit libera todos os buffers de memória para o disco para um armazenamento raiz no modo direto e retornará um código de erro após a falha. Embora Release também libere buffers de memória para o disco, ele não tem capacidade de retornar nenhum código de erro após a falha. Portanto, chamar Release sem primeiro chamar Commit causa resultados indeterminados.

Sintaxe

HRESULT Commit(
  [in] DWORD grfCommitFlags
);

Parâmetros

[in] grfCommitFlags

Controla como as alterações são confirmadas no objeto de armazenamento. Consulte a enumeração STGC para obter uma definição desses valores.

Retornar valor

Esse método pode retornar um desses valores.

Código de retorno Descrição
S_OK As alterações no objeto de armazenamento foram confirmadas com êxito no nível pai. Se STGC_CONSOLIDATE foi especificado, o armazenamento foi consolidado com êxito ou o armazenamento já era muito compacto para consolidar ainda mais.
STG_S_MULTIPLEOPENS A operação de confirmação foi bem-sucedida, mas o armazenamento não pôde ser consolidado porque foi aberto várias vezes usando o sinalizador STGM_NOSNAPSHOT.
STG_S_CANNOTCONSOLIDATE A operação de confirmação foi bem-sucedida, mas o armazenamento não pôde ser consolidado devido a um modo de armazenamento incorreto. Para arquivos compostos, o armazenamento pode ter sido aberto usando o sinalizador STGM_NOSCRATCH ou o armazenamento pode não ser o nível transacionado mais externo.
STG_S_CONSOLIDATIONFAILED A operação de confirmação foi bem-sucedida, mas o armazenamento não pôde ser consolidado devido a um erro interno (por exemplo, uma falha de alocação de memória).
E_PENDING Somente armazenamento assíncrono: parte ou todos os dados a serem confirmados não estão disponíveis no momento.
STG_E_INVALIDFLAG O valor do parâmetro grfCommitFlags não é válido.
STG_E_INVALIDPARAMETER Um dos parâmetros não era válido.
STG_E_NOTCURRENT Outra instância aberta do objeto de armazenamento confirmou alterações. Como resultado, a operação de confirmação atual pode substituir as alterações anteriores.
STG_E_MEDIUMFULL Não há espaço no dispositivo para confirmar.
STG_E_TOOMANYOPENFILES Não foi possível concluir a operação de confirmação porque há muitos arquivos abertos.
STG_E_REVERTED O objeto de armazenamento foi invalidado por uma operação de reverter acima dele na árvore de transações.

Comentários

IStorage::Commit faz alterações permanentes em um objeto de armazenamento que está no modo transacionado, no qual as alterações são acumuladas em um buffer e não são refletidas no objeto de armazenamento até que haja uma chamada para esse método. A alternativa é abrir um objeto no modo direto, no qual as alterações são refletidas imediatamente no objeto de armazenamento. Um objeto aberto no modo direto não requer a chamada de IStorage::Commit para fazer alterações permanentes no objeto de armazenamento. Chamar o método IStorage::Commit em um armazenamento não padrão aberto no modo direto não tem efeito. Abrir um objeto de armazenamento raiz no modo direto garante que as alterações nos buffers de memória sejam gravadas no dispositivo de armazenamento subjacente.

A operação de confirmação publica as alterações atuais neste objeto de armazenamento e seus filhos para o próximo nível na hierarquia de armazenamento. Para desfazer as alterações atuais antes de confirmá-las, chame IStorage::Revert para reverter para a última versão confirmada.

Chamar IStorage::Commit não tem nenhum efeito sobre os elementos aninhados abertos no momento deste objeto de armazenamento. Eles permanecem válidos e podem ser usados. No entanto, o método IStorage::Commit não confirma automaticamente as alterações nesses elementos aninhados. A operação de confirmação publica apenas alterações conhecidas no próximo nível superior na hierarquia de armazenamento. Portanto, as transações para níveis aninhados devem ser confirmadas nesse objeto de armazenamento antes que possam ser confirmadas em níveis mais altos.

Em operações de confirmação, você precisa tomar medidas para garantir que os dados sejam protegidos durante o processo de confirmação:

  • Ao confirmar alterações em objetos de armazenamento raiz, o chamador deve marcar o valor retornado para determinar se a operação foi concluída com êxito e, caso contrário, que o conteúdo antigo confirmado do IStorage ainda está intacto e pode ser restaurado.
  • Se esse objeto de armazenamento tiver sido aberto com alguns de seus itens excluídos, o chamador será responsável por reescrevê-los antes de chamar commit. O modo de gravação é necessário na abertura de armazenamento para que a confirmação seja bem-sucedida.
  • A menos que proíba vários gravadores simultâneos no mesmo objeto de armazenamento, um aplicativo que chama esse método deve especificar pelo menos STGC_ONLYIFCURRENT no parâmetro grfCommitFlags para impedir que as alterações feitas por um gravador substituam inadvertidamente as alterações feitas por outro.
Se o sinalizador STGC_CONSOLIDATE não tiver suporte de uma implementação de armazenamento, chamar IStorage::Commit com STGC_CONSOLIDATE especificado no parâmetro grfCommitFlags retornará o valor STG_E_INVALIDFLAG.

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

IStorage – Implementação de arquivo composto

IStorage::Revert

STGC