#ifndef _DSLOADER__H_
#define _DSLOADER__H_

//
// This header file defines the interface between TWAIN Source manager and
// the import data source loader. An import data source loader is a
// separate module loaded by the Source manager to enumerate, load, and unload
// data sources not in TWAIN traditional form, ie, *.ds files in the TWAIN
// subdirectory. This kind of data sources can be in any form as far as
// the loader can expose them properly so that the Source
// manager can access to them.
// A registry entry is dedicated for the loader(only one loader is allowed,
// although this may be changed in the future):
// ImportDSLoader = REG_SZ : <loader full path name>
//

//
// API names provided by the loader.
//

const CHAR FIND_FIRSTIMPORTDS[]        = "FindFirstImportDS";
const CHAR FIND_NEXTIMPORTDS[]         = "FindNextImportDS";
const CHAR CLOSE_FINDCONTEXT[]         = "CloseFindContext";
const CHAR LOAD_IMPORTDS[]             = "LoadImportDS";
const CHAR UNLOAD_IMPORTDS[]           = "UnloadImportDS";
const CHAR GET_LOADERSTATUS[]          = "GetLoaderStatus";
const CHAR FIND_IMPORTDSBYDEVICENAME[] = "FindImportDSByDeviceName";

//
// We pass the imported data source handle on every call to an imported
// data source so that the loader has a way of dispatching the call
// to the designated data source in case two or more data sources
// share the same DS_Entry.
//

typedef TW_UINT16 (APIENTRY *PFNIMPORTEDDSENTRY)(HANDLE, TW_IDENTITY *,
				            TW_UINT32, TW_UINT16, TW_UINT16, TW_MEMREF);
//
// Each data source has its own load/unload function. This makes it possible
// for the loader to assign different loading/unloading scheme for
// different data source.
//

typedef TW_UINT16 (APIENTRY *PFNLOAD_IMPORTDS)(LPCSTR DeviceName,
					       DWORD DeviceFlags, HANDLE *phDS, PFNIMPORTEDDSENTRY *pDSEntry);
typedef TW_UINT16 (APIENTRY *PFNUNLOAD_IMPORTDS)(HANDLE hDS);

//
// Data structure used to convey information about a
// particular data source
//

typedef struct tagImportDSInfo
{
    DWORD Size;		      // The size of the entire structure in bytes.
    CHAR DeviceName[MAX_PATH];  // The device name which uniquely
				                // identifies a particular device
				                // instance in a system. The content
				                // is up to the loader.
    DWORD DeviceFlags;          // misc flags used by the loader.
				                // Together with DeviceName, it is required
				                // to load a device.
    PFNLOAD_IMPORTDS pfnLoadDS; // Loader provided function to load this
				                // this data source.
				                
    PFNUNLOAD_IMPORTDS	pfnUnloadDS; // Loader provided function to unload this data source.
}IMPORT_DSINFO, *PIMPORT_DSINFO;

//
// Funtion prototypes for the APIs
//

typedef TW_UINT16 (APIENTRY *PFNFIND_FIRSTIMPORTDS)(PIMPORT_DSINFO pDSInfo, PVOID *Context);
typedef TW_UINT16 (APIENTRY *PFNFIND_NEXTIMPORTDS)(PIMPORT_DSINFO pDSInfo, PVOID Context);
typedef TW_UINT16 (APIENTRY *PFNCLOSE_FINDCONTEXT)(PVOID Context);
typedef TW_UINT16 (APIENTRY *PFNFIND_IMPORTDSBYDEVICENAME)(PIMPORT_DSINFO pDSInfo, LPCSTR DeviceName);
typedef TW_UINT16 (APIENTRY *PFNGET_LOADERSTATUS)(TW_STATUS *ptwStatus);

