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

Artículo
08/25/2023

El método WriteMultiple escribe un grupo especificado de propiedades en el conjunto de propiedades actual. Si ya existe una propiedad con un nombre especificado o un identificador de propiedad, se reemplaza, incluso cuando los tipos antiguos y nuevos para el valor de propiedad son diferentes. Si no existe una propiedad de un nombre o un identificador de propiedad especificados, se crea.

Sintaxis

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

Parámetros

[in] cpspec

Número de propiedades establecidas. El valor de este parámetro se puede establecer en cero; sin embargo, esto anula el propósito del método, ya que no se escribe ninguna propiedad.

[in] rgpspec

Matriz de los identificadores de propiedad (PROPSPEC) a los que se establecen las propiedades. Estos no necesitan estar en ningún orden determinado y pueden contener duplicados, pero el último identificador de propiedad especificado es el que surte efecto. Se permite una combinación de identificadores de propiedad y nombres de cadena.

[in] rgpropvar

Matriz (de tamaño cpspec) de estructuras PROPVARIANT que contienen los valores de propiedad que se van a escribir. La matriz debe ser el tamaño especificado por cpspec.

[in] propidNameFirst

Valor mínimo para los identificadores de propiedad que el método debe asignar si el parámetro rgpspec especifica las propiedades con nombre de cadena para las que no existen identificadores de propiedad actualmente. Si todas las propiedades con nombre de cadena especificadas ya existen en este conjunto y, por tanto, ya tienen identificadores de propiedad, este valor se omite. Cuando no se omite, este valor debe ser mayor o igual que, dos y menos que 0x80000000. Los identificadores de propiedad 0 y 1 y mayores que 0x80000000 están reservados para uso especial.

Valor devuelto

Este método admite el valor devuelto estándar E_UNEXPECTED, además de lo siguiente:

Esta función también puede devolver cualquier error del sistema de archivos o errores de Win32 encapsulados en un tipo de datos HRESULT . Para obtener más información, consulte Estrategias de control de errores.

Comentarios

Si ya existe una propiedad especificada, su valor se reemplaza por el especificado en rgpspec, incluso cuando los tipos antiguos y nuevos para el valor de propiedad son diferentes. Si la propiedad especificada aún no existe, se crea esa propiedad. Los cambios no se conservan en el almacenamiento subyacente hasta que se haya llamado a IPropertyStorage::Commit .

Los nombres de propiedad se almacenan en una sección de diccionario especial del conjunto de propiedades, que asigna estos nombres a identificadores de propiedad. Todas las propiedades tienen un identificador, pero los nombres son opcionales. Se proporciona un nombre de cadena especificando PRSPEC_LPWSTR en el miembro ulKind de la estructura PROPSPEC . Si se proporciona un nombre de cadena para una propiedad y el nombre aún no existe en el diccionario, el método asignará un identificador de propiedad y agregará el identificador de propiedad y el nombre al diccionario. El identificador de propiedad se asigna de forma que no entre en conflicto con otros identificadores del conjunto de propiedades. El valor del identificador de propiedad tampoco es menor que el valor especificado por el parámetro propidNameFirst . Si el parámetro rgpspec especifica propiedades con nombre de cadena para las que no existen identificadores de propiedad actualmente, el parámetro propidNameFirst especifica el valor mínimo para los identificadores de propiedad que debe asignar el método WriteMultiple .

Cuando se crea un nuevo conjunto de propiedades, las propiedades de página de códigos especiales (Id. de propiedad 1) e Id. de configuración regional (id. de propiedad 0x80000000) se escriben automáticamente en el conjunto de propiedades. Estas propiedades se pueden leer posteriormente mediante el método IPropertyStorage::ReadMultiple especificando los identificadores de propiedad con los valores de PID_CODEPAGE definidos por el encabezado y PID_LOCALE, respectivamente. Si un conjunto de propiedades no está vacío, tiene una o varias propiedades además de las propiedades codepage y Locale ID o tiene uno o varios nombres en su diccionario, las propiedades de página de códigos especiales y Id. de configuración regional no se pueden modificar llamando a IPropertyStorage::WriteMultiple. Sin embargo, si el conjunto de propiedades está vacío, se puede modificar una o ambas propiedades especiales.

Si un elemento de la matriz rgspec se establece con un valor PRSPEC_PROPID de 0xffffffff (PID_ILLEGAL), IPropertyStorage::WriteMultiple omite el valor correspondiente de la matriz rgvar. Por ejemplo, si se llama a este método con el parámetro cspec establecido en 3, pero rgpspec[1].prspec se establece en PRSPEC_PROPID y rgpspec[1].propid se establece en PID_ILLEGAL, solo se escribirán dos propiedades. El elemento rgpropvar[1] se omite silenciosamente.

Use la macro PropVariantInit para inicializar estructuras PROPVARIANT .

Los conjuntos de propiedades, sin incluir los datos de las propiedades nomples, están limitados a 256 KB de tamaño para Windows NT 4.0 y versiones anteriores. Para Windows 2000, Windows XP y Windows Server 2003, los conjuntos de propiedades OLE están limitados a 1 MB. Si se superan estos límites, se produce un error en la operación y el autor de la llamada recibe un mensaje de error. No existe la posibilidad de que se produzca una pérdida de memoria o una saturación. Para obtener más información, vea Administrar conjuntos de propiedades.

A menos que PROPSETFLAG_CASE_SENSITIVE se pase a IPropertySetStorage::Create, los nombres de conjunto de propiedades no distinguen mayúsculas de minúsculas. Si se especifica una propiedad por su nombre en IPropertyStorage::WriteMultiple , se producirá una búsqueda sin distinción entre mayúsculas y minúsculas de los nombres del conjunto de propiedades. Para comparar cadenas que no distinguen mayúsculas de minúsculas, se debe conocer la configuración regional de las cadenas. Para obtener más información, vea IPropertyStorage::WritePropertyNames.

Para obtener más información, vea Consideraciones sobre el almacenamiento de propiedades.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows 2000 Server [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	propidl.h (include Objbase.h, Propidlbase.h)
Library	Uuid.lib
Archivo DLL	Ole32.dll