DTwainSource::GetSingleCapValue

Syntax

bool DTwainSource::GetSingleCapValue( LONG Cap, LONG& Value, LONG GetType=DTWAIN_CAPGET ) const;

bool DTwainSource::GetSingleCapValue( LONG Cap, std::string& Value, LONG GetType=DTWAIN_CAPGET ) const;

bool DTwainSource::GetSingleCapValue( LONG Cap, double& Value, LONG GetType=DTWAIN_CAPGET ) const;

bool DTwainSource::GetSingleCapValue( LONG Cap, DTwainFrame& Value, LONG GetType=DTWAIN_CAPGET ) const;

Parameters

Cap

Capability values to get.

Value

On return, single capability value retrieved from the Source.

GetType

Capability retrieval mode.  Either DTWAIN_CAPGET, DTWAIN_CAPGETCURRENT, or DTWAIN_CAPGETDEFAULT.

Return Value

true if successful, false if unsuccessful.

Comments

The DTwainSource::GetSingleCapValue function retrieves a single capability value from the Source.  This function is a specialized version of DTwainSource::GetCapValues, the difference being that DTwainSource::GetCapValues can retrieve multiple capability values, while DTwainSource::GetSingleCapValue returns only one value..

There are four forms of CDTwainSource::GetSingleCapValue.  All the forms are both equivalent in terms of every parameter except the Value parameter.  The lCap parameter is one of the capability constants (for example, DTWAIN_CV_ICAPBITDEPTH or DTWAIN_CV_CAPAUTHOR.  See the main help manual for a complete list of these constants).

The GetType determines whether the capability value that will be retrieved is the current value, default value, or all the values supported by the capability. The values of GetType can be one of the following:

If the GetType parameter is omitted, then all the values supported by the capability are returned.

The Value parameter will be either a long value, string value, double (real) value, or DTwainFrame value.  The type of value to use depends on the lCap parameter.  If the wrong value type is used for the lCap value type, DTwainSource::GetSingleCapValue returns false.  In general, the vector types are determined by the following:

If the capability supports an integer type (long, int, boolean, etc.), the type to use is LONG or long.

If the capability supports a floating point type, the type to use is double.

If the capability supports a string type, the type to use is std::string,

If the capability supports a TW_FRAME type, the type to use is DTwainFrame.

To get the data type for a specific capability, you can get the data type defined in the DTWAIN Capability constants in the main help manual, or call DTwainSource::GetCapDataType( ) to determine the type.  Here is a table of the return value from DTwainSource::GetCapDataType, and the correspoding vector type to use:

A return value of false from DTwainSource::GetSingleCapValue could mean one of the following:

As an example, to get the capability values for DTWAIN_CV_ICAPXRESOLUTION, the data types that will be stored  are DTWAIN_FLOATs.  In this case, the call to DTwainSource::GetCapValues must use a reference to a DTwainDoubleArray as the Values parameter.  

To get all of the X-resolution values, the following code snippet shows how this is done:

#include <cdtwain.h>

#include <iostream>

using namespace DTWAIN;

using namespace std;

int main( )

{

   DTwainInterface TI( NULL, NULL ); // start DTWAIN and a Twain session

   DTwainSource Source = DTwainSource::Select( );

   // get the resolution values

   double Resolution;

   Source.GetSingleCapValue( DTWAIN_CV_ICAPXRESOLUTIONS, Resolution, DTWAIN_CAPGETCURRENT );

   cout << "The current x-resolution is " << Resolution << endl;

}