URL.subproj/CFURLAccess.h

   1 /*
   2  * Copyright (c) 2005 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 /*      CFURLAccess.h
  24         Copyright (c) 1998-2005, Apple, Inc. All rights reserved.
  25 */
  26
  27 #if !defined(__COREFOUNDATION_CFURLACCESS__)
  28 #define __COREFOUNDATION_CFURLACCESS__ 1
  29
  30 #include <CoreFoundation/CFBase.h>
  31 #include <CoreFoundation/CFArray.h>
  32 #include <CoreFoundation/CFData.h>
  33 #include <CoreFoundation/CFDictionary.h>
  34 #include <CoreFoundation/CFString.h>
  35 #include <CoreFoundation/CFURL.h>
  36
  37 #if defined(__cplusplus)
  38 extern "C" {
  39 #endif
  40
  41 /* Attempts to read the data and properties for the given URL.  If
  42 only interested in one of the resourceData and properties, pass NULL
  43 for the other.  If properties is non-NULL and desiredProperties is
  44 NULL, then all properties are fetched.  Returns success or failure;
  45 note that as much work as possible is done even if false is returned.
  46 So for instance if one property is not available, the others are
  47 fetched anyway. errorCode is set to 0 on success, and some other
  48 value on failure.  If non-NULL, it is the caller 's responsibility
  49 to release resourceData and properties.
  50
  51     Apple reserves for its use all negative error code values; these
  52 values represent errors common to any scheme.  Scheme-specific error
  53 codes should be positive, non-zero, and should be used only if one of
  54 the predefined Apple error codes does not apply.  Error codes should
  55 be publicized and documented with the scheme-specific properties.
  56
  57 NOTE: When asking for the resource data, this call will allocate the entire
  58 resource in memory. This can be very expensive, depending on the size of the
  59 resource (file). Please use CFStream or other techniques if you are downloading
  60 large files.
  61
  62 */
  63 CF_EXPORT
  64 Boolean CFURLCreateDataAndPropertiesFromResource(CFAllocatorRef alloc, CFURLRef url, CFDataRef *resourceData, CFDictionaryRef *properties, CFArrayRef desiredProperties, SInt32 *errorCode);
  65
  66 /* Attempts to write the given data and properties to the given URL.
  67 If dataToWrite is NULL, only properties are written out (use
  68 CFURLDestroyResource() to delete a resource).  Properties not present
  69 in propertiesToWrite are left unchanged, hence if propertiesToWrite
  70 is NULL or empty, the URL's properties are not changed at all.
  71 Returns success or failure; errorCode is set as for
  72 CFURLCreateDataAndPropertiesFromResource(), above.
  73 */
  74 CF_EXPORT
  75 Boolean CFURLWriteDataAndPropertiesToResource(CFURLRef url, CFDataRef dataToWrite, CFDictionaryRef propertiesToWrite, SInt32 *errorCode);
  76
  77 /* Destroys the resource indicated by url. */
  78 /* Returns success or failure; errorCode set as above. */
  79 CF_EXPORT
  80 Boolean CFURLDestroyResource(CFURLRef url, SInt32 *errorCode);
  81
  82 /* Convenience method which calls through to CFURLCreateDataAndPropertiesFromResource(). */
  83 /* Returns NULL on error and sets errorCode accordingly. */
  84 CF_EXPORT
  85 CFTypeRef CFURLCreatePropertyFromResource(CFAllocatorRef alloc, CFURLRef url, CFStringRef property, SInt32 *errorCode);
  86
  87 /* Common error codes; this list is expected to grow */
  88 typedef enum {
  89     kCFURLUnknownError = -10,
  90     kCFURLUnknownSchemeError = -11,
  91     kCFURLResourceNotFoundError = -12,
  92     kCFURLResourceAccessViolationError = -13,
  93     kCFURLRemoteHostUnavailableError = -14,
  94     kCFURLImproperArgumentsError = -15,
  95     kCFURLUnknownPropertyKeyError = -16,
  96     kCFURLPropertyKeyUnavailableError = -17,
  97     kCFURLTimeoutError = -18
  98 } CFURLError;
  99
 100 /* Property keys */
 101
 102 CF_EXPORT
 103 const CFStringRef kCFURLFileExists;
 104 CF_EXPORT
 105 const CFStringRef kCFURLFileDirectoryContents;
 106 CF_EXPORT
 107 const CFStringRef kCFURLFileLength;
 108 CF_EXPORT
 109 const CFStringRef kCFURLFileLastModificationTime;
 110 CF_EXPORT
 111 const CFStringRef kCFURLFilePOSIXMode;
 112 CF_EXPORT
 113 const CFStringRef kCFURLFileOwnerID;
 114 CF_EXPORT
 115 const CFStringRef kCFURLHTTPStatusCode;
 116 CF_EXPORT
 117 const CFStringRef kCFURLHTTPStatusLine;
 118
 119 /* The value of kCFURLFileExists is a CFBoolean */
 120 /* The value of kCFURLFileDirectoryContents is a CFArray containing CFURLs.  An empty array means the directory exists, but is empty */
 121 /* The value of kCFURLFileLength is a CFNumber giving the file's length in bytes */
 122 /* The value of kCFURLFileLastModificationTime is a CFDate */
 123 /* The value of kCFURLFilePOSIXMode is a CFNumber as given in stat.h */
 124 /* The value of kCFURLFileOwnerID is a CFNumber representing the owner's uid */
 125
 126 /* Properties for the http: scheme.  Except for the common error codes, above, errorCode will be set to the HTTP response status code upon failure.  Any HTTP header name can also be used as a property */
 127 /* The value of kCFURLHTTPStatusCode is a CFNumber */
 128 /* The value of kCFURLHTTPStatusLine is a CFString */
 129
 130 #if defined(__cplusplus)
 131 }
 132 #endif
 133
 134 #endif /* !__COREFOUNDATION_CFURLACCESS__ */
 135