DTwainSource::SetSingleCapValue

 Top  Previous  Next

Syntax

 

bool DTwainSource::SetSingleCapValue( LONG Cap, LONG Value );

 

bool DTwainSource::SetSingleCapValue( LONG Cap, const std::string& Value );

 

bool DTwainSource::SetSingleCapValue( LONG Cap, double Value );

 

bool DTwainSource::SetSingleCapValue( LONG Cap, const DTwainFrame& Value );

 

Parameters

Cap

Capability values to get.

 

Value

Value to use to set for the capability

 

 

Return Value

true if successful, false if unsuccessful.

 

Comments

The DTwainSource::SetSingleCapValue function sets a capability of the source to a single value.  This function is a specialized version of DTwainSource::SetCapValues, the difference being that DTwainSource::SetCapValues can set a capbility with multiple values, while DTwainSource::SetSingleCapValue sets only one value..

 

There are four forms of CDTwainSource::SetSingleCapValue.  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 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::SetSingleCapValue 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 vector to use is DTwainFrame.

 

To set 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:

 

Return from GetCapDataType( )

type to use

TWTY_INT8      

LONG (long)

TWTY_INT16    

LONG (long)

TWTY_INT32    

LONG (long)

TWTY_UINT8  

LONG (long)

TWTY_UINT16

LONG (long)

TWTY_UINT32

LONG (long)

TWTY_BOOL    

LONG (long)

TWTY_FIX32    

double

TWTY_FRAME  

DTwainFrame

TWTY_STR32    

std::string

TWTY_STR64    

std::string

TWTY_STR128  

std::string

TWTY_STR255  

std::string

 

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

 

•The source does not support the capability.
•The Value parameter specifies the wrong type.
•DTWAIN was not initialized
•The Source is not valid (i.e. was not selected and/or did not open successfully).
•The capability cannot be set with a single value
•The value is invalid for the capability.

 

As an example, to set the capability values for DTWAIN_CV_ICAPXRESOLUTION, the data types that will be stored  are DTWAIN_FLOATs.  In this case, the call to DTwainSource::SetSingleCapValues must use a double as the Value parameter (assume the Source supports setting the x-resolution value to 300).

 

#include <cdtwain.h>

using namespace DTWAIN;

 

int main( )

{

   DTwainInterface TI; // start DTWAIN and a Twain session

   DTwainSource Source = DTwainSource::Select( );

 

   // set the resolution value to 300 DPI

   Source.SetSingleCapValue( DTWAIN_CV_ICAPXRESOLUTION, 300.0 );

}