//
// This API finds the first available data source managed by the loader
// Input:
//	pDSInfo -- the buffer to receive the first available data source
//		   information. The structure size must be initialized.
//	Context -- A place holder to store the context created by this
//		   API. It is required for FindNextImportDS.
//		   CloseFindContext should be called to release any
//		   resource alloated for this context.
//Output:
//	standard TWRC_ code. If it is not TWRC_SUCCESS, a call
//	to GetLoaderStatus will returns the corresponding TWCC_ code.
//	If the API succeeded, TWRC_SUCCESS is returned.
//	If the API succeeded, pDSInfo is filled with the data source
//	information.

TW_UINT16 APIENTRY FindFirstImportDS(PIMPORT_DSINFO pDSInfo,PVOID Context);

//
// This API finds the next available data source managed by the loader
// Input:
//	pDSInfo -- the buffer to receive the next available data source
//		   information. The structure size must be initialized.
//	Context -- The context returned by FindFirstImportDS
//Output:
//	standard TWRC_ code. If it is not TWRC_SUCCESS, a call
//	to GetLoaderStatus returns the corresponding TWCC_ code.
//	If the API succeeded, TWRC_SUCCESS is returned.
//	If there are no available Data source, TWRC_ENDOFLIST is
//	returned. If the function succeeded, the buffer designated
//	by pDSInfo is filled with data source information.

TW_UINT16 APIENTRY FindNextImportDS(PIMPORT_DSINFO pDSInfo,PVOID Context);

//
// This API closes the context information used to find the data sources
// managed by the loader. The context is returned from FindFirstImportDS
// API and should be releases by calling this API when the searching
// is done.
// Input:
//	Contex -- the context to be closed
// Output:
//	standard TWRC_ error code

TW_UINT16 APIENTRY CloseFindContext( PVOID Context);

//
// This API asks the loader to load the specific data source
// idenetified by the given IMPORT_DSINFO and returns
// the data source's DSEntry. Each data source can supply its own load function
// or several data sources can share the same function. The choice is up
// to the loader and how it load/unload the data source.
// Input:
//	DeviceName -- the name that uniquely represent the data source
//	phDS	   -- to receive a handle to the loaded data source.
//	pDSEntry   -- to receive the data source DSEntry
// Output:
//	standard TWRC_.
//	If the data source is loaded successfully, TWRC_SUCCESS
//	is returned, pDSEntry is filled with the data source's
//	DSEntry and phDS is filled with the handle to the loaded
//	data source. If this api failed, NULL are returned in phDS
//	and pDSEntry.
//
TW_UINT16 APIENTRY LoadImportDS(LPCSTR DeviceName, DWORD  DeviceFlags,HANDLE *phDS,
                                PFNIMPORTEDDSENTRY *pImportDSEntry);
//
// This API asks the loader to unload the specific data source
// The loader is free to release any resources allocated for this
// data source. When the data source is needed again, it will be
// loaded again.
// Input:
//	hDS	-- handle to the loaded data source obtained
//		   from LoadImportDS API
// Output:
//   standard TWRC_ error code

TW_UINT16 APIENTRY UnloadImportDS(HANDLE hDS);

//
// This API finds the data source designated by the given
// device name. This API is useful when the caller only
// knows about a particular device name.
//
// Input:
//	pDSInfo -- buffer to receive data source info.
//	DeviceName -- the device name use to search
//		      for data source
// Output:
//	TWRC_SUCCESS  if a match is found.
//	TWRC_ENDOFLIST if no math is found.
//	TWRC_	other error code.
//

TW_UINT16 APIENTRY FindImportDSByDeviceName(PIMPORT_DSINFO pDSInfo,LPCSTR DeviceName);

//
// This API returns the current loader TW_STATUS. The loader
// updates its status only when the last api call to the loader
// did not return TWRC_SUCCESS.
// Input:
//	ptwStatus -- buffer to receive the status
// Output:
//	standard TWRC_ code.
//

TW_UINT16 APIENTRY GetLoaderStatus(TW_STATUS *ptwStatus);

#endif	// #ifndef _DSLOADER__H_