Gerenciando propriedades
Cada propriedade consiste em um identificador de propriedade (exclusivo dentro de seu conjunto de propriedades), uma marca de tipo variante (VT ou VarType) que representa o tipo de um valor e o próprio valor . A marca de tipo variante descreve a representação dos dados no valor . Além disso, uma propriedade também pode receber um nome de cadeia de caracteres que pode ser usado para identificar a propriedade, em vez de usar o ID (identificador de propriedade numérica) necessário. Para criar e gerenciar propriedades, COM define a interface IPropertyStorage .
A interface IPropertyStorage inclui métodos para ler e gravar matrizes de propriedades ou nomes de propriedade. A interface inclui métodos Commit e Revert semelhantes aos métodos IStorage de mesmo nome. Há métodos utilitários que permitem definir o CLSID (identificador de classe) do conjunto de propriedades, definir os horários associados ao conjunto e obter estatísticas sobre o conjunto de propriedades. Por fim, o método Enum cria um enumerador e retorna um ponteiro para sua interface IEnumSTATPROPSTG . Você pode chamar os métodos dessa interface para enumerar estruturas STATPROPSTG em seu objeto, o que fornecerá informações sobre todas as propriedades no conjunto de propriedades atual.
Veja a seguir um exemplo de como as propriedades são representadas. Se uma propriedade específica em um conjunto de propriedades tiver o nome científico de um animal, esse nome poderá ser armazenado como uma cadeia de caracteres terminada em zero. Armazenado junto com o nome seria um indicador de tipo para indicar que o valor é uma cadeia de caracteres terminada em zero. Essas propriedades podem ter as seguintes características:
| ID da propriedade | Identificador de cadeia de caracteres | Indicador de tipo | Valor representado |
|---|---|---|---|
| 02 | PID_ANIMALNAME | VT_LPWSTR | Cadeia de caracteres Unicode terminada em zero |
| 03 | PID_LEGCOUNT | VT_I2 | WORD |
Qualquer aplicativo que reconheça o formato do conjunto de propriedades , identificando-o por meio de seu FMTID (identificador de formato) - pode examinar a propriedade com um identificador de PID_ANIMALNAME, determinar que é uma cadeia de caracteres terminada em zero e ler e gravar o valor. Embora o aplicativo possa chamar IPropertyStorage::ReadMultiple para ler qualquer ou todo um conjunto de propriedades (tendo obtido primeiro um ponteiro), o aplicativo deve saber como interpretar o conjunto de propriedades.
Um valor de propriedade é passado por meio de interfaces de propriedade como uma instância do tipo PROPVARIANT.
É importante distinguir entre essas propriedades armazenadas (persistentes) e as propriedades de tempo de execução. Constantes de valor de tipo variante têm nomes que começam com VT_. No entanto, o conjunto de PROPVARIANTs válido não é totalmente equivalente ao conjunto de VARIANTs usado em controles de Automação e ActiveX.
A única diferença entre as duas estruturas é o conjunto permitido de marcas VT_ (Variant Type/VarType) em cada uma. Quando um determinado tipo de propriedade pode ser usado em um VARIANT e um PROPVARIANT, a marca de tipo (o valor VT_) sempre tem um valor idêntico. Além disso, para um determinado valor VT_, a representação na memória usada em VARIANTs e PROPVARIANTs é idêntica. Juntamente, essa abordagem permite que o sistema de tipos capture marcas de tipo não permitidas e, ao mesmo tempo, permita que um cliente experiente implemente uma conversão de ponteiro quando apropriado.
Para obter mais informações, consulte a seção a seguir, Considerações sobre o armazenamento de propriedades.