DTWAIN_GetSourceDetails
|
The DTWAIN_GetSourceDetails function generates a JSON string describing one or more TWAIN Sources.
LONG DTWAIN_GetSourceDetails (
Parameters
szSources Pipe (|) delimeted names of the TWAIN sources. szDetails String buffer. On return, this is filled in with the JSON string. Ignored if value is NULL.
MaxLen Maximum number of characters to write to szDetails. This argument is ignored if szSessionDetails is NULL.
IndentFactor Determines the level of indentation the JSON string will contain. bRefresh Determines if the TWAIN source details will be regenerated. Return Values The return value is the total number of characters copied to szDetails, or if szDetails is NULL, the total number of characters that make up the JSON string.
Character specific version
Comments The DTWAIN_GetSourceDetails function generates a JSON string that describes one or more TWAIN Sources. The szSources is a pipe-delimeted string that consists of all the Product names of the sources to get the details of. For example: "Source 1 | Source 2" would be an example of a pipe-delimited name for two sources, one with product name "Source 1" and the other being "Source 2". If there is only one Source to get the details of, then no pipe symbol is necessary. The reason why the Product name and not the DTWAIN_SOURCE is used is that DTWAIN_GetSourceDetails is able to get the information for Sources that have not been selected and opened, thus the Product Names are used to inform DTWAIN_GetSourceDetails on the exact Sources to retrieve the information from. On return, the szDetails will be filled with the JSON string. The MaxLen argument is the maximum number of characters, including the terminating NULL, that will be copied to szDetails. If szDetails is NULL, the MaxLen argument is ignored. The IndentFactor determines the indentation level of the JSON data. For example, if the IndentFactor is 2, then each level of the JSON data is indented two spaces. If the IndentFactor is -1, then there is no level of indentation (basically a JSON string that has all indentation and carriage returns removed). The bRefresh determines if the TWAIN source information should be refreshed, i.e. if DTWAIN has to determine the source details again instead of using a cached version of the source details. If bRefresh is TRUE, then the source details are refreshed. If bRefresh is FALSE, then a cached version of the session details is used. Note that the initial call to DTWAIN_GetSourceDetails will always result in DTWAIN having to initially go through TWAIN to get the source details, but once this is done, these details are cached, resulting in subsequent calls to DTWAIN_GetSourceDetails with bRefresh as FALSE executing much more quickly than if bRefresh is TRUE. Here is a small excerpt of the JSON data (with an IndentFactor of 2). The actual data will consist of much more information, including the names of the TWAIN sources, capabilities of each source, etc.: { "dtwain-version": "5.7.3", "session-twain-identity": { "device-name": "Demo Program Name", "twain-identity": { "id": 1282, "protocol-major": 1, "protocol-minor": 9, "supported-groups": "DG_CONTROL,DG_IMAGE,DG_AUDIO", "manufacturer": "Demo Program Menu", "product-family": "Demo Program Family", "product-name": "Demo Program Name", "version-majornum": 1, "version-minornum": 0, "version-language": 13, "version-country": 1, "version-info": "1.0" } }, "device-count": 1, To get detailed information on the entire TWAIN session, the DTWAIN_GetSessionDetails function can be used. Prerequisite Function Call(s)
|