/* File: CFURL.h Contains: CoreFoundation urls Version: Technology: Mac OS X Release: QuickTime 6.0.2 Copyright: (c) 1999-2001 by Apple Computer, Inc., all rights reserved Bugs?: For bug reports, consult the following page on the World Wide Web: http://developer.apple.com/bugreporter/ */ #ifndef __CFURL__ #define __CFURL__ #ifndef __CFBASE__ #include #endif #ifndef __CFDATA__ #include #endif #ifndef __CFSTRING__ #include #endif #if PRAGMA_ONCE #pragma once #endif #ifdef __cplusplus extern "C" { #endif #if PRAGMA_IMPORT #pragma import on #endif #if PRAGMA_STRUCT_ALIGN #pragma options align=mac68k #elif PRAGMA_STRUCT_PACKPUSH #pragma pack(push, 2) #elif PRAGMA_STRUCT_PACK #pragma pack(2) #endif #if PRAGMA_ENUM_ALWAYSINT #if defined(__fourbyteints__) && !__fourbyteints__ #define __CFURL__RESTORE_TWOBYTEINTS #pragma fourbyteints on #endif #pragma enumsalwaysint on #elif PRAGMA_ENUM_OPTIONS #pragma option enum=int #elif PRAGMA_ENUM_PACK #if __option(pack_enums) #define __CFURL__RESTORE_PACKED_ENUMS #pragma options(!pack_enums) #endif #endif typedef UInt32 CFURLPathStyle; enum { kCFURLPOSIXPathStyle = 0, kCFURLHFSPathStyle = 1, kCFURLWindowsPathStyle = 2 }; typedef struct __CFURL * CFURLRef; EXTERN_API_C( CFTypeID ) CFURLGetTypeID (void); /* encoding will be used both to interpret the bytes of URLBytes, and to */ /* interpret any percent-escapes within the bytes. */ EXTERN_API_C( 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) */ EXTERN_API_C( CFDataRef ) CFURLCreateData (CFAllocatorRef allocator, CFURLRef url, CFStringEncoding encoding, Boolean escapeWhitespace); /* Any escape sequences in URLString will be interpreted via UTF-8. */ EXTERN_API_C( CFURLRef ) CFURLCreateWithString (CFAllocatorRef allocator, CFStringRef URLString, CFURLRef baseURL); /* 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 */ EXTERN_API_C( CFURLRef ) CFURLCreateWithFileSystemPath (CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory); /* Returns the URL's path in a form suitable for file system use. */ /* The path has been fully processed for the file system type requested */ /* by fsType. If resolveAgainstBase is TRUE, then the URL's path is first */ /* resolved against that of its base URL (if a base URL exists) before being returned. */ EXTERN_API_C( CFStringRef ) CFURLCreateStringWithFileSystemPath (CFAllocatorRef allocator, CFURLRef anURL, CFURLPathStyle pathStyle, Boolean resolveAgainstBase); /* Creates a new URL by resolving the relative portion of relativeURL against its base. */ EXTERN_API_C( CFURLRef ) CFURLCopyAbsoluteURL (CFURLRef relativeURL); /* Returns the URL's string. */ EXTERN_API_C( CFStringRef ) CFURLGetString (CFURLRef anURL); /* Returns the base URL if it exists */ EXTERN_API_C( 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 4 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 */ /* "://" */ /* 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 CFStringCreateReplacingPercentEscapes() to create a new string with the percent escapes */ /* removed. The first argument is the original string containing percent escapes; the second argument */ /* is a string containing any characters that, if escaped in the original string, should NOT be replaced. */ /* Note that this function may return the original string (retained) if the original string contains no */ /* escape sequences to be processed. */ /* 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. */ /* All of the methods discussed above do not require an autorelease pool to be in place. */ /* 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. These functions require an */ /* autorelease pool to be in place, as they will return an autoreleased CFString. They are */ /* CFURLHostName(), CFURLPortNumber() (actually returns an Int32; does not use the autorelease pool), */ /* CFURLUserName(), CFURLPassword(), CFURLQuery(), CFURLParameters(), and CFURLFragment(). 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 "=;" 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 = CFURLParameters(ftpURL, CFSTR("=;%")); */ /* requesting that all percent escape sequences be replaced by the represented characters, except for escaped */ /* '=', '%' or ';' characters. If you are not interested in any escape sequences being left in, pass NULL for the */ /* second argument. */ /* Returns TRUE if anURL conforms to RFC 1808 */ EXTERN_API_C( Boolean ) CFURLCanBeDecomposed (CFURLRef anURL); /* The next several methods leave any percent escape sequences intact */ EXTERN_API_C( CFStringRef ) CFURLCopyScheme (CFURLRef anURL); /* NULL if CFURLCanBeDecomposed(anURL) is FALSE */ EXTERN_API_C( CFStringRef ) CFURLCopyNetLocation (CFURLRef anURL); /* NULL if CFURLCanBeDecomposed(anURL) is FALSE; also does not resolve */ /* the URL against its base. See also CFCreateAbsoluteURL() and */ /* CFStringCreateFileSystemPathFromURL() */ EXTERN_API_C( CFStringRef ) CFURLCopyPath (CFURLRef anURL); /* Returns whether anURL's path represents a directory */ /* (TRUE returned) or a simple file (FALSE returned) */ EXTERN_API_C( Boolean ) CFURLHasDirectoryPath (CFURLRef anURL); /* Any additional resource specifiers after the path. For URLs */ /* that cannot be decomposed, this is everything except the scheme itself. */ EXTERN_API_C( CFStringRef ) CFURLCopyResourceSpecifier (CFURLRef anURL); EXTERN_API_C( CFStringRef ) CFURLCopyHostName (CFURLRef anURL); EXTERN_API_C( SInt32 ) CFURLGetPortNumber (CFURLRef anURL); /* Returns -1 if no port number is specified */ EXTERN_API_C( CFStringRef ) CFURLCopyUserName (CFURLRef anURL); EXTERN_API_C( 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 */ EXTERN_API_C( CFStringRef ) CFURLCopyParameterString (CFURLRef anURL, CFStringRef charactersToLeaveEscaped); EXTERN_API_C( CFStringRef ) CFURLCopyQueryString (CFURLRef anURL, CFStringRef charactersToLeaveEscaped); EXTERN_API_C( CFStringRef ) CFURLCopyFragment (CFURLRef anURL, CFStringRef charactersToLeaveEscaped); /* 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 itself if no characters need to be replaced. */ EXTERN_API_C( CFStringRef ) CFURLCreateStringByReplacingPercentEscapes (CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveEscaped); #if PRAGMA_ENUM_ALWAYSINT #pragma enumsalwaysint reset #ifdef __CFURL__RESTORE_TWOBYTEINTS #pragma fourbyteints off #endif #elif PRAGMA_ENUM_OPTIONS #pragma option enum=reset #elif defined(__CFURL__RESTORE_PACKED_ENUMS) #pragma options(pack_enums) #endif #if PRAGMA_STRUCT_ALIGN #pragma options align=reset #elif PRAGMA_STRUCT_PACKPUSH #pragma pack(pop) #elif PRAGMA_STRUCT_PACK #pragma pack() #endif #ifdef PRAGMA_IMPORT_OFF #pragma import off #elif PRAGMA_IMPORT #pragma import reset #endif #ifdef __cplusplus } #endif #endif /* __CFURL__ */