Although you can quickly delete all the files in the Documents directory using iTunes, I also was looking for a way to clean up the same directory when my device was not connected.

(more...)

I have written about some excellent tutorials and libraries in the past such as this tutorial on using NSCoding and NSFileManager, and this library for simple data saving/loading.

This library takes a different approach, and it’s one that you may get a lot of mileage from.

This open source library acts as an NSCoding replacement, and when added to your project automatically adds methods to create an NSDictionary representation for easy saving/loading to a .PLIST file.

Also supported is saving of various Cocoa collection types and structures.

The library is Auto Magic Coding (AMC) from Stephan Generalov.

On the Github page here you’ll find full instructions along with further information on collections and structures that can be saved.

A very handy library for persisting object data.

Open Source: Library Allows Any Objective-C Object To Easily Be Saved To A Plist File

If you are building a more elaborate iPhone application than just a button which farts or some colorful ball which moves out of your finger you will inevitably want to read and write some files in the iPhone filesystem.

Most of the file operations will start by creating a file manager, though some objects as NSArray and NSDictionary provide handy functions to directly read and write files.

NSFileManager

NSFileManager* fileManager = [NSFileManager defaultManager];

NSFileManager provides a load of handy methods, so it’s always good to check also the XCode documentation of the class.

First of all you will need to get your file’s location. Each application on the iPhone has its own Sandbox which provides you with several different folders to work with. Documents will be the place you want to save your content, read and write files, etc.

Since CocoaTouch conforms to a big extent with OS X, you need to query the filesystem for the current user’s folders. On a mac for example there will be different users like Peter, John, Grandma, etc. Each of them will have separate Documents folder located at a different path. On the iPhone (for the moment) there’s only one user, but you will still need to query the system for the current user’s locations.

As in this example:

NSFileManager* fileManager = [NSFileManager defaultManager];
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory , NSUserDomainMask, YES);
NSString* documentsDir = [paths objectAtIndex:0];

You can get a list of different locations, for reference have a look at the NSSearchPathDirectory definition:

enum {
   NSApplicationDirectory = 1,
   NSDemoApplicationDirectory,
   NSDeveloperApplicationDirectory,
   NSAdminApplicationDirectory,
   NSLibraryDirectory,
   NSDeveloperDirectory,
   NSUserDirectory,
   NSDocumentationDirectory,
   NSDocumentDirectory,
   NSCoreServiceDirectory,
   NSAutosavedInformationDirectory = 11,
   NSDesktopDirectory = 12,
   NSCachesDirectory = 13,
   NSApplicationSupportDirectory = 14,
   NSDownloadsDirectory = 15,
   NSInputMethodsDirectory = 16,
   NSMoviesDirectory = 17,
   NSMusicDirectory = 18,
   NSPicturesDirectory = 19,
   NSPrinterDescriptionDirectory = 20,
   NSSharedPublicDirectory = 21,
   NSPreferencePanesDirectory = 22,
   NSItemReplacementDirectory = 99,
   NSAllApplicationsDirectory = 100,
   NSAllLibrariesDirectory = 101
};
typedef NSUInteger NSSearchPathDirectory;

Once you have the directory path, you can just put yourself together the full file path:

NSString* myFilePath = [NSString stringWithFormat:@”%@/%@”, documentsDir, @”file.txt”];

Here is a list of few functions you might immediately need when dealing with files:

- (BOOL)isDeletableFileAtPath:(NSString *)path

Checks if the file at the given path can be deleted.

- (BOOL)isReadableFileAtPath:(NSString *)path

Checks if the file’s contents at the given path can be loaded.

- (BOOL)isWritableFileAtPath:(NSString *)path

Checks if the app can write at the specified file path.

- (BOOL)fileExistsAtPath:(NSString *)path

Checks if a file exists with the given file path.

- (BOOL)fileExistsAtPath:(NSString *)path isDirectory:(BOOL *)isDirectory

Checks if a file exists with the given file path and you can specify it should be a normal file or a file directory.

- (BOOL)contentsEqualAtPath:(NSString *)path1 andPath:(NSString *)path2

Compares if two given files’ content is the same.

Enumerating trough a directory’s contents

- (NSArray *)contentsOfDirectoryAtPath:(NSString *)path error:(NSError **)error

Gives you an NSArray of all files found in the given directory path. The most simple way to read directory’s contents :

