DTWAIN_SetDSMSearchOrderEx
|
The DTWAIN_SetDSMSearchOrderEx function sets the directories that are searched whenever DTWAIN attempts to locate and load the TWAIN Data Source Manager.
DTWAIN_BOOL DTWAIN_SetDSMSearchOrderEx (
Parameters
SearchOrder A string denoting the order of directory searching when attempting to locate and load the TWAIN Data Source Manager.
UserDirectory A string denoting a user-defined directory when searching for the TWAIN Data Source Manager, or NULL if no user-defined directory is used.
Return Values The return value is TRUE if successful. Otherwise FALSE is returned.
Character specific version
Comments The DTWAIN_SetDSMSearchOrderEx function allows the application to set the order of the directories searched when attempting to locate and load the TWAIN Data Source Manager (DSM) File. This file is usually TWAIN_32.DLL or TWAINDSM.DLL, depending on whether the application is 32-bit or 64-bit.
The functions that use the DSM search order set by DTWAIN_SetDSMSearchOrderEx are DTWAIN_IsTwainAvailable, DTWAIN_GetDSMFullName, DTWAIN_StartTwainSession, and indirectly any function that may start a TWAIN session if a session has not already been started (for example, DTWAIN_SelectSource). The SearchOrder specifies which set of directories to search and the order of searching the directories. The directories to search are specified by a character string, where each character denotes a specific directory to search. The search order string is processed from left-to-right for each character found. The following character values are available to SearchOrder.
The WINDOWS and SYSTEM denote the WINDOWS and SYSTEM directories, as specified by the GetWindowsDirectory and GetSystemDirectory Windows API functions, respectively. The Operating System (O) search uses the search path logic that the Windows Operating System uses to search for DLL files. See Locating and Loading the TWAIN DSM for more information on the WINDOWS, SYSTEM, and OS searches. The Current working directory (C) search will search the current working directory. This is usually the directory where the application's executable is running. The User-defined directory (U) is a directory specified by UserDirectory. If no user directory is required, then UserDirectory should be NULL.
So for example, if SearchOrder is "WSO", then the Windows directory (W) will be searched, followed by the System directory (S), and then the Operating System (O) is searched. Another example is "UWSC" which means to first search the user-defined directory (U), then the Windows (W), System (S), and current working directory (C), respectively. If multiple directories are to be searched, the first directory found that contains the TWAIN DSM will be used. For example, "WSO" will search the WINDOWS directory first, and if the TWAIN DSM can be found in the WINDOWS directory, the search stops successfully (as it is not necessary to search SYSTEM and the OS for the DSM file).
The DTWAIN_SetDSMSearchOrderEx function can be called before calling DTWAIN_SysInitialize, and before calling DTWAIN_IsTwainAvailable. The DTWAIN_IsTwainAvailable function will use the current search order set by DTWAIN_SetDSMSearchOrderEx to check if TWAIN is available on the user's system. By default, if DTWAIN_SetDSMSearchOrdeEx is never called by the application, the search order used by DTWAIN to locate and load the DSM is "CWSO" (current working directory, Windows directory, System directory, and finally utilizing the Windows operating system search logic when attempting to find Dynamic Link Library (DLL) files, which includes searching the directories on the system path).
TWAIN State Transitions None.
Prerequisite Function Call(s) None. |