Implementação autônoma de IPropertyStorage
A implementação autônoma fornecida pelo sistema de IPropertySetStorage inclui uma implementação de IPropertyStorage, a interface que lê e grava propriedades em um armazenamento de conjunto de propriedades. A interface IPropertySetStorage cria e abre conjuntos de propriedades em um armazenamento. As interfaces IEnumSTATPROPSTG e IEnumSTATPROPSETSTG também são fornecidas na implementação autônoma.
Para obter um ponteiro para a implementação autônoma de IPropertyStorage, chame a função StgCreatePropStg para criar um novo conjunto de propriedades ou StgOpenPropStg para obter o ponteiro de interface em um conjunto de propriedades existente (ou chame os métodos Create ou Open da implementação autônoma IPropertySetStorage ).
A implementação autônoma de IPropertyStorage cria conjuntos de propriedades em qualquer objeto de armazenamento ou fluxo, não apenas em fluxos e armazenamentos de arquivos compostos. A implementação autônoma não depende de arquivos compostos e pode ser usada com qualquer implementação de armazenamentos estruturados. Para obter mais informações sobre a implementação de arquivo composto dessa interface, consulte Implementação de arquivo composto IPropertyStorage.
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 IDs de propriedade. Outros métodos dão suporte às operações de confirmação padrão e armazenamento reverter. Também há um método que define os horários associados ao armazenamento de propriedades e outro que permite que a atribuição de um CLSID seja usada para associar outro código, como o código da interface do usuário, ao conjunto de propriedades. O método Enum fornece um ponteiro para a implementação autônoma de IEnumSTATPROPSTG, que enumera as propriedades no conjunto.
Formatos de conjunto de propriedades versão 0 e versão 1
A implementação autônoma de IPropertyStorage dá suporte aos formatos de serialização de conjunto de propriedades versão 0 e versão 1. Para obter mais informações, consulte Serialização do conjunto de propriedades. Os conjuntos de propriedades são criados no formato versão 0 e permanecem nesse formato, a menos que novos recursos sejam solicitados. Nesse momento, 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 estejam em conformidade com o formato da versão 0 sejam gravados e lidos desse conjunto de propriedades, o conjunto de propriedades permanecerá no formato da 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 entendem apenas a versão 0.
Tipos IPropertyStorage e Variant
A implementação autônoma de IPropertyStorage não dá suporte aos tipos variantes VT_UNKNOWN ou VT_DISPATCH no membro vt da estrutura PROPVARIANT .
Os tipos de variante a seguir têm 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, a própria SafeArray manté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 autônoma 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 elementos PROPVARIANT .
Na implementação autônoma fornecida pelo sistema, 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 armazenamentos abertos.
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 , a abertura terá êxito ou falhará dependendo se a propriedade já está aberta ou não 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, passando o acesso (STGM_READWRITE, por exemplo) e valores de compartilhamento (STGM_SHARE_EXCLUSIVE, por exemplo) especificados quando o conjunto de propriedades foi originalmente 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 conclusão da execução, essas propriedades 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 e as propriedades que não existem atualmente são criadas.
-
Exclui as propriedades especificadas no rgpspec[].
-
Lê os 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 a IDs de propriedade especificadas na matriz rgpropid .
-
Exclui os nomes de cadeia de caracteres das IDs de propriedade especificadas na matriz rgpropid gravando NULL no nome da propriedade.
-
Define o CLSID do fluxo do conjunto de propriedades. Na implementação autônoma, definir o CLSID em um conjunto de propriedades não simples (um que pode conter propriedades com valor de armazenamento ou fluxo, conforme descrito em IPropertySetStorage::Create) também define o CLSID no substorage subjacente para que ele possa ser obtido por meio de uma chamada para IStorage::Stat.
-
Para conjuntos de propriedades simples e não simples, libera a imagem de memória para o subsistema de disco. Além disso, para conjuntos de propriedades de modo transacionado não simples, esse método chama IStorage::Commit no conjunto de propriedades.
-
Somente para conjuntos de propriedades não simples, chama o método Revert do armazenamento subjacente e reabre o fluxo de "conteúdo". Para conjuntos de propriedades simples, retorna apenas E_OK.
-
Cria um objeto enumerador que implementa 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.
-
Preenche os membros de uma estrutura STATPROPSETSTG , que contém informações 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 as informações do armazenamento ou fluxo subjacente.
-
Somente para conjuntos de propriedades não simples, define os horários compatíveis com o armazenamento subjacente. Essa implementação de SetTimes chama o método IStorage::SetElementTimes do armazenamento subjacente para modificar os horários. Ele dá suporte aos tempos com suporte pelo método subjacente, que podem ser hora de modificação, hora de acesso ou hora de criação.
Tópicos relacionados