Core Foundation URL Access Utilities Reference

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.

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.

Related Sample Code

• AuthForAll
• GLUT
• HID Config Save
• HID Utilities Source
• MoreSCF

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.

Discussion

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

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.

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.

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.

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.

Related Sample Code

• CFPrefTopScores
• HID Calibrator
• HID Config Save
• HID Dumper
• SeeMyFriends

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 Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLUnknownSchemeError

Indicates that the scheme is not recognized.

Available in Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLResourceNotFoundError

Indicates a resource was not found.

Available in Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLResourceAccessViolationError

Indicates an error in accessing a resource.

Available in Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLRemoteHostUnavailableError

Indicates a remote host is unavailable.

Available in Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLImproperArgumentsError

Indicates one or more arguments are improper.

Available in Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLUnknownPropertyKeyError

Indicates a property key is unknown.

Available in Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLPropertyKeyUnavailableError

Indicates a property key was unavailable.

Available in Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLTimeoutError

Indicates a timeout.

Available in Mac OS X v10.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 Mac OS X v10.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 Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLFileLength

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

Available in Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLFileLastModificationTime

A CFDate object holding the file’s modification time.

Available in Mac OS X v10.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 Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLFileOwnerID

A CFNumber holding the file owner's UID.

Available in Mac OS X v10.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 Mac OS X v10.0 and later.

Declared in CFURLAccess.h.

kCFURLHTTPStatusLine

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

Available in Mac OS X v10.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.

---