SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS Introduction
The SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS is a developer kit for iOS platform powered devices such as iPhone, iPod and iPad. This document and sample applications are provided to help you to integrate high performance barcode recognition functionality into your iOS Object C or Object C++ application for mobile device.
1 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS Overview
Two classes are provided to access barcode recognition functionality: SDTBarcodeEngine and SDTBarcodeScannerViewController .
The major class to access barcode recognition functionality is SDTBarcodeEngine . To create instance of this class you have to call initWithLicense method passing a valid developer license as a parameter.
Once barcode engine has been initiated call readImage: method to read barcode symbols from image. The results are cached internally by SDTBarcodeEngine and can be read by getResultValueAtPos method. See below a SDTBarcodeEngine usage sample. A complete code you can find in sdt-brc-ios-sample2 sample application included into SD-TOOLKIT Barcode SDK for iOS.
SDTBarcodeEngine* barcodeEngine = [[SDTBarcodeEngine alloc] initWithLicense:@"YOUR DEVELOPER LICENSE"]; //Obtain UIImage from UIImageView control of the current UIViewController UIImage* image = imageView.image;
if (barcodeEngine != nil && image != nil) { // Specify barcode types you are interested in [barcodeEngine setReadInputTypes:SDTBARCODETYPE_ALL_1D];
int readResult = [barcodeEngine readImage: [image CGImage]]; if(readResult == 0) { //Obtain number or successfully recognized barcodes int resultCount = [barcodeEngine getResultsCount]; if(resultCount > 0) { //Alloc mutable string to store the barcode value NSMutableString* resultValue = [[NSMutableString alloc] init]; //Get first available result at position 0 [barcodeEngine getResultValueAtPos:0 storeIn:resultValue]; //Show text in UITextView control textView.text = resultValue; //Release unnecessary variables if(resultValue != nil) { [resultValue release]; } } } //Release object when done [barcodeEngine release]; }
The SDTBarcodeScannerViewController class starts Camera preview and scan barcodes on it. Once barcode has been recognized, the delegate’s SDTBarcodeScannerViewControllerDelegate callback
2 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS method onRecognitionComplete: will be called providing reference to SDTBarcodeEngine instance. Use the SDTBarcodeEngine instance to obtain information about recognized barcode and it’s properties. In the example below textView and imageView are instances of UITextView and UIImageView . For complete sample sourcecode see sdt-brc-ios-sample3 project included into the sdk.
// protocol SDTBarcodeScannerViewControllerDelegate implementation - (BOOL )onRecognitionComplete:( SDTBarcodeEngine *)theEngine onImage:( CGImageRef )theImage orientation:( UIImageOrientation )theOrientation {
if (theEngine != nil ) { int resultCount = [theEngine getResultsCount ]; if (resultCount > 0) { NSMutableString * resultValue = [[ NSMutableString alloc ] init ];
[theEngine getResultValueAtPos :0 storeIn :resultValue];
textView .text = resultValue;
if (resultValue != nil ) { [resultValue release ]; } }
}
if (theImage != nil ) { imageView .image = [[ UIImage alloc ] initWithCGImage : theImage scale : 1.0 orientation : theOrientation]; }
//Returning YES will close scanner dialog return YES ; }
3 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS SDTBarcodeEngine Class Reference
Inherits from NSObjec t
Conforms to NSObject(NSObject)
Library sdt -brc -ios2.a
Declared in SDTBarcodeEngine .h
Related sample code sdt -brc -sample2
Overview The major class to access barcode recognition functionality.
The SDTBarcodeEngine class is intended to be used as-is and does not support subclassing. The view hierarchy for this class is private and must not be modified.
Instance Methods initWithLicense:
Initialize the Barcode reader instance.
-(id)initWithLicense:(NSString*)license
Parameters license The purchased Individual Developer or Team Developer license. For purchase details visit http://www.sd-toolkit.com/order.php
Return Value Newelly initialized Barcode reader.
Availability Available in iOS 4.0 and later.
4 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
Declared In SDTBarcodeEngine.h
setUpgradeLicense:
Specify optional upgrade license key which extends access no new SDK versions period for current Developer License Key
-(void)setUpgradeLicense:(NSString*)license
Parameters license The purchased Upgrade license. Note that upgrade license is used as an extension of Developer License and cannot be used without it.
Discussion The purchased Developer License allow access to all new SDK versions released within next 12 months starting from purchase date. After that period of time it is possible to extend such period for 12 months more by purchasing Upgrade License.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
setReadInputDirections:
The method specifies barcode reading directions the Barcode Reader scans input image in next call to readImage method.
-(void)setReadInputDirections:(int)flags;
Parameters flags Specifies barcode reading directions. This parameter can be one or combination of the following values.
Value Integer Value Description
5 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
Left-to-right direction. Used when input image contains SDTREADDIRECTION_LTR 0x00000001 normally oriented barcodes. Right-to-left direction. Used when input image contains SDTREADDIRECTION_RTL 0x00000002 barcodes rotated to 180 degrees. Top-to-bottom direction. Used when input image contains SDTREADDIRECTION_TTB 0x00000004 barcodes rotated to 90 degrees clockwise. Top-to-bottom direction. Used when input image contains SDTREADDIRECTION_BTT 0x00000008 barcodes rotated to 90 degrees counter-clockwise. SDTREADDIRECTION_ALL 0x0000000f All above direction.
Discussion In order to achieve better performance it is recommended to set only expected directions.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
setReadInputTypes:
The method specifies barcode types the Barcode Reader will look for in next call to readImage method.
-(void) setReadInputTypes:(int)flags
Parameters flags Specifies barcode types. This parameter can be one or combination of the following values.
Value Integer Value Description SDTBARCODETYPE_CODABAR 0x00000001 Codabar barcode SDTBARCODETYPE_CODE128 0x00000002 Code 128 barcode Code 32 (also known as Base 32, Pharma 32/39, and SDTBARCODETYPE_CODE32 0x00000004 Italian Pharmacode) SDTBARCODETYPE_CODE39 0x00000008 Code 39 barcode
6 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
SDTBARCODETYPE_CODE93 0x00000010 Code 93 barcode SDTBARCODETYPE_CODE11 0x00000020 Code 11 barcode SDTBARCODETYPE_EAN13 0x00000040 EAN13 barcode SDTBARCODETYPE_EAN8 0x00000080 EAN8 barcode SDTBARCODETYPE_EAN5 0x00000100 EAN5 barcode SDTBARCODETYPE_I2OF5 0x00000200 Interleaved 2 of 5 barcode SDTBARCODETYPE_PATCH_CODE 0x00000400 Patch code barcode SDTBARCODETYPE_POSTNET 0x00000800 Postnet barcode SDTBARCODETYPE_PLUS2 0x00001000 Plus2 (2 -digit supplementals assoc. with EAN and UPC) SDTBARCODETYPE_PLUS5 0x00002000 Plus5 (5 -digit supplementals assoc. with EAN and UPC) SDTBARCODETYPE_UPCA 0x00004000 UPC -A barcode SDTBARCODETYPE_UPCB 0x00008000 UPC -B barcode SDTBARCODETYPE_INTELLIMAIL 0x00010000 Intelligent Mail barcode All above 1-D Barcodes currently supported by SD- SDTBARCODETYPE_ALL_1D 0x0001ffff TOOLKIT Barcode Reader SDTBARCODETYPE_DATAMATRIX 0x00020000 DataMatrix 2D Barcode SDTBARCODETYPE_PDF417 0x00040000 PDF417 2D Barcode SDTBARCODETYPE_QRCODE 0x00080000 QR Code 2D Barcode All above 2-D Barcodes currently supported by SD- SDTBARCODETYPE_ALL_2D 0x000e0000 TOOLKIT Barcode Reader
Discussion In order to achieve better performance it is recommended to minimize the set of barcode types by specifying only types the final application is interested in..
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
setActiveScanRectangleLeft:andTop:andRight:andBottom:
7 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
The method defines a square area within the image where the reader will look for barcodes in next call to readImage method.
-(void)setActiveScanRectangleLeft:(int)left andTop:(int)top andRight:(int)right andBottom:(int)bottom
Parameters left [in] positive integer value specified left boundary of the scan area. top [in] positive integer value specified top boundary of the scan area. right [in] positive integer value specified right boundary of the scan area. bottom [in] positive integer value specified bottom boundary of the scan area.
Discussion If one of the boundary values passed to the function exceeds input image size then image boundary will be used instead.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
readImage:
The method reads the image object image data and recognize barcodes on it. The recognition results values are stored internally and can be obtained later by call to getResultValueAtPos method.
-(int)readImage:(CGImageRef)image
Parameters image the input image object
Return Value If method succeeds, the return value is zero. If method fails, the return value is nonzero and contain extended error information.
8 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
getResultsCount:
The method returns count of successfully recognized barcodes in the previous call readImage method.
-(int)getResultsCount
Return Value Returns count of recognized barcodes or 0 in case no barcodes were detected.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
getResultValueAtPos:storeIn:
The method fill in a mutable string with value of the barcode symbol successfully recognized in the previous call to readImage method.
-(void)getResultValueAtPos:(int)position storeIn:(NSMutableString*)outString
Parameters position index of recognized barcode result. The count of available barcode results is obtained by call to getResultsCount method outString pointer to allocated Mutable String instance which will be filled in with value of barcode symbol
Availability Available in iOS 4.0 and later.
9 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
Declared In SDTBarcodeEngine.h
getResultTypeAtPos:
The method returns integer value of barcode type successfully recognized in the previous call readImage method.
-(void) getResultTypeAtPos:(int)position
Parameters position index of recognized barcode result. The count of available barcode results is obtained by call to getResultsCount method
Return Value Method returns one of the following possible barcode type flags: Value Integer Value Description SDTBARCODETYPE_CODABAR 0x00000001 Codabar barcode SDTBARCODETYPE_CODE128 0x00000002 Code 128 barcode Code 32 (also known as Base 32, Pharma 32/39, and SDTBARCODETYPE_CODE32 0x00000004 Italian Pharmacode) SDTBARCODETYPE_CODE39 0x00000008 Code 39 barcode SDTBARCODETYPE_CODE93 0x00000010 Code 93 barcode SDTBARCODETYPE_CODE11 0x00000020 Code 11 barcode SDTBARCODETYPE_EAN13 0x00000040 EAN13 barcode SDTBARCODETYPE_EAN8 0x00000080 EAN8 barcode SDTBARCODETYPE_EAN5 0x00000100 EAN5 barcode SDTBARCODETYPE_I2OF5 0x00000200 Interleaved 2 of 5 barcode SDTBARCODETYPE_PATCH_CODE 0x00000400 Patch code barcode SDTBARCODETYPE_POSTNET 0x00000800 Postnet barcode SDTBARCODETYPE_PLUS2 0x00001000 Plus2 (2 -digit supplementals assoc. with EAN and UPC) SDTBARCODETYPE_PLUS5 0x00002000 Plus5 (5-digit supplementals assoc. with EAN and UPC) SDTBARCODETYPE_UPCA 0x00004000 UPC -A barcode
10 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
SDTBARCODETYPE_UPCB 0x00008000 UPC -B barcode SDTBARCODETYPE_INTELLIMAIL 0x00010000 Intelligent Mail barcode SDTBARCODETYPE_DATAMATRIX 0x00020000 DataMatrix 2D Barcode SDTBARCODETYPE_PDF417 0x00040000 PDF417 2D Barcode SDTBARCODETYPE_QRCODE 0x00080000 QR Code 2D Barcode
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
getResultTypeNameAtPos:storeIn:
The method returns name of barcode type successfully recognized in the previous call to readImage method.
-(void)getResultTypeNameAtPos:(int)position storeIn:(NSMutableString*)outString
Parameters position index of recognized barcode result. The count of available barcode results is obtained by call to getResultsCount method outString pointer to allocated Mutable String instance which will be filled in with value of barcode type name
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
getResultDirectionAtPos:
The method returns integer value of read direction of the barcode successfully recognized in the previous call readImage method.
-(int)getResultDirectionAtPos:(int)position
11 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
Parameters position index of recognized barcode result. The count of available barcode results is obtained by call to getResultsCount method
Return Value Method returns one of the following possible barcode read direction flags: Value Integer Value Description Left-to-right direction. Used when input image contains SDTREADDIRECTION_LTR 0x00000001 normally oriented barcodes. Right-to-left direction. Used when input image contains SDTREADDIRECTION_RTL 0x00000002 barcodes rotated to 180 degrees. Top-to-bottom direction. Used when input image contains SDTREADDIRECTION_TTB 0x00000004 barcodes rotated to 90 degrees clockwise. Top-to-bottom direction. Used when input image contains SDTREADDIRECTION_BTT 0x00000008 barcodes rotated to 90 degrees counter -clockwise. SDTREADDIRECTION_ALL 0x0000000f All above direction.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
getResultPositionLeftAtPos:
The method returns left boundary of the barcode which was successfully recognized in the previous call readImage method.
-(int)getResultPositionLeftAtPos:(int)position
Parameters position index of recognized barcode result. The count of available barcode results is obtained by call to getResultsCount method
Return Value Method returns position in pixels relative to the left top corner of the image.
12 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
getResultPositionTopAtPos:
The method returns top boundary of the barcode which was successfully recognized in the previous call readImage method.
-(int)getResultPositionTopAtPos:(int)position
Parameters position index of recognized barcode result. The count of available barcode results is obtained by call to getResultsCount method
Return Value Method returns position in pixels relative to the left top corner of the image.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
getResultPositionRightAtPos:
The method returns right boundary of the barcode which was successfully recognized in the previous call readImage method.
-(int)getResultPositionRightAtPos:(int)position
Parameters position index of recognized barcode result. The count of available barcode results is obtained by call to getResultsCount method
Return Value Method returns position in pixels relative to the left top corner of the image.
13 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
getResultPositionBottomAtPos:
The method returns bottom boundary of the barcode which was successfully recognized in the previous call readImage method.
-(int)getResultPositionBottomAtPos:(int)position
Parameters position index of recognized barcode result. The count of available barcode results is obtained by call to getResultsCount method
Return Value Method returns position in pixels relative to the left top corner of the image.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeEngine.h
14 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS SDTBarcodeScannerViewController Class Reference
Inherits from UIViewController
Conforms to UIViewController (UIViewController )
Library sdt -brc -ios2.a
Declared in SDTBarcode ScannerViewController .h
Related sample code sdt -brc -sample 3
Overview The SDTBarcodeScannerViewController shows modal camera preview dialog and scans barcode symbols directly from iPhone/iPad device camera. The SDTBarcodeScannerViewControllerDelegate protocol is used for callback notification about each recognized barcode symbol.
The SDTBarcodeScannerViewController class is intended to be used as-is and does not support subclassing. The view hierarchy for this class is private and must not be modified.
Instance Methods initWithLicense:
Initialize the SDTBarcodeScannerViewController instance and provide SDTBarcodeScannerViewControllerDelegate protocol implementation instance to receive notifications.
-(id)initWithLicense:(NSString*)license callbackDelegate: (id
Parameters license
15 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
The purchased Individual Developer or Team Developer license. For purchase details visit http://www.sd-toolkit.com/order.php theDelegate The implementation instance of SDTBarcodeScannerViewControllerDelegate protocol which method onRecognitionComplete: will be called to notify about recognized barcode symbol
Return Value Newelly initialized SDTBarcodeScannerViewController instance.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeScannerViewController.h
initWithLicenseEx:
Initialize the SDTBarcodeScannerViewController instance and provide SDTBarcodeScannerViewControllerDelegate protocol implementation instance to receive notifications.
-(id)initWithLicenseEx:(NSString*)license callbackDelegate: (id
Parameters license The purchased Individual Developer or Team Developer license. For purchase details visit http://www.sd-toolkit.com/order.php theDelegate The implementation instance of SDTBarcodeScannerViewControllerDelegate protocol which method onRecognitionComplete: will be called to notify about recognized barcode symbol customOverlay The optional UIView object which will be shown on top of camera preview useFrontCamera The boolean flag indicating that front camera will be used to scan barcodes enableAutofocus
16 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
The boolean flag indicating that camera will operate in continuous autofocus mode enableFlash The boolean flag indicating that camera will use camera flash light
Return Value Newelly initialized SDTBarcodeScannerViewController instance.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeScannerViewController.h
setReadInputTypes:
The method specifies barcode types the Barcode scanner will look for on camera video stream.
-(void) setReadInputTypes:(int)flags
Parameters flags Specifies barcode types. This parameter can be one or combination of the following values.
Value Integer Value Description SDTBARCODETYPE_CODABAR 0x00000001 Codabar barcode SDTBARCODETYPE_CODE128 0x00000002 Code 128 barcode Code 32 (also known as Base 32, Pharma 32/39, and SDTBARCODETYPE_CODE32 0x00000004 Italian Pharmacode) SDTBARCODETYPE_CODE39 0x00000008 Code 39 barcode SDTBARCODETYPE_CODE93 0x00000010 Code 93 barcode SDTBARCODETYPE_CODE11 0x00000020 Code 11 barcode SDTBARCODETYPE_EAN13 0x00000040 EAN13 barcode SDTBARCODETYPE_EAN8 0x00000080 EAN8 barcode SDTBARCODETYPE_EAN5 0x00000100 EAN5 barcode SDTBARCODETYPE_I2OF5 0x00000200 Interleaved 2 of 5 barcode SDTBARCODETYPE_PATCH_CODE 0x00000400 Patch code barcode SDTBARCODETYPE_POSTNET 0x00000800 Postnet barcode
17 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
SDTBARCODETYPE_PLUS2 0x00001000 Plus2 (2 -digit supplementals assoc. with EAN and UPC) SDTBARCODETYPE_PLUS5 0x00002000 Plus5 (5-digit supplementals assoc. with EAN and UPC) SDTBARCODETYPE_UPCA 0x00004000 UPC -A barcode SDTBARCODETYPE_UPCB 0x00008000 UPC-B barcode SDTBARCODETYPE_INTELLIMAIL 0x00010000 Intelligent Mail barcode All above 1-D Barcodes currently supported by SD- SDTBARCODETYPE_ALL_1D 0x0001ffff TOOLKIT Barcode Reader SDTBARCODETYPE_DATAMATRIX 0x00020000 DataMatrix 2D Barcode SDTBARCODETYPE_PDF417 0x00040000 PDF417 2D Barcode SDTBARCODETYPE_QRCODE 0x00080000 QR Code 2D Barcode All above 2-D Barcodes currently supported by SD- SDTBARCODETYPE_ALL_2D 0x000e0000 TOOLKIT Barcode Reader
Discussion In order to achieve better performance it is recommended to minimize the set of barcode types by specifying only types the final application is interested in..
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeScannerViewController.h
setUpgradeLicense:
Specify optional upgrade license key which extends access no new SDK versions period for current Developer License Key
-(void)setUpgradeLicense:(NSString*)license
Parameters license The purchased Upgrade license. Note that upgrade license is used as an extension of Developer License and cannot be used without it.
Discussion
18 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
The purchased Developer License allow access to all new SDK versions released within next 12 months starting from purchase date. After that period of time it is possible to extend such period for 12 months more by purchasing Upgrade License.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeScannerViewController.h
startScan:
Start the scanning from camera video stream.
- (void)startScan: (UIViewController*)mainViewController
Parameters mainViewController The parent view controller.
Discussion startScan method will show the Camera preview modal dialog.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeScannerViewController.h
stopScan:
Stops the scanning from camera video stream.
- (void)stopScan
Discussion stopScan method will close the Camera preview modal dialog.
19 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeScannerViewController.h
20 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS SDTBarcodeScannerViewControllerDelega te protocol Reference
Inherits from
Conforms to
Library sdt -brc -ios2.a
Declared in SDTBarcode ScannerViewController .h
Related sample code sdt -brc -sample 3
Overview The SDTBarcodeScannerViewControllerDelegate is a protocol used for notification by SDTBarcodeScannerViewController.
Instance Methods onRecognitionComplete:
The method is called each time new barcode symbol has been recognized from camera video stream. Returning YES will close the Barcode scanner modal view, NO – will keep the Scanner on the screen.
- (BOOL)onRecognitionComplete:(SDTBarcodeEngine*)theEngine onImage:(CGImageRef)theImage orientation:(UIImageOrientation)theOrientation
Parameters theEngine The SDTBarcodeEngine which contain additional information about recognized symbols theImage The video frame image which was used in recognition theOrientation
21 | P a g e
SD-TOOLKIT® Barcode Reader SDK 2.1 for iOS
The image orientation
Return Value Returning YES will close the Barcode scanner modal view, NO – will keep the Scanner on the screen.
Availability Available in iOS 4.0 and later.
Declared In SDTBarcodeScannerViewController.h
22 | P a g e