diff options
Diffstat (limited to 'iphone/doc/compat.rst')
| -rw-r--r-- | iphone/doc/compat.rst | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/iphone/doc/compat.rst b/iphone/doc/compat.rst new file mode 100644 index 0000000..5fb808e --- /dev/null +++ b/iphone/doc/compat.rst @@ -0,0 +1,190 @@ +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. + + +.. warning:: + + Versions before iOS 4 are no longer supported by the library. We are no + longer able to test anything in this section, so you're on your own if you + try to make use of it. + + +The Private API +--------------- + +The API that we use for automatic capture with iOS 3.x (namely +:func:`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: + +.. sourcecode:: sh + + USE_PRIVATE_APIS=1 + +For reference, you can check whether your app refers to the offensive function +with this command: + +.. sourcecode:: sh + + $ 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. + + +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 :class:`ZBarReaderController` with a new +:class:`ZBarReaderViewController` and you're done! See the reference and the +next section for compatibility between the two classes. + +Also see the :doc:`install` instructions for details about upgrading the +header references to use the SDK. + + +Supporting iOS 3.x +------------------ + +The new :class:`ZBarReaderViewController` is intentionally designed to be +compatible with the old :class:`ZBarReaderController` in most aspects that +relate to reading barcodes. When a :class:`ZBarReaderViewController` is +initialized under iOS 3.x, it will *replace* itself with a +:class:`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 +======================================================== ==== +:member:`~ZBarReaderViewController::cameraOverlayView` +:member:`~ZBarReaderViewController::cameraViewTransform` +:member:`~ZBarReaderViewController::enableCache` +:member:`~ZBarReaderViewController::scanner` +:member:`~ZBarReaderViewController::readerDelegate` +:member:`~ZBarReaderViewController::scanCrop` +``showHelpWithReason:`` +:member:`~ZBarReaderViewController::showsZBarControls` +:member:`~ZBarReaderViewController::tracksSymbols` +======================================================== ==== + +Some properties are available with :class:`ZBarReaderViewController` only for +backward compatibility. If these are configured, they must be set as +indicated; attempts to set another value will raise an exception. + +==================================================== ======================================= +:class:`ZBarReaderController` Property :class:`ZBarReaderViewController` Value +==================================================== ======================================= +:member:`~ZBarReaderController::allowsEditing` ``NO`` +:member:`~ZBarReaderController::cameraMode` ``Sampling`` +:member:`~ZBarReaderController::maxScanDimension` (ignored) +:member:`~ZBarReaderController::showsCameraControls` ``NO`` +:member:`~ZBarReaderController::showsHelpOnFail` (ignored) +:member:`~ZBarReaderController::sourceType` ``Camera`` +:member:`~ZBarReaderController::takesPicture` ``NO`` +==================================================== ======================================= + +Also, the ``isSourceTypeAvailable:`` class method of +:class:`ZBarReaderViewController` will return ``YES`` only for the ``Camera`` +source. + +All other members of :class:`ZBarReaderController`, including those inherited +from :class:`UIImagePickerController` are not supported by +:class:`ZBarReaderViewController`. This includes ``takePicture`` and +``scanImage:``, among others. + +Remaining members of :class:`ZBarReaderViewController`: are only available +with the new implementation. At the moment this is only +:member:`~ZBarReaderViewController::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. + +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. + + +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 +(:member:`~ZBarReaderViewController::showsZBarControls`\ ``=NO``), you will +want to provide a button attached to ``takePicture`` for the manual capture +case. The built-in controls do this automatically. |