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.