Función PSCoerceToCanonicalValue (propsys.h)

Artículo
08/25/2023

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

Sintaxis

PSSTDAPI PSCoerceToCanonicalValue(
  [in]      REFPROPERTYKEY key,
  [in, out] PROPVARIANT    *ppropvar
);

Parámetros

[in] key

Tipo: REFPROPERTYKEY

Referencia a una estructura PROPERTYKEY que identifica la propiedad cuyo valor se va a coerced.

[in, out] ppropvar

Tipo: PROPVARIANT*

En la entrada, contiene un puntero a una estructura PROPVARIANT que contiene el valor original. Cuando esta función vuelve correctamente, contiene el valor canónico.

Valor devuelto

Tipo: HRESULT

Entre los valores devueltos 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 .
TYPE_E_TYPEMISMATCH	No se pudo realizar la coerción del tipo del valor al tipo de la descripción de la propiedad. Se ha borrado la estructura PROPVARIANT .
Cualquier otro código de error	No se pudo realizar la coerción del tipo del valor al tipo de la descripción de la propiedad. Se ha borrado la estructura PROPVARIANT .

Comentarios

Esta función es un contenedor alrededor de la implementación del sistema de IPropertyDescription::CoerceToCanonicalValue.

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 ser de tipo VT_LPWSTR. Esta función convierte los valores en este tipo y, a continuación, convierte el resultado en una forma canónica.

Es importante tener en cuenta que si se produce un error en esta función, ya se llamará PropVariantClear en la estructura PROPVARIANT de entrada. Solo si esta función 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.

El sistema de propiedades también realiza la coerción realizada por esta función durante las llamadas a IPropertyStore::GetValue e IPropertyStore::SetValue. Las aplicaciones pueden depender del sistema de propiedades para realizar las coerciones o pueden usar esta función 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:

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 antes de medianoche 1601/01/02.
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 llamando a IPropertyDescription::GetPropertyType. Para obtener información sobre cómo influye el esquema de propiedades en el tipo de una descripción de propiedad, vea typeInfo. Las conversiones se realizan de la siguiente manera:
- Los valores de tipo VT_LPWSTR, VT_BSTR o VT_LPSTR se convierten en VT_VECTOR | VT_LPWSTR mediante InitPropVariantFromStringAsVector.
- Todas las demás conversiones se realizan mediante PropVariantChangeType

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 y no es NULL. Por ejemplo, L"Alice". Si se trata de una propiedad de árbol (es decir, si el atributo isTreeProperty del 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 da como resultado VT_EMPTY si no había contenido.
VT_VECTOR \| VT_LPWSTR	Cada cadena del vector debe cumplir las reglas de VT_LPWSTR enumeradas anteriormente. 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 da como resultado VT_EMPTY.

Si procede, el valor se comprueba con la enumeración de tipo de descripción de propiedad. Se aplican las comprobaciones de la tabla siguiente.

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.

Ejemplos

En el ejemplo siguiente, para incluirse como parte de un programa más grande, se muestra cómo usar PSCoerceToCanonicalValue para coercionar un valor al tipo necesario para PKEY_Keywords.

// PROPVARIANT propvar;
// Assume variable propvar is initialized and valid.

HRESULT hr = PSCoerceToCanonicalValue(PKEY_Keywords, &propvar);

if (SUCCEEDED(hr))
{
    // The conversion succeeded and propvar now is of the correct type for 
    // PKEY_Keywords, or VT_EMPTY.
    PropVariantClear(&propvar);
}
else
{
    // The conversion failed and propvar is now VT_EMPTY.
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP con SP2, Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 con SP1 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	propsys.h
Library	Propsys.lib
Archivo DLL	Propsys.dll (versión 6.0 o posterior)
Redistribuible	Búsqueda de escritorio de Windows (WDS) 3.0