CFURLAccess.h

   1 /*
   2  * Copyright (c) 2015 Apple 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
  24 /*      CFURLAccess.h
  25         Copyright (c) 1998-2014, Apple Inc. All rights reserved.
  26
  27         CFURLAccess is deprecated as of Mac OS X 10.9 and iOS 7.0. The suggested replacement for URLs with network schemes (http, https, ftp, data) are the NSURLSession or NSURLConnection classes. The suggested replacement for URLs with the file scheme are the foundation classes NSFileManager, NSFileHandle and NSURL, or the CoreFoundation classes CFStream and CFURL.
  28 */
  29
  30 #if !defined(__COREFOUNDATION_CFURLACCESS__)
  31 #define __COREFOUNDATION_CFURLACCESS__ 1
  32
  33 #include <CoreFoundation/CFBase.h>
  34 #include <CoreFoundation/CFArray.h>
  35 #include <CoreFoundation/CFData.h>
  36 #include <CoreFoundation/CFDictionary.h>
  37 #include <CoreFoundation/CFError.h>
  38 #include <CoreFoundation/CFString.h>
  39 #include <CoreFoundation/CFURL.h>
  40
  41 CF_IMPLICIT_BRIDGING_ENABLED
  42 CF_EXTERN_C_BEGIN
  43
  44
  45
  46 /* Attempts to read the data and properties for the given URL.  If
  47 only interested in one of the resourceData and properties, pass NULL
  48 for the other.  If properties is non-NULL and desiredProperties is
  49 NULL, then all properties are fetched.  Returns success or failure;
  50 note that as much work as possible is done even if false is returned.
  51 So for instance if one property is not available, the others are
  52 fetched anyway. errorCode is set to 0 on success, and some other
  53 value on failure.  If non-NULL, it is the caller 's responsibility
  54 to release resourceData and properties.
  55
  56     Apple reserves for its use all negative error code values; these
  57 values represent errors common to any scheme.  Scheme-specific error
  58 codes should be positive, non-zero, and should be used only if one of
  59 the predefined Apple error codes does not apply.  Error codes should
  60 be publicized and documented with the scheme-specific properties.
  61
  62 NOTE: When asking for the resource data, this call will allocate the entire
  63 resource in memory. This can be very expensive, depending on the size of the
  64 resource (file). Please use CFStream or other techniques if you are downloading
  65 large files.
  66
  67 */
  68 /* Deprecated -- see top of this file for suggested replacement classes */
  69 CF_EXPORT
  70 Boolean CFURLCreateDataAndPropertiesFromResource(CFAllocatorRef alloc, CFURLRef url, CFDataRef *resourceData, CFDictionaryRef *properties, CFArrayRef desiredProperties, SInt32 *errorCode) CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "For resource data, use the CFReadStream API. For file resource properties, use CFURLCopyResourcePropertiesForKeys.");
  71
  72 /* Attempts to write the given data and properties to the given URL.
  73 If dataToWrite is NULL, only properties are written out (use
  74 CFURLDestroyResource() to delete a resource).  Properties not present
  75 in propertiesToWrite are left unchanged, hence if propertiesToWrite
  76 is NULL or empty, the URL's properties are not changed at all.
  77 Returns success or failure; errorCode is set as for
  78 CFURLCreateDataAndPropertiesFromResource(), above.
  79 */
  80 /* Deprecated -- see top of this file for suggested replacement classes */
  81 CF_EXPORT
  82 Boolean CFURLWriteDataAndPropertiesToResource(CFURLRef url, CFDataRef dataToWrite, CFDictionaryRef propertiesToWrite, SInt32 *errorCode) CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "For resource data, use the CFWriteStream API. For file resource properties, use CFURLSetResourcePropertiesForKeys.");
  83
  84 /* Destroys the resource indicated by url.
  85 Returns success or failure; errorCode set as above.
  86 */
  87 /* Deprecated -- see top of this file for suggested replacement classes */
  88 CF_EXPORT
  89 Boolean CFURLDestroyResource(CFURLRef url, SInt32 *errorCode) CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "Use CFURLGetFileSystemRepresentation and removefile(3) instead.");
  90
  91 /* Convenience method which calls through to CFURLCreateDataAndPropertiesFromResource().
  92 Returns NULL on error and sets errorCode accordingly.
  93 */
  94 /* Deprecated -- see top of this file for suggested replacement classes */
  95 CF_EXPORT
  96 CFTypeRef CFURLCreatePropertyFromResource(CFAllocatorRef alloc, CFURLRef url, CFStringRef property, SInt32 *errorCode) CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "For file resource properties, use CFURLCopyResourcePropertyForKey.");
  97
  98
  99 /* Common error codes (returned only by the older APIs that predate CFError) */
 100 typedef CF_ENUM(CFIndex, CFURLError) {
 101     kCFURLUnknownError = -10L,
 102     kCFURLUnknownSchemeError = -11L,
 103     kCFURLResourceNotFoundError = -12L,
 104     kCFURLResourceAccessViolationError = -13L,
 105     kCFURLRemoteHostUnavailableError = -14L,
 106     kCFURLImproperArgumentsError = -15L,
 107     kCFURLUnknownPropertyKeyError = -16L,
 108     kCFURLPropertyKeyUnavailableError = -17L,
 109     kCFURLTimeoutError = -18L
 110 } CF_ENUM_DEPRECATED(10_0, 10_9, 2_0, 7_0);
 111
 112 /* Older property keys */
 113
 114 CF_EXPORT
 115 const CFStringRef kCFURLFileExists CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "Use CFURLResourceIsReachable instead.");
 116 CF_EXPORT
 117 const CFStringRef kCFURLFileDirectoryContents CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "Use the CFURLEnumerator API instead.");
 118 CF_EXPORT
 119 const CFStringRef kCFURLFileLength CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "Use CFURLCopyResourcePropertyForKey with kCFURLFileSizeKey instead.");
 120 CF_EXPORT
 121 const CFStringRef kCFURLFileLastModificationTime CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "Use CFURLCopyResourcePropertyForKey with kCFURLContentModificationDateKey instead.");
 122 CF_EXPORT
 123 const CFStringRef kCFURLFilePOSIXMode CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "Use CFURLCopyResourcePropertyForKey with kCFURLFileSecurityKey and then the CFFileSecurity API instead.");
 124 CF_EXPORT
 125 const CFStringRef kCFURLFileOwnerID CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "Use CFURLCopyResourcePropertyForKey with kCFURLFileSecurityKey and then the CFFileSecurity API instead.");
 126 CF_EXPORT
 127 const CFStringRef kCFURLHTTPStatusCode CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "Use NSHTTPURLResponse methods instead.");
 128 CF_EXPORT
 129 const CFStringRef kCFURLHTTPStatusLine CF_DEPRECATED(10_0, 10_9, 2_0, 7_0, "Use NSHTTPURLResponse methods instead.");
 130
 131 /* The value of kCFURLFileExists is a CFBoolean */
 132 /* The value of kCFURLFileDirectoryContents is a CFArray containing CFURLs.  An empty array means the directory exists, but is empty */
 133 /* The value of kCFURLFileLength is a CFNumber giving the file's length in bytes */
 134 /* The value of kCFURLFileLastModificationTime is a CFDate */
 135 /* The value of kCFURLFilePOSIXMode is a CFNumber as given in stat.h */
 136 /* The value of kCFURLFileOwnerID is a CFNumber representing the owner's uid */
 137
 138 /* 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 */
 139 /* The value of kCFURLHTTPStatusCode is a CFNumber */
 140 /* The value of kCFURLHTTPStatusLine is a CFString */
 141
 142 CF_EXTERN_C_END
 143 CF_IMPLICIT_BRIDGING_DISABLED
 144
 145 #endif /* ! __COREFOUNDATION_CFURLACCESS__ */
 146