API Availability and Target Conditionals

Writing code for multiple Apple platforms can be tricky, this post aims to provide some guidance and explanations for ways to write code that works on different Apple platforms (iOS, macOS, watchOS, tvOS) and different versions of SDKs, and the OSes at runtime.

Target conditionals

First, let’s take a look at how to tell apart the OS you are compiling for at build time, using the preprocessor (in case of Objective-C) or compilation conditions (Swift).

Swift

In Swift checking the OS you are building for at comile time is done using compilation conditionals and specific platform condition functions:

The os() function can be used to check for the OS the code is compiled for, it takes one argument, which is the operating system name (not quoted). Possible operating system names at the time of writing are macOSiOStvOSwatchOS and Linux.

For example:

Of course sometimes you need to check if you are running the simualtor or not, to do that there is the targetEnvironment() function. It takes one argument, which is the target environment name (not quoted). Possible values are simulator and macCatalyst (since Swift 5.1).

Objective-C, C and C++

For Objective-C, C and C++ conditional compilation is handled by the preprocessor. Apple provides the TargetConditionals.h header which contains specific defines for this.

This header has a lot of defines, I will only list the most useful ones here:

TARGET_OS_OSX
Compiling for macOS
TARGET_OS_IOS
Compiling for iOS
TARGET_OS_TV
Compiling for tvOS
TARGET_OS_WATCH
Compiling for watchOS
TARGET_OS_MACCATALYST
Compiling for Catalyst
TARGET_OS_SIMULATOR
Compiling for Simulator

For example:

To check if compiling for the simulator, just use the TARGET_OS_SIMULATOR define:

Note that there is a TARGET_OS_MAC define, while this sounds like it will be true only for macOS, it is actually true for all Darwin OSes including iOS and tvOS. Another define which can be confusing is the TARGET_OS_IPHONE, which is actually true for all “mobile” platforms, so iOS, tvOS, watchOS and Catalyst.

Clang-specific preprocessor extensions

Since Clang 6.0 or Xcode 9.3 (r320734) Clang has preprocessor extensions similar to the Swift condition functions which can be used to achieve the same as with the target conditional defines above.

To check the OS code is compiled for, there is the __is_target_os() preprocessor macro, which takes a single argument, the operating system name. Possible values for Apple OSes are macOSiOStvOSwatchOS.

For example:

To check what environement the code is compiled for, similar to Swift there is the __is_target_environment() preprocessor macro, which takes as argument the environment name. Possible values are simulator and macabi (Catalyst).

API availability

Something that usually is closely related to above discussed conditional compilation is the need to handle API availability gracefully. There are various aspects to consider about API availability, one is API availability at runtime, another is API availability at compile time depending on the used SDK version.

What is API availability?

API availability, as the name suggests, means if a specific API (function, class, method, etc.) is actually available.

macOS, iOS, tvOS and watchOS handle API availability in the same way, when a new API is introduced it is annotate with a specific macro that indicates the availability of that API. The macro expands to annotations for the API that indicate how the linker is expected to handle linking to it and can provide additional warnings or errors during compilation when using a deprecated API or trying to use a “too new” API in an application set to run on older appleOS versions that lack this API.

This sounds all very abstract and complex, so let’s have a look at this using an example, the clock_gettime() function. If we look at the manpage for clock_gettime we can see that it was introduced in macOS 10.12:

So let’s have a look at how the header declares this function:

So these functions are annotate with __CLOCK_AVAILABILITY, which expands to:

So to be more precise than what the man page tells us, this API is available since macOS 10.12, iOS 10.0, tvOS 10.0 and watchOS 3.0, great!

Of course that still doesn’t provide the full story, to understand what exactly the availability macros do, let’s have a look at the header defining those, Availability.h. Checking this header, we can see that these macros actually expand to (indirectly using a other macros) use of the availability attribute. I recommend reading this for all the details about how exactly this works. The most important takeaway for the purpose of this article is the following:

A declaration can typically be used even when deploying back to a platform version prior to when the declaration was introduced. When this happens, the declaration is weakly linked, as if the weak_import attribute were added to the declaration. A weakly-linked declaration may or may not be present a run-time, and a program can determine whether the declaration is present by checking whether the address of that declaration is non-NULL.

Note that in addition to the Availability.h header, there is the AvailabilityMacros.h header which works similar to the Availability.h header. Depending on the Framework, it might use either the Availability.h or the older AvailabilityMacros.h header.

Checking API availability at runtime

Now let’s see how we can use such a “partially” avaialble function:

If we now compile this targeting macOS 10.14 like that, it just works as expected:

But if we were to try to compile targeting macOS 10.10, we would get a warning:

