#ifndef __DMIDISKSESSION_H__ #define __DMIDISKSESSION_H__ /* DMiDiskSession.h Copyright (C) 2004-2005 Apple Computer, Inc. All rights reserved. Public header file. */ #import #import #import #import /*! @header DMiDiskSession * @abstract Defines access to the DMiDiskSession object, which provides efficient read/write * access to the iDisk belonging to the associated .Mac account. * @discussion Please note: All server-side paths passed as arguments to DMiDiskSession methods * should start with a forward slash, omitting the iDisk account name at the beginning of the * path--for example, if uploading a local file to a user's Public folder, the second path * passed to the putLocalFileAtPath:toPath: method would be of the format '/Public/filename'. */ @class DMAccount; @class DMTransaction; /*! * @class DMiDiskSession * @abstract A DMiDiskSession object provides efficient read/write access to the iDisk belonging * to the associated .Mac account. */ @interface DMiDiskSession : NSObject { id _credentials; NSString *_owner; id _recent_lock_tokens; id _delegate; BOOL _use_synchronous; NSTimeInterval _lockDuration; id _session_data; BOOL _checked; BOOL _checkPreAuth; BOOL _auto_dispatch; NSLock *_auth_lock; id _my_private_ivars; } #pragma mark - #pragma mark Factories and Initers /*! * @method iDiskSessionWithCredentials: * @abstract Returns a new autoreleased session corresponding to the iDisk for the given credentials. * @discussion This method returns an auto-released iDisk session instance that can be used to perform * I/O transactions with the .Mac iDisk servers. It takes an object that conforms to the DMCredential * protocol--the returned session will be used to access the iDisk owned by the .Mac member with the * given credentials. * @param credentials The .Mac credentials needed for iDisk access. * @result An autoreleased DMiDiskSession object. */ + (id)iDiskSessionWithCredentials: (id )credentials; /*! * @method iDiskSessionWithCredentials:andOwner: * @abstract Returns a new autoreleased session corresponding to the iDisk with the given owner. * @discussion This method returns an auto-released iDisk session instance that can be used to perform * I/O transactions with the .Mac iDisk servers. It takes an object that conforms to the DMCredential * protocol and also takes the name of the .Mac member whose iDisk is to be accessed using the provided * credentials. * @param credentials The .Mac credentials needed for iDisk access. * @param memberName The name of the .Mac member who owns the iDisk that will be accessed. * @result An autoreleased DMiDiskSession object. */ + (id)iDiskSessionWithCredentials: (id )credentials andOwner: (NSString *)memberName; /*! * @method initWithCredentials: * @abstract Initialize a new allocated session corresponding to the provided account's iDisk. * @discussion This method returns an iDisk session instance that can be used to perform I/O * transactions with the .Mac iDisk servers. It takes an object that conforms to the DMCredential * protocol--the returned session will be used to access the iDisk owned by the .Mac member with * the given credentials. * @param credentials The .Mac credentials needed for iDisk access. * @result A newly initialized and allocated DMiDiskSession object. */ - (id)initWithCredentials: (id )credentials; /*! * @method initWithCredentials:andOwner: * @abstract Returns a new allocated session corresponding to the iDisk with the given owner. * @discussion This method returns an iDisk session instance that can be used to perform * I/O transactions with the .Mac iDisk servers. It takes an object that conforms to the DMCredential * protocol and also takes the name of the .Mac member whose iDisk is to be accessed using the provided * credentials. * @param credentials The .Mac credentials needed for iDisk access. * @param memberName The name of the .Mac member who owns the iDisk that will be accessed. * @result An newly initialized and allocated DMiDiskSession object. */ - (id)initWithCredentials: (id )credentials andOwner: (NSString *)memberName; /*! * @method credentials * @abstract Returns the DMCredential-conforming object containing the credentials used to access this * sessionŐs iDisk. * @result An object conforming to the DMCredential protocol. */ - (id )credentials; /*! * @method owner * @abstract Returns the name of the .Mac member who owns the iDisk being accessed by this session. * @result An NSString .Mac member name. */ - (NSString *)owner; #pragma mark - #pragma mark Getting the storage quota /*! * @method quotaAttributes * @abstract Gets the user's iDisk quota and amount of space currently used. * @discussion Use this method to get the user's iDisk quota value along with the amount of storage * space that is currently used. The returned DMTransaction object's result method * returns an NSDictionary containing two NSNumber values, which can be retrieved * using the following key constants: kDMiDiskQuotaInBytes and kDMiDiskSpaceUsedInBytes. * @result Returns a DMTransaction whose result method returns an NSDictionary with the user's * iDisk quota and amount of space currently used. */ - (DMTransaction *)quotaAttributes; #pragma mark - #pragma mark Downloading data /*! * @method getDataAtPath: * @abstract Gets data from the provided iDisk path. * @discussion If the transaction is successful, the returned DMTransaction object's result method * returns an NSData object containing the desired resource (this NSData object is * memory-mapped from a file in /tmp, allowing an application to download a large amount * of data without bringing it into real memory until it is actually needed--clean-up of the * temporary file happens automatically). [Note: If the transaction is asynchronous and is not * yet complete, the result method will return the data that has been downloaded so far.] The * returned DMTransaction object can be used to get the result of the transaction, status, * payload, and many other pieces of information about the actual transaction. * @param sourcePath A remote iDisk path. * @result Returns a DMTransaction whose result method returns an NSData object containing data from * the resource of the provided iDisk path. */ - (DMTransaction *)getDataAtPath: (NSString *)sourcePath; /*! * @method getDataAtPath:ifModifiedSince: * @abstract Gets data from the provided iDisk path. * @discussion If the transaction is successful, the returned DMTransaction object's result method * returns an NSData object containing the desired resource (this NSData object is memory-mapped * from a file in /tmp, allowing an application to download a large amount of data without * bringing it into real memory until it is actually needed--clean-up of the temporary file * happens automatically). [Note: If the transaction is asynchronous and is not yet complete, * the result method will return the data that has been downloaded so far.] * The returned DMTransaction object can be used to get the result of the transaction, status, * payload, and many other pieces of information about the actual transaction. * @param sourcePath A remote iDisk path. * @param lastModifiedDate The modified date which determines whether the server will return data * for this get request. * @result Returns a DMTransaction whose result method returns an NSData object containing data from * the resource referenced by the provided iDisk path. */ - (DMTransaction *)getDataAtPath: (NSString *)sourcePath ifModifiedSince: (NSDate *)lastModifiedDate; /*! * @method getDataAtPath:ifModifiedSince:withByteRange: * @abstract Get data from the provided iDisk path. * @discussion If the transaction is successful, the returned DMTransaction object's result method * returns an NSData object containing the desired resource (this NSData object is memory-mapped * from a file in /tmp, allowing an application to download a large amount of data without * bringing it into real memory until it is actually needed--clean-up of the temporary file * happens automatically). The NSRange object, passed as the byteRange argument, * should have its location set as the index of the first byte to be retrieved and its length * should be set as the total number of bytes to be retrieved, including the first byte. * You can also pass nil for lastModifiedDate if you are not interested in when the server * resource was last modified. [Note: If the transaction is aysnchronous and is not yet * complete, the result method will return the data that has been downloaded so far.] * @param sourcePath A remote iDisk path. * @param lastModifiedDate The modified date which determines whether the server will return data * for this get request. * @param byteRange The byte range of the given resource to be retrieved by this get request. * @result Returns a DMTransaction whose result method returns an NSData object containing data from * the resource of the provided iDisk path. */ - (DMTransaction *)getDataAtPath: (NSString *)sourcePath ifModifiedSince: (NSDate *)lastModifiedDate withByteRange: (NSRange)byteRange; #pragma mark - #pragma mark Uploading data /*! * @method putData:toPath: * @abstract Put data to the provided iDisk path. * @discussion This method places the contents of the data argument into the resource at the * location specified by the destination path. [Note: Call will fail if any sublevels * of destinationPath (excluding the object itself) do not exist, and the call may return * nil if an invalid data argument is passed.] * @param data The data to be uploaded. * @param destinationPath A remote iDisk destination path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)putData: (NSData *)data toPath: (NSString *)destinationPath; /*! * @method putData:toPath:withByteRange: * @abstract Put data to the provided iDisk path. * @discussion This method places the contents of the data argument into the resource at the * location specified by the byteRange argument. The NSRange object, passed as the byteRange * argument, should have its location set as the index of the first byte to be written to * and its length should be set as the total number of bytes, including the first byte. * If the end of the specified range is beyond the end of the file, then the length of the * resource is extended to accommodate all of the bytes. [Note: Call will fail if any * sublevels of destinationPath (excluding the object itself) do not exist, and the call * may return nil if an invalid data argument is passed.] * @param data The data to be uploaded. * @param destinationPath A remote iDisk destination path. * @param byteRange The byte range of the remote resource to which data will be written. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)putData: (NSData *)data toPath: (NSString *)destinationPath withByteRange: (NSRange)byteRange; /*! * @method putLocalFileAtPath:toPath: * @abstract Put the data in the local file to the provided iDisk path. * @discussion This method places the contents of a local file into a new server-side file at * the given destination path. If the localPath parameter refers to a symlink, the * symlink will not be preserved--rather, the resource it references will be uploaded. * [Note: Call will fail if all sublevels of destinationPath (excluding the object itself) * do not already exist, and the call may return nil if an invalid localPath argument is passed.] * @param localPath The path to a local file to be uploaded. * @param destinationPath A remote iDisk destination path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)putLocalFileAtPath: (NSString *)localPath toPath: (NSString *)destinationPath; #pragma mark - #pragma mark Creating collections /*! * @method makeCollectionAtPath: * @abstract Create a collection at the provided iDisk path. * @discussion This method creates a collection (directory) at the location specified in thePath. * If any of the levels above the one being created does not exist, then the create will fail. * @param thePath A remote iDisk path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)makeCollectionAtPath: (NSString *)thePath; #pragma mark - #pragma mark Deleting resources /*! * @method deleteResourceAtPath: * @abstract Deletes the resource at the provided iDisk path. * @discussion Deletes the resource referenced by thePath if it is not locked by another client and * the account who owns the credentials used has write access to thePath. If the delete request * fails because the specified resource or its parent is locked, the returned DMTransaction * object's result method will return an NSArray of NSString's representing the exact uri's * which are currently locked. [Note: Unlike on most file systems, a non-empty collection * (directory) can be deleted. Issuing a delete targeted at a collection will delete the * collection and all of it contents without warning (assuming you have the correct access * privileges).] * @param thePath A remote iDisk path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)deleteResourceAtPath: (NSString *)thePath; #pragma mark - #pragma mark Moving and Copying resources /*! * @method moveResourceAtPath:toPath: * @abstract Moves the remote resource specified in sourcePath to destinationPath on the iDisk. * @discussion Moves the resource identified by sourcePath if it is not locked by another client * and the account who owns the credentials used has write access to destinationPath. This * method will overwrite the resource at destinationPath if that resource is not locked by * another client. * @param sourcePath A remote iDisk source path. * @param destinationPath A remote iDisk destination path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)moveResourceAtPath: (NSString *)sourcePath toPath: (NSString *)destinationPath; /*! * @method copyResourceAtPath:toPath: * @abstract Copies the remote resource specified in sourcePath to destinationPath on the iDisk. * @discussion Copies the resource identified by sourcePath if the account who owns the credentials * used has write access to destinationPath. This method will overwrite the resource at * destinationPath if that resource is not locked by another client. * @param sourcePath A remote iDisk source path. * @param destinationPath A remote iDisk destination path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)copyResourceAtPath: (NSString *)sourcePath toPath: (NSString *)destinationPath; #pragma mark - #pragma mark Locking resources /*! * @method lockResourceAtPath: * @abstract Lock the resource at the given iDisk path. * @discussion Locks the resource referenced by thePath so that only this session can execute write * operations (e.g., PUT, DELETE) on that resource. The iDisk server reserves the right to * grant a lock duration/timeout that differs from the requested lock duration--when this method * is successful, the returned DMTransaction object's result method will return an NSDictionary * containing an NSNumber value (accessible using the kDMLockTimeout key) which is the lock * timeout that was granted by the server. The lock will expire after the time specified by * the granted lock timeout (in seconds) has passed. If the lock request fails because the * specified resource or its parent is already locked, the returned DMTransaction object's * result method will return an NSArray of NSString's representing the exact uri's which are * currently locked. To maintain a lock, issue a relock request on the same resource before * the original lock has expired. [Note: The lock created is a cooperative, 'write' lock.] * @param thePath A remote iDisk path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)lockResourceAtPath: (NSString *)thePath; /*! * @method lockResourceAtPath:withDuration: * @abstract Lock the resource at the given iDisk path with the provided duration. * @discussion Locks the resource referenced by thePath so that only this session can execute write * operations (e.g., PUT, DELETE) on that resource. The iDisk server reserves the right to * grant a lock duration/timeout that differs from the requested lock duration--when this method * is successful, the returned DMTransaction object's result method will return an NSDictionary * containing an NSNumber value (accessible using the kDMLockTimeout key) which is the lock * timeout that was granted by the server. The lock will expire after the time specified by the * granted lock timeout (in seconds) has passed. If the lock request fails because the * specified resource or its parent is already locked, the returned DMTransaction object's * result method will return an NSArray of NSString's representing the exact uri's which are * currently locked. To maintain a lock, issue a relock request on the same resource before * the original lock has expired. [Note: The lock created is a cooperative, 'write' lock.] * @param thePath A remote iDisk path. * @param lockDuration The lock duration, in seconds. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)lockResourceAtPath: (NSString *)thePath withDuration: (NSTimeInterval)lockDuration; /*! * @method relockResourceAtPath: * @abstract Relock the resource at the given iDisk path. * @discussion Refreshes the lock on the resource referenced by thePath. The iDisk server reserves * the right to grant a lock duration/timeout that differs from the requested lock * duration--when this method is successful, the returned DMTransaction object's result method * will return an NSDictionary containing an NSNumber value (accessible using the kDMLockTimeout * key) which is the lock timeout that was granted by the server. Once refreshed, the lock will * expire after the time specified by the granted lock timeout (in seconds) has passed. * Attempting to relock a resource that is not locked will always fail. If the relock request * fails because the specified resource or its parent was originally locked by another client, * the returned DMTransaction object's result method will return an NSArray of NSString's * representing the exact uri's which are currently locked. [Note: The lock created is a * cooperative, 'write' lock.] * @param thePath A remote iDisk path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)relockResourceAtPath: (NSString *)thePath; /*! * @method relockResourceAtPath:withDuration: * @abstract Relock the resource at the given iDisk path with the provided duration. * @discussion Refreshes the lock on the resource referenced by thePath. The iDisk server reserves * the right to grant a lock duration/timeout that differs from the requested lock * duration--when this method is successful, the returned DMTransaction object's result method * will return an NSDictionary containing an NSNumber value (accessible using the kDMLockTimeout * key) which is the lock timeout that was granted by the server. Once refreshed, the lock will * expire after the time specified by the granted lock timeout (in seconds) has passed. * Attempting to relock a resource that is not locked will always fail. If the relock request * fails because the specified resource or its parent was originally locked by another client, * the returned DMTransaction object's result method will return an NSArray of NSString's * representing the exact uri's which are currently locked. [Note: The lock created is a * cooperative, 'write' lock.] * @param thePath A remote iDisk path. * @param lockDuration The lock duration, in seconds. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)relockResourceAtPath: (NSString *)thePath withDuration: (NSTimeInterval)lockDuration; /*! * @method unlockResourceAtPath: * @abstract Unlock the resource at the given iDisk path. * @discussion Releases any lock on the resource referenced by thePath. Attempting to unlock a * resource that is not locked will fail. * @param thePath A remote iDisk path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)unlockResourceAtPath: (NSString *)thePath; #pragma mark - #pragma mark Dealing with lock duration /*! * @method setDefaultLockDuration: * @abstract Set the default lock duration used by this session's lock and relock requests. * @discussion This method sets the default lock duration, in seconds, used by all lock-related * DMiDiskSession methods that do not specify a transaction-specific lock duration of * their own. If this method is not called, the default lock duration is 5 minutes, * given in seconds. * @param lockDuration The lock duration, in seconds. */ - (void)setDefaultLockDuration: (NSTimeInterval)lockDuration; /*! * @method defaultLockDuration * @abstract Get the default lock duration used by this session's lock and relock requests. * @discussion This method returns the default lock duration, in seconds, used by all lock-related * DMiDiskSession methods that do not specify a transaction-specific lock duration of * their own. The default lock duration is 5 minutes, given in seconds. * @result Returns an NSTimeInterval, which is the session's default lock duration, in seconds. */ - (NSTimeInterval)defaultLockDuration; #pragma mark - #pragma mark Getting info on objects and collections /*! * @method resourceExistsAtPath: * @abstract Determines whether the resource at the provided iDisk path exists. * @discussion A method which always operates synchronously, resourceExistsAtPath: returns YES * if the resource specified by thePath exists on the iDisk server, and returns NO otherwise. * [Note: To check for the existence of a resource asynchronously, use the * basicAttributesAtPath: method.] * @param thePath A remote iDisk path. * @result Returns a BOOL indicating whether the resource at the provided iDisk path exists. */ - (BOOL)resourceExistsAtPath: (NSString *)thePath; /*! * @method basicAttributesAtPath: * @abstract Provides access to the basic attributes of a given resource if it exists. * @discussion Performs a lightweight access against a single file or collection (directory) * resource referenced by thePath. Use this method when only basic information such as the * last modified date or content length is needed, as it is lighter weight than an * extendedAttributesAtPath: call. If a resource exists at thePath and the transaction * is successful, the returned DMTransaction object's result method returns an NSDictionary. * That NSDictionary contains resource attributes whose values, if present and applicable, * can be retrieved using the following NSString key constants: kDMContentLength and * kDMLastModified. The value corresponding to the kDMContentLength key is an * NSNumber (in bytes) and the value for the kDMLastModified key is an NSDate. * [Note: kDMContentLength is not returned for collections.] * @param thePath A remote iDisk path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)basicAttributesAtPath: (NSString *)thePath; /*! * @method extendedAttributesAtPath: * @abstract Provides access to the extended attributes of a given resource if it exists. * @discussion This method provides the attributes of the file or collection (directory) resource * specified by thePath. If a resource exists at thePath and the request is successful, * the returned DMTransaction object's result method returns an NSDictionary. That * NSDictionary contains resource attributes whose values, if present and applicable, * can be retrieved using the following NSString key constants: kDMContentLength, * kDMLastModified, kDMURI, kDMDisplayName, kDMContentType, kDMIsCollection, kDMIsLocked, * kDMLockOwner, kDMLockToken and kDMLockTimeout. See the DMTypesAndConstants.h for the value * types which correspond to these keys. [Note: kDMContentLength is not returned for * collections.] * @param thePath A remote iDisk path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)extendedAttributesAtPath: (NSString*)thePath; /*! * @method listCollectionAtPath: * @abstract Provides a shallow listing of the contents of the requested collection. * @discussion This method retrieves the contents of a collection (directory) on the server. * The collection contents retrieved by this method are shallow and therefore do not * include the contents of any subdirectories. If the request is successful, the * returned DMTransaction object's result method returns an NSArray of NSDictionaries. * Each dictionary contained in that array has the same format as the resource * attributes dictionary that is retrieved after calling DMiDiskSession's * extendedAttributesAtPath: method. * @param thePath A remote iDisk path. * @result Returns a DMTransaction object that can be used to get the result of the transaction, * status, payload, and many other pieces of information about the actual transaction. */ - (DMTransaction *)listCollectionAtPath: (NSString *)thePath; #pragma mark - #pragma mark Deprecated methods /* Deprecated -- Use +iDiskSessionWithCredentials: instead */ + (id)iDiskSessionWithAccount: (DMAccount *)account; /* Deprecated -- Use +iDiskSessionWithCredentials: instead */ - (id)initWithAccount: (DMAccount *)account; /* Deprecated -- Use DMTransactionGenerator's -setTransactionDelegate: method instead. */ - (void)setDelegate: (id)delegate; /* Deprecated -- Use DMTransactionGenerator's -transactionDelegate: method instead. */ - (id)delegate; /* Deprecated -- Use DMMemberAccount's -validateCredentials method instead. */ - (int)validateAccess; /* Deprecated -- Use the -credentials method instead. */ - (DMAccount *)account; @end #pragma mark /*! * @category DMiDiskSession(DMiDiskFileManager) * @abstract The DMiDiskFileManager category adds NSFileManager-style methods to DMiDiskSession. */ @interface DMiDiskSession (DMiDiskFileManager) /*! @functiongroup DMiDiskFileManager category methods */ #pragma mark - #pragma mark Creating resources /*! * @method createDirectoryAtPath:attributes: * @abstract Create a directory (collection) at the provided iDisk path. * @discussion This method will create a new directory at the given path. It has the same usage * as the corresponding method of NSFileManager. However, it does not support the setting of * attributes and if a non-nil attributes argument is passed to this method, it will be * ignored. * @param path A remote iDisk path. * @param attributes The attributes argument is ignored. * @result Returns a BOOL indicating whether the method was successful. */ - (BOOL)createDirectoryAtPath:(NSString *)path attributes:(NSDictionary *)attributes; /*! * @method createFileAtPath:contents:attributes: * @abstract Create a file at the given iDisk path containing the provided data. * @discussion This method creates a file at path that contains contents, behavior which matches * the style of the corresponding method of NSFileManager. However, it does not support the * setting of attributes and if a non-nil attributes argument is passed to this method, * it will be ignored. * @param path A remote iDisk path. * @param contents The data to be written to the remote iDisk path. * @param attributes The attributes argument is ignored. * @result Returns a BOOL indicating whether the method was successful. */ - (BOOL)createFileAtPath:(NSString *)path contents:(NSData *)contents attributes:(NSDictionary *)attributes; #pragma mark - #pragma mark Uploading/Downloading/Copying/Moving resources /*! * @method copyPath:toPath:handler: * @abstract Copies the resource at the source path to the destination path. * @discussion This method will create a copy of the source resource at the given destination * path, but will not overwrite an existing resource. Each path argument can be either a * local or a remote path--passing a local source path and remote destination path leads to * an upload of a local resource, while passing a remote source path and local destination * path leads to a download of a remote resource. If two remote paths are provided as * arguments, this method issues a single, server-side COPY request. This method has * usage similar to that of the corresponding method of NSFileManager. However, it does * not support the usage of a callback handler and if a non-nil handler argument is * passed to this method, it will be ignored. Only the data forks of files and * directories are copied. In the case of an upload, local symlinks are not preserved-- * when a symlink is encountered, the resource it references will be uploaded. * [Note: If two local paths are provided as arguments, this method calls * NSFileManager's copyPath:toPath:handler: method with whatever handler argument was * provided.] * @param source A local or remote source path. * @param destination A local or remote destination path. * @param handler The handler argument is ignored. * @result Returns a BOOL indicating whether the method was successful. */ - (BOOL)copyPath:(NSString *)source toPath:(NSString *)destination handler:(id)handler; /*! * @method movePath:toPath:handler: * @abstract Moves the resource at the source path to the destination path. * @discussion This method will move the source resource to the given destination path, but will * not overwrite an existing resource. Each path argument can be either a local or a remote * path--passing a local source path and remote destination path leads to an upload of a * local resource, while passing a remote source path and local destination path leads * to a download of a remote resource. If two remote paths are provided as arguments, * this method issues a single, server-side MOVE request. This method has usage similar * to that of the corresponding method of NSFileManager. However, it does not support * the usage of a callback handler and if a non-nil handler argument is passed to this * method, it will be ignored. Only the data forks of files and directories are moved. * In the case of an upload, local symlinks are not preserved--when a symlink is encountered, * the resource it references will be uploaded. [Note: If two local paths are provided * as arguments, this method calls NSFileManager's copyPath:toPath:handler: method with * whatever handler argument was provided.] * @param source A local or remote source path. * @param destination A local or remote destination path. * @param handler The handler argument is ignored. * @result Returns a BOOL indicating whether the method was successful. */ - (BOOL)movePath:(NSString *)source toPath:(NSString *)destination handler:(id)handler; /*! * @method contentsAtPath: * @abstract Retrieves the data contained in the file referenced by the provided iDisk path. * @discussion Returns the contents of the file specified in the path as an NSData object. If * the path specifies a directory, or if some other error occurs, this method returns nil. * [Note: Only the data fork of the given file is returned.] * @param path A remote iDisk path. * @result Returns an NSData object containing the contents of file referenced by the provided * iDisk path. */ - (NSData *)contentsAtPath:(NSString *)path; #pragma mark - #pragma mark Deleting resources /*! * @method removeFileAtPath:handler: * @abstract Deletes the resource referenced by the provided iDisk path. * @discussion This method will remove the resource at the given path and has the same usage as * the corresponding method of NSFileManager. However, it does not support the usage of a * callback handler and if a non-nil handler argument is passed to this method, it will be * ignored. * @param path A remote iDisk path. * @param handler The handler argument is ignored. * @result Returns a BOOL indicating whether the method was successful. */ - (BOOL)removeFileAtPath:(NSString *)path handler:(id)handler; #pragma mark - #pragma mark Getting info on objects and collections /*! * @method fileExistsAtPath: * @abstract Determines whether the resource at the provided iDisk path exists. * @param path A remote iDisk path. * @result Returns YES if the file specified in path exists, or NO if it does not. */ - (BOOL)fileExistsAtPath:(NSString *)path; /*! * @method fileExistsAtPath:isDirectory: * @abstract Determines whether the resource at the provided iDisk path exists, setting the * BOOL referenced by the isDirectory argument to YES if the given resource is a * directory, and to NO if it is a file. * @param path A remote iDisk path. * @param isDirectory A reference to a BOOL, used to specify whether the given path references a * directory. * @result Returns YES if the file specified in path exists, or NO if it does not. */ - (BOOL)fileExistsAtPath:(NSString *)path isDirectory:(BOOL *)isDirectory; /*! * @method directoryContentsAtPath: * @abstract Provides a shallow listing of the contents of the requested directory. * @discussion Searches the contents of the directory specified by path and returns an array * of strings identifying the directories and files contained in the path. The search is * shallow and therefore does not return the contents of any subdirectories. This * method returns nil if the directory referenced by the path does not exist or there is * some other error accessing it. This method returns an empty array if the directory * exists but has no contents. * @param path A remote iDisk path. * @result Returns an NSArray containing the a contents listing of the specified directory. */ - (NSArray *)directoryContentsAtPath:(NSString *)path; @end #endif