- Working with Uniform Type Identifiers
- Accessing the System Pasteboard
- Recipe: Passively Updating the Pasteboard
- Recipe: Enabling Document File Sharing
- Recipe: Monitoring the Documents Folder
- The Document Interaction Controller
- Recipe: Checking for the Open Menu
- Declaring Document Support
- Recipe: Implementing Document Support
- Exported Type Declarations
- Creating URL-Based Services
- Recipe: Adding Custom Settings Bundles-Or Not
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
Recipe: Enabling Document File Sharing
iOS documents aren’t trapped in their sandbox. You can and should share them with your users. Offer users direct control over their documents and access to any material they may have created on-device. A simple Info.plist setting allows iTunes to display the contents of a user’s Documents folder and lets those users add and remove material on demand.
To enable file sharing, add a UIFileSharingEnabled key to the application’s Info.plist and set its value to YES, as shown in Figure 16-2. When working with non-raw keys and values, this item is called “Application supports iTunes file sharing.” iTunes lists all applications that declare file sharing support in each device’s Apps tab, as shown in Figure 16-3.
){kind=link}
){kind=link}
)
Figure 16-2. Enable UIFileSharingEnabled to allow user-access to the Documents folder via iTunes.
You cannot specify which kinds of items are allowed to be in the Documents folder. Users can add any materials they like, and remove any items they want to. What they cannot do, however, is navigate through subfolders using the iTunes interface. Notice the Inbox folder in Figure 16-3. This is an artifact left over from application-to-application document sharing, and it should not be there. Users cannot manage that data directly, and you should not leave the subfolder there to confuse them.
)
Figure 16-3. Each installed application that declares UIFileSharingEnabled is listed in iTunes.
Users can, however, copy that data out in its entirety to the desktop by selecting the folder in iTunes and choosing Save to.... This allows the user to copy folders to local storage and inspect their contents. Users cannot, at this time, upload folders to the device.
This option includes the Inbox folder. Users may copy and inspect the Inbox, but they cannot delete it in iTunes, the way they can delete other files and folders. Nor should your application write files directly to the Inbox. Respect the Inbox’s role, which is to capture any incoming data from other applications. When you implement file-sharing support, always check for an Inbox on resuming active status and process that data to clear out the inbox and remove it.
As a developer, you have access not just to the Documents folder, but also to the entire application sandbox. Use the Xcode Organizer (Command-2) > Devices tab > Device > Applications > Application Name to browse, upload, and download files to and from the sandbox.
You can test basic file sharing by adding a UIFileSharingEnabled property to an application and loading data to your Documents folder. Recipe 16-2 builds two files, creating one in the main Documents folder and adding a second in a custom test folder. Once those files are created, use iTunes to inspect, download, and delete them.
Recipe 16-2. Testing UIFileSharingEnabled by Building Files and Folders
- (void) buildItems
{
// Define the paths
NSString *documentsPath = [NSHomeDirectory()
stringByAppendingPathComponent:@"Documents"];
NSString *testFolderPath = [documentsPath
stringByAppendingPathComponent:@"TestFolder"];
NSString *filePath1 = [testFolderPath
stringByAppendingPathComponent:@"Hello.txt"];
NSString *filePath2 = [documentsPath
stringByAppendingPathComponent:@"Hello.txt"];
NSError *error;
BOOL success;
// Create a folder
if (![[NSFileManager defaultManager]
fileExistsAtPath:testFolderPath])
{
success = [[NSFileManager defaultManager]
createDirectoryAtPath:testFolderPath
withIntermediateDirectories:NO
attributes:nil error:&error];
if (!success)
{
NSLog(@"Error creating test folder: %@",
error.localizedFailureReason);
return;
}
}
// Now put a file there
success = [@"Hello world\n" writeToFile:filePath1
atomically:YES encoding:NSUTF8StringEncoding
error:&error];
if (!success)
{
NSLog(@"Error writing file 1: %@",
error.localizedFailureReason);
return;
}
// Put a file into the main Documents folder too
success = [@"Hello world\n" writeToFile:filePath2
atomically:YES encoding:NSUTF8StringEncoding
error:&error];
if (!success)
{
NSLog(@"Error writing file 2: %@",
error.localizedFailureReason);
return;
}
NSLog(@"Success. Files and folder created.");
}