Implementação de arquivo IStorage-Compound
A implementação de arquivo composto do IStorage permite que você crie e gerencie substorages e fluxos dentro de um objeto de armazenamento que reside em um objeto de arquivo composto. Para criar um objeto de arquivo composto e obter um ponteiro IStorage , chame a função de API StgCreateStorageEx. Para abrir um objeto de arquivo composto existente e obter seu ponteiro IStorage raiz, chame StgOpenStorageEx.
Os aplicativos que usam o armazenamento composto devem ser registrados em HKEY_CLASSES_ROOT\SystemFileAssociations e devem fornecer seus próprios manipuladores de propriedades. Para obter mais informações, consulte a seção "Registrando verbos e outras informações de associação de arquivos" do Registro de Aplicativo.
Quando usar
A maioria dos aplicativos usa essa implementação para criar e gerenciar armazenamentos e fluxos.
Métodos
-
Cria e abre um objeto de fluxo com o nome especificado contido neste objeto de armazenamento. O nome não deve exceder 31 caracteres de comprimento (sem incluir o terminador de cadeia de caracteres). Os caracteres de 000 a 01f, que servem como o primeiro caractere do nome de fluxo/armazenamento, são reservados para uso pelo OLE. Essa é uma restrição de arquivo composta, não uma restrição de armazenamento estruturada. A implementação do arquivo composto fornecido por COM do método IStorage::CreateStream não dá suporte aos seguintes comportamentos:
- Não há suporte para o sinalizador STGM_DELETEONRELEASE.
- Não há suporte para o modo transacionado (STGM_TRANSACTED) para objetos de fluxo.
- Não há suporte para abrir o mesmo fluxo mais de uma vez do mesmo armazenamento. O sinalizador STGM_SHARE_EXCLUSIVE modo de compartilhamento deve ser especificado no parâmetro grfMode .
-
Abre um objeto de fluxo existente dentro desse objeto de armazenamento usando os modos de acesso especificados no parâmetro grfMode . Os caracteres de 000 a 01f, que servem como o primeiro caractere do nome de fluxo/armazenamento, são reservados para uso pelo OLE. Essa é uma restrição de arquivo composta, não uma restrição de armazenamento estruturada. A implementação de arquivo composto fornecida por COM do método IStorage::OpenStream não dá suporte ao seguinte comportamento:
- O sinalizador STGM_DELETEONRELEASE.
- Modo transacionado (STGM_TRANSACTED) para objetos de fluxo.
- Abrindo o mesmo fluxo mais de uma vez do mesmo armazenamento. O sinalizador STGM_SHARE_EXCLUSIVE deve ser especificado.
-
Cria e abre um novo objeto de armazenamento com o nome especificado no modo de acesso especificado. O nome não deve exceder 31 caracteres de comprimento (sem incluir o terminador de cadeia de caracteres). Os caracteres de 000 a 01f, que servem como o primeiro caractere do nome de fluxo/armazenamento, são reservados para uso pelo OLE. Essa é uma restrição de arquivo composta, não uma restrição de armazenamento estruturada. A implementação de arquivo composto fornecida por COM do método IStorage::CreateStorage não dá suporte ao seguinte comportamento:
- O sinalizador STGM_PRIORITY para armazenamentos não padrão.
- Abrindo o mesmo objeto de armazenamento mais de uma vez do mesmo armazenamento pai. O sinalizador STGM_SHARE_EXCLUSIVE deve ser especificado.
- O sinalizador STGM_DELETEONRELEASE. Se esse sinalizador for especificado, a função retornará STG_E_INVALIDFLAG.
-
Abre um objeto de armazenamento existente com o nome especificado no modo de acesso especificado. Os caracteres de 000 a 01f, que servem como o primeiro caractere do nome de fluxo/armazenamento, são reservados para uso pelo OLE. Essa é uma restrição de arquivo composta, não uma restrição de armazenamento estruturada. A implementação do arquivo composto fornecido por COM do método IStorage::OpenStorage não dá suporte ao seguinte comportamento:
- O sinalizador STGM_PRIORITY para armazenamentos não padrão.
- Abrindo o mesmo objeto de armazenamento mais de uma vez do mesmo armazenamento pai. O sinalizador STGM_SHARE_EXCLUSIVE deve ser especificado.
- O sinalizador STGM_DELETEONRELEASE. Se esse sinalizador for especificado, a função retornará STG_E_INVALIDFUNCTION.
-
Copia apenas os substorages e fluxos desse objeto de armazenamento aberto em outro objeto de armazenamento. O parâmetro rgiidExclude pode ser definido como IID_IStream para copiar apenas substorages ou para IID_IStorage para copiar somente fluxos.
-
Copia ou move um substorage ou fluxo desse objeto de armazenamento para outro objeto de armazenamento.
-
Garante que todas as alterações feitas em um objeto de armazenamento aberto no modo transacionado sejam refletidas no armazenamento pai; para um armazenamento raiz, reflete as alterações no dispositivo real; por exemplo, um arquivo em disco. Para um objeto de armazenamento raiz aberto no modo direto, esse método não tem efeito, exceto para liberar todos os buffers de memória para o disco. Para objetos de armazenamento não padrão no modo direto, esse método não tem efeito.
A implementação de arquivos compostos fornecidos por COM usa um processo de confirmação em duas fases, a menos que STGC_OVERWRITE seja especificado no parâmetro grfCommitFlags . Esse processo em duas fases garante a robustez dos dados, caso a operação de confirmação falhe. Primeiro, todos os novos dados são gravados em espaço não utilizado no arquivo subjacente. Se necessário, o novo espaço é alocado para o arquivo. Depois que essa etapa for concluída, uma tabela no arquivo será atualizada usando uma operação de gravação de setor único para indicar que os novos dados devem ser usados no lugar do antigo. Os dados antigos se tornam espaço livre a serem usados na próxima operação de confirmação. Portanto, os dados antigos estão disponíveis e podem ser restaurados se ocorrer um erro ao confirmar alterações. Se STGC_OVERWRITE for especificado, uma única operação de confirmação de fase será usada. Para obter mais informações sobre sinalizadores de modo transacionado, consulte enumeração STGC .
-
Descarta todas as alterações que foram feitas no objeto de armazenamento desde a última operação de confirmação.
-
Cria e recupera um ponteiro para um objeto enumerador que pode ser usado para enumerar os objetos de armazenamento e fluxo contidos nesse objeto de armazenamento. A implementação de arquivo composto fornecida por COM usa uma instantâneo dessas informações. Portanto, as alterações nos fluxos e armazenamentos não são refletidas no enumerador até que um novo enumerador seja obtido.
-
Remove o elemento especificado (subtorage ou stream) desse objeto de armazenamento.
-
Renomeia o substorage ou o fluxo especificados neste objeto de armazenamento. Os caracteres de 000 a 01f, que servem como o primeiro caractere do nome de fluxo/armazenamento, são reservados para uso pelo OLE. Essa é uma restrição de arquivo composta, não uma restrição de armazenamento estruturada.
-
Define os tempos de modificação, acesso e criação do elemento de armazenamento especificado. A implementação de arquivo composto fornecida por COM mantém os tempos de modificação e alteração para objetos de armazenamento internos. Os objetos de armazenamento raiz dão suporte ao que é compatível com o sistema de arquivos subjacente (ou por ILockBytes). A implementação do arquivo composto não mantém nenhum carimbo de data/hora para fluxos internos. Carimbos de data/hora sem suporte são relatados como zero, o que permite que o chamador teste o suporte.
-
Atribui o CLSID especificado a esse objeto de armazenamento.
-
Armazena até 32 bits de informações de estado neste objeto de armazenamento. O estado definido por esse método é apenas para uso externo. A implementação de arquivo composto fornecida por COM não executa nenhuma ação com base no estado .
-
Recupera a estrutura STATSTG para este objeto de armazenamento aberto.
Comentários
Se o objeto de armazenamento for aberto no modo simples, o uso dos métodos acima será restrito. Um armazenamento estará no modo simples se for aberto com o elemento STGM_SIMPLE especificado no parâmetro grfMode da função StgCreateStorageEx ou StgOpenStorageEx . Para obter mais informações sobre armazenamentos de modo simples, consulte Constantes STGM. Se o objeto de armazenamento de modo simples tiver sido obtido da função StgCreateStorageEx , o método CreateStream poderá ser chamado, mas o método OpenStream não poderá. Se o objeto de armazenamento de modo simples tiver sido obtido da função StgOpenStorageEx , o método OpenStream poderá ser chamado, mas o método CreateStream não poderá.
Quando um objeto de armazenamento de modo simples é usado para criar um fluxo, o tamanho mínimo desse fluxo normalmente é de 4096 bytes. Se menos dados forem gravados no fluxo, o tamanho será arredondado para 4096 bytes.
Tópicos relacionados