VariantChangeType Function

Converts a variant from one type to another.

C++
Copy 
HRESULT VariantChangeType(  
  VARIANTARG   *pvargDest,  
  VARIANTARG   *pvarSrc,  
  unsigned short  wFlags,  
  VARTYPE  vt              
);

pvargDest

A pointer to the coerced argument. If this is the same as pvarSrc, the variant will be converted in place.

pvarSrc

A pointer to the argument to be coerced.

wFlags

Flags that control the coercion. Acceptable values are:

  • VARIANT_NOVALUEPROP. Prevents the function from attempting to coerce an object to a fundamental type by getting the Value property. Applications should set this flag only if necessary, because it makes their behavior inconsistent with other applications.

  • VARIANT_ALPHABOOL. Converts a VT_BOOL value to a string containing either "True" or "False".

  • VARIANT_NOUSEROVERRIDE. For conversions to or from VT_BSTR, passes LOCALE_NOUSEROVERRIDE to the core coercion routines.

  • VARIANT_LOCALBOOL. For conversions from VT_BOOL to VT_BSTR and back, uses the language specified by the locale in use on the local computer.

vt

The type to coerce to. If the return code is S_OK, the vt field of the *pvargDest is always the same as this value.

The return value obtained from the returned HRESULT is one of the following.

Value

Meaning

S_OK

Success.

DISP_E_BADVARTYPE

The variant type vt is not a valid type of variant.

DISP_E_OVERFLOW

The data pointed to by pvarSrc does not fit in the destination type.

DISP_E_TYPEMISMATCH

The argument could not be coerced to the specified type.

E_INVALIDARG

One of the arguments is invalid.

E_OUTOFMEMORY

Memory could not be allocated for the conversion.

The VariantChangeType function handles coercions between the fundamental types (including numeric-to-string and string-to-numeric coercions). The pvarSrc argument is changed during the conversion process. For example, if the source variant is of type VT_BOOL and the destination is of type VT_UINT, the pvarSrc argument is first converted to VT_I2 and then the conversion proceeds. A variant that has VT_BYREF set is coerced to a value by obtaining the referenced value. An object is coerced to a value by invoking the object's Value property (DISPID_VALUE).

Typically, the implementor of IDispatch::Invoke determines which member is being accessed, and then calls VariantChangeType to get the value of one or more arguments. For example, if the IDispatch call specifies a SetTitle member that takes one string argument, the implementor would call VariantChangeType to attempt to coerce the argument to VT_BSTR. If VariantChangeType does not return an error, the argument could then be obtained directly from the bstrVal field of the VARIANTARG. If VariantChangeType returns DISP_E_TYPEMISMATCH, the implementor would set *puArgErr to 0 (indicating the argument in error) and return DISP_E_TYPEMISMATCH from IDispatch::Invoke.

Arrays of one type cannot be converted to arrays of another type with this function.

NoteNote

The type of a VARIANTARG should not be changed in the rgvarg array in place.

Show: