macOS NSURLSession

From Lazarus wiki

English (en)


This article applies to macOS only.

See also: Multiplatform Programming Guide


The NSURLSession class and related classes provide an API for downloading content via HTTP. The downloading is performed asynchronously, so your application can remain responsive and handle incoming data or errors as they arrive. This class replaces the macOS NSURLConnection class which was deprecated by Apple in macOS 10.11 (El Capitan) in 2015. NSURLSession is available from macOS 10.9 (Mavericks) onwards.

The NSURLSession API is highly asynchronous. If you use the default, system-provided delegate, you must provide a completion handler block that returns data to your application when a transfer finishes successfully or with an error. Alternatively, if you provide your own custom delegate objects, the task objects call those delegates’ methods with data as it is received from the server (or, for file downloads, when the transfer is complete). The NSURLSession API provides status and progress properties, in addition to delivering this information to delegates. It supports cancelling, resuming, and suspending tasks, and it provides the ability to resume suspended, cancelled, or failed downloads where they left off.

The behaviour of the tasks in a session depends on three things:

  1. the type of session (determined by the type of configuration object used to create it),
  2. the type of task, and
  3. whether the application was in the foreground when the task was created.

Types of sessions

The NSURLSession API supports three types of sessions, as determined by the type of configuration object used to create the session:

  1. Default sessions behave similarly to other Foundation methods for downloading URLs. They use a persistent disk-based cache and store credentials in the user’s keychain. A default session configuration object results in a session that behaves like an NSURLConnection object in its standard configuration. Altering a session configuration obtained through the defaultSessionConfiguration method does not change the default session configuration of which it is a copy.
  2. Ephemeral sessions do not store any data to disk; all caches, credential stores, and so on are kept in RAM and tied to the session. Thus, when your application invalidates the session, they are purged automatically. Ephemeral sessions are therefore ideal if you need to implement private browsing.
  3. Background sessions are similar to default sessions, except that a separate process handles all data transfers. Background sessions have some additional limitations:
    1. The session must provide a delegate for uploads and downloads.
    2. Only HTTP and HTTPS protocols are supported.
    3. Only upload and download tasks are supported (no data tasks).
    4. Redirects are always followed.
    5. If the background transfer is initiated while the app is in the background, the configuration object’s discretionary property is treated as being true.
    6. Background configurations cannot be reused (ie you cannot use two background session configurations using the same configuration identifier).

Types of Tasks

An NSURLSession supports four types of tasks:

  • data tasks,
  • download tasks,
  • upload tasks, and
  • webSocket tasks.

Data tasks send and receive data using NSData objects. Data tasks are intended for short, often interactive requests to a server. Data tasks can return data to your application one piece at a time after each piece of data is received, or all at once through a completion handler. As data tasks do not store the data to a file, they are not supported in background sessions.

Download tasks retrieve data in the form of a file, and support background downloads.

Upload tasks send data (usually in the form of a file), and support background uploads.

Web socket tasks exchange messages over TCP and TLS, using the WebSocket protocol defined in RFC 6455.


The NSURLSession API is highly asynchronous. It returns data to your application in one of two ways, depending on the methods you call:

  • by calling a completion handler block when a transfer finishes successfully or with an error; or
  • by calling methods on the session’s delegate as data arrives and when the transfer is complete.

In addition to delivering this information to delegates, the NSURLSession provides status and progress properties that you can query if you need to make programmatic decisions based on the current state of the task (with the caveat that its state can change at any time).

Protocol support

An NSURLSession natively supports the data, file, ftp, http, and https URL schemes, with transparent support for proxy servers and SOCKS gateways, as configured in the user’s system preferences. It supports HTTP/1.1 and HTTP/2 protocols. HTTP/2, described in RFC 7540, requires a server that supports Application-Layer Protocol Negotiation (ALPN).

Creating a session

