DTWAIN_ArrayGetAtStringPtr

The DTWAIN_ArrayGetAtStringPtr function retrieves a pointer to a string value from a DTWAIN_ARRAY.

LPCTSTR DTWAIN_ArrayGetAtStringPtr (

DTWAIN_ARRAY	Array,
LONG	Index );

Parameters

Array

DTWAIN_ARRAY that the value will be retrieved from.

Position

Index of value to retrieve.

Return Values

If the function succeeds, a pointer to the null-terminated string is returned. If the function fails a NULL pointer or 0 value is returned.

Comments

The DTWAIN_ArrayGetAtStringPtr function returns a pointer to the string stored in the DTWAIN ARRAY Array at index Index. 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.

The returned value is a constant pointer to a string, where the string is non-changeable. Attempting to alter the buffer pointed to by the returned LPCTSTR will result in undefined behavior to the application (possible crash or other undesirable effects).

The pointer returned is temporary in that the pointer to the string may become invalid if a subsequent call to a DTWAIN function affects the DTWAIN_ARRAY in any way (adding an element, removing an element, destruction of the DTWAIN_ARRAY, etc.) Therefore the application must make sure that the pointer is used as locally and in as small a scope as possible (at least make sure that the pointer is not used after a DTWAIN call that affects the DTWAIN_ARRAY).

The DTWAIN_ArrayGetAtStringPtr function has the advantage over DTWAIN_ArrayGetAtString in that no copying needs to be done to return the string.

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

#include <tchar.h>

//...

DTWAIN_ARRAY sArray;

// create the array

sArray = DTWAIN_ArrayCreate( DTWAIN_ARRAYSTRING, 1);

// set a string at the first element

DTWAIN_ArraySetAtString( sArray, 0, _T("This is a string"));

// get a pointer to the string.

TCHAR *ptr = DTWAIN_ArrayGetAtStringPtr( sArray, 0 );

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

TWAIN State Transitions

None.

Prerequisite Function Call(s)

DTWAIN_SysInitialize