1iOS
2===
3This chapter deals with the iOS specific properties of the AusweisApp2 SDK.
4The AusweisApp2 core is encapsulated into an **XCFramework** which needs to
5be linked into your application.
6
7Subsequent sections deal with the SDK interface itself and explain which
8steps are necessary in order to talk to the AusweisApp2 SDK.
9
10.. important::
11   Apple released the necessary NFC API with iOS 13.0!
12   Be aware that it is not possible to support older versions.
13
14
15
16Use XCFramework
17---------------
18The interface ``AusweisApp2.h`` of the SDK for iOS is provided as **C-Header**
19that you need to import/include into your application. It grants access to
20start and shutdown a separate background thread with the integrated
21AusweisApp2 core.
22
23After you established a connection to the AusweisApp2 SDK your application
24can send :doc:`commands` and receive :doc:`messages`.
25
26
27Clone
28^^^^^
29The XCFramework is provided in our github repository. It is recommended
30to use at least Xcode 12 and the dependency handling of at
31least Swift 5.3 (Swift Package Manager).
32
33  https://github.com/Governikus/AusweisApp2-SDK-iOS
34
35You can clone and add that repository with Xcode and import it into your
36project under the following menu.
37
38  :menuselection:`File --> Swift Packages --> Add Package Dependency`
39
40
41Import
42^^^^^^
43After you added the repository to your Xcode project you can import the
44module via ``import AusweisApp2`` in Swift classes or ``@import AusweisApp2;``
45in Objective-C classes and call the functions of the ``AusweisApp2.h`` header.
46
47.. code-block:: c
48
49  typedef void (* AusweisApp2Callback)(const char* pMsg);
50  bool ausweisapp2_init(AusweisApp2Callback pCallback);
51  void ausweisapp2_shutdown(void);
52  bool ausweisapp2_is_running(void);
53  void ausweisapp2_send(const char* pCmd);
54
55First, you need to define a callback function that will be called by the AusweisApp2
56to request or provide additional information. If your application initializes the
57SDK you must pass that callback to ``ausweisapp2_init``. That function will return
58``false`` if the callback is ``NULL`` or the SDK is already running.
59
60After you called that function the AusweisApp2 SDK will start up. If the
61initialization is finished the SDK calls your callback function once with
62``NULL`` as parameter to indicate that it is ready to accept :doc:`commands`.
63Do not call ``ausweisapp2_send`` until your callback received that message, otherwise
64that command will be ignored.
65
66Once the SDK is ready to go you can send :doc:`commands` by ``ausweisapp2_send``.
67Your callback will receive the :doc:`messages`.
68
69If you call ``ausweisapp2_shutdown`` the AusweisApp2 SDK will be terminated. This
70function joins the thread of the AusweisApp2 and blocks until the AusweisApp2 is
71finished. You should not call this function in your callback as it is called
72by the AusweisApp2 thread. In that case ``ausweisapp2_shutdown`` cannot be a
73blocking call to avoid a deadlock.
74If you call this function while a workflow is running the workflow will be
75canceled automatically before the shutdown.
76
77
78.. important::
79   Your callback will be called by the separate AusweisApp2 thread. Do **not**
80   make long running or blocking calls! It is recommended to use an async dispatcher.
81
82   Also, you should not call ``ausweisapp2_send`` or ``ausweisapp2_shutdown`` within
83   your callback function.
84
85
86
87Info.plist
88----------
89You need to enable the card identifier in your applications ``Info.plist`` like this,
90otherwise iOS will not recognize any identity cards. Also, it is necessary to provide
91a message why your application needs access to the NFC hardware.
92
93.. code-block:: xml
94
95  <key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
96  <array>
97    <string>E80704007F00070302</string>
98  </array>
99
100  <key>NFCReaderUsageDescription</key>
101  <string>AusweisApp2 needs NFC to access the ID card.</string>
102
103
104.. seealso::
105
106  * https://developer.apple.com/documentation/bundleresources/information_property_list/select-identifiers
107  * https://developer.apple.com/documentation/bundleresources/information_property_list/nfcreaderusagedescription
108
109
110
111Entitlements
112------------
113Your application needs to provide an entitlement file to request the format
114of reader sessions.
115
116.. code-block:: xml
117
118  <?xml version="1.0" encoding="UTF-8"?>
119  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
120  <plist version="1.0">
121    <dict>
122      <key>com.apple.developer.nfc.readersession.formats</key>
123      <array>
124        <string>TAG</string>
125      </array>
126    </dict>
127  </plist>
128
129.. seealso::
130
131  https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_nfc_readersession_formats
132
133
134
135Logging
136-------
137
138The AusweisApp2 uses default logging of iOS and has its own log file.
139It is **recommended** to collect that log file if an error occurs in
140your application to receive better support.
141
142The log file is in your application path:
143
144.. code-block:: text
145
146    NSTemporaryDirectory() + /AusweisApp2.XXXXXX.log
147
148The *XXXXXX* characters will be replaced by an automatically generated
149portion of the filename to avoid conflicts with previous instances.
150
151A new log file will be created for each new instance of the AusweisApp2 and
152will be deleted after a correct shutdown.
153In case of old or multiple log files, it is highly probable that the
154previous instance crashed.
155
156The AusweisApp2 deletes any log files that are older than 14 days.
157