Everything You Need to Know about iOS and OS X Deprecated APIs

Deprecated APIs, as you may know, are methods or classes that are outdated and will eventually be removed. Apple deprecates APIs when they introduce a superior replacement, usually because they want to take advantage of new hardware, OS or language features (e.g. blocks) that were’t around when the original API was conceived.

Whenever Apple adds new methods, they suffix the method declarations with a special macro that makes it clear which versions of iOS support them. For example, for UIViewController, Apple added a new way to present modal controllers that uses a block callback. The method declaration looks like this:

- (void)presentViewController:(UIViewController *)viewControllerToPresent 
 animated: (BOOL)flag completion:(void (^)(void))completion NS_AVAILABLE_IOS(5_0);

Note the NS_AVAILABLE_IOS(5_0) – this tells us that this method is available from iOS 5.0 and upwards. If we try to call this method on an iOS version that is older than the specified version, it will crash.

So what about the old method that this replaces? Well, there’s a similar syntax for marking methods as deprecated:

- (void)presentModalViewController:(UIViewController *)modalViewController 
 animated:(BOOL)animated NS_DEPRECATED_IOS(2_0, 6_0);

The NS_DEPRECATED_IOS(2_0, 6_0) macro has two version numbers. The first number is when the method was introduced, and the second is when it was deprecated. Deprecated doesn’t mean the method doesn’t exist any more, it just means that we should start thinking about moving our code to a newer API.

There are other forms of these macros used for classes that are shared between iOS and OSX. For example this method on NSarray:

- (void)setObject:(id)obj atIndexedSubscript: 
  (NSUInteger)idx NS_AVAILABLE(10_8, 6_0);

The NS_AVAILABLE macro here is telling us that the method was introduced in Mac OS 10.8 and iOS 6.0, respectively. The NS_DEPRECATED macro confusingly reverses the order of the arguments from the NS_DEPRECATED_IOS version:

- (void)removeObjectsFromIndices:(NSUInteger *)indices 
  numIndices:(NSUInteger)cnt NS_DEPRECATED(10_0, 10_6, 2_0, 4_0);

This is telling us that the method was introduced in Mac OS 10.0 and iOS 2.0 and deprecated in Mac OS 10.6 and iOS 4.0.

Easy Come, Easy Go

Last week we talked about the new Base64 encoding APIs that Apple added in the iOS 7 and Mac OS 10.9 SDKs. Interestingly, they also both added and deprecated a separate set of Base64 methods that do the same thing. Why would Apple introduce an API and deprecate it at the same time? Surely that’s pointless? Well, no actually – it makes perfect sense in this case:

The now-deprecated Base64 methods actually existed as a private API since iOS 4 and Mac OS 10.6. Apple never made these public until now, presumably because they were never really happy with the implementation, and had a feeling that they might want to change them.

Sure enough, in iOS 7, Apple decided on a Base64 API that they were happy with, and added it as a public addition to NSData. But now that they knew that the old methods had been replaced and weren’t going to change, they exposed them so that developers would have a built-in way to use Base64 encoding for apps that still need to support iOS 6 and earlier.

This is why, if you look at the method declaration for the new APIs, the “from” value in the NS_DEPRECATED macro is 4_0, even though the method wasn’t actually introduced as a public API until iOS 7:

- (NSString *)base64Encoding NS_DEPRECATED(10_6, 10_9, 4_0, 7_0);

That’s telling you that apps built with the iOS 7 SDK that call this method will be able to run on iOS 4+ or Mac OS 10.6+ without crashing. Handy.

Using Deprecated APIs in your App

So if we have an app that needs to work on both iOS 6 and 7, and we want to use the built-in Base64 methods, how do we do that? Actually, it’s very simple, for now you can just call the deprecated APIs.

Won’t that create compiler warnings? Nope – you will only get a compiler warning if your deployment target is set equal to or higher than the version when the method was deprecated. As long as you are still supporting an iOS version in which the method was not yet deprecated, you won’t get warnings.

