dbarscan-sl Components for Windows Phone

Transcription

1 dlsoft dbarscan-sl Components for Windows Phone By dlsoft

2

3 This manual was produced using ComponentOne Doc-To-Help.

4

5 Contents Introduction... 1 dbarscan.sl 1D... 1 Using dbarscan.sl Components in Visual Studio Setting and retrieving property values programmatically... 2 Decoding a barcode image... 3 Licensing the component D decoding Reference... 4 Methods... 4 Properties... 5 Index 13 dlsoft dbarscan-sl Components for Windows Phone Contents v

6

7 Introduction dbarscan.sl Components are components that allows barcode images to be decoded within the developer s own Windows Phone application. dbarscan accepts graphic images, typically from the phone s camera, scans an area of the image for a barcode, and decodes the barcode into its textual data. TestWare versions randomly scramble the decoded data. Developer versions require the developer s serial number to be passed to the component using the Serial property. Incorrectly licensed version will behave as TestWare and produce randomly scrambled decoding data. dbarscan.sl Components are designed to work with Visual Studio 2010 or later and require the Windows Phone SDK to be installed on any PC using the components during development. Example code is provided with the component for use with C#. The sample can be deployed to a developer unlocked Windows Phone or to the emulator although the Windows Phone emulator is not able to emulate a camera. The sample project was created in Visual Studio 2010 to target Windows Phone OS 7.1, but may be loaded into Visual Studio 2012 and the target changed to Windows Phone OS 8.0 dbarscan.sl 1D The dbarscan.sl 1D Component can identify and decode the following barcode types: Type Code Value Code 39 C39 0 Extended Code 39 E39 1 Standard 2 of 5 TOF 2 Interleaved 2 of 5 ITF 3 Codabar CDA 4 ITF-14 ITF14 5 Code 93 C93 6 Extended Code 93 E93 7 Code 128 C28 8 GS1/EAN/UCC 128 E28 9 EAN/UCC 14 E ,2 EAN-13/JAN-13 E EAN-8 EA UPC-E UPE 13 1 UPC-A UPA 14 IATA 2 of 5 IAT 15 Notes: 1. including 2 and 5 digit supplementaries 2. including ISBN, ISSN, ISMN dlsoft dbarscan-sl Components for Windows Phone Index 1

8 It is important to note that, as with a normal barcode scanner, it is not a good idea to enable every type and hope the scanner will decode the image correctly. Some barcode types are very easily mistaken for others, particularly if the image is imperfect. The ideal would probably be to know exactly what barcode type is being scanned and enable dbarscan for just that type. However, even this has disadvantages for example Interleaved 2 of 5 is notorious for resulting in short scans where only part of the barcode data is returned. Similarly a partial scan of several barcode types can be mistaken for a UPC-E code. The dbarscan scan() methods each return one of the following values: -1 = a barcode detected and decoded, but not confirmed by finding the stop bars -2= a barcode detected and decode and the stop bars confirmed any other value represents an error code (see reference section) Our advice is to enable only those barcode types you expect to be scanning, and to check the value returned from one of the scan() methods. Using dbarscan.sl Components in Visual Studio 2010 The package in which the dbarscan SL component is provided for developers includes a Windows Phone 7.1 sample application developed using Visual Studio 2010 and the Windows Phone SDK 7.1. (The sample application will not compile with the 7.0 SDK) If the sample application is built in release mode it can only be tested on a developer unlocked Windows Phone because the emulator does not have a real camera. However, it can be built in debug mode, in which case pushing the Scan button causes a sample picture to be loaded in place of a camera image. Adding a dbarscan.sl component to a project. Copy the component DLL (eg. DLSCAN7.DLL) to the directory containing the source files for the project. In the Solution Explorer window expand the project name and select the References item. Right-click on References and choose Add Reference. Select the Browse tab in the Add Reference dialog, the select the component DLL from the list of files. In the relevant code of your project (which can be the application App.xaml.cs, or a specific page, such as Page1.xaml.cs) create a variable of the class, eg. DLSCAN7.DLSCAN BarScan1=new DLSCAN7.DLSCAN(); Setting and retrieving property values programmatically The dbarscan.sl Components may be operated entirely by setting or retrieving Property values programmatically. Some properties must be set before a scan is attempted, eg. BarScan1.TypeMask = TypeMask; BarScan1.dImage = bmp; While other aill be returned after a scan has been initiated, eg. 2 Index dlsoft dbarscan-sl Components for Windows Phone

