Functions



CFURLCanBeDecomposed

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

NameDescription
anURLThe URL to test.
Result: TRUE if the URL conforms to RFC 1808; otherwise FALSE.

CFURLCopyAbsoluteURL

Abstract: Creates a new URL by resolving the relative portion of relativeURL against its base.
CFURLRef CFURLCopyAbsoluteURL(CFURLRef relativeURL);

Parameters

NameDescription
relativeURLThe URL you wish to resolve.
Result: The newly created URL.

CFURLCopyFileSystemPath

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

NameDescription
anURLThe URL whose path you wish to obtain.
pathStyleThe 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.

CFURLCopyFragment

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

NameDescription
anURLThe URL whose fragment you wish to obtain.
charactersToLeaveEscapedCharacters 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.

CFURLCopyHostName

Abstract: Obtains the hostname from the specified URL.
CFStringRef CFURLCopyHostName(CFURLRef anURL);

Parameters

NameDescription
anURLThe URL whose hostname you wish to obtain.
Result: The URL's hostname.

CFURLCopyLastPathComponent

Abstract: Obtains the last path component of the specified URL.
CFStringRef CFURLCopyLastPathComponent(CFURLRef url);

Parameters

NameDescription
anURLThe URL whose last path component you wish to obtain.
Result: The URL's last path component.

CFURLCopyNetLocation

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

NameDescription
anURLThe 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).

CFURLCopyParameterString

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

NameDescription
anURLThe URL whose parameter string you wish to obtain.
charactersToLeaveEscapedCharacters 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.

CFURLCopyPassword

Abstract: Obtains the password from the specified URL.
CFStringRef CFURLCopyPassword(CFURLRef anURL);

Parameters

NameDescription
anURLThe 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.

CFURLCopyPath

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

NameDescription
anURLThe 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).

CFURLCopyPathExtension

Abstract: Obtains the path extension of the specified URL.
CFStringRef CFURLCopyPathExtension(CFURLRef url);

Parameters

NameDescription
anURLThe URL whose path extension you wish to obtain.
Result: The URL's path extension.

CFURLCopyQueryString

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

NameDescription
anURLThe URL whose query string you wish to obtain.
charactersToLeaveEscapedCharacters 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.

CFURLCopyResourceSpecifier

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

NameDescription
anURLThe URL whose additional resource specifiers you wish to obtain.
Result: The resources specifiers.

CFURLCopyScheme

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

NameDescription
anURLThe URL whose scheme you wish to obtain.
Result: The scheme of the URL.

CFURLCopyStrictPath

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

NameDescription
anURLThe URL whose path you wish to obtain.
isAbsoluteOn 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).

CFURLCopyUserName

Abstract: Obtains the user name from the specified URL.
CFStringRef CFURLCopyUserName(CFURLRef anURL);

Parameters

NameDescription
anURLThe 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.

CFURLCreateCopyAppendingPathComponent

Abstract: Creates a copy of the specified URL and appends a path component.
CFURLRef CFURLCreateCopyAppendingPathComponent(CFAllocatorRef allocator, CFURLRef url, CFStringRef pathComponent, Boolean isDirectory);

Parameters

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
urlThe URL to which you wish to append a path.
pathComponentThe path component you wish appended to the URL.
Result: The newly created URL.

CFURLCreateCopyAppendingPathExtension

Abstract: Creates a copy of the specified URL and appends a path extension.
CFURLRef CFURLCreateCopyAppendingPathExtension(CFAllocatorRef allocator, CFURLRef url, CFStringRef extension);

Parameters

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
urlThe URL to which you wish to append a path extension.
extensionThe extension you wish appended to the URL.

CFURLCreateCopyDeletingLastPathComponent

Abstract: Creates a copy of the specified URL and deletes its last path component.
CFURLRef CFURLCreateCopyDeletingLastPathComponent(CFAllocatorRef allocator, CFURLRef url);

Parameters

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
urlThe URL whose last path component you wish to delete.
Result: The newly created URL.

CFURLCreateCopyDeletingPathExtension

