iOS5 NSURLConnection methods deprecated

I'm trying to write an iOS app that makes asynchronous requests to get data over the network. It seems like a lot of people recommend using NSURLConnection for this, and frequently mention the delegate method connection:didReceiveData:.

Unfortunately, I cannot for the life of me find out where this delegate method is documented. For one, it is not in the protocol reference for NSURLConnectionDelegate. It is listed in the NSURLConnection Class Reference, but has apparently been deprecated as of iOS5. The documentation does not explain why it was deprecated, or what developers should use instead to achieve similar functionality.

What am I missing? A lot of what I've read seems to imply that big changes were made to NSURLConnection for iOS5. Where are these changes documented? Is the documentation of delegate methods complete?

Thanks

Fishing around the header files tells me that the methods were moved from an informal protocol (which is a deprecated Obj-C pattern) into a formal delegate protocol called NSURLConnectionDataDelegate that's in NSURLConnection.h, but doesn't have a public documentation.

The rest of the documentation keeps using the methods as before, so my guess is this is an omission in the documentation. I.e. the methods (mostly) aren't going anywhere, they were just reshuffled into several protocols and the documentation team has been slacking off. Try making your delegate object conform to the appropriate protocol, and implement the methods with the signatures from the header file.

Documentation is indeed a mess, although looking at the changelog from 4.3 to 5.0 for NSURLConnection.h:

Removed

Removed -[NSObject connection:canAuthenticateAgainstProtectionSpace:]
Removed -[NSObject connection:didCancelAuthenticationChallenge:]
Removed -[NSObject connection:didFailWithError:]
Removed -[NSObject connection:didReceiveAuthenticationChallenge:]
Removed -[NSObject connection:didReceiveData:]
Removed -[NSObject connection:didReceiveResponse:]
Removed -[NSObject connection:didSendBodyData:totalBytesWritten:totalBytesExpectedToWrite:]
Removed -[NSObject connection:needNewBodyStream:]
Removed -[NSObject connection:willCacheResponse:]
Removed -[NSObject connection:willSendRequest:redirectResponse:]
Removed -[NSObject connectionDidFinishLoading:]
Removed -[NSObject connectionShouldUseCredentialStorage:]
Removed NSObject(NSURLConnectionDelegate)

Added

Added -[NSURLConnection currentRequest]
Added -[NSURLConnection originalRequest]
Added +[NSURLConnection sendAsynchronousRequest:queue:completionHandler:]
Added -[NSURLConnection setDelegateQueue:]
Added NSURLConnectionDataDelegate
Added -[NSURLConnectionDataDelegate connection:didReceiveData:]
Added -[NSURLConnectionDataDelegate connection:didReceiveResponse:]
Added -[NSURLConnectionDataDelegate connection:didSendBodyData:totalBytesWritten:totalBytesExpectedToWrite:]
Added -[NSURLConnectionDataDelegate connection:needNewBodyStream:]
Added -[NSURLConnectionDataDelegate connection:willCacheResponse:]
Added -[NSURLConnectionDataDelegate connection:willSendRequest:redirectResponse:]
Added -[NSURLConnectionDataDelegate connectionDidFinishLoading:]
Added NSURLConnectionDelegate
Added -[NSURLConnectionDelegate connection:canAuthenticateAgainstProtectionSpace:]
Added -[NSURLConnectionDelegate connection:didCancelAuthenticationChallenge:]
Added -[NSURLConnectionDelegate connection:didFailWithError:]
Added -[NSURLConnectionDelegate connection:didReceiveAuthenticationChallenge:]
Added -[NSURLConnectionDelegate connection:willSendRequestForAuthenticationChallenge:]
Added -[NSURLConnectionDelegate connectionShouldUseCredentialStorage:]
Added NSURLConnectionDownloadDelegate
Added -[NSURLConnectionDownloadDelegate connection:didWriteData:totalBytesWritten:expectedTotalBytes:]
Added -[NSURLConnectionDownloadDelegate connectionDidFinishDownloading:destinationURL:]
Added -[NSURLConnectionDownloadDelegate connectionDidResumeDownloading:totalBytesWritten:expectedTotalBytes:]
Added NSURLConnection(NSURLConnectionQueuedLoading)

So it seems those functions are indeed still there. Just add the protocols to your @interface declaration and you should be good to go.

I tried the new NSURLConnectionDownloadDelegate, be warned that if these methods are present in your delegate, your NSURLConnectionDataDelegate methods will NOT be called.

I also had issue opening the destinationURL, iOS kept telling me the file did not exist although the documentation indicates the file is guaranteed to exist during the method call.

The documentation is a @$@#$ mess. That's the real story.

The Documentation on NSURLConnection, as written, leaves you high and dry.

The first part of the documentation tells you to use various methods in the NSURLConnection protocol (like connection:didReceiveData:) to handle incoming data. If you click on any of those methods in the overview, it leads you to a list of DEPRECATED METHODS!)

The real story that I've been able to piece together is that most of the methods formerly in NSURLConnectionProtocol have been moved to a new protocol called NSURLConnectionDataProtocol. Unfortunately, that new protocol is either not documented, or it's not indexed, so you can't find it. Which amounts to the same thing.)

In other interesting news, there is apparently a new protocol called NSURLConnectionDownloadDelegate. It sounds like NSURLConnection for iOS is adding some of the functionality that is available in NSURLDownload in MacOS. The NSURLConnectionDownloadDelegate protocol IS documented.

You would think deprecating those methods from NSURLConnection would warrant some kind of explainer, but I have not yet found one. The best I could do so far is from Apple's URL Loading System Programming Guide:

> In order to download the contents of a URL, an application needs to provide a delegate object that, at a minimum, implements the following delegate methods: connection:didReceiveResponse:, connection:didReceiveData:, connection:didFailWithError: and connectionDidFinishLoading:

which implies an informal protocol.