CFURL

CFURL
Name	CFURL
Type	Core Foundation type
Developer	Apple Inc.
First appeared	Mac OS X 10.0
Programming languages	C, Objective-C, Swift
Platform	Darwin, iOS, macOS
License	Proprietary

CFURL

CFURL is a Core Foundation opaque type used by Apple Inc. frameworks to represent Uniform Resource Locators and file system paths. Designed for low-level C APIs, CFURL interoperates with higher-level Foundation classes and system services such as Core Services and URL Loading System. CFURL underpins features in AppKit, UIKit, Launch Services, and APIs used by Xcode-built applications.

Overview

CFURL encapsulates a string-based resource identifier with metadata that describes scheme, host, path, query, fragment, and file system representation. It coexists with Foundation’s NSURL and provides functions for parsing, resolving, and normalizing URIs compliant with RFC standards used by HTTP, FTP, file and custom schemes registered with Launch Services. CFURL is used extensively by system components including Spotlight, Core Data, AVFoundation, and the File System Events API.

Creation and Initialization

CFURL objects are created via constructor functions exposed in Core Foundation. Common functions include creators that accept a bytes buffer, a CFString encoding, or file system path representations. Typical initialization patterns mirror those in NSURL and are used in codebases that bridge to Objective‑C or Swift runtimes. CFURL supports creation from absolute and relative strings, separators and base URLs such as URLs provided by NSFileManager and entries returned from File Manager APIs. It also supports creation from components derived from network APIs such as requests from CFHTTPMessage and responses consumed by CFNetwork.

File System and URL Representations

CFURL exposes file system-specific semantics including POSIX-style paths and URL-encoded representations used by HFS+, APFS, and network file systems like SMB and NFS. It handles path normalization, resolving symbolic links and tilde expansion common to user home directories in macOS, and provides conversion helpers between file system references (FSRef) used historically by Carbon and modern URL-based APIs used by Cocoa. CFURL also interoperates with URL schemes commonly handled by Launch Services for determining application handlers and by UTI lookups for content type.

Resource Access and Manipulation

CFURL is frequently used as a key or parameter for resource-access APIs. It integrates with I/O layers such as CFReadStream, CFWriteStream, and CFHTTPStream to open, read, and write data. Developers use CFURL with file coordination services like NSFileCoordinator and with sandboxing components used by App Sandbox to manage secure file access. CFURL supports resolving relative references against base URLs, retrieving path components, extracting host and port information for network endpoints, and constructing query strings compatible with HTTP requests handled by NSURLSession or legacy CFURLConnection wrappers.

Memory Management and Toll-Free Bridging

CFURL follows Core Foundation memory conventions where ownership is transferred according to "Create" and "Copy" rule semantics, requiring explicit release via CFRelease in unmanaged contexts. CFURL is toll-free bridged to NSURL in many cases, enabling seamless interchange between C APIs and Objective‑C objects when bridged casts are used. Care must be taken when bridging across Automatic Reference Counting boundaries in Objective‑C and when using bridged types in Swift to avoid retain cycles or premature deallocation, especially for callbacks registered with RunLoop or dispatch queues.

Error Handling and Security Considerations

CFURL routines return status codes and may produce error objects consistent with Core Foundation and Foundation error handling patterns; callers are expected to check return values and inspect CFError or NSError where available. Security considerations include validating hostnames and certificate chains for network-based schemes processed alongside CFNetwork or Security framework APIs, avoiding injection issues in constructed query strings used with HTTP endpoints, and respecting sandbox entitlements mandated by App Sandbox and Gatekeeper policies. Careful handling of user-supplied paths mitigates symlink attacks and path traversal exploited against file system APIs used by macOS and iOS services.

Sample Usage and Code Examples

Sample code typically shows creation, inspection, and bridging. Common examples include creating a CFURL from a file path returned by NSOpenPanel, converting CFURL to CFString components, and opening streams with CFReadStreamCreateWithFile. In bridged Objective‑C code, CFURLRef can be cast to NSURL to access higher-level APIs in Foundation. Example patterns are used in utilities interacting with Launch Services to resolve application handlers, in media apps using AVFoundation to reference assets, and in synchronization clients interfacing with CloudKit or File Provider extensions.

Category:Apple APIs