The NSURLSession API provides a wide range of configuration options:

  • Private storage support for caches, cookies, credentials, and protocols in a way that is specific to a single session.
  • Authentication, tied to a specific request (task) or group of requests (session).
  • File uploads and downloads by URL, which encourages separation of the data (the file’s contents) from the metadata (the URL and settings).
  • Configuration of the maximum number of connections per host.
  • Per-resource timeouts that are triggered if an entire resource cannot be downloaded in a certain amount of time.
  • Minimum and maximum TLS version support Custom proxy dictionaries.
  • Control over cookie policies.
  • Control over HTTP pipelining behaviour.

When you instantiate a session object, you specify the following:

  • A configuration object that governs the behaviour of that session and the tasks within it
  • Optionally, a delegate object to process incoming data as it is received and handle other events specific to the session and the tasks within it, such as server authentication, determining whether a resource load request should be converted into a download, and so on.
  • If you do not provide a delegate, the NSURLSession object uses a system-provided delegate. In this way, you can readily use NSURLSession in place of existing code that uses the sendAsynchronousRequest:queue:completionHandler: convenience method on NSURLSession.

As these settings are contained in a separate configuration object, you can reuse commonly used settings in other sessions.

Retrieving data using system-provided delegates

This simple demonstration shows how to use NSURLSession and related classes to download and display a web page using NSURLSession as a drop-in replacement for the NSURLConnection sendAsynchronousRequest:queue:completionHandler: method. Using this method, you need to provide only two pieces of code in your application:

  1. code to create a configuration object and a session based on that object; and
  2. code to implement a completion handler routine to do something with the data after it has been fully received.

Example code

unit Unit1;

{$mode objfpc}{$H+}
{$modeswitch objectivec1}
{$modeswitch cblocks}


  Forms,      // for the main form
  Dialogs,    // for ShowMessage
  StdCtrls,   // for the button
  SysUtils,   // for IntToStr()
  CocoaAll,   // for NSData and other Cocoa types
  CocoaUtils; // for NSStringString

  // setup cBlock for completion handler
  tblock = reference to procedure(data: NSData; response: NSURLResponse; connectionError: NSError); cdecl; cblock;

  // redefine version from packages/cocoaint/src/foundation/
  NSURLSession = objcclass external (NSObject)
    class function sessionWithConfiguration(configuration: NSURLSessionConfiguration): NSURLSession; 
      message 'sessionWithConfiguration:';

  NSURLSessionAsynchronousConvenience = objccategory external (NSURLSession)
    function dataTaskWithURL_completionHandler(url: NSURL; completionHandler: tBlock): NSURLSessionDataTask; 
      message 'dataTaskWithURL:completionHandler:';

  { TForm1 }

  TForm1 = class(TForm)
    Button1: TButton;
    procedure Button1Click(Sender: TObject);



  Form1: TForm1;
  myCache: NSURLcache;
  webData: String;
  webResponse: String;
  webHTML: String;
  webStatusCode: Integer;
  webError: String;
  webErrorReason: String;
  didFinish: PRTLEvent;


{$R *.lfm}

{ TForm1 }


// Completion handler: Executed after URL has been retrieved or retrieval fails
procedure myCompletionHandler(data: NSData; response: NSURLResponse; connectionError: NSError);
  httpResponse: NSHTTPURLResponse;
  NSLog(NSStr('entering completion handler'));

  // if no error
  if((data.Length > 0) and (connectionError = Nil)) then
      {$IFDEF DEBUG}
      webData     :=  NSStringToString(data.description);
      {$IFDEF DEBUG}
      NSLog(NSStr('Web data' + webData));

      // The NSHTTPURLResponse class is a subclass of NSURLResponse
      // so we can cast an NSURLResponse as an NSHTTPURLResponse
      httpResponse := NSHTTPURLResponse(response);

      // Extract status code from response header
      {$IFDEF DEBUG}

      webStatusCode :=  httpResponse.statusCode;
      webResponse   :=  NSStringToString(response.description);
      webHTML       :=  NSSTringToString(NSString.alloc.initWithData(data,NSUTF8StringEncoding));
  // o/w return error
      {$IFDEF DEBUG}
      NSLog(NSStr('Error %@'), connectionError.userInfo);

      webError := 'Error description: ' + LineEnding +  NSStringToString(connectionError.description);
      webErrorReason := 'Error retrieving: ' + NSStringToString(connectionError.userInfo.valueForKey(NSErrorFailingUrlStringKey))
        + LineEnding + LineEnding + 'Reason: ' + NSStringToString(connectionError.localizedDescription);

  // notify main thread that completion handler thread has finished

  NSLog(NSStr('leaving completion handler'));

