1、STD-AIIM MSb3-ENGL 379b 3032348 0503343 78b Approved As Standards InsaMe (ANSI) September 26,1996 ASSOCIATION FOR INFORMATION ANO IMAGE MANAGEMENT INTERNATIONAL 11 O0 Wayne Avenue Suite 11 O0 Silver Spring, Maryland 20910 AIIM 301-587-8202 COPYRIGHT Association for Information includes (but is not l
2、imited to) the active feature set, the version of the API definition supported, and the identification of the driver (name and level). This command includes the ability to retrieve and set both default and current scanner settings. A private field of undefined size is required to accommodate vendorl
3、application specific functionaiity. A querylset parameter pool-size is required so that the appiicatiodimage system can correctly aliocate memory. In addition, the API is required to query the valid values of a parameter. The values can either be a numeric range (low, high, step) or a list of values
4、. 4.13 Profile maintenance The imaging system will allow the user to set up profiles for scanners when establishing the system as well as during a scan process. When the user wants to specify parameter values for a scanner profile, the imaging system wiil notify the device driver, then open a dialog
5、 with the user, and return the results to the imaging system. When establishing the system for a scanning session, the user wiil select a pre-stored profile (owned by the imaging system) that specifies ail parameter values. During a scan operation there will always be a dialog between the imaging sy
6、stem and the user in which the user can request a change of parameter values that will trigger a request to the device driver to open a diaiog with the user. This is a defnition of the querylset functions associated with the scanner API. The data associated with these functions must be passed in a d
7、ata stream to ensure compatibility when the device driver and the API are at different levels. The new fields added in a subsequent level must be added at the end of the data stream; new values for an existing field must be resolved by the initial handshaking where the level of the driver is determi
8、ned. 43 optional functions The following optional functions can be features of the actual hardware, or features of the driver software that emulates the hardware. For example, compression can be a hardware feature or a software routine - the calling system does not know the difference. 4.2.1 Image e
9、nhancement functions 4.2.1.1 Brightness Adjust the scanner brightness control. 4.2.1.2 Contrast Adjust the scanner contrast control. 4.2.13 Dithering and halftone Group pixels in pre- defined units such that a wider tonal range can be simulated by a limited number of tones. Most commonly, this featu
10、re is used to simulate gray-scale when performing a bitonal (black and white) scan. 4.2.1.4 Gamma curve selection Select and download specific Gamma Curves used in image enhancement algorithms. 4.2.1.5 Gray-scale to bitonal thresholding Adjust the sensitivity setting of the scanner and control how a
11、 bitonal image is created from a gray-scale scan. 4.2.1.6 Speckle removal Remove random particles, speckles, and other noise from an image. 4.2.1.7 Background suppression Automatically detect, monitor, and remove background levels from image. 4.2.1.8 Sensitivity level Adjust sensitivity levels used
12、in automatic thresholding. 4.2.1.9 Text-photo mode Automatically detect and enhance image corrections for pages with text and photo content. 4.2.2 Image processing functions 433.1 Bar-de detection and reading Interpret the bar- code(s) on scanned page and retuni the information to the calling system
13、. 4.2.2.2 Border detection and page size determination Detect the border of a page that is smailer than the designated scan area and return an image that has the same size as the physical input page. 43.2.3 Compression Use algorithmic techniques to reduce the image file size. Examples of these techn
14、iques would be Group 3 for example, to correct for variance in form position due to feeder or placement inaccuracies. 4.2.2.9 Resolution Scan at various resolutions (pixels per unit). 4.2.2.10 scaling Adjust the physical size of the image to fit a bigger or smaller rectangular area. 4.2.2.11 Skew de
15、tection and correction Detect that a sheet has rotated during the feed process and the resulting page image data are skewed and (optional) correct the image for skew. 4.2.3 Scan functions 4.2.3.1 Duplex scanning Scan both sides of a sheet in one pass. 4.232 Streaming device control Enablddisable a s
16、treaming device (such as a tape Wnter, CD writer, etc.). 4.2.4 Scan inpu/output functions 4.2.4.1 Feeder control Control the scanner feed mechanism (e.g., feed a page from the input hopper through the scanner). 4.2.4.2 Format controls Control format of the image file produced from the scanning proce
17、ss. At a minimum this would include specification of byte-ordering and line- ordering. 4.2.43 Multiple-mode scan Scan bitonal and gray-scale in one scan pass. 4.2.4.4 Stacker selection and sorting Cause the sheet to move to a specific stacker on a scanner with multiple stackers. This could be caused
18、 by processing function such as counters, forms recognition, bar-code, and patch-code. 4.2.5 Miscellaneous functions 4.2.5.1 Endorsement (electronic and physical) Add an endorsement to the page and/or the page image. Although many devices do not directly support endorsement incrementation, some driv
19、ers implement this automatic increment feature. 43.53 Multiple buffering support Manage more than one data area used to receive the images from the scanner. The calling system owns any buffers it uses to transfer the image or coded data. 4.2.53 Operator display Send visuai messages to the operator o
20、n a scanners display device. 4.2.5.4 Operator signais Detect operator signais; for example, activation of a foot pedal or console key. 5 API syntactical structure The API syntax is a function call with a parameter list. All data storage areas are under control of the imaging system that is calling t
21、he device driver. This structure allows the API to be extensible to accommodate features, operations, and formats not yet in existence. By using this syntactical model, the API can grow in a straightforward and compatible way - implementation of new features by developers does not require a new vers
22、ion of this specification. All strings can be stored in system resources (regardless of the host operating system) allowing customization and harmonization with international standards and techniques without a need to modify source code. Furthermore, while the API does provide the valid parameter va
23、lues it does not assume that a particular set of values is legal in all circumstances. Figure 1 shows the block diagram of the system and where the functions represented by this API definition fit. 5 Association for Information and Image Management International STD*AIIM MSb2-ENGL 199b 2022348 05023
24、53 825 COPYRIGHT Association for Information two signed 32-bit quantities (Num. and Denom.) Used for unchecked tmeless variables SCANIRRT SCANHRV SCAN“ Image Registration/rotation/translation (structure shown in 6.1.7.4.1) I pscANIRRT PSCANHDRV PSCANHRUN Data structure which is a handle to a driver
25、Handle for operations (scanning, compression, etc.) SCA“ST SCANHMEM SCANHWM) IPSCANHWND 1 Handle toa window PSCA“ST PSCANHMEM Handle to an instance (usually a process or thread ID) A memorv handle (lock with ScanMemLock) SCANRC I PSCANRC3 I Function return Results Code (unsigned 32-bit integer) SCAN
26、DRVENTRY PSCANDRVENTRY Used to hide pascal and other platform dependent T I kevwords when defining a scanner driver entrv. SCANCALLBACK I PSCANCALLBACK I callback Function returning SCANRC result Table 1 - Data types SCANIMAGE is provided solely for the purpose of funire portability to define specia
27、l pointers (e.g., for thunking from a 32 bit flat pointer to a 16:16 segmented pointer, a concern not directly addressed by this API.) PSCANRC is provided for consistency and convenience to the application programmer that might need it for special reasons such as saving the result of a threaded acqu
28、isition in the allocated memory of the parent, this API does not require this type for any of its functions. ?SCANDRVENTRY is provided for consistency and convenience to the application programmer, this API does not require this type for any of its functions. 7 Association for information and Image
29、Management international STD-AIIM MSbL-ENGL L97b = LO32348 0501355 bT8 - COPYRIGHT Association for Information 3 #endif /* WIN environment logic */ Listing 1 - Environment logic example 5.4 Setting and getting API parameter values This section explains how to get and set parameter values. 9 Associat
30、ion for Information and Image Management International STDmAIIM MSbL-ENGL 377b = 30L2348 0503357 1.170 COPYRIGHT Association for Information SCANRATIO ratXRes ; SCANUCHAR pcDitherMAX-DTH - LENGTH; ScanParmGetLong( ScanParmGetRational( ScanParmGetString( Listing 2 - Parameter access example The 0 in
31、the rst two function calls specifies which element to retrieve from the parameter. All parameter values are signed. Some parameters may have more than one element (for example PARM-GRAYRESPONSECURVE). To find out how many elements a parameter has, the function ScanParmGetLength can be used: SCANUINT
32、32 dwlength; ScanParmGetLength( a pointer to the driver handle and the parameter number. If a parameter number of zero is used, ail values are set to their defaults. 5.43 Misceiianeous parameter functions ScanParmGetFlags can be used to remieve a 32-bit flag-word for a parameter. Currently, no bits
33、are dened. The function ScanParmGetType retrieves the data-type of a parameter. ScanParmSaveValue and ScanParmRestoreValue save and restore a single parameter or all parameters. The function ScanParmFluchValue should be used if ScanParmRestoreValue is not called. This frees the system resources that
34、 are being used to hold the saved values. 5.4.4 Getting parameter choice values An application can get a set of legal values for each parameter. This set can be represented either as a list or as a range. 10 Association for Information and Image Management International STD*AIIM MSbL-ENGL L97b 30323
35、LI8 0503358 307 COPYRIGHT Association for Information SCANUCHAR pcBufferLl281; /* params are always represented as lists */ ScanChoiceGetCount( for (j=O; ji; j+) CcanChoiceGetString( printf(“%d. %sn“, j, pcBuffer); 11 Association for Information and Image Management International STD.AIIM MSbL-ENGL
36、L99b 10123Li8 0501359 243 M COPYRIGHT Association for Information if (dwFlags SCAN-CHOICEHIGH, SCAN-CHOICE-STEP, LratValue3); /* give ratvaluel and ratValue3 a common denominator */ if (ratValue3.Denom != ratVa1uel.Denom) ratValuel.Num *= ratValue3.Denom; ratValuel.Denom *= ratValue3.Denom; ratValue
37、3.Num *= ratValuel.Denom; ratValue3.Denom *= ratValuel.Denom) ratValue2.Num * ratValuel.Denom) printf(“%ld / %ldn“, ratValuel.Num , ratVa1uel.Denom); ratValuel.Num += ratValue3.Num) while (ratValuel.Num * ratValue2.Denom = else /* if (dwFlags for (i=O; iwCount; i+) ScanChoiceGetRational( printf(“%ld
38、 / %ldn“, ratValuel.Num, ratValuel.Denom) 1 The following example displays all the X Resolution values that a driver supports. SCANUINT32 dwFlags; SCANUINT16 wCount; SCANRATIO ratvaluel, ratValue2, ratValue3; SCANUINT16 i; Listing 5 - Range processing example 5.4.5 Setting parameters An application
39、program can either set values using the choice values as a guide, or it can call the driver itself to set these parameters. The foilowing function displays a dialog-box with choices for the user. The exact format and extent of the dialog box depends on the scanner and the parameters it is able to se
40、t. Using this dialog box makes it possible to set features that are unique to a scanner. SCANHDRV hDr iver ; SCAN“D hWnd; SCANHINST hInst ; /* handle to driver */ /* handle to parent window */ /* instance of parent */ IScanDrvSetDialog( Listing 6 - Parameter setting example 12 Association for Inform
41、ation and Image Management International STD*AIIM MSbL-ENGL L77b = 1012348 05D13b0 Tb5 W COPYRIGHT Association for Information if (dwBits if (dwBits else printf(“The feeder is empty.“); 1 else printf(“Cannot tell if page is present.“); dwBi t s ; Listing 7 - Feeder detection example Scanning a page
42、involves a “RunZone“ loop such as in listing 8. The loop consists of three parts: ScanDrvRunStart, ScanDrvRunStep, and ScanDrvRunDone. Breaking the process into steps makes it possible for background scanning or reading to occur in multitasking environments. Note: This is one example of a way to sca
43、n. SCANRC MyScanRunZone(pDriver, ibBuffer, ulSize) PSCANHDRV pDriver: SCANBUF ibBuf f er: SCANULONG ulSize: E SCANDRVRUN hRun ; SCANRC rcStatus, rcStatus2 ; if (SCANRC-OK(rcStatus = ScanDrvRunStart(pDriver, rcstatus = ScanDrvRunStep(hRun, ibBuffer, ulSize, O); break; (SCANUINT32)rcStatus, ibBuffer):
44、 1 if (SCANRC-ERRID(rcStatus) = SCAN-ERR-ENDZONE) rcstatus = SCAN-SUCCESS; 3 rcStatus2 = ScanDrvRunDone(hRun); if (SCANRC-ISOK(rcStatus) ) rcstatus = rcStatus2 ; return rcstatus; 1 Listing 8 - Scanning example 13 Association for Information and Image Management International STD-AIIM MSbL-ENGL 377b
45、m LL23q 0503363 9T3 m - COPYRIGHT Association for Information ScanDrvGetString( printf (“Version: %sn“ I aucBuf) ; ScanDrvGetString( printf(“Name: %sn“ , aucBuf) ; ScanDrvGetString( Drintf“Vendor: %sn“ , aucBuf) : Listing 9 - Scanner information example This program fragment produces a display simii
46、ar to the following: Version: Version 1.39 Name: “Manufacturer“ “Series“ / “Model“ Vendor: Copyright O 1992 “Company Name“ Listing 10 - Get string results 5.7 Error handihg 5.7.1 Result code overview Unless otherwise specified, ail functions or macros return a signed 32-bit integer result code value
47、. The SCANRC-* macros (see 5.3.2) are provided to help checking and manipulating these result codes. If this number is negative, an error has occurred. Either zero or a positive value indicates success. Functions are provided to retrieve the name of the driver that caused the error, and a string des
48、cribing the error. It is strongly recommended that applications implement error-handling functions. Example results codes for error conditions are given in Annex A (Informative) Example Error Codes. A sample error-handiing function for Microsoft Windowsm environment is shown below. Simply displaying
49、 a generic “Scanner Error“ makes it very difficult for end-users and technical support staff to determine the problem. It is recommended that error checking be implemented at the beginning of application development to aid in debugging as well as providing important information to users. 14 Association for Information and image Management International STD*AIIM MSbL-ENGL 199b LOL23iB 050L3b2 838 w COPYRIGHT Association for Information i f ( SCANRC-ISOK (rcstatus ) ) if (!pDriver rcStatus = SCANRC-MAKERC(SCANRC_ERRID(rcCtatus) 1; c /* custom erro
