DTWAIN_ArrayGetAtWideStringPtr

Top Previous Next

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

LPCWSTR DTWAIN_ArrayGetAtWideStringPtr (

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

Comments

The DTWAIN_ArrayGetAtWideStringPtr 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 LPCWSTR 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_ArrayGetAtWideStringPtr function has the advantage over DTWAIN_ArrayGetAtWideString 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 (Unicde) or 16-bit character strings values. The DTWAIN_ARRAY must be created with

1) The DTWAIN_ARRAYWIDESTRING style

2) with the DTWAIN_ARRAYSTRING style if using the Unicode version of the DTWAIN library (DTWAIN32U.DLL, DTWAIN64U.DLL).

To retrieve pointers to 8-bit or ANSI character strings, use DTWAIN_ArrayGetAtANSIStringPtr.

TWAIN State Transitions

None.

Prerequisite Function Call(s)

DTWAIN_SysInitialize