DTwainSource::GetCapValues

Syntax

bool DTwainSource::GetCapValues( LONG Cap, DTwainLongArray& Values, LONG GetType=DTWAIN_CAPGET ) const;

bool DTwainSource::GetCapValues( LONG Cap, DTwainStringArray& Values, LONG GetType=DTWAIN_CAPGET ) const;

bool DTwainSource::GetCapValues( LONG Cap, DTwainDoubleArray& Values, LONG GetType=DTWAIN_CAPGET ) const;

bool DTwainSource::GetCapValues( LONG Cap, DTwainFrameArray& Values, LONG GetType=DTWAIN_CAPGET ) const;

Parameters

Cap

Capability values to get.

Values

On return, capability values 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::GetCapValues function retrieves capability values from the Source, and fills an array with these values on return.

There are four forms of CDTwainSource::GetCapValues.  All the forms are both equivalent in terms of every parameter except the Values 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 Values parameter will be either an STL vector of long values, string values, double (real) values, or DTwainFrame values.  The type of vector to use depends on the lCap parameter.  If the wrong vector type is used for the lCap value type, DTwainSource::GetCapValues returns false.  The DTWAIN C++ library uses typedef's for the various vector types.  These typedef's that are used for capability setting and retrieval are DTwainLongArray, DTwainStringArray, DTwainDoubleArray, and DTwainFrameArray.  In general, the vector types are determined by the following:

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

If the capability supports a floating point type, the vector to use is DTwainDoubleArray

If the capability supports a string type, the vector to use is DTwainStringArray.

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

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::GetCapValues 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

   DTwainDoubleArray Resolutions;

   Source.GetCapValues( DTWAIN_CV_ICAPXRESOLUTION, Resolutions );

   // display values on the console

   for (int i = 0; i < Resolutions.size( ); ++i )

       std::cout << Resolutions[i] << std::endl;

}

The Values parameter is an STL vector type, so all of the functions that can apply to vectors can apply to the Values parameter. For example, note the use of the size( ) member function that returns the number of elements in the vector.

The only capability that returns a DTwainFrameArray is DTWAIN_CV_ICAPFRAMES.  The following example shows how to get the current value of this capability.

#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

   DTwainFrameArray AllFrames;

   Source.GetCapValues( DTWAIN_CV_ICAPFRAMES, AllFrames );

   // display all values on the console

   // Let's use an iterator in this example.

  DTwainFrameArray::iterator cur = AllFrames.begin( );

  DTwainFrameArray::iterator last = AllFrames.end( );

  // loop for all frames

  while ( cur != last )

  {

     // display (Left, top, right, bottom) of the frame

     std::cout << "(" << cur->Left( ) << ", " << cur->Top( ) << ", " <<

                                     cur->Right( ) << ", " << cur->Bottom( ) << ")" << std::endl;

     // go to next frame in the array

    ++cur;

  }

}

If the capability returns a range of values, it is sometimes advantageous to expand the range into discrete values.  Here is a revised example of the example above that returns the x-resolution values.

#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

   DTwainDoubleArray Resolutions;

   Source.GetCapValues( DTWAIN_CV_ICAPXRESOLUTION, Resolutions );

   // Check if this returns a range

   if ( Source.IsCapContainerRange( DTWAIN_CV_ICAPXRESOLUTION ) )

   {

        // create a range using the values from Resolution, and expand the values

        // back into the Resolution vector

       MakeDoubleRange( Resolutions ).Expand( Resolutions );

   }

   // display values on the console

   for (int i = 0; i < Resolutions.size( ); ++i )

       std::cout << Resolutions[i] << std::endl;

}

Note the usage of MakeDoubleRange( ) which creates a range from a DTwainDoubleArray that actually contains a range definition.  The Expand( ) function then expands the range values into discrete values.