2.5. Backward Compatibility

Generally speaking, we take great care to ensure that each release of the library is backward compatible with previous versions - upgrading the library should not require any changes to your code and will continue to provide equivalent functionality. The notable exception to this is the iOS 4 upgrade and associated “deprecation” of the former automatic capture method by our vendor.

2.5.1. The Private API

The API that we use for automatic capture with iOS 3.x (namely UIGetScreenImage()) has an interesting history. It has changed status several times, starting with “Private, unless we like you” moving to “reluctantly Public but undocumeted” by popular demand and reverting to “strictly Private” as of iOS 4. The current story: if you want to distribute on the App Store, you had better not be using it - IOW, no automatic capture for you with iOS 3.x.

Since App Store distribution is the most common use for the library, the default configuration, and thus the binary SDK, does not use any private APIs.

Users targeting ad-hoc or enterprise distribution may not care about the status of the API and may prefer to continue supporting automatic capture for iOS 3.x. To do this you will need to rebuild the library with the following define set for all configurations:

USE_PRIVATE_APIS=1

For reference, you can check whether your app refers to the offensive function with this command:

$ otool -vI MyApp.app/MyApp | grep UIGetScreenImage

If there is any output, then the executable includes the private API and is bound to be rejected if submitted for review. Otherwise it is “clean” as far as this library is concerned.

2.5.2. Upgrading to iOS 4

If you were using the reader before iOS 4 was introduced, you will want to upgrade to the new reader controller. The performance has improved quite a bit, and you can continue to support automatic capture on the App Store.

Note

This discussion only applies to automatic capture from the camera. If you are only scanning image files, or prefer/need to use manual capture, you should not change anything.

Basically just replace your old ZBarReaderController with a new ZBarReaderViewController and you’re done! See the reference and the next section for compatibility between the two classes.

Also see the Installing the SDK instructions for details about upgrading the header references to use the SDK.

2.5.3. Supporting iOS 3.x

The new ZBarReaderViewController is intentionally designed to be compatible with the old ZBarReaderController in most aspects that relate to reading barcodes. When a ZBarReaderViewController is initialized under iOS 3.x, it will replace itself with a ZBarReaderController. You can leverage the compatibility of these controllers to continue supporting iOS 3.x.

The following properties and methods should be equivalent across implementations. You may use them without regard for the actual instance type.

Equivalent Members  
cameraOverlayView  
cameraViewTransform  
enableCache  
scanner  
readerDelegate  
scanCrop  
showHelpWithReason:  
showsZBarControls  
tracksSymbols  

Some properties are available with ZBarReaderViewController only for backward compatibility. If these are configured, they must be set as indicated; attempts to set another value will raise an exception.

ZBarReaderController Property ZBarReaderViewController Value
allowsEditing NO
cameraMode Sampling
maxScanDimension (ignored)
showsCameraControls NO
showsHelpOnFail (ignored)
sourceType Camera
takesPicture NO

Also, the isSourceTypeAvailable: class method of ZBarReaderViewController will return YES only for the Camera source.

All other members of ZBarReaderController, including those inherited from UIImagePickerController are not supported by ZBarReaderViewController. This includes takePicture and scanImage:, among others.

Remaining members of ZBarReaderViewController: are only available with the new implementation. At the moment this is only readerView, but any new properties or methods not listed here will also fall in this category.

To access settings that may not be available in a potential fallback environment, you must verify that they exist and may be set as desired - eg, by testing the specific reader subtype.

2.5.3.1. Weak Linking

When leveraging fallbacks to iOS 3.x, it is important that features introduced in iOS 4 are referenced using weak links. You must configure your project correctly to support this:

  • Make sure the iOS 4 frameworks are set to Weak. Specifically, these are AVCapture, CoreMedia and CoreVideo.
  • Build with the latest SDK - do not use the “Base SDK” setting to target earlier devices.
  • Set the correct iOS 3.x version for the “iPhone OS Deployment Target” build setting.

2.5.4. Example: Fallback to Manual Capture

This code example will configure the reader for automatic capture from the camera for iOS 4 and fall back to manual or automatic capture for iOS 3.x, depending on whether the library was compiled to use private APIs:

if(![ZBarReaderController isSourceTypeAvailable:
                              UIImagePickerControllerSourceTypeCamera]) {
    // camera unavailable: display warning and abort
    // or resort to keypad entry, etc...
    return;
}

ZBarReaderViewController *reader = [ZBarReaderViewController new];
// reader will be a ZBarReaderController for iOS 3.x
// or a ZBarReaderViewController for iOS 4

reader.readerDelegate = self;
reader.sourceType = UIImagePickerControllerSourceTypeCamera;
reader.showsZBarControls = YES;

if(reader.cameraMode == ZBarReaderControllerCameraModeSampling) {
    // additional automatic capture configuration here
}
else {
    // additional manual capture configuration here
}

[self presentModalViewController: reader
      animated: YES];

If you are using a custom control set (showsZBarControls=NO), you will want to provide a button attached to takePicture for the manual capture case. The built-in controls do this automatically.