Compartir a través de

Método IPropertyDescription::CoerceToCanonicalValue (propsys.h)

  • Artículo

Convierte el valor en el valor canónico, según la descripción de la propiedad.

Sintaxis

HRESULT CoerceToCanonicalValue(
  [in, out] PROPVARIANT *ppropvar
);

Parámetros

[in, out] ppropvar

Tipo: PROPVARIANT*

En la entrada, contiene un puntero a una estructura PROPVARIANT que contiene el valor original. Cuando este método devuelve , contiene el valor canónico.

Valor devuelto

Tipo: HRESULT

Si el código de error no es INPLACE_S_TRUNCATED o E_INVALIDARG, no se pudo borrar la coerción del tipo del valor al tipo de la descripción de la propiedad y se ha borrado la estructura PROPVARIANT .

Entre los resultados posibles se incluyen los siguientes:

Código devuelto Descripción
S_OK
 La función se ha realizado correctamente. El valor de propiedad especificado por ppropvar ahora está en forma canónica.
INPLACE_S_TRUNCATED
 El valor de propiedad especificado por ppropvar ahora está en forma canónica truncada.
E_INVALIDARG
 El parámetro ppropvar no es válido. Se ha borrado la estructura PROPVARIANT .

Comentarios

Para obtener más información, vea el atributo type del elemento typeInfo en el archivo .propdesc de la propiedad.

La mayoría de las descripciones de propiedades especifican el tipo que se espera que usen sus valores. Por ejemplo, la descripción de la propiedad de System.Title especifica que los valores de System.Title deben usar VT_LPWSTR. Este método coerce los valores de este tipo y convierte el resultado en una forma canónica.

Es importante tener en cuenta que si se produce un error en este método, ya habrá llamado a PropVariantClear en la estructura PROPVARIANT de entrada. Solo si este método se realiza correctamente es la aplicación que realiza la llamada responsable de llamar a PropVariantClear en ppropvar cuando la estructura ya no es necesaria.

La coerción realizada por este método también se realiza mediante el sistema de propiedades durante las llamadas A IPropertyStore::GetValue e IPropertyStore::SetValue . Las aplicaciones pueden depender del sistema de propiedades para realizar las coerciones o pueden usar este método para realizar la coerción en un momento de la elección de la aplicación.

La coerción se realiza en cuatro pasos, como se indica a continuación:

  1. Los valores siguientes se convierten en VT_EMPTY.
    • Valores de tipo VT_NULL.
    • Valores de tipo VT_LPWSTR, VT_BSTR, o VT_LPSTR cuyo puntero es NULL.
    • Valores de tipo VT_LPWSTR, VT_BSTR, o VT_LPSTR que están vacíos o que constan completamente de espacios.
    • Valores de tipo VT_FILETIME anteriores a medianoche 1601/01/02.
  2. Si el valor no es de tipo VT_EMPTY después del paso 1, se convierte en el tipo especificado por la descripción de la propiedad. El tipo de una descripción de propiedad se puede obtener mediante IPropertyDescription::GetPropertyType. Consulte typeInfo para obtener información sobre cómo influye el esquema de propiedades en el tipo de una descripción de propiedad. Las conversiones se realizan de la siguiente manera:
  3. Después de los pasos 2 y 3, el valor se coercita en un formulario canónico basado en su tipo. Los formularios canónicos se resumen en la tabla siguiente.
    Tipo de valor Formulario canónico
    VT_EMPTY Siempre canónico.
    VT_LPWSTR
    • No hay espacios iniciales ni finales. La cadena no está vacía. La cadena no es NULL. Por ejemplo, L"Alice".
    • Si se trata de una propiedad de árbol (es decir, si el atributo del isTreeProperty elemento typeInfo es TRUE), no debe tener barras diagonales iniciales o finales (/), no debe tener espacios entre el texto y las barras diagonales, y no debe tener dos barras diagonales consecutivas(/). Por ejemplo: L"Friend/Bob"
    • La coerción quita caracteres innecesarios y dará lugar VT_EMPTY a que no haya contenido.
    VT_VECTOR | VT_LPWSTR
    • Cada cadena del vector debe cumplir las reglas de VT_LPWSTR la lista anterior. Además, el vector no debe tener duplicados y no tiene punteros NULL.
    • Si se trata de una propiedad de árbol, ningún valor puede ser el antecesor de otro valor. Por ejemplo, L"Friend" es un antecesor de L"Friend/Bob".
    • Si no hay contenido, la coerción quita caracteres duplicados y antecesor y dará como resultado VT_EMPTY.
     
  4. Si procede, el valor se comprueba con la enumeración de tipo de descripción de propiedad. Se aplican las siguientes comprobaciones.
    Tipo de enumeración Tipo de valor Formulario canónico
    Discrete o Ranged VT_EMPTY Siempre canónico
    Discrete VT_LPWSTR La cadena coincide con una de las cadenas enumeradas permitidas para la propiedad . Las comparaciones no distinguen entre mayúsculas y minúsculas. Si no es así, convierta el valor en VT_EMPTY.
    Discrete Numeric El número coincide con uno de los valores enumerados permitidos para la propiedad . Si no es así, convierta el valor en VT_EMPTY.
    Discrete VT_VECTOR | VT_LPWSTR Cada cadena del vector coincide con una de las cadenas enumeradas permitidas para la propiedad . Las comparaciones no distinguen entre mayúsculas y minúsculas. Si no es así, quite esa cadena del vector. Si el vector resultante está vacío, convierta el valor en VT_EMPTY.
    Discrete VT_VECTOR | Numérico Cada número del vector coincide con uno de los valores enumerados permitidos para la propiedad . Si no es así, quite ese número del vector. Si el vector resultante está vacío, convierta el valor en VT_EMPTY.
    Extendieron VT_LPWSTR La cadena existe en el intervalo permitido para la propiedad . Las comparaciones distinguen entre mayúsculas y minúsculas. Si no es así, convierta el valor en VT_EMPTY.
    Extendieron Numeric El número existe en el intervalo permitido para la propiedad . Si no es así, convierta el valor en VT_EMPTY.
    Extendieron VT_VECTOR | VT_LPWSTR Cada cadena del vector existe en el intervalo permitido para la propiedad . Las comparaciones distinguen entre mayúsculas y minúsculas. Si no es así, quite esa cadena del vector. Si el vector resultante está vacío, convierta el valor en VT_EMPTY.
    Extendieron VT_VECTOR | Numérico Cada número del vector existe en el intervalo permitido para la propiedad . Si no es así, quite ese número del vector. Si el vector resultante está vacío, convierta el valor en VT_EMPTY.
     

Requisitos

Requisito Value
Cliente mínimo compatible Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado propsys.h

Consulte también

IPropertyDescription

Esquema de descripción de propiedades