Core Foundation URL Access Utilities Reference

Framework	CoreFoundation/CoreFoundation.h
Declared in	CFURLAccess.h

Overview

Core Foundation URL Access Utilities give you convenient system-independent methods of creating, reading, updating, or deleting a URL resource.

Given a CFURL object that holds either a file or http URL, you can read the resource’s data with the CFURLCreateDataAndPropertiesFromResource function. You can write data to the URL resource, possibly creating a new file, with the CFURLWriteDataAndPropertiesToResource function. Finally, you can destroy, or delete, the resource pointed to by the URL with the CFURLDestroyResource function.

Functions

CFURLCreateDataAndPropertiesFromResource

Loads the data and properties referred to by a given URL.

Boolean CFURLCreateDataAndPropertiesFromResource (
   CFAllocatorRef alloc,
   CFURLRef url,
   CFDataRef *resourceData,
   CFDictionaryRef *properties,
   CFArrayRef desiredProperties,
   SInt32 *errorCode
);

Parameters

allocator: The allocator to use to allocate memory for the new CFData and CFDictionary objects returned in resourceData and properties. Pass NULL or kCFAllocatorDefault to use the current default allocator.
url: The URL referring to the data and/or properties you wish to load.
resourceData: On return, contains a CFData object containing the data referred to by url. Ownership follows the Create Rule.
properties: On return, a pointer to a CFDictionary object containing the resource properties referred to by url. Ownership follows the Create Rule.
desiredProperties: A list of the properties you wish to obtain and return in properties. See “File URL Properties” and “HTTP URL Properties” for the list of available properties.
errorCode: 0 if successful, otherwise an error code indicating the nature of the problem. See “Error Codes” for a list of possible error codes.

Return Value

true if successful, false otherwise.

Discussion

If you are interested in loading only the resource data or the resource's properties, pass NULL for the one you don't want. If properties is non-NULL and desiredProperties is NULL then all properties are fetched. Note that as much work as possible is done even if false is returned. For instance, if one property is not available, the others are fetched anyway. This function is intended for convenience, not performance.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Sampler Unit Presets (LoadPresetDemo)

Declared In

CFURLAccess.h

CFURLCreatePropertyFromResource

Returns a given property specified by a given URL and property string.

CFTypeRef CFURLCreatePropertyFromResource (
   CFAllocatorRef alloc,
   CFURLRef url,
   CFStringRef property,
   SInt32 *errorCode
);

Parameters

allocator: The allocator to use to to allocate memory for the new CFType object for the requested property. Pass NULL or kCFAllocatorDefault to use the current default allocator.
url: The CFURL object referring to the resource whose properties are loaded.
property: The name of the property you wish to load. Pass one of the provided string constants indicating the property. See “File URL Properties” and “HTTP URL Properties” for the list of available properties.
errorCode: On return, 0 if successful, otherwise an error code indicating the nature of the problem. See “Error Codes” for a list of possible error codes.

Return Value

If successful, the requested property as a CFType object, NULL otherwise. Ownership follows the Create Rule.

Discussion

This is a convenience function for retrieving individual property values which calls through to CFURLCreateDataAndPropertiesFromResource.

Availability

Available in iOS 2.0 and later.

Declared In

CFURLAccess.h

CFURLDestroyResource

Destroys a resource indicated by a given URL.

Boolean CFURLDestroyResource (
   CFURLRef url,
   SInt32 *errorCode
);

Parameters

url: The CFURL object of the resource to destroy.
errorCode: On return, 0 if successful, otherwise an error code indicating the nature of the problem. See “Error Codes” for a list of possible error codes.

Return Value

true if successful, false otherwise.

Discussion

If url uses an http scheme, an http DELETE request is sent to the resource. If url uses a file scheme, then:

if the reference is a file, the file is deleted;
if the reference is a directory and the directory is empty, the directory is deleted;
if the reference is a directory and the directory is not empty, the function returns false and errorCode contains kCFURLUnknownError.

Availability

Available in iOS 2.0 and later.

Declared In

CFURLAccess.h

CFURLWriteDataAndPropertiesToResource

Writes the given data and properties to a given URL.

Boolean CFURLWriteDataAndPropertiesToResource (
   CFURLRef url,
   CFDataRef dataToWrite,
   CFDictionaryRef propertiesToWrite,
   SInt32 *errorCode
);