// Retrieve web page
procedure TForm1.Button1Click(Sender: TObject);
  urlSessionConfig: NSURLSessionConfiguration;
  cachePath: NSString;
  urlSession: NSURLSession;
  // create event to synchronise completion handler background thread
  // with the GUI main thread
  didFinish := RTLEventCreate;  

  // create default url session config
  urlSessionConfig := NSURLSessionConfiguration.defaultSessionConfiguration;

  // configure caching behavior for the default session
  cachePath := NSTemporaryDirectory.stringByAppendingPathComponent(NSStr('/nsurlsessiondemo.cache'));

  NSLog(NSStr('Cache path: %@'), cachePath);

  myCache := NSURLCache.alloc.initWithMemoryCapacity_diskCapacity_diskPath(16384, 268435456, cachePath);

  // set cache policy

  // create a session for configuration
  urlSession := NSURLSession.sessionWithConfiguration(urlSessionConfig);

  // create NSURL
  URL := NSURL.URLWithString(NSSTR(PAnsiChar('')));
  if(Url = Nil) then
      ShowMessage('NSURL.URLWithString failed!');

  // setup and execute (resume) data task
  urlSession.dataTaskWithURL_completionHandler(URL, @myCompletionHandler).resume;

  // wait for completion handler to finish

  // display results
  if(webErrorReason <> '') then
      ShowMessage('HTTP status code: ' + IntToStr(webStatusCode) + LineEnding
        + LineEnding + 'Raw data: ' + LineEnding + webData);
      ShowMessage('Response: ' + LineEnding + LineEnding + webResponse);
      ShowMessage('Web page: ' + LineEnding + LineEnding + webHTML);

  // housekeeping

  // housekeeping

To compile the above code successfully you are going to have to add the missing initWithData function to the NSString class by editing /usr/local/share/fpcsrc/fpc-[3.0.4|3.2.0|3.3.1]/packages/cocoaint/src/foundation/ to add the missing (highlighted) function as follows:

---        (revision 45778)
+++        (working copy)
@@ -105,6 +105,7 @@
     function characterAtIndex (index: NSUInteger): unichar; message 'characterAtIndex:';
     function init: instancetype; message 'init'; { NS_DESIGNATED_INITIALIZER }
     function initWithCoder (aDecoder: NSCoder): instancetype; message 'initWithCoder:'; { NS_DESIGNATED_INITIALIZER }
+    function initWithData(data: NSData; encoding: NSStringEncoding) : instancetype; message 'initWithData:encoding:';
     { Adopted protocols }
     function copyWithZone (zone: NSZonePtr): id; message 'copyWithZone:';

and then recompile the FPC source. This has been tested with FPC 3.0.4, FPC 3.2.0 and FPC 3.3.1. Note that for FPC 3.0.4 you need to replace "instancetype" in the highlighted line with "id"

I use the following script (for FPC 3.3.1; substitute your FPC version numbers as appropriate) to recompile FPC:

cd /usr/local/share/fpcsrc/fpc-3.3.1/
make clean all FPC=/usr/local/lib/fpc/3.3.1/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64 OPT="-XR/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/"
make install FPC=/usr/local/lib/fpc/3.3.1/ppcx64 OS_TARGET=darwin CPU_TARGET=x86_64
  • Note 1: The highlighted line(s) above should be all on one line.
  • Note 2: You will almost certainly have to use sudo to execute that script successfully or face permissions problems.

Retrieving data using a custom delegate

When using a custom delegate to retrieve data, the delegate must implement at least the following methods:

  • URLSession:dataTask:didReceiveData: Tells the delegate that the data task has received some of the expected data.
  • URLSession:task:didCompleteWithError: Tells the delegate that the data task finished transferring the data.

If you don’t need the features provided by a delegate, you can use this API without providing one by passing nil when you create a session.

Example code

To come.

See also

External links