DTWAIN_ArrayGetAtANSIStringPtr

The DTWAIN_ArrayGetAtANSIStringPtr function retrieves a pointer to a Unicode (16-bit character) string from a DTWAIN_ARRAY.

LPCSTR DTWAIN_ArrayGetAtANSIStringPtr (

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 ANSI null-terminated string is returned. If the function fails a NULL pointer or 0 value is returned.

Comments

The DTWAIN_ArrayGetAtANSIStringPtr 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 LPCSTR 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_ArrayGetAtANSIStringPtr function has the advantage over DTWAIN_ArrayGetAtANSIString in that no copying needs to be done to return the string.

This function will only work for DTWAIN_ARRAY's that can store wide ANSI or 8-bit character strings values. The DTWAIN_ARRAY must be created with

1) The DTWAIN_ARRAYANSISTRING style

2) with the DTWAIN_ARRAYSTRING style if using the ANSI version of the DTWAIN library (DTWAIN32.DLL, DTWAIN64.DLL).

To retrieve pointers to 16-bit or Unicode character strings, use DTWAIN_ArrayGetAtWideStringPtr.

TWAIN State Transitions

None.

Prerequisite Function Call(s)

DTWAIN_SysInitialize