Abstract: Creates a copy of the specified URL and deletes its last path extension.
CFURLRef CFURLCreateCopyDeletingPathExtension(CFAllocatorRef allocator, CFURLRef url);

Parameters

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
urlThe URL whose path extension you wish to delete.
Result: The newly created URL.

CFURLCreateData

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

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
urlThe URL you wish to convert into a CFData.
encodingThe encoding to use when converting the CFURL into a CFData. See XXX for a list of possible values.
escapeWhitespacePass TRUE to escape whitespace characters in the URL; otherwise pass FALSE.
Result: The newly created CFData.

CFURLCreateFromFileSystemRepresentation

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

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
bufferThe character bytes you wish to convert into a CFURL.
bufLenThe number of bytes in the buffer string.
isDirectoryA 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.

CFURLCreateFromFileSystemRepresentationRelativeToBase

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

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
bufferThe character bytes you wish to convert into a CFURL.
bufLenThe number of bytes in the buffer string.
isDirectoryA 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.
baseURLThe base URL against which to resolve the filePath.
Result: The newly created CFURL.

CFURLCreateStringByReplacingPercentEscapes

Abstract: Creates a new string by replacing any percent escape sequences with their character equivalent.
CFStringRef CFURLCreateStringByReplacingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveEscaped);

Parameters

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
charactersToLeaveEscapedCharacters 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.

CFURLCreateWithBytes

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

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
URLBytesThe character bytes you wish to convert into a CFURL.
lengthThe number of bytes in the URLBytes string.
encodingThe encoding of the URLBytes string. See XXX for a list of possible values.
baseURLThe 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.

CFURLCreateWithFileSystemPath

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

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
filePathThe pathname you wish to convert to a CFURL.
pathStyleThe operating system path style used in the filePath string. See CFURLPathStyle for a list of possible values.
isDirectoryA 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.

CFURLCreateWithFileSystemPathRelativeToBase

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

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
filePathThe pathname you wish to convert to a CFURL.
pathStyleThe operating system path style used in the filePath string. See CFURLPathStyle for a list of possible values.
isDirectoryA 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.
baseURLThe base URL against which to resolve the filePath.
Result: The newly created CFURL.

CFURLCreateWithString

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

NameDescription
allocatorThe memory allocator to use. Pass kCFAllocatorDefault to use the system allocator.
URLStringA CFString containing a URL.
baseURLThe 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.

CFURLGetBaseURL

Abstract: Returns the base URL if it exists.
CFURLRef CFURLGetBaseURL(CFURLRef anURL);

Parameters

NameDescription
anURLThe URL whose base you wish to obtain.
Result: The newly created URL.

CFURLGetFileSystemRepresentation

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

NameDescription
urlThe URL whose native file system representation you wish to obtain.
resolveAgainstBasePass TRUE if you wish an absolute path name to be returned.
bufferA pointer to a character buffer. On return, holds the native file system's represenation of the URL's path.
maxBufLenThe 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.

CFURLGetPortNumber

Abstract: Obtains the port number from the specified URL.
SInt32 CFURLGetPortNumber(CFURLRef anURL); 

Parameters

NameDescription
anURLThe URL whose port number you wish to obtain.
Result: The URL's port number; or -1 if no port number exists.

CFURLGetString

Abstract: Returns the URL as a CFString.
CFStringRef CFURLGetString(CFURLRef anURL);

Parameters

NameDescription
anURLThe URL you wish converted into a CFString.
Result: The newly created CFString.

CFURLGetTypeID

Abstract: Returns the Core Foundation type identifier for a CFURL.
CFTypeID CFURLGetTypeID(void);

Result: The type identifier.

CFURLHasDirectoryPath

Abstract: Determines if the specified URL's path represents a directory.
Boolean CFURLHasDirectoryPath(CFURLRef anURL);

Parameters

NameDescription
anURLThe URL to test.
Result: TRUE if the URL represents a directory; otherwise FALSE.

© 2000 Apple Computer, Inc. — (Last Updated 7/20/2000)