Parameters

url: The resource to write.
dataToWrite: The data to write. Pass NULL to write only properties.
propertiesToWrite: The properties to write. Pass NULL to write only data. See “File URL Properties” and “HTTP URL Properties” for the list of available properties.
errorCode: Upon return, 0 if successful, otherwise contains an error code indicating the nature of the problem. See “Error Codes” for a list of possible error codes.

Return Value

true if successful, false otherwise.

Discussion

Properties not present in propertiesToWrite are left unchanged, hence if propertiesToWrite is NULL or empty, the URL's properties are not changed at all.

If url uses a file scheme and it references a file, the contents of dataToWrite are written to the referenced file, overwriting any preexisting data, and the file’s properties are modified according to propertiesToWrite. If the file does not exist, but all intermediate directories along the path do already exist, the file is created (otherwise it is not).

If url uses a file scheme and it references a directory (the last path character is "/"), the contents of dataToWrite are ignored, but if the parameter value is not NULL—and all intermediate directories along the path do already exist—a new directory is created (otherwise it is not).

If url uses an http scheme, an http PUT request is sent to the resource with propertiesToWrite as the header fields and dataToWrite as the data.

Availability

Available in iOS 2.0 and later.

Declared In

CFURLAccess.h

Constants

Error Codes

CFURL error codes.

enum CFURLError {
   kCFURLUnknownError = -10,
   kCFURLUnknownSchemeError = -11,
   kCFURLResourceNotFoundError = -12,
   kCFURLResourceAccessViolationError = -13,
   kCFURLRemoteHostUnavailableError = -14,
   kCFURLImproperArgumentsError = -15,
   kCFURLUnknownPropertyKeyError = -16,
   kCFURLPropertyKeyUnavailableError = -17,
   kCFURLTimeoutError = -18
};
typedef enum CFURLError CFURLError;

Constants

kCFURLUnknownError

Indicates an unknown error.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLUnknownSchemeError

Indicates that the scheme is not recognized.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLResourceNotFoundError

Indicates a resource was not found.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLResourceAccessViolationError

Indicates an error in accessing a resource.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLRemoteHostUnavailableError

Indicates a remote host is unavailable.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLImproperArgumentsError

Indicates one or more arguments are improper.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLUnknownPropertyKeyError

Indicates a property key is unknown.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLPropertyKeyUnavailableError

Indicates a property key was unavailable.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLTimeoutError

Indicates a timeout.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

Availability

Available in OS X version 10.0 and later.

Declared In

CFURLAccess.h

File URL Properties

Properties for file URL resources.

const CFStringRef kCFURLFileExists;
const CFStringRef kCFURLFileDirectoryContents;
const CFStringRef kCFURLFileLength;
const CFStringRef kCFURLFileLastModificationTime;
const CFStringRef kCFURLFilePOSIXMode;
const CFStringRef kCFURLFileOwnerID;

Constants

kCFURLFileExists

A CFBoolean object indicating whether the file referred to by a URL exists.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLFileDirectoryContents

A CFArray object holding CFURL objects for the contents of a directory referred to by a URL.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLFileLength

A CFNumber object holding the file’s length in bytes.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLFileLastModificationTime

A CFDate object holding the file’s modification time.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLFilePOSIXMode

A CFNumber holding the file’s POSIX mode as given in /usr/include/sys/stat.h.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLFileOwnerID

A CFNumber holding the file owner's UID.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

Availability

Available in OS X version 10.0 and later.

Declared In

CFURLAccess.h

HTTP URL Properties

Properties for HTTP URL resources.

const CFStringRef kCFURLHTTPStatusCode;
const CFStringRef kCFURLHTTPStatusLine;

Constants

kCFURLHTTPStatusCode

A CFNumber object holding the status code of an HTTP request.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

kCFURLHTTPStatusLine

A CFString object holding the status line of an HTTP request.

Available in iOS 2.0 and later.

Declared in CFURLAccess.h.

Discussion

In addition to the above properties, each field within an HTTP request or response header is itself a property. You can specify a header field by using the field name as the property name.

Availability

Available in OS X version 10.0 and later.

Declared In

CFURLAccess.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.