9 Output = BarScan1.oData; Report = BarScan1.report; Decoding a barcode image dbarscan provides a single method for decoding a barcode image. The scan() method attempts to decode the image by starting at the centre of the image and searching for a barcode. The method assumes that the image is in landscape orientation (most 1D barcodes are wider than they are tall, and in any case it is the width of the bars that is important rather than their height). A simple example of the code required to decode an image from a bitmap image using the scan() method is: BarScan1.TypeMask = TypeMask; BarScan1.dImage = bmp; Int err = Barscan1.scan(); if (err<0) { Output=Barscan1.oData(); // returns the barcode data Status = BarScan1.Status; } else { Ouput = ; Status = Scan failed ; } Licensing the component dbarscan.sl components will behave as Testware versions (returning scrambled barcode scans) unless correctly licensed. Developer versions require the developer s serial number to be passed to the component using the Serial property before the scan() method is called. The Serial property should be set to the serial number provided for your component, e.g. Barscan1.Serial="12345" for VB Barscan1.Serial="12345"; for C# If your own application supports tombstoning it is important to ensure that the Serial property is set at a point in your code after an instance of the DLSCAN class has been created. dlsoft dbarscan-sl Components for Windows Phone Index 3

10 1D decoding Reference Methods Scan() Return type: int Declaration: public int scan() Parameters: none This method scans the entire width of the image, starting to the centre of the image and scanning a height equivalent to the aperture ( or 4 scan lines if the aperture is 0). Returns -1 if a barcode has been identified and decoded; returns -2 if a decode is known to be complete (i.e the stop bars have been identified). Otherwise returns an error value (see ErrorCode). TargetType() Return type: string Declaration: public string TargetType(int itype) Parameters: int itype the barcode code type value whose name is required. Returns the string form of a barcode type name (e.g. Code 39) corresponding the the code type value itype. For a list of the barcode types supported see ocode. If itype has a value that is not supported the method returns an empty string. The number of available types is found in the ntargettypes property (currently 14). Fncval() Return type: void Declaration: public void Fncval(int icode, char charval) Parameteres: int icode the position in the FNC128 string of Code128/GS1-128 Special Characters which appear in these barcodes. Char charval the actual character that you wish to appear in the output string in place of the default character. Note that the entire range of the 12 special characters may be seen and modified using the FNC128 property (see below). It is usual for the special characters to be chosen so that they canot be mistaken for normal barcode data characters, so the default values used and shown in the table below are not characters encountered on US/English keyboards. The default Code 128 special characters are shown in the following table. These characters may be provided to the Fncval() method as Chr(XYZ) (in VB) or entered on a PC keyboard as <ALT>0XYZ, where XYZ is the correspopnding 3 digit ASCII code: XYZ character Code A Code B Code C 197 Å DEL 198 Æ func. 3 func Ç func. 2 func È shift shift 4 Index dlsoft dbarscan-sl Components for Windows Phone

11 201 É code C code C 202 Ê code B func. 4 code B 203 Ë func. 4 code A code A 204 Ì func. 1 func. 1 func Í Start A Start A Start A 206 Î Start B Start B Start B 207 Ï Start C Start C Start C 208 Ð NUL Examples: VB Barscan1.Fncval(7, Chr(204)) C# Barscan1.Fncval(7, Ì); Sets the character used for the fnc1 character to Ì. Properties aperture type: int default: 1. Minimum value 1. The number of pixels across the image combined when searching for bars and spaces. The default value is suitable for scanning using the VideoBrush. High resolution images obtained from CaptureImageAvailable() would be more rapidly decoded with a larger value, eg 2 4. bcheckcheck type: bool default: true When true bcheckcheck causes dbarscan to check the check digit(s) for all EAN/UPC/UCC, Code 39 and Code 93 barcodes, the result being returned through the bchecked property. bchecked type: bool, read-only If bcheckcheck is true the barcode check digit calculations are check for decoded barcodes of EAN/UPC/UCC, Code 39 and Code 93 types. If the calculated value matches that included in the barcode bchecked is true. If the calculated value does not match the included value bchecked is false. In either case the calculated and found values are available in ichkc1 and ichka1. For Code 93 barcodes the second check digits are in ichkc2 and ichka2. dlsoft dbarscan-sl Components for Windows Phone Index 5

12 blandscape type bool default: true To obtain the best results images will normally be obtained so that the width of the barcode uses maximum number of image pixels. For a Windows Phone the available image size is typically 640 x 480 or larger, so the barcode is best captured in landscape mode as shown below. Landscape image When blandscape is true the image is scanned across the image as illustrated by the red line. If blandscape is false it is assumed that the image has been captured in portrait mode, so the image is scanned as shown below. Portrait image dcontrol1 type: int default: 0; A control flag for modifying the output from specific barcode types. At the present time this flag effects only Coadbar barcodes. A value of 0 permits the start and stop character to be included in the odata output. A value of 1 removes the start and stop characters. 6 Index dlsoft dbarscan-sl Components for Windows Phone

13 dcontrol2 type: int default: 0; A control flag for modifying the output from specific barcode types. At the present time this flag affects only EAN and UPC barcodes. A value of 1 permits the detection of 2 or 5 digit supplementaries; a value of 0 means that any supplementaries present in the barcode a not scanned or decoded. This flag is applied to the following barcodes: EAN-8 EAN-13/JAN-13 UPC-A UPC-E dimage type: WriteableBitmap default: none The dimage property contains the WriteableBitmap to be decoded. The image may be obtained from a resource (e.g. using Uri jpeguri = new Uri("pic1.jpg",UriKind.Relative); BitmapImage bb = new BitmapImage(jpegUri); WriteableBitmap bmp = new WriteableBitmap(bb); bc.dimage = bmp; Or from the phone s camera using code of the form void OnCameraCaptureTaskCompleted(object sender, PhotoResult args) { if (args.taskresult == TaskResult.OK) { BitmapImage bb = new BitmapImage(); bb.setsource(args.chosenphoto); WriteableBitmap bmp = new WriteableBitmap(bb.PixelWidth, bb.pixelheight); bmp.setsource(args.chosenphoto); scanit(); } } ErrorCode Type: int, read only After one of the scan() methods is used, the ErrorCode property may contain one of the following: ErrorCode meaning 0 no barcode detected 1 invalid region of image specified 3 error opening bitmap 8 incomplete decoding dlsoft dbarscan-sl Components for Windows Phone Index 7

14 9 reverse orientation FNC128 type: string (of 12 characters) default: ÅÆÇÈÉÊËÌÍÎÏÐ Code 128 and EAN/UCC 128 barcodes include in their character sets 12 special characters which are used for a variety of purposes but not generally required in any human readable form. dbarscan can report these characters using the character substitutions specified by the FNC128 string, so the developer may set these characters to any convenient values that do not conflict with the barcode data. The default Code 128 special characters are shown in the following table. These characters may be provided to the Fncval() method as Chr(XYZ) (in VB) or entered on a PC keyboard as <ALT>0XYZ, where XYZ is the correspopnding 3 digit ASCII code: XYZ character Code A Code B Code C 197 Å DEL 198 Æ func. 3 func Ç func. 2 func È shift shift 201 É code C code C 202 Ê code B func. 4 code B 203 Ë func. 4 code A code A 204 Ì func. 1 func. 1 func Í Start A Start A Start A 206 Î Start B Start B Start B 207 Ï Start C Start C Start C 208 Ð NUL ichk values Four integer values representing the calculated and found values of check digits. These values are filled only if the bcheckcheck property is true and only for EAN/UPC/UCC, Code 39 and Code 93 barcodes. ichkc1 calculated first check digit ichka1 found value of first check digit. For Code 93 and Extended 93 barcodes a second check digit is used: ichkc2 calculated second check digit ichka2 found value of second check digit. nspread type: int default value = 0 8 Index dlsoft dbarscan-sl Components for Windows Phone

15 allowed values 0,1,2 If nspread is 0 the image is scanned across the center of the image, ie. At a position which is half the height of the image.. If nspread is 1 the image is scanned across the center of the image, and, if this scan does not decode a barcode, the image is scanned again at a height of 3/8 and (if that fails) again at 5/8. If nspread is greater than 1 then the action for nspread =1 is performed and, if that fails, the image is scanned again at positions of + and - n/64 from the center of the height of the image, where n ranges from 0 to nspread. odata type: string; read only odata is a string that contains the decoded data after a successful return from one of the scan() methods. The string content is valid only if the scan() methods return a value <0. ocode type: int; read only ocode is an integer representing the type of barcode identified and decoded after a successful return from one of the scan() methods. The value is valid only if the scan() methods return a value <0. The code values are shown in the table below. A string representation of the barcode type may be obtained by using the method TypeName(i). Type Code Value Code 39 C39 0 Extended Code 39 E39 1 Standard 2 of 5 TOF 2 Interleaved 2 of 5 ITF 3 Codabar CDA 4 MSI/Plessey MSI 5 Code 93 C93 6 Extended Code 93 E93 7 Code 128 C28 8 EAN/UCC 128 E28 9 EAN/UCC 14 E ,2 EAN-13/JAN-13 E EAN-8 EA UPC-E UPE 13 1 UPC-A UPA 14 Notes: 1. including 2 and 5 digit supplementaries when dcontrol2 is true 2. including ISBN, ISSN, ISMN dlsoft dbarscan-sl Components for Windows Phone Index 9

16 Nbars Type: int; read only After a successful return from one of the scan() methods, Nbars contains the number of barcode elements identified (bars and spaces), couting from the first bar to the last bar inclusive. ntargettypes type: int; read only The number of barcode types that can be identified and decoded by dbarscan 1D. Currently 14. See ocode for a list of the types supported. Report type: string; read only The Report string provides a brief analysis of a decode, including (where relevant) the barcode type detected, details of any check digit and subtype changes (as in subtypes A, B and C in Code 128 and GS1-128 symbols) present in the barcode, the mean bar and space element widths (in pixels), the Gain and the mean and maximum deviations of bar and space widths from the expected values. Status type: string; read only After a call to one of the scan() methods the Status string contains one of the following messages (where type indicates the type of barcode identified): Scan() return Status contains -2 Found (type) complete scan -1 Found (type) INCOMPLETE scan 0 failed TypeMask Type: int Default: 7945 ( x1F09) A bitwise mask where each bit represents one of the barcode types that dbarscan can attempt to identify and decode. When a bit is a 1 the corresponding barcode type is included in the scan. If the bit is a 0 the barcode type is not included The value of TypeMask may be derived by ORing together the hexadecimal codes of the barcode types required. Type Bit number hexadecimal Code Index dlsoft dbarscan-sl Components for Windows Phone

17 Extended Code Standard 2 of Interleaved 2 of Codabar 4 0x0010 MSI/Plessey 5 0x0020 Code x0040 Extended Code x0080 Code x0100 EAN/UCC x0200 EAN/UCC x0400 1,2 EAN-13/JAN x EAN x UPC-E 13 0x UPC-A 14 0x4000 Notes: 1. including 2 and 5 digit supplementaries when dcontrol2 is true 2. including ISBN, ISSN, ISMN dlsoft dbarscan-sl Components for Windows Phone Index 11

18

19 M Methods 4 Index N Nbars 10 nspread 8 ntargettypes 10 O ocode 9 odata 9 1 1D decoding Reference 4 A Adding a dbarscan.sl component to a project. 2 aperture 5 B bcheckcheck 5 bchecked 5 blandscape 6 D dbarscan.sl 1D 1 dcontrol1 6 dcontrol2 7 Decoding a barcode image 3 dimage 7 E ErrorCode 7 P Properties 5 R Report 10 S Scan() 4 Setting and retrieving property values programmatically 2 Status 10 T TargetType() 4 TypeMask 10 U Using dbarscan.sl Components in Visual Studio F FNC128 8 Fncval() 4 I ichk values 8 Introduction 1 L Licensing the component 3 dlsoft dbarscan-sl Components for Windows Phone Index 13