/* NSURL.h Copyright (c) 1997-2012, Apple Inc. All rights reserved. */ #import #import #if !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE) #import #endif @class NSNumber, NSData, NSDictionary; #if (TARGET_OS_EMBEDDED || TARGET_OS_IPHONE) @interface NSURL: NSObject #else @interface NSURL: NSObject #endif { NSString *_urlString; NSURL *_baseURL; void *_clients; __strong void *_reserved; } /* As more schemes are used and understood, strong constants for them will be added here */ FOUNDATION_EXPORT NSString *NSURLFileScheme; /* Convenience initializers */ - (id)initWithScheme:(NSString *)scheme host:(NSString *)host path:(NSString *)path; // this call percent-encodes both the host and path, so this cannot be used to set a username/password or port in the hostname part or with a IPv6 '[...]' type address; use initWithString: and construct the string yourself in those cases - (id)initFileURLWithPath:(NSString *)path isDirectory:(BOOL)isDir NS_AVAILABLE(10_5, 2_0); - (id)initFileURLWithPath:(NSString *)path; // Better to use initFileURLWithPath:isDirectory: if you know if the path is a directory vs non-directory, as it saves an i/o. + (id)fileURLWithPath:(NSString *)path isDirectory:(BOOL) isDir NS_AVAILABLE(10_5, 2_0); + (id)fileURLWithPath:(NSString *)path; // Better to use fileURLWithPath:isDirectory: if you know if the path is a directory vs non-directory, as it saves an i/o. /* These methods expect their string arguments to contain any percent escape codes that are necessary. It is an error for URLString to be nil. */ - initWithString:(NSString *)URLString; - initWithString:(NSString *)URLString relativeToURL:(NSURL *)baseURL; + (id)URLWithString:(NSString *)URLString; + (id)URLWithString:(NSString *)URLString relativeToURL:(NSURL *)baseURL; - (NSString *)absoluteString; - (NSString *)relativeString; // The relative portion of a URL. If baseURL is nil, or if the receiver is itself absolute, this is the same as absoluteString - (NSURL *)baseURL; // may be nil. - (NSURL *)absoluteURL; // if the receiver is itself absolute, this will return self. /* Any URL is composed of these two basic pieces. The full URL would be the concatenation of [myURL scheme], ':', [myURL resourceSpecifier] */ - (NSString *)scheme; - (NSString *)resourceSpecifier; /* If the URL conforms to rfc 1808 (the most common form of URL), the following accessors will return the various components; otherwise they return nil. The litmus test for conformance is as recommended in RFC 1808 - whether the first two characters of resourceSpecifier is @"//". In all cases, they return the component's value after resolving the receiver against its base URL. */ - (NSString *)host; - (NSNumber *)port; - (NSString *)user; - (NSString *)password; - (NSString *)path; - (NSString *)fragment; - (NSString *)parameterString; - (NSString *)query; - (NSString *)relativePath; // The same as path if baseURL is nil - (BOOL)isFileURL; // Whether the scheme is file:; if [myURL isFileURL] is YES, then [myURL path] is suitable for input into NSFileManager or NSPathUtilities. - (NSURL *)standardizedURL; /* Returns whether the URL's resource exists and is reachable. This method synchronously checks if the resource's backing store is reachable. Checking reachability is appropriate when making decisions that do not require other immediate operations on the resource, e.g. periodic maintenance of UI state that depends on the existence of a specific document. When performing operations such as opening a file or copying resource properties, it is more efficient to simply try the operation and handle failures. If this method returns NO, the optional error is populated. This method is currently applicable only to URLs for file system resources. For other URL types, NO is returned. Symbol is present in iOS 4, but performs no operation. */ - (BOOL)checkResourceIsReachableAndReturnError:(NSError **)error NS_AVAILABLE(10_6, 4_0); /* Working with file reference URLs */ /* Returns whether the URL is a file reference URL. Symbol is present in iOS 4, but performs no operation. */ - (BOOL)isFileReferenceURL NS_AVAILABLE(10_6, 4_0); /* Returns a file reference URL that refers to the same resource as a specified file URL. File reference URLs use a URL path syntax that identifies a file system object by reference, not by path. This form of file URL remains valid when the file system path of the URL’s underlying resource changes. An error will occur if the url parameter is not a file URL. File reference URLs cannot be created to file system objects which do not exist or are not reachable. In some areas of the file system hierarchy, file reference URLs cannot be generated to the leaf node of the URL path. A file reference URL's path should never be persistently stored because is not valid across system restarts, and across remounts of volumes -- if you want to create a persistent reference to a file system object, use a bookmark (see -bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error:). Symbol is present in iOS 4, but performs no operation. */ - (NSURL *)fileReferenceURL NS_AVAILABLE(10_6, 4_0); /* Returns a file path URL that refers to the same resource as a specified URL. File path URLs use a file system style path. An error will occur if the url parameter is not a file URL. A file reference URL's resource must exist and be reachable to be converted to a file path URL. Symbol is present in iOS 4, but performs no operation. */ - (NSURL *)filePathURL NS_AVAILABLE(10_6, 4_0); /* Resource access The behavior of resource value caching is slightly different between the NSURL and CFURL API. When the NSURL methods which get, set, or use cached resource values are used from the main thread, resource values cached by the URL (except those added as temporary properties) are invalidated the next time the main thread's run loop runs. The CFURL functions do not automatically clear any resource values cached by the URL. The client has complete control over the cache lifetime. If you are using CFURL API, you must use CFURLClearResourcePropertyCacheForKey or CFURLClearResourcePropertyCache to clear cached resource values. */ /* Returns the resource value identified by a given resource key. This method first checks if the URL object already caches the resource value. If so, it returns the cached resource value to the caller. If not, then this method synchronously obtains the resource value from the backing store, adds the resource value to the URL object's cache, and returns the resource value to the caller. The type of the resource value varies by resource property (see resource key definitions). If this method returns YES and value is populated with nil, it means the resource property is not available for the specified resource and no errors occurred when determining the resource property was not available. If this method returns NO, the optional error is populated. This method is currently applicable only to URLs for file system resources. Symbol is present in iOS 4, but performs no operation. */ - (BOOL)getResourceValue:(out id *)value forKey:(NSString *)key error:(out NSError **)error NS_AVAILABLE(10_6, 4_0); /* Returns the resource values identified by specified array of resource keys. This method first checks if the URL object already caches the resource values. If so, it returns the cached resource values to the caller. If not, then this method synchronously obtains the resource values from the backing store, adds the resource values to the URL object's cache, and returns the resource values to the caller. The type of the resource values vary by property (see resource key definitions). If the result dictionary does not contain a resource value for one or more of the requested resource keys, it means those resource properties are not available for the specified resource and no errors occurred when determining those resource properties were not available. If this method returns NULL, the optional error is populated. This method is currently applicable only to URLs for file system resources. Symbol is present in iOS 4, but performs no operation. */ - (NSDictionary *)resourceValuesForKeys:(NSArray *)keys error:(NSError **)error NS_AVAILABLE(10_6, 4_0); /* Sets the resource value identified by a given resource key. This method writes the new resource value out to the backing store. Attempts to set a read-only resource property or to set a resource property not supported by the resource are ignored and are not considered errors. If this method returns NO, the optional error is populated. This method is currently applicable only to URLs for file system resources. Symbol is present in iOS 4, but performs no operation. */ - (BOOL)setResourceValue:(id)value forKey:(NSString *)key error:(NSError **)error NS_AVAILABLE(10_6, 4_0); /* Sets any number of resource values of a URL's resource. This method writes the new resource values out to the backing store. Attempts to set read-only resource properties or to set resource properties not supported by the resource are ignored and are not considered errors. If an error occurs after some resource properties have been successfully changed, the userInfo dictionary in the returned error contains an array of resource keys that were not set with the key kCFURLKeysOfUnsetValuesKey. The order in which the resource values are set is not defined. If you need to guarantee the order resource values are set, you should make multiple requests to this method or to -setResourceValue:forKey:error: to guarantee the order. If this method returns NO, the optional error is populated. This method is currently applicable only to URLs for file system resources. Symbol is present in iOS 4, but performs no operation. */ - (BOOL)setResourceValues:(NSDictionary *)keyedValues error:(NSError **)error NS_AVAILABLE(10_6, 4_0); FOUNDATION_EXPORT NSString * const NSURLKeysOfUnsetValuesKey NS_AVAILABLE(10_7, 5_0); // Key for the resource properties that have not been set after setResourceValues:error: returns an error, returned as an array of of strings. /* The File System Resource Keys URLs to file system resources support the properties defined below. Note that not all property values will exist for all file system URLs. For example, if a file is located on a volume that does not support creation dates, it is valid to request the creation date property, but the returned value will be nil, and no error will be generated. */ /* Resource keys applicable to all file system objects */ FOUNDATION_EXPORT NSString * const NSURLNameKey NS_AVAILABLE(10_6, 4_0); // The resource name provided by the file system (Read-write, value type NSString) FOUNDATION_EXPORT NSString * const NSURLLocalizedNameKey NS_AVAILABLE(10_6, 4_0); // Localized or extension-hidden name as displayed to users (Read-only, value type NSString) FOUNDATION_EXPORT NSString * const NSURLIsRegularFileKey NS_AVAILABLE(10_6, 4_0); // True for regular files (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsDirectoryKey NS_AVAILABLE(10_6, 4_0); // True for directories (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsSymbolicLinkKey NS_AVAILABLE(10_6, 4_0); // True for symlinks (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsVolumeKey NS_AVAILABLE(10_6, 4_0); // True for the root directory of a volume (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsPackageKey NS_AVAILABLE(10_6, 4_0); // True for packaged directories (Read-only 10_6 and 10_7, read-write 10_8, value type boolean NSNumber). Note: You can only set or clear this property on directories; if you try to set this property on non-directory objects, the property is ignored. If the directory is a package for some other reason (extension type, etc), setting this property to false will have no effect. FOUNDATION_EXPORT NSString * const NSURLIsSystemImmutableKey NS_AVAILABLE(10_6, 4_0); // True for system-immutable resources (Read-write, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsUserImmutableKey NS_AVAILABLE(10_6, 4_0); // True for user-immutable resources (Read-write, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsHiddenKey NS_AVAILABLE(10_6, 4_0); // True for resources normally not displayed to users (Read-write, value type boolean NSNumber). Note: If the resource is a hidden because its name starts with a period, setting this property to false will not change the property. FOUNDATION_EXPORT NSString * const NSURLHasHiddenExtensionKey NS_AVAILABLE(10_6, 4_0); // True for resources whose filename extension is removed from the localized name property (Read-write, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLCreationDateKey NS_AVAILABLE(10_6, 4_0); // The date the resource was created (Read-write, value type NSDate) FOUNDATION_EXPORT NSString * const NSURLContentAccessDateKey NS_AVAILABLE(10_6, 4_0); // The date the resource was last accessed (Read-only, value type NSDate) FOUNDATION_EXPORT NSString * const NSURLContentModificationDateKey NS_AVAILABLE(10_6, 4_0); // The time the resource content was last modified (Read-write, value type NSDate) FOUNDATION_EXPORT NSString * const NSURLAttributeModificationDateKey NS_AVAILABLE(10_6, 4_0); // The time the resource's attributes were last modified (Read-write, value type NSDate) FOUNDATION_EXPORT NSString * const NSURLLinkCountKey NS_AVAILABLE(10_6, 4_0); // Number of hard links to the resource (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLParentDirectoryURLKey NS_AVAILABLE(10_6, 4_0); // The resource's parent directory, if any (Read-only, value type NSURL) FOUNDATION_EXPORT NSString * const NSURLVolumeURLKey NS_AVAILABLE(10_6, 4_0); // URL of the volume on which the resource is stored (Read-only, value type NSURL) FOUNDATION_EXPORT NSString * const NSURLTypeIdentifierKey NS_AVAILABLE(10_6, 4_0); // Uniform type identifier (UTI) for the resource (Read-only, value type NSString) FOUNDATION_EXPORT NSString * const NSURLLocalizedTypeDescriptionKey NS_AVAILABLE(10_6, 4_0); // User-visible type or "kind" description (Read-only, value type NSString) FOUNDATION_EXPORT NSString * const NSURLLabelNumberKey NS_AVAILABLE(10_6, 4_0); // The label number assigned to the resource (Read-write, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLLabelColorKey NS_AVAILABLE(10_6, 4_0); // The color of the assigned label (Read-only, value type NSColor) FOUNDATION_EXPORT NSString * const NSURLLocalizedLabelKey NS_AVAILABLE(10_6, 4_0); // The user-visible label text (Read-only, value type NSString) FOUNDATION_EXPORT NSString * const NSURLEffectiveIconKey NS_AVAILABLE(10_6, 4_0); // The icon normally displayed for the resource (Read-only, value type NSImage) FOUNDATION_EXPORT NSString * const NSURLCustomIconKey NS_AVAILABLE(10_6, 4_0); // The custom icon assigned to the resource, if any (Currently not implemented, value type NSImage) FOUNDATION_EXPORT NSString * const NSURLFileResourceIdentifierKey NS_AVAILABLE(10_7, 5_0); // An identifier which can be used to compare two file system objects for equality using -isEqual (i.e, two object identifiers are equal if they have the same file system path or if the paths are linked to same inode on the same file system). This identifier is not persistent across system restarts. (Read-only, value type id) FOUNDATION_EXPORT NSString * const NSURLVolumeIdentifierKey NS_AVAILABLE(10_7, 5_0); // An identifier that can be used to identify the volume the file system object is on. Other objects on the same volume will have the same volume identifier and can be compared using for equality using -isEqual. This identifier is not persistent across system restarts. (Read-only, value type id) FOUNDATION_EXPORT NSString * const NSURLPreferredIOBlockSizeKey NS_AVAILABLE(10_7, 5_0); // The optimal block size when reading or writing this file's data, or nil if not available. (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsReadableKey NS_AVAILABLE(10_7, 5_0); // true if this process (as determined by EUID) can read the resource. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsWritableKey NS_AVAILABLE(10_7, 5_0); // true if this process (as determined by EUID) can write to the resource. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsExecutableKey NS_AVAILABLE(10_7, 5_0); // true if this process (as determined by EUID) can execute a file resource or search a directory resource. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLFileSecurityKey NS_AVAILABLE(10_7, 5_0); // The file system object's security information encapsulated in a NSFileSecurity object. (Value type NSFileSecurity) FOUNDATION_EXPORT NSString * const NSURLIsExcludedFromBackupKey NS_AVAILABLE(10_8, 5_1); // true if resource should be excluded from backups, false otherwise (Read-write, value type boolean NSNumber). This property is only useful for excluding cache and other application support files which are not needed in a backup. Some operations commonly made to user documents will cause this property to be reset to false and so this property should not be used on user documents. FOUNDATION_EXPORT NSString * const NSURLPathKey NS_AVAILABLE(10_8, 6_0); // the URL's path as a file system path (Read-only, value type NSString) FOUNDATION_EXPORT NSString * const NSURLIsMountTriggerKey NS_AVAILABLE(10_7, 5_0); // true if this URL is a file system trigger directory. Traversing or opening a file system trigger will cause an attempt to mount a file system on the trigger directory. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLFileResourceTypeKey NS_AVAILABLE(10_7, 5_0); // Returns the file system object type. (Read-only, value type NSString) /* The file system object type values returned for the NSURLFileResourceTypeKey */ FOUNDATION_EXPORT NSString * const NSURLFileResourceTypeNamedPipe NS_AVAILABLE(10_7, 5_0); FOUNDATION_EXPORT NSString * const NSURLFileResourceTypeCharacterSpecial NS_AVAILABLE(10_7, 5_0); FOUNDATION_EXPORT NSString * const NSURLFileResourceTypeDirectory NS_AVAILABLE(10_7, 5_0); FOUNDATION_EXPORT NSString * const NSURLFileResourceTypeBlockSpecial NS_AVAILABLE(10_7, 5_0); FOUNDATION_EXPORT NSString * const NSURLFileResourceTypeRegular NS_AVAILABLE(10_7, 5_0); FOUNDATION_EXPORT NSString * const NSURLFileResourceTypeSymbolicLink NS_AVAILABLE(10_7, 5_0); FOUNDATION_EXPORT NSString * const NSURLFileResourceTypeSocket NS_AVAILABLE(10_7, 5_0); FOUNDATION_EXPORT NSString * const NSURLFileResourceTypeUnknown NS_AVAILABLE(10_7, 5_0); /* Resource keys applicable only to regular files */ FOUNDATION_EXPORT NSString * const NSURLFileSizeKey NS_AVAILABLE(10_6, 4_0); // Total file size in bytes (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLFileAllocatedSizeKey NS_AVAILABLE(10_6, 4_0); // Total size allocated on disk for the file in bytes (number of blocks times block size) (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLTotalFileSizeKey NS_AVAILABLE(10_7, 5_0); // Total displayable size of the file in bytes (this may include space used by metadata), or nil if not available. (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLTotalFileAllocatedSizeKey NS_AVAILABLE(10_7, 5_0); // Total allocated size of the file in bytes (this may include space used by metadata), or nil if not available. This can be less than the value returned by NSURLTotalFileSizeKey if the resource is compressed. (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLIsAliasFileKey NS_AVAILABLE(10_6, 4_0); // true if the resource is a Finder alias file or a symlink, false otherwise ( Read-only, value type boolean NSNumber) /* Volumes resource keys As a convenience, volume resource values can be requested from any file system URL. The value returned will reflect the property value for the volume on which the resource is located. */ FOUNDATION_EXPORT NSString * const NSURLVolumeLocalizedFormatDescriptionKey NS_AVAILABLE(10_6, 4_0); // The user-visible volume format (Read-only, value type NSString) FOUNDATION_EXPORT NSString * const NSURLVolumeTotalCapacityKey NS_AVAILABLE(10_6, 4_0); // Total volume capacity in bytes (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeAvailableCapacityKey NS_AVAILABLE(10_6, 4_0); // Total free space in bytes (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeResourceCountKey NS_AVAILABLE(10_6, 4_0); // Total number of resources on the volume (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsPersistentIDsKey NS_AVAILABLE(10_6, 4_0); // true if the volume format supports persistent object identifiers and can look up file system objects by their IDs (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsSymbolicLinksKey NS_AVAILABLE(10_6, 4_0); // true if the volume format supports symbolic links (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsHardLinksKey NS_AVAILABLE(10_6, 4_0); // true if the volume format supports hard links (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsJournalingKey NS_AVAILABLE(10_6, 4_0); // true if the volume format supports a journal used to speed recovery in case of unplanned restart (such as a power outage or crash). This does not necessarily mean the volume is actively using a journal. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeIsJournalingKey NS_AVAILABLE(10_6, 4_0); // true if the volume is currently using a journal for speedy recovery after an unplanned restart. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsSparseFilesKey NS_AVAILABLE(10_6, 4_0); // true if the volume format supports sparse files, that is, files which can have 'holes' that have never been written to, and thus do not consume space on disk. A sparse file may have an allocated size on disk that is less than its logical length (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsZeroRunsKey NS_AVAILABLE(10_6, 4_0); // For security reasons, parts of a file (runs) that have never been written to must appear to contain zeroes. true if the volume keeps track of allocated but unwritten runs of a file so that it can substitute zeroes without actually writing zeroes to the media. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsCaseSensitiveNamesKey NS_AVAILABLE(10_6, 4_0); // true if the volume format treats upper and lower case characters in file and directory names as different. Otherwise an upper case character is equivalent to a lower case character, and you can't have two names that differ solely in the case of the characters. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsCasePreservedNamesKey NS_AVAILABLE(10_6, 4_0); // true if the volume format preserves the case of file and directory names. Otherwise the volume may change the case of some characters (typically making them all upper or all lower case). (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsRootDirectoryDatesKey NS_AVAILABLE(10_7, 5_0); // true if the volume supports reliable storage of times for the root directory. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsVolumeSizesKey NS_AVAILABLE(10_7, 5_0); // true if the volume supports returning volume size values (NSURLVolumeTotalCapacityKey and NSURLVolumeAvailableCapacityKey). (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsRenamingKey NS_AVAILABLE(10_7, 5_0); // true if the volume can be renamed. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsAdvisoryFileLockingKey NS_AVAILABLE(10_7, 5_0); // true if the volume implements whole-file flock(2) style advisory locks, and the O_EXLOCK and O_SHLOCK flags of the open(2) call. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeSupportsExtendedSecurityKey NS_AVAILABLE(10_7, 5_0); // true if the volume implements extended security (ACLs). (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeIsBrowsableKey NS_AVAILABLE(10_7, 5_0); // true if the volume should be visible via the GUI (i.e., appear on the Desktop as a separate volume). (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeMaximumFileSizeKey NS_AVAILABLE(10_7, 5_0); // The largest file size (in bytes) supported by this file system, or nil if this cannot be determined. (Read-only, value type NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeIsEjectableKey NS_AVAILABLE(10_7, 5_0); // true if the volume's media is ejectable from the drive mechanism under software control. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeIsRemovableKey NS_AVAILABLE(10_7, 5_0); // true if the volume's media is removable from the drive mechanism. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeIsInternalKey NS_AVAILABLE(10_7, 5_0); // true if the volume's device is connected to an internal bus, false if connected to an external bus, or nil if not available. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeIsAutomountedKey NS_AVAILABLE(10_7, 5_0); // true if the volume is automounted. Note: do not mistake this with the functionality provided by kCFURLVolumeSupportsBrowsingKey. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeIsLocalKey NS_AVAILABLE(10_7, 5_0); // true if the volume is stored on a local device. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeIsReadOnlyKey NS_AVAILABLE(10_7, 5_0); // true if the volume is read-only. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLVolumeCreationDateKey NS_AVAILABLE(10_7, 5_0); // The volume's creation date, or nil if this cannot be determined. (Read-only, value type NSDate) FOUNDATION_EXPORT NSString * const NSURLVolumeURLForRemountingKey NS_AVAILABLE(10_7, 5_0); // The NSURL needed to remount a network volume, or nil if not available. (Read-only, value type NSURL) FOUNDATION_EXPORT NSString * const NSURLVolumeUUIDStringKey NS_AVAILABLE(10_7, 5_0); // The volume's persistent UUID as a string, or nil if a persistent UUID is not available for the volume. (Read-only, value type NSString) FOUNDATION_EXPORT NSString * const NSURLVolumeNameKey NS_AVAILABLE(10_7, 5_0); // The name of the volume (settable if NSURLVolumeSupportsRenamingKey is YES, value type NSString) FOUNDATION_EXPORT NSString * const NSURLVolumeLocalizedNameKey NS_AVAILABLE(10_7, 5_0); // The user-presentable name of the volume (Read-only, value type NSString) /* Ubiquitous item resource keys */ FOUNDATION_EXPORT NSString * const NSURLIsUbiquitousItemKey NS_AVAILABLE(10_7, 5_0); // true if this item is synced to the cloud, false if it is only a local file. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLUbiquitousItemHasUnresolvedConflictsKey NS_AVAILABLE(10_7, 5_0); // true if this item has conflicts outstanding. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLUbiquitousItemIsDownloadedKey NS_AVAILABLE(10_7, 5_0); // true if there is local data present for this item. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLUbiquitousItemIsDownloadingKey NS_AVAILABLE(10_7, 5_0); // true if data is being downloaded for this item. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLUbiquitousItemIsUploadedKey NS_AVAILABLE(10_7, 5_0); // true if there is data present in the cloud for this item. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLUbiquitousItemIsUploadingKey NS_AVAILABLE(10_7, 5_0); // true if data is being uploaded for this item. (Read-only, value type boolean NSNumber) FOUNDATION_EXPORT NSString * const NSURLUbiquitousItemPercentDownloadedKey NS_DEPRECATED(10_7, 10_8, 5_0, 6_0); // Use NSMetadataQuery and NSMetadataUbiquitousItemPercentDownloadedKey on NSMetadataItem instead FOUNDATION_EXPORT NSString * const NSURLUbiquitousItemPercentUploadedKey NS_DEPRECATED(10_7, 10_8, 5_0, 6_0); // Use NSMetadataQuery and NSMetadataUbiquitousItemPercentUploadedKey on NSMetadataItem instead /* Working with Bookmarks and alias (bookmark) files */ typedef NS_OPTIONS(NSUInteger, NSURLBookmarkCreationOptions) { NSURLBookmarkCreationPreferFileIDResolution = ( 1UL << 8 ), /* At resolution time, this bookmark will prefer resolving by the embedded fileID to the path */ NSURLBookmarkCreationMinimalBookmark = ( 1UL << 9 ), /* Creates a bookmark with "less" information, which may be smaller but still be able to resolve in certain ways */ NSURLBookmarkCreationSuitableForBookmarkFile = ( 1UL << 10 ), /* include properties required in Finder alias files in created bookmark */ NSURLBookmarkCreationWithSecurityScope NS_ENUM_AVAILABLE(10_7, NA) = ( 1 << 11 ), /* include information in the bookmark data which allows the same sandboxed process to access the resource after being relaunched */ NSURLBookmarkCreationSecurityScopeAllowOnlyReadAccess NS_ENUM_AVAILABLE(10_7, NA) = ( 1 << 12 ), /* if used with kCFURLBookmarkCreationWithSecurityScope, at resolution time only read access to the resource will be granted */ } NS_ENUM_AVAILABLE(10_6, 4_0); typedef NS_OPTIONS(NSUInteger, NSURLBookmarkResolutionOptions) { NSURLBookmarkResolutionWithoutUI = ( 1UL << 8 ), /* don't perform any UI during bookmark resolution */ NSURLBookmarkResolutionWithoutMounting = ( 1UL << 9 ), /* don't mount a volume during bookmark resolution */ NSURLBookmarkResolutionWithSecurityScope NS_ENUM_AVAILABLE(10_7, NA) = ( 1 << 10 ) /* use the secure information included at creation time to provide the ability to access the resource in a sandboxed process */ }; typedef NSUInteger NSURLBookmarkFileCreationOptions; /* Create a NSData containing a externalizable representation from a given url, which can later be resolved or interrogated for properties */ - (NSData *)bookmarkDataWithOptions:(NSURLBookmarkCreationOptions)options includingResourceValuesForKeys:(NSArray *)keys relativeToURL:(NSURL *)relativeURL error:(NSError **)error NS_AVAILABLE(10_6, 4_0); /* Resolve bookmark data into a url; init and factory methods */ - (id)initByResolvingBookmarkData:(NSData *)bookmarkData options:(NSURLBookmarkResolutionOptions)options relativeToURL:(NSURL *)relativeURL bookmarkDataIsStale:(BOOL *)isStale error:(NSError **)error NS_AVAILABLE(10_6, 4_0); + (id)URLByResolvingBookmarkData:(NSData *)bookmarkData options:(NSURLBookmarkResolutionOptions)options relativeToURL:(NSURL *)relativeURL bookmarkDataIsStale:(BOOL *)isStale error:(NSError **)error NS_AVAILABLE(10_6, 4_0); /* Property access. Given a NSData* created with bookmarkDataWithOptions, return a given property or all of the properties in bookmark data */ + (NSDictionary *)resourceValuesForKeys:(NSArray *)keys fromBookmarkData:(NSData *)bookmarkData NS_AVAILABLE(10_6, 4_0); /* Create a bookmark file on disk at bookmarkFileURL which can be resolved back to the file system item represented by bookmarkData, using the given options. If relativeToURL is non-NULL, create a relative url. The bookmark data must have been created with the NSURLBookmarkCreationSuitableForBookmarkFile flag or this routine will fail. If bookmarkFileURL is a directory then the file will be created in that directory with the name of the item represented by the bookmarkData with ".alias" appended. If bookmarkFileURL is a file url then its extension will be changed to ".alias", if not present. */ + (BOOL)writeBookmarkData:(NSData *)bookmarkData toURL:(NSURL *)bookmarkFileURL options:(NSURLBookmarkFileCreationOptions)options error:(NSError **)error NS_AVAILABLE(10_6, 4_0); /* Given the url of a file which is a Finder "alias" file, return a NSData with the bookmark data from the file. If bookmarkFileURL points to an alias file created before SnowLeopard which contains Alias Manager information and no bookmark data, then a NSData will be synthesized which contains a approximation of the alias information in a format which can be used to resolve the bookmark. If an error prevents reading the data or if it is corrupt, nil will be returned and error will be filled in if errorRef is non-NULL. */ + (NSData *)bookmarkDataWithContentsOfURL:(NSURL *)bookmarkFileURL error:(NSError **)error NS_AVAILABLE(10_6, 4_0); /* Given a NSURL created by resolving a bookmark data created with security scope, make the resource referenced by the url accessible to the process. When access to this resource is no longer needed the client should call stopAccessingSecurityScopedResource. Each call to startAccessingSecurityScopedResource must be balanced with a call to stopAccessingSecurityScopedResource */ - (BOOL) startAccessingSecurityScopedResource NS_AVAILABLE(10_7, NA); /* Revokes the access granted to the url by a prior successful call to startAccessingSecurityScopedResource */ - (void) stopAccessingSecurityScopedResource NS_AVAILABLE(10_7, NA); @end @interface NSString (NSURLUtilities) /* Adds all percent escapes necessary to convert the receiver into a legal URL string. Uses the given encoding to determine the correct percent escapes (returning nil if the given encoding cannot encode a particular character). See CFURLCreateStringByAddingPercentEscapes in CFURL.h for more complex transformations */ - (NSString *)stringByAddingPercentEscapesUsingEncoding:(NSStringEncoding)enc; /* Replaces all percent escapes with the matching characters as determined by the given encoding. Returns nil if the transformation is not possible (i.e. the percent escapes give a byte sequence not legal in the given encoding). See CFURLCreateStringByReplacingPercentEscapes in CFURL.h for more complex transformations */ - (NSString *)stringByReplacingPercentEscapesUsingEncoding:(NSStringEncoding)enc; @end @interface NSURL (NSURLPathUtilities) /* The following methods work on the path portion of a URL in the same manner that the NSPathUtilities methods on NSString do. */ + (NSURL *)fileURLWithPathComponents:(NSArray *)components NS_AVAILABLE(10_6, 4_0); - (NSArray *)pathComponents NS_AVAILABLE(10_6, 4_0); - (NSString *)lastPathComponent NS_AVAILABLE(10_6, 4_0); - (NSString *)pathExtension NS_AVAILABLE(10_6, 4_0); - (NSURL *)URLByAppendingPathComponent:(NSString *)pathComponent NS_AVAILABLE(10_6, 4_0); - (NSURL *)URLByAppendingPathComponent:(NSString *)pathComponent isDirectory:(BOOL)isDirectory NS_AVAILABLE(10_7, 5_0); - (NSURL *)URLByDeletingLastPathComponent NS_AVAILABLE(10_6, 4_0); - (NSURL *)URLByAppendingPathExtension:(NSString *)pathExtension NS_AVAILABLE(10_6, 4_0); - (NSURL *)URLByDeletingPathExtension NS_AVAILABLE(10_6, 4_0); /* The following methods work only on `file:` scheme URLs; for non-`file:` scheme URLs, these methods return the URL unchanged. */ - (NSURL *)URLByStandardizingPath NS_AVAILABLE(10_6, 4_0); - (NSURL *)URLByResolvingSymlinksInPath NS_AVAILABLE(10_6, 4_0) ; @end #if (TARGET_OS_MAC || (TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) /* NSFileSecurity encapsulates a file system object's security information. NSFileSecurity and CFFileSecurity are toll-free bridged. */ @interface NSFileSecurity : NSObject @end #endif /* deprecated interfaces */ #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) /* Client informal protocol for use with the deprecated loadResourceDataNotifyingClient: below. */ @interface NSObject (NSURLClient) - (void)URL:(NSURL *)sender resourceDataDidBecomeAvailable:(NSData *)newBytes NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); - (void)URLResourceDidFinishLoading:(NSURL *)sender NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); - (void)URLResourceDidCancelLoading:(NSURL *)sender NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); - (void)URL:(NSURL *)sender resourceDidFailLoadingWithReason:(NSString *)reason NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); @end /* This entire protocol is deprecated; use NSURLConnection instead. */ @interface NSURL (NSURLLoading) - (NSData *)resourceDataUsingCache:(BOOL)shouldUseCache NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); // Blocks to load the data if necessary. If shouldUseCache is YES, then if an equivalent URL has already been loaded and cached, its resource data will be returned immediately. If shouldUseCache is NO, a new load will be started - (void)loadResourceDataNotifyingClient:(id)client usingCache:(BOOL)shouldUseCache NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); // Starts an asynchronous load of the data, registering delegate to receive notification. Only one such background load can proceed at a time. - (id)propertyForKey:(NSString *)propertyKey NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); /* These attempt to write the given arguments for the resource specified by the URL; they return success or failure */ - (BOOL)setResourceData:(NSData *)data NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); - (BOOL)setProperty:(id)property forKey:(NSString *)propertyKey NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); - (NSURLHandle *)URLHandleUsingCache:(BOOL)shouldUseCache NS_DEPRECATED(10_0, 10_4, 2_0, 2_0); // Sophisticated clients will want to ask for this, then message the handle directly. If shouldUseCache is NO, a newly instantiated handle is returned, even if an equivalent URL has been loaded @end #endif