DTWAIN_ArrayGetAtANSIString

Top  Previous  Next

The DTWAIN_ArrayGetAtANSIString function retrieves a ANSI string value from a DTWAIN_ARRAY.

 

DTWAIN_BOOL DTWAIN_ArrayGetAtANSIString (

DTWAIN_ARRAY

Array,

LONG

Index,

LPSTR

pValue );

 

Parameters

Array

DTWAIN_ARRAY that the value will be retrieved from.

 

Position

Index of value to retrieve.

 

pValue

Pointer to the character buffer that will receive the string.  The returned string is terminated with a NULL value.

 

Return Values

If the function succeeds, TRUE is returned.  If the function fails FALSE is returned.

 

Comments

DTWAIN_ArrayGetAtANSIString is a specialized version of DTWAIN_ArrayGetAt.

 

The DTWAIN_ArrayGetAtANSIString function copies the string located at index Index to the address pValue.   A DTWAIN_ARRAY is indexed starting from position 0 through position n-1, where n is the total number of items in the DTWAIN_ARRAY Array.

 

Note that pValue must point to a character buffer that has a length greater or equal to the length of the string that is retrieved, with also room for the terminating null character..  To ensure that the buffer is sized correctly, call DTWAIN_ArrayGetStringLength to get the number of characters:

 

Below is a small C++ code example of ensuring that strings are retrieved correctly from a buffer:

 

   DTWAIN_ARRAY sArray;

    // create the array

   sArray = DTWAIN_ArrayCreate( DTWAIN_ARRAYANSISTRING, 1);

 

   // set a string at the first element

   DTWAIN_ArraySetAtANSIString( sArray, 0,  "This is an ANSI string");

 

   // get the length of the string

   LONG sLen = DTWAIN_ArrayGetStringLength( sArray, 0 );

 

   // create a dynamic string using new[].  Make sure we have room for the NULL terminator */

   LPSTR pBuffer = new char[ sLen + 1 ];

 

   // get the string

   DTWAIN_ArrayGetAtANSIString( sArray, 0, pBuffer );

 

 

Other languages should also make the appropriate provisions provided by the language to ensure that the buffer passed to DTWAIN_ArrayGetAtANSIString is large enough to hold the string, plus the ending null terminator.  If this is not done, the application may crash or experience erratic behavior.

 

This function will only work for DTWAIN_ARRAY's that can store wide string values (i.e. the DTWAIN_ARRAY was created with the DTWAIN_ARRAYANSISTRING style. See DTWAIN_ArrayCreate for more information).

 

TWAIN State Transitions

None.

 

Prerequisite Function Call(s)

DTWAIN_SysInitialize

 

See Also

Retrieving Values from a DTWAIN_ARRAY