Functions
Abstract: Determines if the specified URL conforms to RFC 1808 and therefore can be decomposed.
Boolean CFURLCanBeDecomposed(CFURLRef anURL);
If a given CFURL can be decomposed, you can ask for each of the four basic pieces separately (scheme, net location, path, and resource specifer), as well as for its base URL.
Parameters
Name | Description |
anURL | The URL to test. |
Result: TRUE if the URL conforms to RFC 1808; otherwise FALSE.
Abstract: Creates a new URL by resolving the relative portion of relativeURL against its base.
CFURLRef CFURLCopyAbsoluteURL(CFURLRef relativeURL);
Parameters
Name | Description |
relativeURL | The URL you wish to resolve. |
Result: The newly created URL.
Abstract: Obtains the path portion of the specified URL.
CFStringRef CFURLCopyFileSystemPath(CFURLRef anURL, CFURLPathStyle pathStyle);
This function returns the URL's path as a file system path for the specified path style.
Parameters
Name | Description |
anURL | The URL whose path you wish to obtain. |
pathStyle | The operating system path style used in the filePath string. See CFURLPathStyle for a list of possible values. |
Result: The URL's path in the format specified by pathStyle.
Abstract: Obtains the fragment from the specified URL.
CFStringRef CFURLCopyFragment(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
A fragment is the text following a "#". These are generally used to indicate locations within a single file. This function removes all percent escape sequences except those for characters specified in charactersToLeaveEscaped.
Parameters
Name | Description |
anURL | The URL whose fragment you wish to obtain. |
charactersToLeaveEscaped | Characters whose escape sequences you wish to leave intact. Pass NULL to request that no percent escapes be replaced, or the empty string (CFSTR("")) to request that all be replaced. |
Result: The fragment; or NULL if no fragment exists.
Abstract: Obtains the hostname from the specified URL.
CFStringRef CFURLCopyHostName(CFURLRef anURL);
Parameters
Name | Description |
anURL | The URL whose hostname you wish to obtain. |
Result: The URL's hostname.
Abstract: Obtains the last path component of the specified URL.
CFStringRef CFURLCopyLastPathComponent(CFURLRef url);
Parameters
Name | Description |
anURL | The URL whose last path component you wish to obtain. |
Result: The URL's last path component.
Abstract: Obtains the net location (IP address or host name) portion of the specified URL.
CFStringRef CFURLCopyNetLocation(CFURLRef anURL);
This function leaves any percent escape sequences intact.
Parameters
Name | Description |
anURL | The URL whose net location you wish to obtain. |
Result: The URL's net location, or NULL if the URL cannot be decomposed (doesn't conform to RFC 1808).
Abstract: Obtains the parameter string from the specified URL.
CFStringRef CFURLCopyParameterString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
This function removes all percent escape sequences except those for characters specified in charactersToLeaveEscaped.
Parameters
Name | Description |
anURL | The URL whose parameter string you wish to obtain. |
charactersToLeaveEscaped | Characters whose escape sequences you wish to leave intact. Pass NULL to request that no percent escapes be replaced, or the empty string (CFSTR("")) to request that all be replaced. |
Result: The parameter string; or NULL if no parameter string exists.
Abstract: Obtains the password from the specified URL.
CFStringRef CFURLCopyPassword(CFURLRef anURL);
Parameters
Name | Description |
anURL | The URL whose password you wish to obtain. |
Result: The password; or NULL if no password exists. In some cases this function may return the empty string (CFSTR("")) instead of NULL. You must be prepared for either one.
Abstract: Obtains the path portion of the specified URL.
CFStringRef CFURLCopyPath(CFURLRef anURL);
This function does not resolve the URL against its base and replaces all percent escape sequences. Note that any leading "/" is not considered part of the URL's path, although its presence or absence determines whether the path is absolute. This function's return value includes any leading slash (giving the path the normal POSIX appearance). If this behaviour is not appropriate, use CFURLCopyStrictPath whose return value omits any leading slash. You may also want to use the function CFURLCopyFileSystemPath which returns the URL's path as a file system path for the given path style.
Parameters
Name | Description |
anURL | The URL whose path you wish to obtain. |
Result: The URL's path, or NULL if the URL cannot be decomposed (doesn't conform to RFC 1808).
Abstract: Obtains the path extension of the specified URL.
CFStringRef CFURLCopyPathExtension(CFURLRef url);
Parameters
Name | Description |
anURL | The URL whose path extension you wish to obtain. |
Result: The URL's path extension.
Abstract: Obtains the query string from the specified URL.
CFStringRef CFURLCopyQueryString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
This function removes all percent escape sequences except those for characters specified in charactersToLeaveEscaped.
Parameters
Name | Description |
anURL | The URL whose query string you wish to obtain. |
charactersToLeaveEscaped | Characters whose escape sequences you wish to leave intact. Pass NULL to request that no percent escapes be replaced, or the empty string (CFSTR("")) to request that all be replaced. |
Result: The query string; or NULL if no parameter string exists.
Abstract: Obtains any additional resource specifiers after the path.
CFStringRef CFURLCopyResourceSpecifier(CFURLRef anURL);
This function leaves any percent escape sequences intact. For URLs that cannot be decomposed, this function returns everything except the scheme itself.
Parameters
Name | Description |
anURL | The URL whose additional resource specifiers you wish to obtain. |
Result: The resources specifiers.
Abstract: Obtains the scheme portion of the specified URL.
CFStringRef CFURLCopyScheme(CFURLRef anURL);
The URL scheme is the portion of the URL specifying the transport type. For example http, ftp, and rtsp are schemes. This function leaves any percent escape sequences intact.
Parameters
Name | Description |
anURL | The URL whose scheme you wish to obtain. |
Result: The scheme of the URL.
Abstract: Obtains the path portion of the specified URL.
CFStringRef CFURLCopyStrictPath(CFURLRef anURL, Boolean *isAbsolute);
This function does not resolve the URL against its base and replaces all percent escape sequences. Note that any leading "/" is not considered part of the URL's path, although its presence or absence determines whether the path is absolute. This function's return value does not include a leading slash and uses isAbsolute to report whether the URL's path is absolute. If this behaviour is not appropriate, use CFURLCopyPath whose return value includes the leading slash (giving the path the normal POSIX appearance). You may also want to use the function CFURLCopyFileSystemPath which returns the URL's path as a file system path for the given path style.
Parameters
Name | Description |
anURL | The URL whose path you wish to obtain. |
isAbsolute | On return, indicates whether the URL's path is absolute. |
Result: The URL's path, or NULL if the URL cannot be decomposed (doesn't conform to RFC 1808).
Abstract: Obtains the user name from the specified URL.
CFStringRef CFURLCopyUserName(CFURLRef anURL);
Parameters
Name | Description |
anURL | The URL whose user name you wish to obtain. |
Result: The user name; or NULL if no user name exists. In some cases this function may return the empty string (CFSTR("")) instead of NULL. You must be prepared for either one.
Abstract: Creates a copy of the specified URL and appends a path component.
CFURLRef CFURLCreateCopyAppendingPathComponent(CFAllocatorRef allocator, CFURLRef url, CFStringRef pathComponent, Boolean isDirectory);
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
url | The URL to which you wish to append a path. |
pathComponent | The path component you wish appended to the URL. |
Result: The newly created URL.
Abstract: Creates a copy of the specified URL and appends a path extension.
CFURLRef CFURLCreateCopyAppendingPathExtension(CFAllocatorRef allocator, CFURLRef url, CFStringRef extension);
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
url | The URL to which you wish to append a path extension. |
extension | The extension you wish appended to the URL. |
Abstract: Creates a copy of the specified URL and deletes its last path component.
CFURLRef CFURLCreateCopyDeletingLastPathComponent(CFAllocatorRef allocator, CFURLRef url);
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
url | The URL whose last path component you wish to delete. |
Result: The newly created URL.
Abstract: Creates a copy of the specified URL and deletes its last path extension.
CFURLRef CFURLCreateCopyDeletingPathExtension(CFAllocatorRef allocator, CFURLRef url);
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
url | The URL whose path extension you wish to delete. |
Result: The newly created URL.
Abstract: Creates a CFData containing the specified URL.
CFDataRef CFURLCreateData(CFAllocatorRef allocator,
CFURLRef url,
CFStringEncoding encoding,
Boolean escapeWhitespace);
This function escapes any character that is not 7-bit ASCII with the byte-code for the given encoding. If escapeWhitespace is TRUE, whitespace characters (' ', '\t', '\r', '\n') will be escaped as well. This is desirable if you wish to embed the URL into a larger text stream like HTML.
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
url | The URL you wish to convert into a CFData. |
encoding | The encoding to use when converting the CFURL into a CFData. See XXX for a list of possible values. |
escapeWhitespace | Pass TRUE to escape whitespace characters in the URL; otherwise pass FALSE. |
Result: The newly created CFData.
Abstract: Creates a new CFURL for a file system entity using the native representation.
CFURLRef CFURLCreateFromFileSystemRepresentation(CFAllocatorRef allocator,
const UInt8 *buffer,
CFIndex bufLen,
Boolean isDirectory);
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
buffer | The character bytes you wish to convert into a CFURL. |
bufLen | The number of bytes in the buffer string. |
isDirectory | A flag that determines whether the string is treated as a directory path when resolving against relative path components. Pass TRUE if the pathname indicates a directory; otherwise pass FALSE. |
Result: The newly created URL.
Abstract: Creates a CFURL by resolving the specified path name (expressed as a native character string) against a base URL.
CFURLRef CFURLCreateFromFileSystemRepresentationRelativeToBase(CFAllocatorRef allocator,
const UInt8 *buffer,
CFIndex bufLen,
Boolean isDirectory,
CFURLRef baseURL);
This function takes a path name in the form of a native character string, resolves it against a base URL, and returns a new CFURL containing the result.
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
buffer | The character bytes you wish to convert into a CFURL. |
bufLen | The number of bytes in the buffer string. |
isDirectory | A flag that determines whether the string is treated as a directory path when resolving against relative path components. Pass TRUE if the pathname indicates a directory; otherwise pass FALSE. |
baseURL | The base URL against which to resolve the filePath. |
Result: The newly created CFURL.
Abstract: Creates a new string by replacing any percent escape sequences with their character equivalent.
CFStringRef CFURLCreateStringByReplacingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveEscaped);
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
charactersToLeaveEscaped | Characters whose escape sequences you wish to leave intact. Pass NULL to request that no percent escapes be replaced, or the empty string (CFSTR("")) to request that all be replaced. |
Result: The newly created string, or NULL if an error occurred. Returns the original string (retained) if no characters need to be replaced.
Abstract: Creates a CFURL using the specified character bytes.
CFURLRef CFURLCreateWithBytes(CFAllocatorRef allocator,
const UInt8 *URLBytes,
CFIndex length,
CFStringEncoding encoding,
CFURLRef baseURL);
The specified string encoding will be used both to interpret URLBytes, and to
interpret any percent-escapes within the string.
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
URLBytes | The character bytes you wish to convert into a CFURL. |
length | The number of bytes in the URLBytes string. |
encoding | The encoding of the URLBytes string. See XXX for a list of possible values. |
baseURL | The URL to which the URLBytes string is relative. Pass NULL if URLBytes contains an absolute URL or if you wish to create a relative URL. If URLBytes contains an absolute URL, the function detects this and ignores baseURL. |
Result: The newly created CFURL.
Abstract: Creates a CFURL using a local file system pathname.
CFURLRef CFURLCreateWithFileSystemPath(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory);
If filePath is not absolute, the resulting URL will be considered relative to the current working directory (evaluated when this function is being invoked).
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
filePath | The pathname you wish to convert to a CFURL. |
pathStyle | The operating system path style used in the filePath string. See CFURLPathStyle for a list of possible values. |
isDirectory | A flag that determines whether filePath is treated as a directory path when resolving against relative path components. Pass TRUE if the pathname indicates a directory; otherwise pass FALSE. |
Result: The newly created CFURL.
Abstract: Creates a CFURL by resolving the specified path name (expressed a s CFString) against a base URL.
CFURLRef CFURLCreateWithFileSystemPathRelativeToBase(CFAllocatorRef allocator,
CFStringRef filePath,
CFURLPathStyle pathStyle,
Boolean isDirectory,
CFURLRef baseURL);
This function takes a path name in the form of a CFString, resolves it against a base URL, and returns a new CFURL containing the result.
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
filePath | The pathname you wish to convert to a CFURL. |
pathStyle | The operating system path style used in the filePath string. See CFURLPathStyle for a list of possible values. |
isDirectory | A flag that determines whether filePath is treated as a directory path when resolving against relative path components. Pass TRUE if the pathname indicates a directory; otherwise pass FALSE. |
baseURL | The base URL against which to resolve the filePath. |
Result: The newly created CFURL.
Abstract: Creates a CFURL using the specified CFString.
CFURLRef CFURLCreateWithString(CFAllocatorRef allocator,
CFStringRef URLString,
CFURLRef baseURL);
Any escape sequences in URLString will be interpreted using UTF-8.
Parameters
Name | Description |
allocator | The memory allocator to use. Pass kCFAllocatorDefault to use the system allocator. |
URLString | A CFString containing a URL. |
baseURL | The URL to which the URLString is relative. Pass "NULL" if URLBytes contains an absolute URL or if you wish to create a relative URL. If URLString contains an absolute URL, the function detects this and ignores baseURL. |
Result: The newly created CFURL.
Abstract: Returns the base URL if it exists.
CFURLRef CFURLGetBaseURL(CFURLRef anURL);
Parameters
Name | Description |
anURL | The URL whose base you wish to obtain. |
Result: The newly created URL.
Abstract: Fills a buffer with the file system's native string representation of URL's path.
Boolean CFURLGetFileSystemRepresentation(CFURLRef url,
Boolean resolveAgainstBase,
UInt8 *buffer,
CFIndex maxBufLen);
No more than maxBufLen bytes are written to buffer. usedBufLen is set to the number of bytes actually written; returns success or failure. If the translation fails, usedBufLen is set to the necessary size for the translation.
Parameters
Name | Description |
url | The URL whose native file system representation you wish to obtain. |
resolveAgainstBase | Pass TRUE if you wish an absolute path name to be returned. |
buffer | A pointer to a character buffer. On return, holds the native file system's represenation of the URL's path. |
maxBufLen | The maximum number of characters that can be written to the buffer. On return, the number of characters that were actually written. |
Result: TRUE if successful; FALSE if an error occurred.
Abstract: Obtains the port number from the specified URL.
SInt32 CFURLGetPortNumber(CFURLRef anURL);
Parameters
Name | Description |
anURL | The URL whose port number you wish to obtain. |
Result: The URL's port number; or -1 if no port number exists.
Abstract: Returns the URL as a CFString.
CFStringRef CFURLGetString(CFURLRef anURL);
Parameters
Name | Description |
anURL | The URL you wish converted into a CFString. |
Result: The newly created CFString.
Abstract: Returns the Core Foundation type identifier for a CFURL.
CFTypeID CFURLGetTypeID(void);
Result: The type identifier.
Abstract: Determines if the specified URL's path represents a directory.
Boolean CFURLHasDirectoryPath(CFURLRef anURL);
Parameters
Name | Description |
anURL | The URL to test. |
Result: TRUE if the URL represents a directory; otherwise FALSE.
© 2000 Apple Computer, Inc. (Last Updated 7/20/2000)