In addition to archiving and NSData’s binary read and write methods, there are a few more methods for transferring data to and from the filesystem. One of them, Core Data, is coming up in Chapter 17. A couple of the others are worth mentioning here.
You have access to the standard file I/O functions from the C library. These functions look like this:
FILE *inFile = fopen("textfile", "rt"); char *buffer = malloc(someSize); fread(buffer, byteCount, 1, inFile); FILE *outFile = fopen("binaryfile", "w"); fwrite(buffer, byteCount, 1, outFile);
However, you won’t see these functions used much because there are more convenient ways of reading and writing binary and text data. Using NSData works well for binary data. For text data, NSString has two instance methods writeToFile:atomically:encoding:error: and initWithContentsOfFile:. They are used as follows:
// A local variable to store an error object if one comes back
NSError *err;
NSString *someString = @"Text Data";
BOOL success = [someString writeToFile:@"/some/path/"
atomically:YES
encoding:NSUTF8StringEncoding
error:&err];
if (!success) {
NSLog(@"Error writing file: %@", [err localizedDescription]);
}
NSString *x = [[NSString alloc] initWithContentsOfFile:@"/some/path/"
encoding:NSUTF8StringEncoding
error:&err];
if (!x) {
NSLog(@"Error reading file: %@", [err localizedDescription]);
}
What’s that NSError object? Some methods might fail for a variety of reasons – for example, writing to the filesystem might fail because the path is invalid or the user doesn’t have permission to write to the specified path. NSError objects contain the reasons for failure. You can send the message localizedDescription to an instance of NSError for a human-readable description of the error. This is something you can show to the user or print out to a debug console.
Error objects also have code and domain properties. The code is an integer representing the error. The domain represents the error domain. For example, not having permission to write to a directory results in error code 513 in error domain NSCocoaErrorDomain. Each domain has its own set of error codes, and codes within different domains can have the same integer value; therefore, an error is uniquely specified by its code and error domain. You can check out the error codes for the NSCocoaErrorDomain in the file Foundation/FoundationErrors.h.
The syntax for getting back an NSError instance is a little strange. An error object is only created if an error occurred; otherwise, there is no need for the object. When a method can return an error through one of its arguments, you create a local variable that is a pointer to an NSError object. Notice that you don’t instantiate the error object – that is the job of the method you are calling. Instead, you pass the address of your pointer variable (&err) to the method that might generate an error. If an error occurs in the implementation of that method, an NSError instance is created, and your pointer is set to point at that new object. If you don’t care about the error object, you can always pass nil.
Sometimes you want to show the error to the user. This is typically done with an UIAlertView:
NSString *x = [[NSString alloc] initWithContentsOfFile:@"/some/path/"
encoding:NSUTF8StringEncoding
error:&err];
if (!x) {
UIAlertView *a = [[[UIAlertView alloc] initWithTitle:@"Read Failed"
message:[err localizedDescription]
delegate:nil
cancelButtonTitle:@"OK"
otherButtonTitles:nil] autorelease];
[a show];
}
Like NSString, the classes NSDictionary and NSArray have writeToFile: and initWithContentsOfFile: methods. In order to write objects of these types to the filesystem in this fashion, they must contain only property list serializable objects. The only objects that are property list serializable are NSString, NSNumber, NSDate, NSData, NSArray, and NSDictionary. When an NSArray or NSDictionary is written to the filesystem with these methods, an XML property list is created. An XML property list is a collection of tagged values:
<?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"> <array> <dict> <key>firstName</key> <string>Joe</string> <key>lastName</key> <string>Conway</string> </dict> <dict> <key>firstName</key> <string>Aaron</string> <key>lastName</key> <string>Hillegass</string> </dict> </array> </plist>
XML property lists are a convenient way to store data because they can be read on nearly any system. Many web service applications use property lists as input and output. The code for writing and reading a property list looks like this:
NSMutableDictionary *d = [NSMutableDictionary dictionary]; [d setObject:@"A string" forKey:@"String"]; [d writeToFile:@"/some/path" atomically:YES]; NSMutableDictionary *anotherD = [[NSMutableDictionary alloc] initWithContentsOfFile:@"/some/path"];