1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
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.
|
