GetDeviceValue method

Article
05/31/2018

The IStillImage::GetDeviceValue method is used to obtain information from the registry that has been associated with an image acquisition device API such as TWAIN or ISIS.

Syntax

HRESULT GetDeviceValue(
  [in]  LPWSTR  pwszDeviceName,
  [out] LPWSTR  pValueName,
  [out] LPDWORD pType,
  [out] LPBYTE  pData,
  [out] LPDWORD cbData
);

Parameters

pwszDeviceName [in]

Pointer to a string that represents the name of the value tag. It is the key that is used with GetDeviceValue to look up the ancillary data. Microsoft has defined and reserved the following device values:

Value	Meaning
STI_DEVICE_VALUE_TWAIN_NAME	The data associated with this registry key is the name of a TWAIN device.
STI_DEVICE_VALUE_ISIS_NAME	The data associated with this registry key is the name of an ISIS device.
STI_DEVICE_VALUE_ICM_PROFILE	The data associated with this registry key is the file name of the ICM device profile for the device.
STI_DEVICE_VALUE_DEFAULT_LAUNCHAPP	The data associated with this registry key is the name of the default launch application for events on the device.

pValueName [out]

Pointer to a string that receives information from the registry that has been associated with an image acquisition device API.

pType [out]

Pointer to a variable that receives the key's value type. The pType parameter can be NULL if the type is not required. The value returned through this parameter is one of the following.

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_DWORD_LITTLE_ENDIAN	A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order byte. This is the most common format for computers running Windows NT/Windows 2000 and Windows 98/Windows Me.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order byte.
REG_EXPAND_SZ	A null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It is a Unicode or ANSI string depending on whether you use the Unicode or ANSI methods.
REG_LINK	A Unicode symbolic link.
REG_MULTI_SZ	An array of null-terminated strings, terminated by two null characters.
REG_NONE	No defined value type.
REG_RESOURCE_LIST	A device-driver resource list.
REG_SZ	A null-terminated string. It is a Unicode or ANSI string depending on whether you use the Unicode or ANSI methods.

pData [out]

Pointer to a buffer that receives the value's data. This parameter can be NULL if the data is not required.

cbData [out]

Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pData parameter. When the method returns, this variable contains the size of the data copied to pData .

Return value

If the method succeeds, the return value is S_OK.

If the method fails because the buffer specified by pData parameter is not large enough to hold the data, the return value is ERROR_MORE_DATA.

If the method fails for another reason, the return value is the appropriate COM error.

Remarks

If the buffer specified by pData parameter is not large enough to hold the data, the method returns the value ERROR_MORE_DATA, and stores the required buffer size, in bytes, into the parameter pointed to by cbData .

If pData is NULL, and cbData is non-NULL, the method returns S_OK, and stores the size of the data, in bytes, in the parameter pointed to by cbData . This allows an application to determine the best way to allocate a buffer for the value key's data.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, then pData also includes the size of the terminating null character.

The cbData parameter can be NULL only if pData is NULL.

Requirements


Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Sti.h
Library	Sti.lib
DLL	Sti.dll

Share via