Práticas recomendadas e perguntas frequentes do manipulador de propriedades

Algumas propriedades para arquivos são fornecidas pela fonte de dados do sistema de arquivos, como:

• PKEY_FileName
• PKEY_Extension
• PKEY_ModifiedTime

Em geral, os manipuladores de propriedades não podem fornecer valores para essas propriedades. No entanto, em alguns casos, essas propriedades podem ser substituídas com base nas informações de registro fornecidas pelo manipulador de propriedades. Os manipuladores de propriedades preenchem HKEY_CLASSES_ROOT\CLSID\{handler clsid}\OverrideFileSystemProperties com os nomes das propriedades que desejam substituir. Isso é limitado a um conjunto fixo de propriedades mostrado na lista a seguir da qual o sistema tem conhecimento.

Há suporte para substituição para os seguintes valores de propriedade:

• System.Kind
• System.FileName
• System.IsPinnedToNameSpaceTree
• System.ItemNameDisplay
• System.SFGAOFlags
• System.ItemPathDisplay
• System.ItemPathDisplayNarrow
• System.ItemFolderNameDisplay
• System.ItemFolderPathDisplay
• System.ItemFolderPathDisplayNarrow

Para obter uma lista completa de todas as propriedades do Shell, consulte Propriedades do Shell.

Há duas opções básicas disponíveis para armazenar propriedades em formatos de arquivo baseados em XML:

• Armazene cada propriedade usando elementos XML e atributos de acordo com o esquema XML do documento. Essa abordagem é mais "amigável ao XML".
• Serialize todo o repositório de propriedades em um BLOB (objeto binário grande) de memória, converta o BLOB em uma cadeia de caracteres codificada em base64 e armazene essa cadeia de caracteres no XML. Essa é a abordagem mais simples das duas abordagens e pode ser usada para fornecer suporte trivialmente para metadados abertos.

Alguns manipuladores podem combinar essas abordagens, armazenando alguns valores importantes no formato XML padrão e armazenando o restante em um BLOB, por exemplo.

Algumas propriedades são derivadas de atributos específicos de um arquivo. Por exemplo, a propriedade System.Image.Dimensions é determinada pelas dimensões reais da imagem em um arquivo de imagem. Como esses valores de propriedade não podem ser alterados pelo manipulador de propriedades, eles são marcados isInnate="true" na descrição da propriedade. Outras propriedades são computadas de uma parte de uma propriedade específica ou agregando os valores de várias propriedades. Como as atualizações dessas propriedades "computadas" criariam ambiguidade quanto à forma como os valores de "origem" devem ser alterados, as propriedades computadas devem ser marcadas isInnate="true" na descrição da propriedade ou relatadas como somente leitura. A última opção está disponível instruindo o manipulador a retornar S_FALSE de IPropertyStoreCapabilities::IsPropertyWritable.

O indexador do Windows Search é executado como um serviço do sistema e não pode carregar DLLs armazenadas no diretório de perfil do usuário. Se você estiver criando e depurando usando o Microsoft Visual Studio, ele colocará a DLL em seu perfil de usuário (e, portanto, não será carregada pelo indexador). Para contornar isso, copie sua DLL fora da pasta de perfil (por exemplo, em C:\Arquivos de Programas\SeuAppName) e registre-a lá.

Para obter diretrizes mais específicas sobre como desenvolver manipuladores de propriedades para trabalhar com o indexador do Windows Search, consulte Desenvolvendo manipuladores de propriedades para a Pesquisa do Windows.

Nem todos os clientes de objetos de repositório de propriedades usam esses métodos. Alguns clientes estão cientes das propriedades que planejam solicitar diretamente (pelo nome PKEY) ou recebem informações de propriedade por meio de uma lista de descrição da propriedade. Os métodos de descoberta de propriedade suppportam vários outros cenários. Se uma propriedade não precisar participar desses cenários, ela não precisará ser enumerada. Portanto, um manipulador de propriedades pode produzir um valor não VT_EMPTY para propriedades que não são descobertas por meio dos métodos IPropertyStore::GetCount e IPropertyStore::GetAt .