So what if Apple decides to remove the deprecated Base64 methods in iOS 8 – what will happen to your app? It will crash, but don’t let that put you off: It’s vanishingly unlikely that Apple will remove a deprecated API within a couple of OS releases (the vast majority of APIs deprecated in any version of iOS have yet to be removed), and unless you are planning on never doing further updates to your app there will be plenty of opportunity to update to the new APIs once you’ve dropped support for iOS 6.

But if we assume the worst case scenario (i.e. we never update our app, and Apple suddenly develops a zero-tolerance policy to backwards compatibility), how can we future-proof our code and still support older OS versions?

It’s actually pretty easy, we just need to do some runtime method detection. Using the respondsToSelector: method of NSObject, we can test if the new API exists, and if it does we’ll call it. Otherwise, we fall back to the deprecated API. Easy:

NSData *someData = ...
NSString *base64String = nil;
 
// Check if new API is available
if ([someData respondsToSelector:@selector(base64EncodedDataWithOptions:)])
{
  // It exists, so let's call it
  base64String = [someData base64EncodedDataWithOptions:0];
}
else
{
  // Use the old API
  base64String = [someData base64Encoding];
}

This code will work on iOS 4+ and is completely future-proof against Apple removing the base64Encoding method in a future iOS release.

Coding for other Coders

That’s all very well if you are writing an app, but what if you’re writing a code library for consumption by others? The code above will work great if used in a project that targets iOS 4 or 6, but if it’s set to a deployment target of iOS 7+, you’ll get a compiler warning for using the deprecated base64Encoding method.

The code will actually continue to work fine forever, because that method will never be called at runtime (since the respondsToSelector: check will always return YES on iOS 7), but unfortunately the compiler isn’t quite smart enough to figure that out. And if, like me, you won’t use 3rd party code that generates warnings on principle, you certainly don’t want to be producing them in your own libraries!

How can we rewrite our code so that it works for any deployment target without generating warnings? Fortunately there is a compiler macro for branching code based on the deployment target. By using __IPHONE_OS_VERSION_MIN_REQUIRED, we can produce different code depending on which minimum iOS version the app is built for.

The following code will work on any iOS version (past or future) and won’t generate any warnings:

#if __IPHONE_OS_VERSION_MIN_REQUIRED < __IPHONE_7_0
 
// Check if new API is not available
if (![someData respondsToSelector:@selector(base64EncodedDataWithOptions:)])
{
  // Use the old API
  base64String = [someData base64Encoding];
}
else
 
#endif
 
{
  // Use the new API
  base64String = [someData base64EncodedDataWithOptions:0];
}

See what we did there? We reversed the respondsToSelector: test to see if the new API isn’t available, then put that whole branch inside a conditional code block that is only compiled if the deployment target is less than iOS 7. If the app is built for iOS 6, it will check if the new API doesn’t exist first and call the old one if not. If the app is built for iOS 7, that whole piece of logic is skipped and we just call the new API.

Additional Reading

Apple has a brief write up on Finding Instances of Deprecated API Usage and related compiler warnings.

Nick Lockwood is the author of iOS Core Animation: Advanced Techniques. Nick also wrote iCarousel, iRate and other Mac and iOS open source projects.

2 comments

How can I replace deprecated method dispatch_get_current_queue() from ios5 to ios6 in iphone?

by Phyllis Gallagher on Feb 14, 2014. Reply #

@phyillis there are two parts to this question, really: 1) how to detect if the function is available, and 2) what to use instead.

1) To detect if a C-style function is available, you can check if it’s address is NULL. So this should work:

if (&dispatch_get_current_queue)
{
//function exists and we can call it
}

2) As far as I know, there is no direct replacement for dispatch_get_current_queue. It’s deprecated because it was only intended for debugging. Depending on exactly what you are trying to do, you can achieve similar things by using [NSThread currentThread] or [NSOperationQueue currentQueue].

by Nick Lockwood on Feb 15, 2014. Reply #