IWiaPropertyStorage::GetPropertyAttributes method (wia_xp.h)
The IWiaPropertyStorage::GetPropertyAttributes method retrieves access rights and legal value information for a specified set of properties.
Syntax
HRESULT GetPropertyAttributes(
[in] ULONG cpspec,
[in] PROPSPEC [] rgpspec,
[out] ULONG [] rgflags,
[out] PROPVARIANT [] rgpropvar
);
Parameters
[in] cpspec
Type: ULONG
Specifies the number of property attributes to query.
[in] rgpspec
Type: PROPSPEC[]
Specifies an array of Device Information Property Constants. Each constant in the array selects a property to query.
[out] rgflags
Type: ULONG[]
An array that receives a property attribute descriptor for each property specified in the rgpspec array. Each element in the array is one or more descriptor values combined with a bitwise OR operation.
[out] rgpropvar
Type: PROPVARIANT[]
An array that receives a property attribute descriptor for each property specified in the pPROPSPEC array. For more information, see PROPVARIANT.
Return value
Type: HRESULT
This method returns one of the following values or a standard COM error code:
| Return Value | Meaning |
|---|---|
| S_OK | This method succeeded. |
| S_FALSE | The specified property names do not exist. No attributes were retrieved. |
| STG_E_ACCESSDENIED | The application does not have access to the property stream or the stream may already be open. |
| STG_E_INSUFFICIENTMEMORY | There is not enough memory to complete the operation. |
| ERROR_NOT_SUPPORTED | The property type is not supported. |
| STG_E_INVALIDPARAMETER | One or more parameters are invalid. One or more of the PROPSPEC structures contain invalid data. |
| STG_E_INVALIDPOINTER | One or more of the pointers passed to this method are invalid. |
| ERROR_NO_UNICODE_TRANSLATION | A translation from Unicode to ANSI or ANSI to Unicode failed. |
Remarks
This method retrieves both property access rights and valid property values. Access rights report whether the property is readable, writable, or both. Valid property values are specified as a range of values, a list of values, or a group of flag values. For more information, see Property Attributes.
If the property access rights flag has the WIA_PROP_NONE bit set, no legal value information is available for this property. Read only properties and properties with a binary data type are examples of properties that would have the WIA_PROP_NONE bit set.
If the property has a range of valid values, they can be determined through the rgpropvar parameter upon completion of this method. The ppvValidValues parameter specifies an array of PROPVARIANT structures.
For example, if the property range is specified as VT_VECTOR | VT_UI4, range information can be retrieved through the structure member
rgpropvar[n].caul.pElems[range_specifier]
where n is the index number of the property that is inspected and range_specifier is one of the following:
| Range Specifier | Meaning |
|---|---|
| WIA_RANGE_MAX | Maximum value to which the property may be set. |
| WIA_RANGE_MIN | Minimum value to which the property may be set. |
| WIA_RANGE_NOM | Normal or default property value. |
| WIA_RANGE_STEP | Increment or decrement between property values. |
If the property has a list of valid values, applications determine them through the ppvValidValues parameter upon completion of this method.
For example, if the property range is specified as VT_VECTOR | VT_UI4, the list of valid property values can be retrieved through the structure member
rgpropspecValues[n].caul.pElems[list_specifier]
where n is the index number of the property that is inspected and list_specifier is one of the following:
| Range Specifier | Meaning |
|---|---|
| WIA_LIST_COUNT | Total number of list elements excluding the nominal value. |
| WIA_LIST_NOM | Nominal value for the property. |
| WIA_LIST_VALUES | The index number of the first value. |
Programs also use the ppvValidValues parameter to retrieve valid flag values. For instance, if the property flags are specified as VT_UI4, valid flag values can be determined through the structure member
rgpropspec[n].caul.pElems[flag_specifier]
where n is the index number of the property that is inspected, and flag_specifier is one of the following:
| Range Specifier | Meaning |
|---|---|
| WIA_FLAG_NOM | The nominal value for the property. |
| WIA_FLAG_NUM_ELEMS | Total number of list elements excluding the nominal value. |
| WIA_FLAG_VALUES | All values with all valid flag bits set. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional, Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | wia_xp.h (include Wia.h) |
| Library | Wiaguid.lib |
| DLL | Wiaservc.dll |