No entanto, as propriedades deverão ser visíveis por meio desses métodos se qualquer uma das seguintes condições for atendida:

• Se a propriedade for indexada para que seja pesquisável: Isso significa que ele está incluído no repositório de propriedades da Pesquisa do Windows (indicado por isColumn = "true" no esquema de descrição da propriedade) ou disponível para pesquisas de texto completo (inInvertedIndex = "true"). Na ausência desses sinalizadores ou na ausência de uma descrição de propriedade, as propriedades do tipo "string" serão adicionadas automaticamente ao índice invertido para habilitar a pesquisa. Como a lista de propriedades conhecidas (aquelas com descrições de propriedade instaladas) no sistema de propriedades é muito grande (mais de 800 propriedades), seria impraticável solicitar a cada manipulador de propriedades cada propriedade registrada no sistema de propriedades. Em vez disso, o processo de indexação enumera as propriedades relevantes do manipulador de propriedades para cada item indexado e usa os valores das propriedades enumeradas para criar o índice de texto completo.
• Se a propriedade deve ser copiada quando o conjunto de propriedades do item é duplicado: Para implementar uma função "copiar um conjunto de propriedades", o item de origem torna as propriedades que devem ser copiadas visíveis por meio dos métodos IPropertyStore::GetCount e IPropertyStore::GetAt . As propriedades que não precisam ser copiadas ou não fazem sentido serem copiadas não devem ser incluídas.
• Se o valor da propriedade não estiver vazio (VT_EMPTY): Valores de propriedade vazios não são úteis para clientes. Quando os clientes tentam retornar valores de propriedade vazios, um valor de VT_EMPTY é retornado. Portanto, as propriedades com valores vazios não devem ser enumeradas.
• Se a propriedade deve ser removida ao invocar a função "remover propriedades": Esse recurso existe para proteger a privacidade; ele descobre todos os valores do manipulador de propriedades por meio da enumeração e remove cada um selecionado para remoção pelo usuário.

Para obter informações sobre o suporte para metadados abertos, consulte "Tipos de arquivo que dão suporte a metadados abertos" em Tipos de Arquivo.

Não. VT_NULL valores serão convertidos em VT_EMPTY em chamadas para IPropertyStore::GetValue e IPropertyStore::SetValue.

Geralmente, as propriedades que representam valores de data/hora devem ser representadas usando VT_FILETIME. No entanto, muitas fontes de dados fornecem essas informações no formulário de cadeia de caracteres. A API auxiliar PropVariantChangeType dá suporte à coerção de alguns formatos de data de cadeia de caracteres em valores FILETIME , conforme mostrado na tabela a seguir.

Sim. Algumas implementações do manipulador de propriedades não dão suporte à gravação de valores de propriedade. Esses manipuladores de propriedades devem retornar STGM_E_ACCESSDENIED em chamadas para IInitializeXXX::Initialize que passam STGM_READWRITE ou em qualquer chamada para IPropertyStore::SetValue.

Todos os manipuladores de propriedades abertos no modo STGM_READ devem retornar STGM_E_ACCESSDENIED em chamadas para IPropertyStore::SetValue.

Sim. No sistema de esquema, as propriedades são anotadas como somente leitura (incluindo aquelas com isInnate = "true") ou leitura/gravação. Manipuladores de propriedade que não dão suporte à gravação de uma propriedade específica que o esquema diz que deve ser gravável devem implementar IPropertyStoreCapabilities e retornar S_FALSE em chamadas para IPropertyStoreCapabilities::IsPropertyWritable para essa propriedade. Isso indica que, no contexto desse manipulador e desse arquivo, a propriedade não é gravável.

Tópicos relacionados

Noções básicas sobre manipuladores de propriedade

Usando nomes de tipo

Usando listas de propriedades

Inicializando manipuladores de propriedade

Registrando e distribuindo manipuladores de propriedades