for (NSString* fileName in [fileManager contentsOfDirectoryAtPath: [[NSBundle mainBundle] resourcePath] error:nil]) {
NSLog(@”file: %@”, fileName);
}

This example will show you the contents of your app’s resources directory (eg. the files you bundle with your app)

Reading and Writing files

You can use NSData to hold the contents of a file you want to read or write:

NSData* data [fileManager contentesAtPath:filePath];
[fileManager createFileAtPath:filePath contents:data attributes:nil];

This way you should deal with the data format you are going to supply to NSData yourself. If your data is property list data: NSString, NSInteger, NSData, NSArray, etc. it is much easier to use the handy functions below.

Let’s say you have a list of values (or a tree of values) which can be stored as an xml file. In this case you can tell directly to your NSArray or NSDictionary to save it contents to a file, or read the contents of a file and populate itself.

NSArray* array = … some initialization …
[array writeToFile:myFilePath atomically:YES];
NSArray* newArray = [NSArray arrayWithContentsOfFile:myFilePath];

NSDictionary* dict = …some initialization …
[dict writeToFile:myFilePath atomically:YES];
NSDictionary* newDict = [NSDictionary dictionaryWithContentesOfFile:myFilePath];

Managing files

[fileManager moveItemAtPath:myPath toPath:myNewPath error:NULL];

Moves (or if you move to the same directory renames) a file.

[fileManager copyItemAtPath:myPath toPath:myNewPath error:NULL];

Copies a file to a new location.

[fileManager removeItemAtPath: myPath error:NULL];

Deletes the file from the file system.

This wraps up the overview of working with files.

You can share files between an iOS app and your Mac using file sharing via iTunes. Using file sharing the contents of your application’s Documents directory is available in iTunes. This also works the other way, where you can place files from your Mac into the shared area of iTunes and make them available to your iOS app.

This feature works well if you need to log information from within your app and make the log available for offline viewing at another time. I’ve used idea this a number of times to save debugging information for later viewing.

UIFileSharingEnabled

The first step is to add the flag UIFileSharingEnabled to the application plist file. If you edit the plist as XML, you can add the flag as shown here:

<key>UIFileSharingEnabled</key>
<true/>

Using the plist editor, the entry is as shown below:

Write a file to Document Directory

With the property file updated, the next step is to write a file to the Documents directory within the app. The code below creates an array as well as a dictionary object and writes both containers to a file named DictionaryContents.text.

- (void) writeFileToDocumentDirectory
{
  NSArray *grains = [NSArray arrayWithObjects:
                    @"Caramunich", @"Hallertauer", @"Special B", nil];

  NSDictionary *dictionary = [NSDictionary dictionaryWithObjectsAndKeys:
                             grains, @"arrayKey", @"Magnum", @"hopKey", @"Belgian Strong", @"yeastKey", nil];

  // Get path to documents directory
  NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
                                                       NSUserDomainMask, YES);
  if ([paths count] > 0)
  {
    // Path to save dictionary
    NSString  *dictPath = [[paths objectAtIndex:0]
                           stringByAppendingPathComponent:@"DictionaryContents.text"];
    // Write dictionary
    [dictionary writeToFile:dictPath atomically:YES];
  }
}

Call the method above somewhere in your application to write the file to the Documentsdirectory.

iTunes File Sharing

To view the file within iTunes, plugin your device and select your device in the DEVICES section on the left:

Choose the Apps button on the top of iTunes and scroll to the bottom of the screen, you will see a list of all the apps that can transfer files between your computer and your device.

Save the file DictionaryContents.txt to your system, the contents will look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>arrayKey</key>
  <array>
    <string>Caramunich</string>
    <string>Hallertauer</string>
    <string>Special B</string>
  </array>
  <key>hopKey</key>
  <string>Magnum</string>
  <key>yeastKey</key>
  <string>Belgian Strong</string>
</dict>
</plist>

Copy Files To An App

You can also copy files from your system to the Documents directory, making the files accessible to your app – drag/drop files onto the Sandbox Documents area.

Keeping Data Private

- If you need to keep application information private, do not store the files in the Documentsdirectory. Instead, store private information in the Library directory, or a folder within that directory. With one exception, the Library directory and all its sub-directories will be preserved across application backups and updates – /Library/Caches is not saved.

- With file sharing, you cannot share files between applications.