Mac Developer Library

Developer

CoreFoundation Framework Reference Core Foundation URL Access Utilities Reference

Options
Deployment Target:

On This Page

Core Foundation URL Access Utilities Reference

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

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

    Declaration

    Objective-C

    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 in Memory Management Programming Guide for Core Foundation.

    properties

    On return, a pointer to a CFDictionary object containing the resource properties referred to by url. Ownership follows the Create Rule in Memory Management Programming Guide for Core Foundation.

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

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

    Declaration

    Objective-C

    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 in Memory Management Programming Guide for Core Foundation.

    Discussion

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • Destroys a resource indicated by a given URL.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • Writes the given data and properties to a given URL.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

Constants

Miscellaneous

  • CFURL error codes.

    Declaration

    Objective-C

    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

      kCFURLUnknownError

      Indicates an unknown error.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLUnknownSchemeError

      kCFURLUnknownSchemeError

      Indicates that the scheme is not recognized.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLResourceNotFoundError

      kCFURLResourceNotFoundError

      Indicates a resource was not found.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLResourceAccessViolationError

      kCFURLResourceAccessViolationError

      Indicates an error in accessing a resource.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLRemoteHostUnavailableError

      kCFURLRemoteHostUnavailableError

      Indicates a remote host is unavailable.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLImproperArgumentsError

      kCFURLImproperArgumentsError

      Indicates one or more arguments are improper.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLUnknownPropertyKeyError

      kCFURLUnknownPropertyKeyError

      Indicates a property key is unknown.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLPropertyKeyUnavailableError

      kCFURLPropertyKeyUnavailableError

      Indicates a property key was unavailable.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLTimeoutError

      kCFURLTimeoutError

      Indicates a timeout.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    Import Statement

    Availability

    Available in OS X version 10.0 and later.

  • Properties for file URL resources.

    Declaration

    Objective-C

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

    Constants

    • kCFURLFileExists

      kCFURLFileExists

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLFileDirectoryContents

      kCFURLFileDirectoryContents

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLFileLength

      kCFURLFileLength

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLFileLastModificationTime

      kCFURLFileLastModificationTime

      A CFDate object holding the file’s modification time.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLFilePOSIXMode

      kCFURLFilePOSIXMode

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLFileOwnerID

      kCFURLFileOwnerID

      A CFNumber holding the file owner's UID.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    Import Statement

  • Properties for HTTP URL resources.

    Declaration

    Objective-C

    const CFStringRef kCFURLHTTPStatusCode; const CFStringRef kCFURLHTTPStatusLine;

    Constants

    • kCFURLHTTPStatusCode

      kCFURLHTTPStatusCode

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCFURLHTTPStatusLine

      kCFURLHTTPStatusLine

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    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.

    Import Statement