The -Wunguarded-availability flag is what causes the compiler to emit this warning. For APIs available since macOS 10.13, iOS 11, watchOS 4 and tvOS 11 you will get these warnings even without specifying this flag, as there is a new flag-Wunguarded-availability-new which is enabled by default in recent Clang/Xcode versions.

As the name of the warning already gives it away, it only warns about “unguarded” availability, which implies we can “guard” such API usage. There are two ways how this can be done.

Checking the symbols address

The “old” way to check if a partially available function is available would be to check its address:

Not only is this a bit weird to read, it has some downsides:

  • The compiler will still warn about this
  • Objective-C methods and classes can’t easily be checked this way
  • It is cumbersome to check all relevant symbols this way
Using the availability helper

Fortunately since some time there is a bette way to handle this! In fact, the compiler would already points this out in the partial availability warning:

note: enclose 'clock_gettime' in a __builtin_available check to silence this warning

So let’s do that:

And now it will compile without warning again! On macOS at least, that is. We can check multiple platform versions just by listing them all:

The star at the end is mandatory and means “all other platforms”. So the previous check that just listed macOS would still compile for iOS and crash at runtime when ran on iOS versions lower than iOS 10 which lack clock_gettime. So take care to cover all cases where the code will run in your availability check!

In Objective-C there is the @available helper which looks a bit nicer than the longer version from C but is used in the exact same way:

In Swift there is #available, again the usage is the same except for the different name:

Note that negating the check or using it together with any other condition is not supported and does not properly guards availability!

Additionally keep in mind that this is a runtime check, so using APIs inside a availability check that are missing in the current SDK version that is compiled with is still an error. To support multiple SDK versions, see the next section for how to check at compile-time!

Checking API availability at compile-time

Sometimes it is necessary to check the availability of a specific API at compile-time, for example when you want to remain compatible with multiple Apple SDKs, where some versions offer new API that you want to use and some versions lack this API.

In the previous section I already mentioned two headers, Availability.h and AvailabilityMacros.h. These headers define two important macros:

__<OS-VARIANT>_VERSION_MAX_ALLOWED
Indicates the maximum version that we are allowed to use APIs from.
__<OS-VARIANT>_VERSION_MIN_REQUIRED
Indicates the minimum required version that we are allowed to use APIs from.

The <OS-VARIANT> needs to be replaced with the OS variant we want to check for and can be MAC_OS_XIPHONE_OSTV_OS or WATCH_OS.

The above sounds quite abstract so lets illustrate it with a example. Suppose we have a new API introduced for macOS 10.12, so it is first present in the macOS 10.12 SDK. If we were to compile with that SDK, the __MAC_OS_X_VERSION_MAX_ALLOWED macro is automatically set to the version of the SDK, as that is the maximum macOS version that we can use APIs from, we cannot ever use any APIs newer than the SDK we are using because those are simply not declared. So in case of the 10.12 SDK, __MAC_OS_X_VERSION_MAX_ALLOWED will be 101200.

If we want to stay compatible with older SDKs, we can use the following preprocessor macros:

Note that there are defines for the specific appleOS versions in the availability headers, like __MAC_10_12 so it is tempting to write __MAC_OS_X_VERSION_MAX_ALLOWED >= __MAC_10_12 but this will not work because lower SDK versions, like for example the macOS 10.11 SDK will not have the define for higher macOS versions like macOS 10.12!

What is important to note is that the preprocessor checks are done at compile-time, so proper availability handling at runtime is still needed, see the previous section for details about that!

The second macro, __<OS-VARIANT>_VERSION_MIN_REQUIRED, is useful when you have legacy code that you want to disable when targeting recent enough appleOS versions. Suppose we have function needed for macOS <= 10.11, we can easily disable that when targeting macOS 10.12 or higher by using the __MAC_OS_X_VERSION_MIN_REQUIRED macro:

Of course a lot of other and more complex scenarios are possible with more complex checks, but I won’t cover all of the possibilities here.

Note that the AvailabilityMacros.h header defines MAC_OS_X_VERSION_MIN_REQUIRED without the two leading underscores, but the Availability.h header does not define those. Both define the version with the leading underscores so to prevent confusing code I would recommend to not use the version without the leading underscores.

Note that the above only works for C/C++/Objective-C code, in Swift there is currently no way to check the SDK at compile-time.

参考链接


不同版本的TLS在Android/iOS中的支持情况

本文要解决的两类问题:
  • 在Android4.1-Android5.0的系统上启用TLSv1.1和TLSv1.2
  • java.lang.IllegalArgumentException: protocol TLSv1.1 is not supported

这两个问题比较具有代表性,在群里面讨论的时候见过的次数也是最多的,因此有些人遇到的问题也许协议名称不一样,但是本质都是类似的。

问题原因和解决思路分析

