<!--
{
  "availability" : [
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSURLHandle",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSURLHandle"
  },
  "title" : "NSURLHandle"
}
-->

# NSURLHandle

An object that accesses and manages resource data indicated by a URL.

```
class NSURLHandle
```

## Overview> Important:
> ``doc://com.apple.foundation/documentation/Foundation/NSURLHandle`` is deprecated in macOS 10.4 and later. Use ``doc://com.apple.foundation/documentation/Foundation/URLSession`` instead.

A single [`NSURLHandle`](/documentation/Foundation/NSURLHandle) can service multiple equivalent [`NSURL`](/documentation/Foundation/NSURL) objects, but only if these URLs map to the same resource.

### Overview

Cocoa provides private concrete subclasses to handle HTTP and file URL schemes. If you want to implement support for additional URL schemes, you would do so by creating a subclass of `NSURLHandle`. You can use `NSURL` and `NSURLHandle` to download from FTP sites without subclassing.

## Topics

### Constructing NSURLHandles

[`+  cachedHandleForURL:`](/documentation/Foundation/NSURLHandle/cachedHandleForURL:)

Returns the URL handle from the cache that has serviced the specified URL or another identical URL.

[`-  initWithURL:cached:`](/documentation/Foundation/NSURLHandle/initWithURL:cached:)

Initializes a newly created URL handle with the specified URL.

### Managing subclasses

[`+  URLHandleClassForURL:`](/documentation/Foundation/NSURLHandle/URLHandleClassForURL:)

Returns the class of the URL handle that will be used for a specified URL.

[`+  canInitWithURL:`](/documentation/Foundation/NSURLHandle/canInitWithURL:)

Returns whether a URL handle can be initialized with a given URL.

[`+  registerURLHandleClass:`](/documentation/Foundation/NSURLHandle/registerURLHandleClass:)

Registers a subclass of `NSURLHandle` as an available subclass for handling URLs

### Managing clients

[`-  addClient:`](/documentation/Foundation/NSURLHandle/addClient:)

Adds a client of the URL handle.

[`-  removeClient:`](/documentation/Foundation/NSURLHandle/removeClient:)

Removes `client` as an `NSURLHandleClient` of the receiver.

### Setting and getting resource properties

[`-  propertyForKey:`](/documentation/Foundation/NSURLHandle/propertyForKey:)

Returns the property for the specified key.

[`-  propertyForKeyIfAvailable:`](/documentation/Foundation/NSURLHandle/propertyForKeyIfAvailable:)

Returns the property for the specified key only if the value is already available; that is, the client doesn’t need to do any work.

[`-  writeProperty:forKey:`](/documentation/Foundation/NSURLHandle/writeProperty:forKey:)

Sets the property of the receiver’s resource for a specified key to the specified value.

### Loading resource data

[`-  availableResourceData`](/documentation/Foundation/NSURLHandle/availableResourceData)

Immediately returns the currently available resource data managed by the URL handle.

[`-  backgroundLoadDidFailWithReason:`](/documentation/Foundation/NSURLHandle/backgroundLoadDidFailWithReason:)

Called when a background load fails.

[`-  beginLoadInBackground`](/documentation/Foundation/NSURLHandle/beginLoadInBackground)

Called when a background load begins.

[`-  cancelLoadInBackground`](/documentation/Foundation/NSURLHandle/cancelLoadInBackground)

Called to cancel a load currently in progress.

[`-  didLoadBytes:loadComplete:`](/documentation/Foundation/NSURLHandle/didLoadBytes:loadComplete:)

Appends new data to the receiver’s resource data.

[`-  endLoadInBackground`](/documentation/Foundation/NSURLHandle/endLoadInBackground)

Halts any background loading.

[`-  expectedResourceDataSize`](/documentation/Foundation/NSURLHandle/expectedResourceDataSize)

Returns the expected length of the resource data if it is provided by the server.

[`-  failureReason`](/documentation/Foundation/NSURLHandle/failureReason)

Returns a string describing the reason a load failed.

[`-  flushCachedData`](/documentation/Foundation/NSURLHandle/flushCachedData)

Flushes any cached data for the URL served by this URL handle.

[`-  loadInBackground`](/documentation/Foundation/NSURLHandle/loadInBackground)

Loads the receiver’s data in the background.

[`-  loadInForeground`](/documentation/Foundation/NSURLHandle/loadInForeground)

Loads the receiver’s data synchronously.

[`-  resourceData`](/documentation/Foundation/NSURLHandle/resourceData)

Returns the resource data managed by the receiver, loading it if necessary.

[`-  status`](/documentation/Foundation/NSURLHandle/status-c.method)

Returns the status of the receiver.

[`Status`](/documentation/Foundation/NSURLHandle/Status-swift.enum)

These following constants are defined by `NSURLHandle` and are returned by [`status`](/documentation/Foundation/NSURLHandle/status-c.method).

### Writing resource data

[`-  writeData:`](/documentation/Foundation/NSURLHandle/writeData:)

Attempts to write a specified set of data to the location specified by the receiver’s URL.

### Resource Property Keys

[`NSFTPPropertyActiveTransferModeKey`](/documentation/Foundation/NSFTPPropertyActiveTransferModeKey)

Key for retrieving whether in active transfer mode, returned as a boolean wrapped in an `NSNumber` object.

[`NSFTPPropertyFTPProxy`](/documentation/Foundation/NSFTPPropertyFTPProxy)

`NSDictionary` containing proxy information to use in place of proxy identified in `SystemConfiguration.framework`.

[`NSFTPPropertyFileOffsetKey`](/documentation/Foundation/NSFTPPropertyFileOffsetKey)

Key for retrieving the file offset, returned as an `NSNumber` object. The default value for this key is zero.

[`NSFTPPropertyUserLoginKey`](/documentation/Foundation/NSFTPPropertyUserLoginKey)

Key for the user login, returned as an `NSString` object.

[`NSFTPPropertyUserPasswordKey`](/documentation/Foundation/NSFTPPropertyUserPasswordKey)

Key for the user password, returned as an `NSString` object.

[`NSHTTPPropertyErrorPageDataKey`](/documentation/Foundation/NSHTTPPropertyErrorPageDataKey)

Key for retrieving an error page as an `NSData` object.

[`NSHTTPPropertyHTTPProxy`](/documentation/Foundation/NSHTTPPropertyHTTPProxy)

Key for retrieving the `NSDictionary` object containing proxy information to use in place of proxy identified in `SystemConfiguration.framework`.

[`NSHTTPPropertyRedirectionHeadersKey`](/documentation/Foundation/NSHTTPPropertyRedirectionHeadersKey)

Key for retrieving the redirection headers as an `NSDictionary` object with each header value keyed to the header name.

[`NSHTTPPropertyServerHTTPVersionKey`](/documentation/Foundation/NSHTTPPropertyServerHTTPVersionKey)

Key for retrieving the HTTP version as an `NSString` object containing the initial server status line up to the first space.

[`NSHTTPPropertyStatusCodeKey`](/documentation/Foundation/NSHTTPPropertyStatusCodeKey)

Key for the status code, returned as an integer wrapped in an `NSNumber` object.

[`NSHTTPPropertyStatusReasonKey`](/documentation/Foundation/NSHTTPPropertyStatusReasonKey)

Key for the remainder of the HTTP status line following the status code, returned as an `NSString` object.

## Relationships

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

### Conforms To

[`CVarArg`](/documentation/Swift/CVarArg)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`Hashable`](/documentation/Swift/Hashable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Equatable`](/documentation/Swift/Equatable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)