URL.subproj/CFURL.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*      CFURL.h
  26         Copyright (c) 1998-2003, Apple, Inc. All rights reserved.
  27 */
  28
  29 #if !defined(__COREFOUNDATION_CFURL__)
  30 #define __COREFOUNDATION_CFURL__ 1
  31
  32 #include <CoreFoundation/CFBase.h>
  33 #include <CoreFoundation/CFData.h>
  34 #include <CoreFoundation/CFString.h>
  35
  36 #if defined(__cplusplus)
  37 extern "C" {
  38 #endif
  39
  40 typedef enum {
  41     kCFURLPOSIXPathStyle = 0,
  42     kCFURLHFSPathStyle,
  43     kCFURLWindowsPathStyle
  44 } CFURLPathStyle;
  45
  46 typedef const struct __CFURL * CFURLRef;
  47
  48 /* CFURLs are composed of two fundamental pieces - their string, and a */
  49 /* (possibly NULL) base URL.  A relative URL is one in which the string */
  50 /* by itself does not fully specify the URL (for instance "myDir/image.tiff"); */
  51 /* an absolute URL is one in which the string does fully specify the URL */
  52 /* ("file://localhost/myDir/image.tiff").  Absolute URLs always have NULL */
  53 /* base URLs; however, it is possible for a URL to have a NULL base, and still */
  54 /* not be absolute.  Such a URL has only a relative string, and cannot be */
  55 /* resolved.  Two CFURLs are considered equal if and only if their strings */
  56 /* are equal and their bases are equal.  In other words, */
  57 /* "file://localhost/myDir/image.tiff" is NOT equal to the URL with relative */
  58 /* string "myDir/image.tiff" and base URL "file://localhost/".  Clients that */
  59 /* need these less strict form of equality should convert all URLs to their */
  60 /* absolute form via CFURLCopyAbsoluteURL(), then compare the absolute forms. */
  61
  62 CF_EXPORT
  63 CFTypeID CFURLGetTypeID(void);
  64
  65 /* encoding will be used both to interpret the bytes of URLBytes, and to */
  66 /* interpret any percent-escapes within the bytes. */
  67 CF_EXPORT
  68 CFURLRef CFURLCreateWithBytes(CFAllocatorRef allocator, const UInt8 *URLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL);
  69
  70 /* Escapes any character that is not 7-bit ASCII with the byte-code */
  71 /* for the given encoding.  If escapeWhitespace is true, whitespace */
  72 /* characters (' ', '\t', '\r', '\n') will be escaped also (desirable */
  73 /* if embedding the URL into a larger text stream like HTML) */
  74 CF_EXPORT
  75 CFDataRef CFURLCreateData(CFAllocatorRef allocator, CFURLRef url, CFStringEncoding encoding, Boolean escapeWhitespace);
  76
  77 /* Any escape sequences in URLString will be interpreted via UTF-8. */
  78 CF_EXPORT
  79 CFURLRef CFURLCreateWithString(CFAllocatorRef allocator, CFStringRef URLString, CFURLRef baseURL);
  80
  81 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
  82
  83 /* Create an absolute URL directly, without requiring the extra step */
  84 /* of calling CFURLCopyAbsoluteURL().  If useCompatibilityMode is  */
  85 /* true, the rules historically used on the web are used to resolve */
  86 /* relativeString against baseURL - these rules are generally listed */
  87 /* in the RFC as optional or alternate interpretations.  Otherwise, */
  88 /* the strict rules from the RFC are used.  The major differences are */
  89 /* that in compatibility mode, we are lenient of the scheme appearing */
  90 /* in relative portion, leading "../" components are removed from the */
  91 /* final URL's path, and if the relative portion contains only */
  92 /* resource specifier pieces (query, parameters, and fragment), then */
  93 /* the last path component of the base URL will not be deleted  */
  94 CFURLRef CFURLCreateAbsoluteURLWithBytes(CFAllocatorRef alloc, const UInt8 *relativeURLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL, Boolean useCompatibilityMode) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  95 #endif
  96
  97 /* filePath should be the URL's path expressed as a path of the type */
  98 /* fsType.  If filePath is not absolute, the resulting URL will be */
  99 /* considered relative to the current working directory (evaluated */
 100 /* at creation time).  isDirectory determines whether filePath is */
 101 /* treated as a directory path when resolving against relative path */
 102 /* components */
 103 CF_EXPORT
 104 CFURLRef CFURLCreateWithFileSystemPath(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory);
 105
 106 CF_EXPORT
 107 CFURLRef CFURLCreateFromFileSystemRepresentation(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory);
 108
 109 CF_EXPORT
 110 CFURLRef CFURLCreateWithFileSystemPathRelativeToBase(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory, CFURLRef baseURL);
 111
 112 CF_EXPORT
 113 CFURLRef CFURLCreateFromFileSystemRepresentationRelativeToBase(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory, CFURLRef baseURL);
 114
 115 /* Fills buffer with the file system's native representation of */
 116 /* url's path. No more than maxBufLen bytes are written to buffer. */
 117 /* The buffer should be at least the maximum path length for */
 118 /* the file system in question to avoid failures for insufficiently */
 119 /* large buffers.  If resolveAgainstBase is true, the url's relative */
 120 /* portion is resolved against its base before the path is computed. */
 121 /* Returns success or failure. */
 122 CF_EXPORT
 123 Boolean CFURLGetFileSystemRepresentation(CFURLRef url, Boolean resolveAgainstBase, UInt8 *buffer, CFIndex maxBufLen);
 124
 125 /* Creates a new URL by resolving the relative portion of relativeURL against its base. */
 126 CF_EXPORT
 127 CFURLRef CFURLCopyAbsoluteURL(CFURLRef relativeURL);
 128
 129 /* Returns the URL's string. */
 130 CF_EXPORT
 131 CFStringRef CFURLGetString(CFURLRef anURL);
 132
 133 /* Returns the base URL if it exists */
 134 CF_EXPORT
 135 CFURLRef CFURLGetBaseURL(CFURLRef anURL);
 136
 137 /*
 138 All URLs can be broken into two pieces - the scheme (preceding the
 139 first colon) and the resource specifier (following the first colon).
 140 Most URLs are also "standard" URLs conforming to RFC 1808 (available
 141 from www.w3c.org).  This category includes URLs of the file, http,
 142 https, and ftp schemes, to name a few.  Standard URLs start the
 143 resource specifier with two slashes ("//"), and can be broken into
 144 four distinct pieces - the scheme, the net location, the path, and
 145 further resource specifiers (typically an optional parameter, query,
 146 and/or fragment).  The net location appears immediately following
 147 the two slashes and goes up to the next slash; it's format is
 148 scheme-specific, but is usually composed of some or all of a username,
 149 password, host name, and port.  The path is a series of path components
 150 separated by slashes; if the net location is present, the path always
 151 begins with a slash.  Standard URLs can be relative to another URL,
 152 in which case at least the scheme and possibly other pieces as well
 153 come from the base URL (see RFC 1808 for precise details when resolving
 154 a relative URL against its base).  The full URL is therefore
 155
 156 <scheme> "://" <net location> <path, always starting with slash> <add'l resource specifiers>
 157
 158 If a given CFURL can be decomposed (that is, conforms to RFC 1808), you
 159 can ask for each of the four basic pieces (scheme, net location, path,
 160 and resource specifer) separately, as well as for its base URL.  The
 161 basic pieces are returned with any percent escape sequences still in
 162 place (although note that the scheme may not legally include any
 163 percent escapes); this is to allow the caller to distinguish between
 164 percent sequences that may have syntactic meaning if replaced by the
 165 character being escaped (for instance, a '/' in a path component).
 166 Since only the individual schemes know which characters are
 167 syntactically significant, CFURL cannot safely replace any percent
 168 escape sequences.  However, you can use
 169 CFURLCreateStringByReplacingPercentEscapes() to create a new string with
 170 the percent escapes removed; see below.
 171
 172 If a given CFURL can not be decomposed, you can ask for its scheme and its
 173 resource specifier; asking it for its net location or path will return NULL.
 174
 175 To get more refined information about the components of a decomposable
 176 CFURL, you may ask for more specific pieces of the URL, expressed with
 177 the percent escapes removed.  The available functions are CFURLCopyHostName(),
 178 CFURLGetPortNumber() (returns an Int32), CFURLCopyUserName(),
 179 CFURLCopyPassword(), CFURLCopyQuery(), CFURLCopyParameters(), and
 180 CFURLCopyFragment().  Because the parameters, query, and fragment of an
 181 URL may contain scheme-specific syntaxes, these methods take a second
 182 argument, giving a list of characters which should NOT be replaced if
 183 percent escaped.  For instance, the ftp parameter syntax gives simple
 184 key-value pairs as "<key>=<value>;"  Clearly if a key or value includes
 185 either '=' or ';', it must be escaped to avoid corrupting the meaning of
 186 the parameters, so the caller may request the parameter string as
 187
 188 CFStringRef myParams = CFURLCopyParameters(ftpURL, CFSTR("=;%"));
 189
 190 requesting that all percent escape sequences be replaced by the represented
 191 characters, except for escaped '=', '%' or ';' characters.  Pass the empty
 192 string (CFSTR("")) to request that all percent escapes be replaced, or NULL
 193 to request that none be.
 194 */
 195
 196 /* Returns true if anURL conforms to RFC 1808 */
 197 CF_EXPORT
 198 Boolean CFURLCanBeDecomposed(CFURLRef anURL);
 199
 200 /* The next several methods leave any percent escape sequences intact */
 201
 202 CF_EXPORT
 203 CFStringRef CFURLCopyScheme(CFURLRef anURL);
 204
 205 /* NULL if CFURLCanBeDecomposed(anURL) is false */
 206 CF_EXPORT
 207 CFStringRef CFURLCopyNetLocation(CFURLRef anURL);
 208
 209 /* NULL if CFURLCanBeDecomposed(anURL) is false; also does not resolve the URL */
 210 /* against its base.  See also CFURLCopyAbsoluteURL().  Note that, strictly */
 211 /* speaking, any leading '/' is not considered part of the URL's path, although */
 212 /* its presence or absence determines whether the path is absolute. */
 213 /* CFURLCopyPath()'s return value includes any leading slash (giving the path */
 214 /* the normal POSIX appearance); CFURLCopyStrictPath()'s return value omits any */
 215 /* leading slash, and uses isAbsolute to report whether the URL's path is absolute. */
 216
 217 /* CFURLCopyFileSystemPath() returns the URL's path as a file system path for the */
 218 /* given path style.  All percent escape sequences are replaced.  The URL is not */
 219 /* resolved against its base before computing the path. */
 220 CF_EXPORT
 221 CFStringRef CFURLCopyPath(CFURLRef anURL);
 222
 223 CF_EXPORT
 224 CFStringRef CFURLCopyStrictPath(CFURLRef anURL, Boolean *isAbsolute);
 225
 226 CF_EXPORT
 227 CFStringRef CFURLCopyFileSystemPath(CFURLRef anURL, CFURLPathStyle pathStyle);
 228
 229 /* Returns whether anURL's path represents a directory */
 230 /* (true returned) or a simple file (false returned) */
 231 CF_EXPORT
 232 Boolean CFURLHasDirectoryPath(CFURLRef anURL);
 233
 234 /* Any additional resource specifiers after the path.  For URLs */
 235 /* that cannot be decomposed, this is everything except the scheme itself. */
 236 CF_EXPORT
 237 CFStringRef CFURLCopyResourceSpecifier(CFURLRef anURL);
 238
 239 CF_EXPORT
 240 CFStringRef CFURLCopyHostName(CFURLRef anURL);
 241
 242 CF_EXPORT
 243 SInt32 CFURLGetPortNumber(CFURLRef anURL); /* Returns -1 if no port number is specified */
 244
 245 CF_EXPORT
 246 CFStringRef CFURLCopyUserName(CFURLRef anURL);
 247
 248 CF_EXPORT
 249 CFStringRef CFURLCopyPassword(CFURLRef anURL);
 250
 251 /* These remove all percent escape sequences except those for */
 252 /* characters in charactersToLeaveEscaped.  If charactersToLeaveEscaped */
 253 /* is empty (""), all percent escape sequences are replaced by their */
 254 /* corresponding characters.  If charactersToLeaveEscaped is NULL, */
 255 /* then no escape sequences are removed at all */
 256 CF_EXPORT
 257 CFStringRef CFURLCopyParameterString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 258
 259 CF_EXPORT
 260 CFStringRef CFURLCopyQueryString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 261
 262 CF_EXPORT
 263 CFStringRef CFURLCopyFragment(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 264
 265 CF_EXPORT
 266 CFStringRef CFURLCopyLastPathComponent(CFURLRef url);
 267
 268 CF_EXPORT
 269 CFStringRef CFURLCopyPathExtension(CFURLRef url);
 270
 271 /* These functions all treat the base URL of the supplied url as */
 272 /* invariant.  In other words, the URL returned will always have */
 273 /* the same base as the URL supplied as an argument. */
 274
 275 CF_EXPORT
 276 CFURLRef CFURLCreateCopyAppendingPathComponent(CFAllocatorRef allocator, CFURLRef url, CFStringRef pathComponent, Boolean isDirectory);
 277
 278 CF_EXPORT
 279 CFURLRef CFURLCreateCopyDeletingLastPathComponent(CFAllocatorRef allocator, CFURLRef url);
 280
 281 CF_EXPORT
 282 CFURLRef CFURLCreateCopyAppendingPathExtension(CFAllocatorRef allocator, CFURLRef url, CFStringRef extension);
 283
 284 CF_EXPORT
 285 CFURLRef CFURLCreateCopyDeletingPathExtension(CFAllocatorRef allocator, CFURLRef url);
 286
 287 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
 288 /* Fills buffer with the bytes for url, returning the number of bytes */
 289 /* filled.  If buffer is of insufficient size, returns -1 and no bytes */
 290 /* are placed in buffer.  If buffer is NULL, the needed length is */
 291 /* computed and returned.  The returned bytes are the original bytes */
 292 /* from which the URL was created; if the URL was created from a */
 293 /* string, the bytes will be the bytes of the string encoded via UTF-8  */
 294 CFIndex CFURLGetBytes(CFURLRef url, UInt8 *buffer, CFIndex bufferLength) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 295
 296 typedef enum {
 297         kCFURLComponentScheme = 1,
 298         kCFURLComponentNetLocation = 2,
 299         kCFURLComponentPath = 3,
 300         kCFURLComponentResourceSpecifier = 4,
 301
 302         kCFURLComponentUser = 5,
 303         kCFURLComponentPassword = 6,
 304         kCFURLComponentUserInfo = 7,
 305         kCFURLComponentHost = 8,
 306         kCFURLComponentPort = 9,
 307         kCFURLComponentParameterString = 10,
 308         kCFURLComponentQuery = 11,
 309         kCFURLComponentFragment = 12
 310 } CFURLComponentType;
 311
 312 /*
 313 Gets the  range of the requested component in the bytes of url, as
 314 returned by CFURLGetBytes().  This range is only good for use in the
 315 bytes returned by CFURLGetBytes!
 316
 317 If non-NULL, rangeIncludingSeparators gives the range of component
 318 including the sequences that separate component from the previous and
 319 next components.  If there is no previous or next component, that end of
 320 rangeIncludingSeparators will match the range of the component itself.
 321 If url does not contain the given component type, (kCFNotFound, 0) is
 322 returned, and rangeIncludingSeparators is set to the location where the
 323 component would be inserted.  Some examples -
 324
 325 For the URL http://www.apple.com/hotnews/
 326
 327 Component           returned range      rangeIncludingSeparators
 328 scheme              (0, 4)              (0, 7)
 329 net location        (7, 13)             (4, 16)
 330 path                (20, 9)             (20, 9)
 331 resource specifier  (kCFNotFound, 0)    (29, 0)
 332 user                (kCFNotFound, 0)    (7, 0)
 333 password            (kCFNotFound, 0)    (7, 0)
 334 user info           (kCFNotFound, 0)    (7, 0)
 335 host                (7, 13)             (4, 16)
 336 port                (kCFNotFound, 0)    (20, 0)
 337 parameter           (kCFNotFound, 0)    (29, 0)
 338 query               (kCFNotFound, 0)    (29, 0)
 339 fragment            (kCFNotFound, 0)    (29, 0)
 340
 341
 342 For the URL ./relPath/file.html#fragment
 343
 344 Component           returned range      rangeIncludingSeparators
 345 scheme              (kCFNotFound, 0)    (0, 0)
 346 net location        (kCFNotFound, 0)    (0, 0)
 347 path                (0, 19)             (0, 20)
 348 resource specifier  (20, 8)             (19, 9)
 349 user                (kCFNotFound, 0)    (0, 0)
 350 password            (kCFNotFound, 0)    (0, 0)
 351 user info           (kCFNotFound, 0)    (0, 0)
 352 host                (kCFNotFound, 0)    (0, 0)
 353 port                (kCFNotFound, 0)    (0, 0)
 354 parameter           (kCFNotFound, 0)    (19, 0)
 355 query               (kCFNotFound, 0)    (19, 0)
 356 fragment            (20, 8)             (19, 9)
 357
 358
 359 For the URL scheme://user:pass@host:1/path/path2/file.html;params?query#fragment
 360
 361 Component           returned range      rangeIncludingSeparators
 362 scheme              (0, 6)              (0, 9)
 363 net location        (9, 16)             (6, 19)
 364 path                (25, 21)            (25, 22)
 365 resource specifier  (47, 21)            (46, 22)
 366 user                (9, 4)              (6, 8)
 367 password            (14, 4)             (13, 6)
 368 user info           (9, 9)              (6, 13)
 369 host                (19, 4)             (18, 6)
 370 port                (24, 1)             (23, 2)
 371 parameter           (47, 6)             (46, 8)
 372 query               (54, 5)             (53, 7)
 373 fragment            (60, 8)             (59, 9)
 374 */
 375 CFRange CFURLGetByteRangeForComponent(CFURLRef url, CFURLComponentType component, CFRange *rangeIncludingSeparators) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 376 #endif
 377
 378 /* Returns a string with any percent escape sequences that do NOT */
 379 /* correspond to characters in charactersToLeaveEscaped with their */
 380 /* equivalent.  Returns NULL on failure (if an invalid percent sequence */
 381 /* is encountered), or the original string (retained) if no characters */
 382 /* need to be replaced. Pass NULL to request that no percent escapes be */
 383 /* replaced, or the empty string (CFSTR("")) to request that all percent */
 384 /* escapes be replaced.  Uses UTF8 to interpret percent escapes. */
 385 CF_EXPORT
 386 CFStringRef CFURLCreateStringByReplacingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveEscaped);
 387
 388 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
 389 /* As above, but allows you to specify the encoding to use when interpreting percent escapes */
 390 CF_EXPORT
 391 CFStringRef CFURLCreateStringByReplacingPercentEscapesUsingEncoding(CFAllocatorRef allocator, CFStringRef origString, CFStringRef charsToLeaveEscaped, CFStringEncoding encoding) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 392 #endif
 393
 394 /* Creates a copy or originalString, replacing certain characters with */
 395 /* the equivalent percent escape sequence based on the encoding specified. */
 396 /* If the originalString does not need to be modified (no percent escape */
 397 /* sequences are missing), may retain and return originalString. */
 398 /* If you are uncertain of the correct encoding, you should use UTF-8, */
 399 /* which is the encoding designated by RFC 2396 as the correct encoding */
 400 /* for use in URLs.  The characters so escaped are all characters that */
 401 /* are not legal URL characters (based on RFC 2396), plus any characters */
 402 /* in legalURLCharactersToBeEscaped, less any characters in */
 403 /* charactersToLeaveUnescaped.  To simply correct any non-URL characters */
 404 /* in an otherwise correct URL string, do: */
 405
 406 /* newString = CFURLCreateStringByAddingPercentEscapes(NULL, origString, NULL, NULL, kCFStringEncodingUTF8); */
 407 CF_EXPORT
 408 CFStringRef CFURLCreateStringByAddingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveUnescaped, CFStringRef legalURLCharactersToBeEscaped, CFStringEncoding encoding);
 409
 410
 411 #if defined(__cplusplus)
 412 }
 413 #endif
 414
 415 #endif /* !__COREFOUNDATION_CFURL__ */
 416