Android5.0 行为变更 可以看到 Android 5.0 开始默认启用了 TLSv1.1TLSv1.2,但是从 Android 4.1 开始 TLSv1.1TLSv1.2 其实就被支持了,只是默认没有启用而已。

我们最常用到的几种协议是SSLv3TLSv1TLSv1.1TLSv1.2,解决上面两个问题要搞清楚的是这几个协议在Android 系统中被支持的情况和被启用的情况,然后我们结合 minSdkVersiontargetSdkVersion 来选择协议即可,不同版本的 Android 系统对上述协议的支持情况:

客户端(SSLSocket)的支持情况:

协议 被支持(Api级别) 被启用(Api级别)
SSLv3 1–25 1–22
TLSv1 1+ 1+
TLSv1.1 16+ 20+
TLSv1.2 16+ 20+

服务端(SSLServerSocket)的支持情况:

协议 被支持(Api级别) 被启用(Api级别)
SSLv3 1–25 1–22
TLSv1 1+ 1+
TLSv1.1 16+ 16+
TLSv1.2 16+ 16+

数据来源:https://developer.android.com/reference/javax/net/ssl/SSLSocket

注意:这里说的客户端和服务端不是指Android端和JavaEE端/PHP端(还有Python、.NET等等),是指的在Android开发中的客户端Socket(SSLSocket)和服务端Socket(SSLServerSocket)。

到这里其实已经知道本文开始处的问题的原因了,TLSv1.1和TLSv1.2从Android4.1(Api级别16)开始才被支持,从Android4.4 Wear(Api级别20)才被启用(手机是Android5.0,Api级别21),因此在不同版本的Android系统中会出现需要被启用和启用时报不被支持的问题。

我们可以写一个TLS协议通用的兼容类,在所有的Android中强制启用已经被支持的所有协议,总结一下就是Android8.0及以上系统可以强制启用TLSv1、TLSv1.1和TLSv1.2协议,Android4.1-Android7.1.1系统可以强制启用SSLv3、TLSv1、TLSv1.1和TLSv1.2协议,其它版本系统可以强制启用SSLv3和TLSv1协议。

综上所述,如果开发者使用SSLv3协议,那么minSdkVersion不限制,targetSdkVersion不高于25,并且需要尽快更新为TLSv1.1协议或者TLS1.2协议;如果开发者使用TLSv1.1协议或者TLSv1.2协议,那么minSdkVersion应该不低于16,targetSdkVersion不限制;如果开发者使用TLSv1协议,那么目前不受限制。

代码实现

我们需要让SSLSocket启用对应的协议,代码对应的方法是:

因此我们需要先在不同版本的Android系统中生成不同的协议数组:

SSLSocket是由SSLSocketFactory负责生成的,我们再写一个SSLSocketFactory的包装类,主要代码如下:

iOS客户端支持情况

iOS 客户端(SSLSocket)的支持情况:

TLS 1.2 从 iOS 5 开始支持(TLS 1.2 was first added to iOS in iOS 5

另外 对于在 2020 年 9 月 1 日格林尼治标准时间/世界标准时间 00:00 或之后颁发的 TLS 服务器证书,其有效期不得超过 398 天

参考链接


Android/iOS手机朝向获取

对于iOS手机:

苹果公司给出了一个枚举,如下:

2、对于获取手机屏幕
(1)

(2)

3、对于当前手机是不是横屏或者竖屏的判断
(1)判断是否是竖屏

(2)判断是否是横屏

对于Android手机:

判断手机方向的具体判断代码如下:

对于 Flutter:

使用 native_device_orientation 插件完成相同的检测功能。

参考链接


LocalAuthentication开发实践

在iPhone 5s加入Touch ID后,指纹识别的功能在App中逐渐受到青睐,特别是对于本地安全较高的应用(如带支付的App)指纹识别是必备的功能,它既能解决在验证过程中输入密码的繁琐过程,同时指纹识的安全等级更高。那么,要想在自己开发的应用中使用指纹识别,就必须要LocalAuthentication.framework提供的API,下面将详细地介绍如何使用这个框架来实现指纹识别功能。

基础用法

我们先来看下面的例子:

继续阅读LocalAuthentication开发实践

移动端系统生物认证技术详解

相信大家对于生物认证应该不会陌生,使用指纹登陆或者 FaceId 支付等的需求场景如今已经很普遍,所以基本上只要涉及移动端开发,不管是 Android 、iOS 或者是 RN 、Flutter 都多多少少会接触到这一业务场景。

当然,不同之处可能在于大家对于平台能力或者接口能力的熟悉程度,所以本篇主要介绍 Android 和 iOS 上使用系统的生物认证需要注意什么,具体流程是什么,给需要或者即将需要的大家出一份汇总的资料

继续阅读移动端系统生物认证技术详解

iOS - keychain详解及变化

keychain介绍

iOS keychain 是一个相对独立的空间,保存到keychain钥匙串中的信息不会因为卸载/重装app而丢失。相对于NSUserDefaults、plist文件保存等一般方式,keychain保存更为安全。所以我们会用keyChain保存一些私密信息,比如密码、证书、设备唯一码(把获取到用户设备的唯一ID 存到keychain 里面这样卸载或重装之后还可以获取到id,保证了一个设备一个ID)等等。keychain是用SQLite进行存储的。用苹果的话来说是一个专业的数据库,加密我们保存的数据,可以通过metadata(attributes)进行高效的搜索。keychain适合保存一些比较小的数据量的数据,如果要保存大的数据,可以考虑文件的形式存储在磁盘上,在keychain里面保存解密这个文件的密钥。

继续阅读iOS - keychain详解及变化

在macOS Big Sur(11.4)编译Hummer

最近在macOS Big Sur(11.4)编译Hummer

Android版本编译:

如果报错如下:

参考 ABIs [arm64-v8a] are not supported for platform. Supported ABIs are [armeabi-v7a, x86].

如果运行测试用例时报错如下:

解决方案为在项目中增加:

IOS版本编译:

参考链接


AX88179 USB网卡无法在macOS Big Sur(11.0.1)系统上正常使用

Background
Last year, we wrote that older macOS drivers, known as System Extensions (KEXTs), would begin to be deprecated as of the macOS 10.15 Catalina release. This week, as macOS 11 Big Sur is released, KEXTs have officially been deprecated and are no longer functional.

Instead, Apple is now enforcing the requirement for devices that require third-party drivers to operate as DriverKit Extensions (DEXTs). This change affects many products across the consumer electronics industry, including Docking Stations, USB peripherals, Security/Anti-Virus software, and Networking adapters.

Luckily, most platform vendors and integrated circuit (IC) manufacturers have been prepared for this change and began working on their DEXT implementation after Apple released pertinent documentation at their WWDC (World Wide Developer Conference) in June 2019.

Unfortunately, some vendors could not begin their full transition from KEXT to DEXT until this year. Not all pertinent DriverKit documentation was released at the 2019 event as expected, but, instead, was released at WWDC 2020 in June. Specifically, for Plugable and many other brands, this applies to ASIX-based USB Ethernet Adapters like our USB3-E1000, USBC-E1000, USB2-E1000, and USB2-E100, which we wrote about here for the release of macOS 10.15 Catalina:
https://plugable.com/2019/10/04/usb-ethernet-adapter-not-working-after-macos-catalina-10-15-update-we-can-help/

Current Status for ASIX-based Ethernet Adapters [Novemeber 13, 2020]
We began removing macOS support from our most popular wired network adapters (USB3-E1000 and USBC-E1000) in October 2019. We saw the continued potential for a poor or broken user experience with ASIX-based adapters on macOS and could not in good conscience market the adapters as fully compatible in the long-term as long as ASIX was unwilling to commit to continued development and support of their ICs on macOS.

We have continued to push ASIX for a DEXT beta driver to validate and test internally in the past year. Unfortunately, ASIX has been unable to deliver this solution as requested in anticipation of this significant macOS milestone. We expect a Beta driver from ASIX by the end of November for AX88179 products like the USB3-E1000 and USBC-E1000. Once the driver is validated, we will update this blog post and product driver pages with links to download the driver.

If a wired Ethernet connection is critical to your workflow, Plugable recommends not updating to macOS 11 Big Sur from macOS 10.15 Catalina.

At this time, Plugable is unable to provide a DEXT driver for the following products:
USB3-E1000 IC: AX88179
USBC-E1000 IC: AX88179
USB2-E1000 IC: AX88178 (ASIX has discontinued the IC in this product, and they have not committed to a compatible driver for macOS 11 Big Sur)
The USB2-E100 IC: AX88772 ASIX-based product continues to function, utilizing the in-box drivers in macOS.

We understand this news can be frustrating for our customers and is a situation we have been working to avoid for over one year. We will update this blog post as new information is available to us.

While we cannot promise a functional DEXT driver at any point in the future, if you would like to be notified of that news should it occur, please sign-up on the form below, and we will email everyone as soon as it is available.

继续阅读AX88179 USB网卡无法在macOS Big Sur(11.0.1)系统上正常使用

在macOS Catalina(10.15.5)上搭建Flutter开发环境

下载并安装目前最新的Android Studio 4.0,然后通过Android Studio 4.0安装Android SDK

下载目前最新的flutter

配置环境变量

上述环境变量,全部追加到 .bashrc 尾部

如果不增加到.bashrc 尾部,则在 Android Studio 4.0 创建项目的时候,会非常慢,主要是网络问题。

必要的环境配置,依赖下载

继续阅读在macOS Catalina(10.15.5)上搭建Flutter开发环境