Método IPropertyStorage::WritePropertyNames (propidlbase.h)

Artigo
08/25/2023

O método WritePropertyNames atribui nomes de cadeia de caracteres IPropertyStorage a uma matriz especificada de IDs de propriedade no conjunto de propriedades atual.

Sintaxe

HRESULT WritePropertyNames(
  [in] ULONG             cpropid,
  [in] const PROPID []   rgpropid,
  [in] const LPOLESTR [] rglpwstrName
);

Parâmetros

[in] cpropid

O tamanho na entrada da matriz rgpropid. Pode ser zero. No entanto, torná-lo zero faz com que esse método se torne não operacional.

[in] rgpropid

Uma matriz das IDs de propriedade para as quais os nomes devem ser definidos.

[in] rglpwstrName

Uma matriz de novos nomes a serem atribuídos às IDs de propriedade correspondentes na matriz rgpropid . Esses nomes não podem exceder 255 caracteres (sem incluir o terminador NULL ).

Retornar valor

Esse método dá suporte ao valor retornado padrão E_UNEXPECTED, além do seguinte:

Comentários

Para obter mais informações sobre conjuntos de propriedades e gerenciamento de memória, consulte Gerenciando conjuntos de propriedades.

IPropertyStorage::WritePropertyNames atribui nomes de cadeia de caracteres a IDs de propriedade passadas para o método na matriz rgpropid . Ele associa cada nome de cadeia de caracteres na matriz rglpwstrName à respectiva ID de propriedade em rgpropid. É explicitamente válido definir um nome para uma ID de propriedade que não está presente atualmente no objeto de armazenamento de propriedades.

Também é válido alterar o mapeamento de um nome de cadeia de caracteres existente (determinado por uma correspondência que não diferencia maiúsculas de minúsculas). Ou seja, você pode usar o método WritePropertyNames para mapear um nome existente para uma nova ID de propriedade ou mapear um novo nome para uma ID de propriedade que já tenha um nome no dicionário. Em ambos os casos, o mapeamento original é excluído. Os nomes de propriedade devem ser exclusivos (assim como as IDs de propriedade) dentro do conjunto de propriedades.

O armazenamento de nomes de propriedade de cadeia de caracteres preserva o caso. A menos que PROPSETFLAG_CASE_SENSITIVE seja passado para IPropertySetStorage::Create, os nomes dos conjuntos de propriedades não diferenciam maiúsculas de minúsculas por padrão. Com conjuntos de propriedades que não diferenciam maiúsculas de minúsculas, as cadeias de caracteres de nome passadas pelo chamador são interpretadas de acordo com a localidade do conjunto de propriedades, conforme especificado pela propriedade PID_LOCALE . Se o conjunto de propriedades não tiver nenhuma propriedade de localidade, o usuário atual será assumido por padrão. Os nomes de propriedade de cadeia de caracteres são limitados em comprimento a 128 caracteres. Os nomes de propriedade que começam com os caracteres Unicode binários 0x0001 por meio de 0x001F são reservados para uso futuro.

Se o valor de um elemento no parâmetro de matriz rgpropid for definido como 0xffffffff (PID_ILLEGAL), o nome correspondente será ignorado por IPropertyStorage::WritePropertyNames. Por exemplo, se esse método for chamado com um parâmetro cpropid de 3, mas o primeiro elemento da matriz, rgpropid[1], for definido como PID_ILLEGAL, somente dois nomes de propriedade serão gravados. O elemento rgpropid[1] é ignorado.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	propidlbase.h (inclua Objbase.h, Propidlbase.h)
Biblioteca	Uuid.lib
DLL	Ole32.dll