Implementação de arquivo IPropertyStorage-Compound
A implementação COM da arquitetura de Armazenamento Estruturado é chamada de arquivos compostos. Os objetos de armazenamento, conforme implementado em arquivos compostos, incluem uma implementação de IPropertyStorage, a interface que gerencia um único conjunto de propriedades persistentes e IPropertySetStorage, a interface que gerencia grupos de conjuntos de propriedades persistentes. Para obter mais informações sobre a interface IPropertyStorage , consulte Considerações sobre IPropertyStorage e Armazenamento de Propriedades.
Para obter um ponteiro para a implementação de arquivo composto de IPropertyStorage, chame StgCreateStorageEx para criar um novo objeto de arquivo composto ou StgOpenStorageEx para abrir um objeto de arquivo composto criado anteriormente. No caso de StgCreateStorageEx, o parâmetro stgfmt deve ser definido como STGFMT_STORAGE. No caso de StgOpenStorageEx, o parâmetro stgfmt deve ser definido como STGFMT_STORAGE ou STGFMT_ANY. Em ambos os casos, o parâmetro riid deve ser definido como IID_IPropertySetStorage. Ambas as funções fornecem um ponteiro para a interface IPropertySetStorage do objeto. Ao chamar o método Create ou Open dessa interface, você obterá um ponteiro para a interface IPropertyStorage , que você pode usar para chamar qualquer um de seus métodos.
Uma maneira alternativa de obter um ponteiro para a implementação de arquivo composto de IPropertySetStorage é chamar as funções stgCreateDocfile e StgOpenStorage mais antigas ou especificar um parâmetro riid de IID_IStorage para a função StgCreateStorageEx ou StgOpenStorageEx . Em ambos os casos, um ponteiro para a interface IStorage do objeto é retornado. Com conjuntos de propriedades persistentes, chame QueryInterface para a interface IPropertySetStorage , especificando o nome definido pelo cabeçalho para o IID (identificador de interface) IID_IPropertySetStorage.
Quando usar
Use IPropertyStorage para gerenciar propriedades em um único conjunto de propriedades. Seus métodos dão suporte à leitura, gravação e exclusão de propriedades e aos nomes de cadeia de caracteres opcionais que podem ser associados a identificadores de propriedade. Outros métodos dão suporte às operações de armazenamento de commit e reverter padrão. Há também um método que permite definir horários associados ao armazenamento de propriedades e outro que permite a atribuição de um CLSID que pode ser usado para associar outro código, como código de interface do usuário, ao conjunto de propriedades. Chamar o método Enum fornece um ponteiro para a implementação de arquivo composto de IEnumSTATPROPSTG, que permite enumerar as propriedades no conjunto.
Observação
Se você obtiver um ponteiro para IPropertyStorage chamando StgCreateDocfile, StgCreateStorageEx, StgOpenStorage ou StgOpenStorageEx em um armazenamento de conjunto de propriedades de modo simples, os métodos IPropertyStorage seguem as regras de fluxos de modo simples. O armazenamento do conjunto de propriedades será um modo simples se ele tiver sido obtido para um arquivo que foi criado ou aberto com o sinalizador STGM_SIMPLE. Nesse caso, nem sempre é possível aumentar o fluxo subjacente e não é possível substituir as propriedades existentes por propriedades maiores. Para obter mais informações, consulte Implementação de arquivo composto IPropertySetStorage.
IPropertyStorage e cache
A implementação de arquivo composto de IPropertyStorage armazena em cache conjuntos de propriedades abertos na memória para melhorar o desempenho. Como resultado, as alterações em um conjunto de propriedades não são gravadas no arquivo composto até que os métodos Commit ou Release (última referência) sejam chamados.
Conjuntos de propriedades de modo simples
Um objeto de armazenamento de propriedades estará no modo simples se ele for criado a partir de um objeto de armazenamento de conjunto de propriedades de modo simples. Por exemplo, um objeto de armazenamento do conjunto de propriedades estaria no modo simples se fosse obtido da função StgOpenStorageEx , com o sinalizador STGM_SIMPLE definido no parâmetro grfMode . Observe que o "modo simples" não está relacionado a "conjuntos de propriedades simples". Um conjunto de propriedades será simples se for criado chamando IPropertySetStorage::Create com o sinalizador PROPSETFLAG_NONSIMPLE definido no parâmetro grfFlags . Para obter mais informações sobre conjuntos de propriedades simples e não simples, consulte Objetos de Armazenamento e Stream para um Conjunto de Propriedades.
Quando um objeto de armazenamento de propriedades de modo simples é criado, não há restrições em seu uso. Quando um objeto de armazenamento de propriedades de modo simples existente é aberto, o objeto de fluxo subjacente que armazena o conjunto de propriedades não pode ser cultivado. Consequentemente, nem sempre é possível modificar esse objeto de armazenamento de propriedades se a alteração exigir um fluxo maior.
Formatos do conjunto de propriedades
A implementação de arquivo composto de IPropertyStorage dá suporte aos formatos de serialização da versão 0 e do conjunto de propriedades versão 1. O formato versão 1 tem suporte em computadores em execução no Windows 2000. Para obter mais informações, consulte Serialização do conjunto de propriedades. Os conjuntos de propriedades são criados no formato de versão 0 e permanecem nesse formato, a menos que novos recursos sejam solicitados. Quando isso ocorre, o formato é atualizado para a versão 1.
Por exemplo, se um conjunto de propriedades for criado com o sinalizador PROPSETFLAG_DEFAULT, seu formato será a versão 0. Desde que os tipos de propriedade que estão em conformidade com o formato da versão 0 sejam gravados e lidos desse conjunto de propriedades, o conjunto de propriedades permanecerá no formato de versão 0. Se um tipo de propriedade versão 1 for gravado no conjunto de propriedades, o conjunto de propriedades será atualizado automaticamente para a versão 1. Posteriormente, esse conjunto de propriedades não pode mais ser lido por implementações que reconhecem apenas a versão 0.
Tipos IPropertyStorage e Variant
A implementação de arquivo composto de IPropertyStorage não dá suporte aos tipos variantes VT_UNKNOWN ou VT_DISPATCH no membro vt da estrutura PROPVARIANT .
A tabela a seguir lista os tipos variantes com suporte em um SafeArray; ou seja, esses valores podem ser combinados com VT_ARRAY no membro vt da estrutura PROPVARIANT .
Tipos variantes com suporte no SafeArray pela implementação de arquivo composto de IPropertyStorage
VT_I1
VT_UI1
VT_I2
VT_UI2
VT_I4
VT_UI4
VT_INT
VT_UINT
VT_R4
VT_R8
VT_CY
VT_DATE
VT_BSTR
VT_BOOL
VT_DECIMAL
VT_ERROR
VT_VARIANT
Quando VT_VARIANT é combinado com VT_ARRAY, o próprio SafeArray contém estruturas PROPVARIANT . No entanto, os tipos desses elementos devem ser retirados da lista anterior, não podem ser VT_VARIANT e não podem incluir os indicadores VT_VECTOR, VT_ARRAY ou VT_BYREF.
Métodos IPropertyStorage
A implementação de arquivo composto de IPropertyStorage dá suporte aos seguintes métodos:
-
Lê as propriedades especificadas na matriz rgpspec e fornece os valores de todas as propriedades válidas na matriz rgvar de PROPVARIANTs. Na implementação do arquivo composto COM, identificadores de propriedade duplicados que se referem a tipos de fluxo ou armazenamento resultam em várias chamadas para IStorage::OpenStream ou IStorage::OpenStorage e o êxito ou falha de ReadMultiple depende da capacidade da implementação de armazenamento subjacente de compartilhar operações de abertura. Como em um arquivo composto STGM_SHARE_EXCLUSIVE for forçado, várias tentativas abertas falharão. Não há suporte para abrir o mesmo objeto de armazenamento mais de uma vez do mesmo armazenamento pai. O sinalizador STGM_SHARE_EXCLUSIVE deve ser especificado.
Além disso, para garantir a operação thread-safe se a mesma propriedade com valor de fluxo ou armazenamento for solicitada várias vezes por meio do mesmo ponteiro IPropertyStorage na implementação de arquivo composto COM, a operação aberta terá êxito ou falhará dependendo se a propriedade já estiver aberta e se o sistema de arquivos subjacente manipula várias aberturas de um fluxo ou armazenamento. Assim, a operação ReadMultiple em uma propriedade com valor de fluxo ou armazenamento sempre resulta em uma chamada para IStorage::OpenStream ou IStorage::OpenStorage, que passa o acesso (STGM_READWRITE e assim por diante) e compartilha sinalizadores (STGM_SHARE_EXCLUSIVE e assim por diante) especificados quando o conjunto de propriedades original foi aberto ou criado.
Se o método falhar, os valores gravados em rgvar[] serão indefinidos. Se algumas propriedades com valor de fluxo ou armazenamento forem abertas com êxito, mas ocorrer um erro antes da execução ser concluída, elas deverão ser liberadas antes que o método retorne.
-
Grava as propriedades especificadas na matriz rgpspec[], atribuindo-lhes as marcas e valores PROPVARIANT especificados em rgvar[]. As propriedades que já existem recebem os valores PROPVARIANT especificados. As propriedades que não existem atualmente são criadas.
-
Exclui as propriedades especificadas no rgpspec[].
-
Lê nomes de cadeia de caracteres existentes associados às IDs de propriedade especificadas na matriz rgpropid[].
-
Atribui nomes de cadeia de caracteres especificados na matriz rglpwstrName às IDs de propriedade especificadas na matriz rgpropid .
-
Exclui nomes de propriedade para as propriedades especificadas na matriz rgpropid[].
-
Define o CLSID do fluxo do conjunto de propriedades. Na implementação do arquivo composto, definir o CLSID em um conjunto de propriedades não simples (um que pode conter legalmente propriedades com valor de armazenamento ou fluxo, conforme descrito em IPropertySetStorage::Create) também define o CLSID na subconstrução subjacente para que possa ser obtida por meio de uma chamada para IStorage::Stat.
-
Para conjuntos de propriedades simples e não simples, libera a imagem de memória do conjunto de propriedades para o armazenamento subjacente. Além disso, para conjuntos de propriedades transacted-mode não simplificados, esse método executa uma confirmação (como em IStorage::Commit) no armazenamento que contém o conjunto de propriedades.
-
Somente para conjuntos de propriedades não simplificados, chama o método Revert do armazenamento subjacente e reabre o fluxo de "conteúdo". Para conjuntos de propriedades simples, essa interface sempre retorna S_OK. Conjuntos de propriedades não simples são aqueles que foram criados usando o sinalizador PROPSETFLAG_NONSIMPLE no método IPropertySetStorage::Create . Para obter mais informações, consulte Objetos de armazenamento e fluxo para um conjunto de propriedades .
-
Constrói uma instância de IEnumSTATPROPSTG, cujos métodos podem ser chamados para enumerar as estruturas STATPROPSTG que fornecem informações sobre cada uma das propriedades no conjunto. Essa implementação cria uma matriz na qual todo o conjunto de propriedades é lido e que pode ser compartilhado quando IEnumSTATPROPSTG::Clone é chamado. As alterações no conjunto de propriedades não são refletidas em uma instância IEnumSTATPROPSTG aberta. Para ver essas alterações, uma nova instância desse enumerador deve ser construída.
-
Preenche os membros de uma estrutura STATPROPSETSTG , que contém dados sobre o conjunto de propriedades como um todo. No retorno, fornece um ponteiro para a estrutura. Para conjuntos de armazenamento não simplificados, essa implementação chama IStorage::Stat (ou IStream::Stat) para obter os horários do armazenamento ou fluxo subjacente. Para conjuntos de armazenamento simples, nenhum horário é mantido.
-
Somente para conjuntos de propriedades não simplificados, define os horários compatíveis com o armazenamento subjacente. A implementação de armazenamento de arquivos compostos dá suporte a todos os três: modificação, acesso e criação. Essa implementação de SetTimes chama o método IStorage::SetElementTimes do armazenamento subjacente para recuperar esses tempos.
Tópicos relacionados