446	CHAPTER 13: Basic Data Persistence

Your Application’s Sandbox

All four of this chapter’s data-persistence mechanisms share an important common element: your application’s /Documents folder. Every application gets its own /Documents folder, and applications are allowed to read and write from only their own

/Documents directory.

To give you some context, let’s take a look at how applications are organized in iOS, by examining the folder layout used by the iPhone simulator. In order to see this, you’ll need to look inside the Library directory contained in your home directory. On Mac OS X 10.6 and earlier, this is no problem, but starting with 10.7, Apple decided to make the Library folder hidden by default, so there’s a small extra hoop to jump through. Open a Finder window, and navigate to your home directory. If you can see your Library folder, that’s great. If not, select Go Go to Folder… to open a small sheet that prompts you for the name of a directory. Type Library and press enter, and the Finder will take you there.

Within the Library folder, drill down into Application Support/iPhone Simulator/. Within that directory, you’ll see a subdirectory for each version of iOS supported by your current Xcode installation. For example, you might see one directory named 4.3 and another named 5.0. Drill down into the directory representing the latest version of iOS supported by your version of Xcode. At this point, you should see four subfolders, including one named Applications (see Figure 13–1).

NOTE: If you’ve installed multiple versions of the SDK, you may see a few additional folders inside the iPhone Simulator directory, with names indicating the iOS version number they

represent. That’s perfectly normal.

Figure 13–1. The layout of one user’s Library/Application Support/iPhone Simulator/5.0/ directory showing the Applications folder

Although this listing represents the simulator, the file structure is similar to what’s on the actual device. As is probably obvious, the Applications folder is where iOS stores its applications. If you open the Applications folder, you’ll see a bunch of folders and files with names that are long strings of characters. These names are globally unique identifiers (GUIDs) and are generated automatically by Xcode. Each of these folders contains one application and its supporting folders.

If you open one of the application subdirectories, you should see something that looks familiar. You’ll find one of the iOS applications you’ve built, along with three support folders:

www.it-ebooks.info

CHAPTER 13: Basic Data Persistence

447

Documents: Your application stores its data in Documents, with the exception of NSUserDefaults-based preference settings.

Library: NSUserDefaults-based preference settings are stored in the

Library/Preferences folder.

tmp: The tmp directory offers a place where your application can store temporary files. Files written into tmp will not be backed up by iTunes when your iOS device syncs, but your application does need to take responsibility for deleting the files in tmp once they are no longer needed, to avoid filling up the file system.

Getting the Documents Directory

Since our application is in a folder with a seemingly random name, how do we retrieve the full path to the Documents directory so that we can read and write our files? It’s actually quite easy. The C function NSSearchPathForDirectoriesInDomain() will locate various directories for you. This is a Foundation function, so it is shared with Cocoa for Mac OS X. Many of its available options are designed for Mac OS X and won’t return any values on iOS, either because those locations don’t exist on iOS (such as the Downloads folder) or because your application doesn’t have rights to access the location due to iOS’s sandboxing mechanism.

Here’s some code to retrieve the path to the Documents directory:

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,

NSUserDomainMask, YES);

NSString *documentsDirectory = [paths objectAtIndex:0];

The constant NSDocumentDirectory says we are looking for the path to the Documents directory. The second constant, NSUserDomainMask, indicates that we want to restrict our search to our application’s sandbox. In Mac OS X, this same constant is used to indicate that we want the function to look in the user’s home directory, which explains its somewhat odd name.

Though an array of matching paths is returned, we can count on our Documents directory residing at index 0 in the array. Why? We know that only one directory meets the criteria we’ve specified, since each application has only one Documents directory.

We can create a file name by appending another string onto the end of the path we just retrieved. We’ll use an NSString method designed for just that purpose called stringByAppendingPathComponent:.

NSString *filename = [documentsDirectory stringByAppendingPathComponent:@"theFile.txt"];

After this call, filename would contain the full path to a file called theFile.txt in our application’s Documents directory, and we can use filename to create, read, and write from that file.

www.it-ebooks.info