mirror of
https://github.com/nillerusr/source-engine.git
synced 2024-12-23 14:46:53 +00:00
404 lines
18 KiB
C
404 lines
18 KiB
C
/* CFURL.h
|
|
Copyright (c) 1998-2003, Apple, Inc. All rights reserved.
|
|
*/
|
|
|
|
#if !defined(__COREFOUNDATION_CFURL__)
|
|
#define __COREFOUNDATION_CFURL__ 1
|
|
|
|
#include <CoreFoundation/CFBase.h>
|
|
#include <CoreFoundation/CFData.h>
|
|
#include <CoreFoundation/CFString.h>
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
typedef enum {
|
|
kCFURLPOSIXPathStyle = 0,
|
|
kCFURLHFSPathStyle,
|
|
kCFURLWindowsPathStyle
|
|
} CFURLPathStyle;
|
|
|
|
typedef const struct __CFURL * CFURLRef;
|
|
|
|
/* CFURLs are composed of two fundamental pieces - their string, and a */
|
|
/* (possibly NULL) base URL. A relative URL is one in which the string */
|
|
/* by itself does not fully specify the URL (for instance "myDir/image.tiff"); */
|
|
/* an absolute URL is one in which the string does fully specify the URL */
|
|
/* ("file://localhost/myDir/image.tiff"). Absolute URLs always have NULL */
|
|
/* base URLs; however, it is possible for a URL to have a NULL base, and still */
|
|
/* not be absolute. Such a URL has only a relative string, and cannot be */
|
|
/* resolved. Two CFURLs are considered equal if and only if their strings */
|
|
/* are equal and their bases are equal. In other words, */
|
|
/* "file://localhost/myDir/image.tiff" is NOT equal to the URL with relative */
|
|
/* string "myDir/image.tiff" and base URL "file://localhost/". Clients that */
|
|
/* need these less strict form of equality should convert all URLs to their */
|
|
/* absolute form via CFURLCopyAbsoluteURL(), then compare the absolute forms. */
|
|
|
|
CF_EXPORT
|
|
CFTypeID CFURLGetTypeID(void);
|
|
|
|
/* encoding will be used both to interpret the bytes of URLBytes, and to */
|
|
/* interpret any percent-escapes within the bytes. */
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateWithBytes(CFAllocatorRef allocator, const UInt8 *URLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL);
|
|
|
|
/* 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 also (desirable */
|
|
/* if embedding the URL into a larger text stream like HTML) */
|
|
CF_EXPORT
|
|
CFDataRef CFURLCreateData(CFAllocatorRef allocator, CFURLRef url, CFStringEncoding encoding, Boolean escapeWhitespace);
|
|
|
|
/* Any escape sequences in URLString will be interpreted via UTF-8. */
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateWithString(CFAllocatorRef allocator, CFStringRef URLString, CFURLRef baseURL);
|
|
|
|
#if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
|
|
|
|
/* Create an absolute URL directly, without requiring the extra step */
|
|
/* of calling CFURLCopyAbsoluteURL(). If useCompatibilityMode is */
|
|
/* true, the rules historically used on the web are used to resolve */
|
|
/* relativeString against baseURL - these rules are generally listed */
|
|
/* in the RFC as optional or alternate interpretations. Otherwise, */
|
|
/* the strict rules from the RFC are used. The major differences are */
|
|
/* that in compatibility mode, we are lenient of the scheme appearing */
|
|
/* in relative portion, leading "../" components are removed from the */
|
|
/* final URL's path, and if the relative portion contains only */
|
|
/* resource specifier pieces (query, parameters, and fragment), then */
|
|
/* the last path component of the base URL will not be deleted */
|
|
CFURLRef CFURLCreateAbsoluteURLWithBytes(CFAllocatorRef alloc, const UInt8 *relativeURLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL, Boolean useCompatibilityMode) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
|
|
#endif
|
|
|
|
/* filePath should be the URL's path expressed as a path of the type */
|
|
/* fsType. If filePath is not absolute, the resulting URL will be */
|
|
/* considered relative to the current working directory (evaluated */
|
|
/* at creation time). isDirectory determines whether filePath is */
|
|
/* treated as a directory path when resolving against relative path */
|
|
/* components */
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateWithFileSystemPath(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory);
|
|
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateFromFileSystemRepresentation(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory);
|
|
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateWithFileSystemPathRelativeToBase(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory, CFURLRef baseURL);
|
|
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateFromFileSystemRepresentationRelativeToBase(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory, CFURLRef baseURL);
|
|
|
|
/* Fills buffer with the file system's native representation of */
|
|
/* url's path. No more than maxBufLen bytes are written to buffer. */
|
|
/* The buffer should be at least the maximum path length for */
|
|
/* the file system in question to avoid failures for insufficiently */
|
|
/* large buffers. If resolveAgainstBase is true, the url's relative */
|
|
/* portion is resolved against its base before the path is computed. */
|
|
/* Returns success or failure. */
|
|
CF_EXPORT
|
|
Boolean CFURLGetFileSystemRepresentation(CFURLRef url, Boolean resolveAgainstBase, UInt8 *buffer, CFIndex maxBufLen);
|
|
|
|
/* Creates a new URL by resolving the relative portion of relativeURL against its base. */
|
|
CF_EXPORT
|
|
CFURLRef CFURLCopyAbsoluteURL(CFURLRef relativeURL);
|
|
|
|
/* Returns the URL's string. */
|
|
CF_EXPORT
|
|
CFStringRef CFURLGetString(CFURLRef anURL);
|
|
|
|
/* Returns the base URL if it exists */
|
|
CF_EXPORT
|
|
CFURLRef CFURLGetBaseURL(CFURLRef anURL);
|
|
|
|
/*
|
|
All URLs can be broken into two pieces - the scheme (preceding the
|
|
first colon) and the resource specifier (following the first colon).
|
|
Most URLs are also "standard" URLs conforming to RFC 1808 (available
|
|
from www.w3c.org). This category includes URLs of the file, http,
|
|
https, and ftp schemes, to name a few. Standard URLs start the
|
|
resource specifier with two slashes ("//"), and can be broken into
|
|
four distinct pieces - the scheme, the net location, the path, and
|
|
further resource specifiers (typically an optional parameter, query,
|
|
and/or fragment). The net location appears immediately following
|
|
the two slashes and goes up to the next slash; it's format is
|
|
scheme-specific, but is usually composed of some or all of a username,
|
|
password, host name, and port. The path is a series of path components
|
|
separated by slashes; if the net location is present, the path always
|
|
begins with a slash. Standard URLs can be relative to another URL,
|
|
in which case at least the scheme and possibly other pieces as well
|
|
come from the base URL (see RFC 1808 for precise details when resolving
|
|
a relative URL against its base). The full URL is therefore
|
|
|
|
<scheme> "://" <net location> <path, always starting with slash> <add'l resource specifiers>
|
|
|
|
If a given CFURL can be decomposed (that is, conforms to RFC 1808), you
|
|
can ask for each of the four basic pieces (scheme, net location, path,
|
|
and resource specifer) separately, as well as for its base URL. The
|
|
basic pieces are returned with any percent escape sequences still in
|
|
place (although note that the scheme may not legally include any
|
|
percent escapes); this is to allow the caller to distinguish between
|
|
percent sequences that may have syntactic meaning if replaced by the
|
|
character being escaped (for instance, a '/' in a path component).
|
|
Since only the individual schemes know which characters are
|
|
syntactically significant, CFURL cannot safely replace any percent
|
|
escape sequences. However, you can use
|
|
CFURLCreateStringByReplacingPercentEscapes() to create a new string with
|
|
the percent escapes removed; see below.
|
|
|
|
If a given CFURL can not be decomposed, you can ask for its scheme and its
|
|
resource specifier; asking it for its net location or path will return NULL.
|
|
|
|
To get more refined information about the components of a decomposable
|
|
CFURL, you may ask for more specific pieces of the URL, expressed with
|
|
the percent escapes removed. The available functions are CFURLCopyHostName(),
|
|
CFURLGetPortNumber() (returns an Int32), CFURLCopyUserName(),
|
|
CFURLCopyPassword(), CFURLCopyQuery(), CFURLCopyParameters(), and
|
|
CFURLCopyFragment(). Because the parameters, query, and fragment of an
|
|
URL may contain scheme-specific syntaxes, these methods take a second
|
|
argument, giving a list of characters which should NOT be replaced if
|
|
percent escaped. For instance, the ftp parameter syntax gives simple
|
|
key-value pairs as "<key>=<value>;" Clearly if a key or value includes
|
|
either '=' or ';', it must be escaped to avoid corrupting the meaning of
|
|
the parameters, so the caller may request the parameter string as
|
|
|
|
CFStringRef myParams = CFURLCopyParameters(ftpURL, CFSTR("=;%"));
|
|
|
|
requesting that all percent escape sequences be replaced by the represented
|
|
characters, except for escaped '=', '%' or ';' characters. Pass the empty
|
|
string (CFSTR("")) to request that all percent escapes be replaced, or NULL
|
|
to request that none be.
|
|
*/
|
|
|
|
/* Returns true if anURL conforms to RFC 1808 */
|
|
CF_EXPORT
|
|
Boolean CFURLCanBeDecomposed(CFURLRef anURL);
|
|
|
|
/* The next several methods leave any percent escape sequences intact */
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyScheme(CFURLRef anURL);
|
|
|
|
/* NULL if CFURLCanBeDecomposed(anURL) is false */
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyNetLocation(CFURLRef anURL);
|
|
|
|
/* NULL if CFURLCanBeDecomposed(anURL) is false; also does not resolve the URL */
|
|
/* against its base. See also CFURLCopyAbsoluteURL(). Note that, strictly */
|
|
/* speaking, any leading '/' is not considered part of the URL's path, although */
|
|
/* its presence or absence determines whether the path is absolute. */
|
|
/* CFURLCopyPath()'s return value includes any leading slash (giving the path */
|
|
/* the normal POSIX appearance); CFURLCopyStrictPath()'s return value omits any */
|
|
/* leading slash, and uses isAbsolute to report whether the URL's path is absolute. */
|
|
|
|
/* CFURLCopyFileSystemPath() returns the URL's path as a file system path for the */
|
|
/* given path style. All percent escape sequences are replaced. The URL is not */
|
|
/* resolved against its base before computing the path. */
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyPath(CFURLRef anURL);
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyStrictPath(CFURLRef anURL, Boolean *isAbsolute);
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyFileSystemPath(CFURLRef anURL, CFURLPathStyle pathStyle);
|
|
|
|
/* Returns whether anURL's path represents a directory */
|
|
/* (true returned) or a simple file (false returned) */
|
|
CF_EXPORT
|
|
Boolean CFURLHasDirectoryPath(CFURLRef anURL);
|
|
|
|
/* Any additional resource specifiers after the path. For URLs */
|
|
/* that cannot be decomposed, this is everything except the scheme itself. */
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyResourceSpecifier(CFURLRef anURL);
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyHostName(CFURLRef anURL);
|
|
|
|
CF_EXPORT
|
|
SInt32 CFURLGetPortNumber(CFURLRef anURL); /* Returns -1 if no port number is specified */
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyUserName(CFURLRef anURL);
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyPassword(CFURLRef anURL);
|
|
|
|
/* These remove all percent escape sequences except those for */
|
|
/* characters in charactersToLeaveEscaped. If charactersToLeaveEscaped */
|
|
/* is empty (""), all percent escape sequences are replaced by their */
|
|
/* corresponding characters. If charactersToLeaveEscaped is NULL, */
|
|
/* then no escape sequences are removed at all */
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyParameterString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyQueryString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyFragment(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyLastPathComponent(CFURLRef url);
|
|
|
|
CF_EXPORT
|
|
CFStringRef CFURLCopyPathExtension(CFURLRef url);
|
|
|
|
/* These functions all treat the base URL of the supplied url as */
|
|
/* invariant. In other words, the URL returned will always have */
|
|
/* the same base as the URL supplied as an argument. */
|
|
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateCopyAppendingPathComponent(CFAllocatorRef allocator, CFURLRef url, CFStringRef pathComponent, Boolean isDirectory);
|
|
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateCopyDeletingLastPathComponent(CFAllocatorRef allocator, CFURLRef url);
|
|
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateCopyAppendingPathExtension(CFAllocatorRef allocator, CFURLRef url, CFStringRef extension);
|
|
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateCopyDeletingPathExtension(CFAllocatorRef allocator, CFURLRef url);
|
|
|
|
#if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
|
|
/* Fills buffer with the bytes for url, returning the number of bytes */
|
|
/* filled. If buffer is of insufficient size, returns -1 and no bytes */
|
|
/* are placed in buffer. If buffer is NULL, the needed length is */
|
|
/* computed and returned. The returned bytes are the original bytes */
|
|
/* from which the URL was created; if the URL was created from a */
|
|
/* string, the bytes will be the bytes of the string encoded via UTF-8 */
|
|
CF_EXPORT
|
|
CFIndex CFURLGetBytes(CFURLRef url, UInt8 *buffer, CFIndex bufferLength) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
|
|
|
|
typedef enum {
|
|
kCFURLComponentScheme = 1,
|
|
kCFURLComponentNetLocation = 2,
|
|
kCFURLComponentPath = 3,
|
|
kCFURLComponentResourceSpecifier = 4,
|
|
|
|
kCFURLComponentUser = 5,
|
|
kCFURLComponentPassword = 6,
|
|
kCFURLComponentUserInfo = 7,
|
|
kCFURLComponentHost = 8,
|
|
kCFURLComponentPort = 9,
|
|
kCFURLComponentParameterString = 10,
|
|
kCFURLComponentQuery = 11,
|
|
kCFURLComponentFragment = 12
|
|
} CFURLComponentType;
|
|
|
|
/*
|
|
Gets the range of the requested component in the bytes of url, as
|
|
returned by CFURLGetBytes(). This range is only good for use in the
|
|
bytes returned by CFURLGetBytes!
|
|
|
|
If non-NULL, rangeIncludingSeparators gives the range of component
|
|
including the sequences that separate component from the previous and
|
|
next components. If there is no previous or next component, that end of
|
|
rangeIncludingSeparators will match the range of the component itself.
|
|
If url does not contain the given component type, (kCFNotFound, 0) is
|
|
returned, and rangeIncludingSeparators is set to the location where the
|
|
component would be inserted. Some examples -
|
|
|
|
For the URL http://www.apple.com/hotnews/
|
|
|
|
Component returned range rangeIncludingSeparators
|
|
scheme (0, 4) (0, 7)
|
|
net location (7, 13) (4, 16)
|
|
path (20, 9) (20, 9)
|
|
resource specifier (kCFNotFound, 0) (29, 0)
|
|
user (kCFNotFound, 0) (7, 0)
|
|
password (kCFNotFound, 0) (7, 0)
|
|
user info (kCFNotFound, 0) (7, 0)
|
|
host (7, 13) (4, 16)
|
|
port (kCFNotFound, 0) (20, 0)
|
|
parameter (kCFNotFound, 0) (29, 0)
|
|
query (kCFNotFound, 0) (29, 0)
|
|
fragment (kCFNotFound, 0) (29, 0)
|
|
|
|
|
|
For the URL ./relPath/file.html#fragment
|
|
|
|
Component returned range rangeIncludingSeparators
|
|
scheme (kCFNotFound, 0) (0, 0)
|
|
net location (kCFNotFound, 0) (0, 0)
|
|
path (0, 19) (0, 20)
|
|
resource specifier (20, 8) (19, 9)
|
|
user (kCFNotFound, 0) (0, 0)
|
|
password (kCFNotFound, 0) (0, 0)
|
|
user info (kCFNotFound, 0) (0, 0)
|
|
host (kCFNotFound, 0) (0, 0)
|
|
port (kCFNotFound, 0) (0, 0)
|
|
parameter (kCFNotFound, 0) (19, 0)
|
|
query (kCFNotFound, 0) (19, 0)
|
|
fragment (20, 8) (19, 9)
|
|
|
|
|
|
For the URL scheme://user:pass@host:1/path/path2/file.html;params?query#fragment
|
|
|
|
Component returned range rangeIncludingSeparators
|
|
scheme (0, 6) (0, 9)
|
|
net location (9, 16) (6, 19)
|
|
path (25, 21) (25, 22)
|
|
resource specifier (47, 21) (46, 22)
|
|
user (9, 4) (6, 8)
|
|
password (14, 4) (13, 6)
|
|
user info (9, 9) (6, 13)
|
|
host (19, 4) (18, 6)
|
|
port (24, 1) (23, 2)
|
|
parameter (47, 6) (46, 8)
|
|
query (54, 5) (53, 7)
|
|
fragment (60, 8) (59, 9)
|
|
*/
|
|
CF_EXPORT
|
|
CFRange CFURLGetByteRangeForComponent(CFURLRef url, CFURLComponentType component, CFRange *rangeIncludingSeparators) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
|
|
#endif
|
|
|
|
/* Returns a string with any percent escape sequences that do NOT */
|
|
/* correspond to characters in charactersToLeaveEscaped with their */
|
|
/* equivalent. Returns NULL on failure (if an invalid percent sequence */
|
|
/* is encountered), or the original string (retained) if no characters */
|
|
/* need to be replaced. Pass NULL to request that no percent escapes be */
|
|
/* replaced, or the empty string (CFSTR("")) to request that all percent */
|
|
/* escapes be replaced. Uses UTF8 to interpret percent escapes. */
|
|
CF_EXPORT
|
|
CFStringRef CFURLCreateStringByReplacingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveEscaped);
|
|
|
|
#if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
|
|
/* As above, but allows you to specify the encoding to use when interpreting percent escapes */
|
|
CF_EXPORT
|
|
CFStringRef CFURLCreateStringByReplacingPercentEscapesUsingEncoding(CFAllocatorRef allocator, CFStringRef origString, CFStringRef charsToLeaveEscaped, CFStringEncoding encoding) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
|
|
#endif
|
|
|
|
/* Creates a copy or originalString, replacing certain characters with */
|
|
/* the equivalent percent escape sequence based on the encoding specified. */
|
|
/* If the originalString does not need to be modified (no percent escape */
|
|
/* sequences are missing), may retain and return originalString. */
|
|
/* If you are uncertain of the correct encoding, you should use UTF-8, */
|
|
/* which is the encoding designated by RFC 2396 as the correct encoding */
|
|
/* for use in URLs. The characters so escaped are all characters that */
|
|
/* are not legal URL characters (based on RFC 2396), plus any characters */
|
|
/* in legalURLCharactersToBeEscaped, less any characters in */
|
|
/* charactersToLeaveUnescaped. To simply correct any non-URL characters */
|
|
/* in an otherwise correct URL string, do: */
|
|
|
|
/* newString = CFURLCreateStringByAddingPercentEscapes(NULL, origString, NULL, NULL, kCFStringEncodingUTF8); */
|
|
CF_EXPORT
|
|
CFStringRef CFURLCreateStringByAddingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveUnescaped, CFStringRef legalURLCharactersToBeEscaped, CFStringEncoding encoding);
|
|
|
|
|
|
struct FSRef;
|
|
|
|
CF_EXPORT
|
|
CFURLRef CFURLCreateFromFSRef(CFAllocatorRef allocator, const struct FSRef *fsRef);
|
|
|
|
CF_EXPORT
|
|
Boolean CFURLGetFSRef(CFURLRef url, struct FSRef *fsRef);
|
|
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#endif /* !__COREFOUNDATION_CFURL__ */
|
|
|