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

Artigo
08/25/2023

O método WriteMultiple grava um grupo de propriedades especificado no conjunto de propriedades atual. Se uma propriedade com um nome ou identificador de propriedade especificado já existir, ela será substituída, mesmo quando os tipos antigos e novos para o valor da propriedade forem diferentes. Se uma propriedade de um determinado nome ou ID de propriedade não existir, ela será criada.

Sintaxe

HRESULT WriteMultiple(
  [in] ULONG                cpspec,
  [in] const PROPSPEC []    rgpspec,
  [in] const PROPVARIANT [] rgpropvar,
  [in] PROPID               propidNameFirst
);

Parâmetros

[in] cpspec

O número de propriedades definidas. O valor desse parâmetro pode ser definido como zero; no entanto, isso derrota a finalidade do método, pois nenhuma propriedade é então gravada.

[in] rgpspec

Uma matriz das IDs de propriedade (PROPSPEC) para as quais as propriedades são definidas. Eles não precisam estar em nenhuma ordem específica e podem conter duplicatas, no entanto, a última ID de propriedade especificada é aquela que entra em vigor. Uma combinação de IDs de propriedade e nomes de cadeia de caracteres é permitida.

[in] rgpropvar

Uma matriz (de tamanho cpspec) de estruturas PROPVARIANT que contêm os valores de propriedade a serem gravados. A matriz deve ser o tamanho especificado por cpspec.

[in] propidNameFirst

O valor mínimo para as IDs de propriedade que o método deve atribuir se o parâmetro rgpspec especificar propriedades com nome de cadeia de caracteres para as quais nenhuma ID de propriedade existe atualmente. Se todas as propriedades com nome de cadeia de caracteres especificadas já existirem nesse conjunto e, portanto, já tiverem IDs de propriedade, esse valor será ignorado. Quando não ignorado, esse valor deve ser maior ou igual a dois e menor que 0x80000000. As IDs de propriedade 0 e 1 e superiores a 0x80000000 são reservadas para uso especial.

Retornar valor

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

Essa função também pode retornar erros do sistema de arquivos ou erros do Win32 encapsulados em um tipo de dados HRESULT . Para obter mais informações, consulte Estratégias de tratamento de erros.

Comentários

Se uma propriedade especificada já existir, seu valor será substituído pelo especificado em rgpspec, mesmo quando os tipos antigo e novo para o valor da propriedade forem diferentes. Se a propriedade especificada ainda não existir, essa propriedade será criada. As alterações não são mantidas no armazenamento subjacente até que IPropertyStorage::Commit tenha sido chamado.

Os nomes de propriedade são armazenados em uma seção de dicionário especial do conjunto de propriedades, que mapeia esses nomes para IDs de propriedade. Todas as propriedades têm uma ID, mas os nomes são opcionais. Um nome de cadeia de caracteres é fornecido especificando PRSPEC_LPWSTR no membro ulKind da estrutura PROPSPEC . Se um nome de cadeia de caracteres for fornecido para uma propriedade e o nome ainda não existir no dicionário, o método alocará uma ID de propriedade e adicionará a ID da propriedade e o nome ao dicionário. A ID da propriedade é alocada de tal forma que não está em conflito com outras IDs no conjunto de propriedades. O valor da ID da propriedade também não é menor que o valor especificado pelo parâmetro propidNameFirst . Se o parâmetro rgpspec especificar propriedades nomeadas por cadeia de caracteres para as quais nenhuma ID de propriedade existe atualmente, o parâmetro propidNameFirst especificará o valor mínimo para as IDs de propriedade que o método WriteMultiple deve atribuir.

Quando um novo conjunto de propriedades é criado, as propriedades especial codepage (ID da propriedade 1) e ID da localidade (ID da propriedade 0x80000000) são gravadas automaticamente no conjunto de propriedades. Essas propriedades podem ser lidas posteriormente, usando o método IPropertyStorage::ReadMultiple , especificando IDs de propriedade com os valores de PID_CODEPAGE e PID_LOCALE definidos pelo cabeçalho, respectivamente. Se um conjunto de propriedades não estiver vazio — tiver uma ou mais propriedades além das propriedades codepage e ID de localidade ou tiver um ou mais nomes em seu dicionário — a página de código especial e as propriedades de ID de localidade não poderão ser modificadas chamando IPropertyStorage::WriteMultiple. No entanto, se o conjunto de propriedades estiver vazio, uma ou ambas essas propriedades especiais poderão ser modificadas.

Se um elemento na matriz rgspec for definido com um valor PRSPEC_PROPID de 0xffffffff (PID_ILLEGAL), o valor correspondente na matriz rgvar será ignorado por IPropertyStorage::WriteMultiple. Por exemplo, se esse método for chamado com o parâmetro cspec definido como 3, mas rgpspec[1].prspec for definido como PRSPEC_PROPID e rgpspec[1].propid estiver definido como PID_ILLEGAL, apenas duas propriedades serão gravadas. O elemento rgpropvar[1] é silenciosamente ignorado.

Use a macro PropVariantInit para inicializar estruturas PROPVARIANT .

Os conjuntos de propriedades, que não incluem os dados para propriedades não simples, são limitados a 256 KB de tamanho para Windows NT 4,0 e anteriores. Para Windows 2000, Windows XP e Windows Server 2003, os conjuntos de propriedades OLE são limitados a 1 MB. Se esses limites forem excedidos, a operação falhará e o chamador receberá uma mensagem de erro. Não há nenhuma possibilidade de perda ou estouro de memória. Para obter mais informações, consulte Gerenciando conjuntos de propriedades.

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. Especificar uma propriedade por seu nome em IPropertyStorage::WriteMultiple resultará em uma pesquisa que não diferencia maiúsculas de minúsculas dos nomes no conjunto de propriedades. Para comparar cadeias de caracteres que não diferenciam maiúsculas de minúsculas, a localidade das cadeias de caracteres deve ser conhecida. Para obter mais informações, consulte IPropertyStorage::WritePropertyNames.

Para obter mais informações, consulte Considerações sobre o armazenamento de propriedades.

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