IStillImage::GetDeviceValue

[This is preliminary documentation and subject to change.]

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

HRESULT GetDeviceValue(
  LPWSTR pwszDeviceName,
  LPWSTR pValueName,
  LPDWORD pType,
  LPBYTE pData,
  LPDWORD cbData
);

Parameters

pwszDeviceName

Pointer to the friendly device name of the still-image device that caused the event. The device friendly name is retrieved when IStillImage::GetSTILaunchInformation is called. See the code fragment in the section entitled Making An Application Still Image-Aware.

Pointer to a string that represents the name of the value tag. It is the key that will be used with GetDeviceValue to lookup the ancillary data. The defined device values that are defined and reserved by Microsoft :

STI_DEVICE_VALUE_TWAIN_NAME

The data associated with this registry key is the name of the TWAIN device.

STI_DEVICE_VALUE_ISIS_NAME

The data associated with this registry key is the name of the 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

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

pType

Pointer to a variable that receives the key's value type. The value returned through this parameter will be 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 and Windows 95.
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 will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
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 will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.

The pType parameter can be NULL if the type is not required.

pData

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

cbData

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

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

If pData is NULL, and cbData is non-NULL, the function returns S_OK, and stores the size of the data, in bytes, in the variable pointed to by cbData. This lets an application 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 will also include the size of the terminating null character.

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

Return Values

If the function succeeds, the return value is S_OK.

If the function 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 function fails for another reason, the return value is the appropriate COM error.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Requires Windows 98.
  Windows CE: Unsupported.
  Header: Declared in sti.h.
  Import Library: Included as a resource in sti.dll.

See Also

Still Image Overview, Making An Application Still Image-Aware