Let’s take a brief look at how files are arranged into a coherent system of data storage. Although your application does not, for the most part, need the information in this section to perform its basic file management chores, it provides some background for the file handling about which you will learn in later sections.

A file system is a way of organizing files and the information necessary to access them. Mac OS X uses a hierarchical file system to organize files on a volume. In the hierarchical file system used by Mac OS X, files are grouped into directories. These directories are also referred to as folders. A directory is a named collection of files and other directories. Each directory can contain any combination of files and other directories. The directory in which a file is located is that file’s parent directory. This holds true for directories as well; for each subdirectory, the directory within which it is located is known as the parent directory.

Each volume has a single root directory, which serves as the base of the directory hierarchy on that volume; all other directories are subdirectories of the root directory. In the example shown in Figure 11.1 the folder titled “MyVolume” is the root directory of a volume named “MyVolume”.

Figure 11-1. The hierarchical file system

A volume appears on the desktop only after it has been mounted. For nonejectable drives, this occurs automatically at system startup. For CDs (and similar ejectable media), this occurs after the CD is inserted into the computer’s CD drive. When a volume is mounted, the File Manager assigns the volume a volume reference number. You can use this volume reference number to refer to the volume only for as long as it is mounted.

There are two different ways in which the hierarchical organization of the file system is represented:

The Finder is responsible for representing the file system to the user. The Finder reflects the basic characteristics of the hierarchical file system. Volumes are represented by icons of disks, directories are represented by folder icons, and user-created files are represented by document icons. A given directory can contain any combination of directories and files; files cannot contain other files or directories. Volumes, directories, and files are identified explicitly by their names (which are displayed next to their icons) and identified implicitly by their location within the directory hierarchy. Thus, to a user and to the file system, the file named main.c in the folder MoonTravelPlanner is different from the file named main.c in the folder MyMTPProject. No two files or subdirectories within a given directory may have the same name. Figure 11.2 shows a typical Finder window in Mac OS X, representing one part of the file system hierarchy on the volume “Flower Power”.

Figure 11-2. The file system, as portrayed by the Finder

The volume format is the physical representation of the file system organization on the data storage device. It defines the way that information is laid out on the volume. The default volume format used by the Mac OS is HFS Plus (HFS stands for Hierarchical File System). Mac OS X supports other volume formats, too; namely:

The two volume formats that you will encounter most frequently on Mac OS X are HFS Plus and UFS. The volume format not only specifies how all of the user files and folders are arranged on the volume, it also includes all of the structures needed to retrieve the data.

For the most part, unless you are writing a disk-checking utility or some other application that requires low-level access to the volume, you do not need to know the details of how the volume format represents this information; the File Manager takes care of interpreting this information and locating the appropriate structures on the volume. There are some cases, however, in which you may want to know about the particular volume format used by the system on which your application is running; for instance, that filenames on HFS Plus volumes are case-insensitive, but filenames on UFS volumes are not. If you try to create a file named MyFile in the same directory that contains the file myfile on an HFS Plus volume, the File Manager returns a duplicate filename error. The same attempt will succeed on a UFS volume, however.

If you’re still curious and would like to learn more about the volume formats available on Mac OS X, see the File Manager documentation in Carbon Help (available in the Project Builder Help menu).

If you want to manipulate files, you need to know how to refer to them. When your application needs to open a particular file, you have to tell the File Manager which file you are referring to, in a way that the File Manager understands. The File Manager uses the FSRef data type to represent a file; therefore, you use FSRefs to specify files to the File Manager.

An FSRef structure uniquely identifies a file. The FSRef data type is an opaque structure that contains the identity of the volume on which the file resides, as well as the information that the File Manager needs to locate the file on that volume. Because this structure is opaque, its information is private to the File Manager; you cannot access the structure directly. To create a new FSRef or to access the information contained in an FSRef, you must use File Manager functions provided for that purpose.

You can use the File Manager function FSMakeFSRefUnicode to create an FSRef structure for a file. If you are creating a new file, you can also get an FSRef directly from the function that you use to create the file, FSCreateFileUnicode. To create an FSRef structure (or to create a new file), you must know:

The combination of a file’s name and its location uniquely identifies a file. Of course, you’re probably still wondering how you go about getting the name and location of the file. Most applications will do file handling while working with user files and will use Navigation Services to interface with the user for operations performed on these files. Navigation Services returns an FSRef for the file or directory chosen by the user. For an open operation, Navigation Services returns an FSRef to the file to open. For a save operation, Navigation Services returns the FSRef of the file’s parent directory. You will learn more about Navigation Services in Section 11.1.2.

To transfer information between your application and file, you need to access the file through an access path. When you open a file, the File Manager creates an access path to the file. This path specifies the route to be followed when accessing the file on the volume. This access path is described by a file reference number. The file reference number is a number greater than 0 that uniquely identifies the path that you have opened. You use this reference number to specify the path when you read data from, and write data to, the file. Multiple paths to the same file can be opened simultaneously; each path has a different file reference number.

For each open access path to a file, the File Manager also maintains certain information that you need to know about. Specifically, it maintains the file mark and the permissions. The file mark identifies the current position within the file. The file mark is the number of the next byte in the file that will be written or read; each time a byte is written or read, the file mark is moved. Unless you have just opened the access path (which automatically sets the file mark to the beginning of the file), you should set the position of the file mark before you begin to access data in a file, to ensure that the read or write operation begins where you actually want it to begin. For instance, before you read in a user’s moon travel itinerary, you probably want to set the file mark to the beginning of the file. If you don’t, the File Manager will begin reading data from the current position of the file mark, which may not be the file’s beginning.

As you create more complicated applications and you begin to save different types of data in a file (for example, you may choose to allow your users to store pictures of their destination spots with their moon travel itineraries), knowing where in the file your current operation will begin is even more important. If you start from an unknown spot, you run the risk of missing the boundaries between different types of data and improperly interpreting the contents of the file.

You should also be aware of the permissions associated with an access path to a file. The permissions specify which operations you can perform on the file via that access path. There are three basic types of permission you can have: permission to read the file, permission to write to the file, and permission to read and write the file. When you open a file, you request the type of permissions that you will need to get your job done. For instance, if you are opening a file that is editable by the user, you should ask for read and write permission; you should be able to read data from the file to display it to the user and write data to the file when the user wants to save the changes that he has made. On the other hand, if you are opening a document that the user should be able to read, but not change, you can request read-only permission, to display the information to the user.

While more than one access path can read a file at one time, only one path at a time may have write access. If you try to open a file and another access path is already open to the file that has conflicting permissions, your request for access to the file will be denied. Thus, if you ask for read/write permission to a file that is already being written to via another access path, the File Manager will return an error and an invalid reference number.

Knowing how to identify and access a file is crucial to any type of file handling that you do; knowing how to express the size of a file is less critical, but still important. Although the simple file handling that you will do later in this chapter doesn’t really require that you know the file’s size, as your application becomes more complex and the amount of data that you wish to store grows, you will want to know how to measure a file’s size.

The maximum file size has several constraints. One constraint is the size of the volume on which it is located. Another possible constraint is the size of the value used by the File Manager to specify file sizes. On Mac OS X, this is a signed 64-bit value; if it were up to the File Manager alone, you could create a file that was 2⁶³ bytes, or 8 million terabytes.

Not only do you need to know how large your file can be, you also need to know how to express the size of the file. The basic measure of a file’s size is the number of bytes that it contains. A file actually has two different sizes. These are the logical size and the physical size. This comes about because the File Manager allocates space to a file in chunks called allocation blocks, which contain multiple bytes. (It wouldn’t be very efficient to allocate space one byte at a time.) The size of an allocation block is variable from one volume to another and is determined at the time of the volume’s initialization.

The physical size (or physical end-of-file) is the number of bytes currently allocated to the file. The logical size (or logical end-of-file) is the number of allocated bytes in the file that currently contain data. The difference between physical and logical size is illustrated in Figure 11.3. The file that is shown fills up only 509 bytes of its last allocation block, but all 1024 bytes are allocated to the file. For the most part, you will be concerned with the file’s logical size; it is the file’s logical size that the File Manager returns when you call the function FSGetForkSize to determine the size of a file.

Figure 11-3. Physical and logical end-of-file

To create a new file, you use the File Manager function FSCreateFileUnicode. As you discovered in Section 11.1.1.1.4 you need the name and location of the file that you wish to create in order to identify it to the File Manager. (Remember, since the file does not yet exist, you don’t yet have an FSRef for the file). You pass the new file’s name and an FSRef structure identifying the parent directory of the file (that is, identifying the folder where the file will be created) to FSCreateFileUnicode. The File Manager then creates this file on the volume, in the directory which you specified, and returns an FSRef for the new file.

For the most part, you will need to create a new file when:

In both cases, you should use Navigation Services to ask the user for the name that she wishes to give to the file and for the location where she wishes to save the file. Navigation Services then returns an FSRef for the directory in which to place the new file (that is, an FSRef for the file’s parent directory) and the file’s name, which you can use to create the file. You will learn more about Navigation Services later in this chapter.

Before you can access or change the data that a file contains, the file must be open. To open a file, use the File Manager function FSOpenFork. When you call FSOpenFork, you must tell the File Manager which file you wish to open, the name of the file fork that you wish to open, and the type of access that you want (that is, the permissions). The File Manager returns the file reference number that identifies the access path that it has created to the file.

To specify the file to open, pass an FSRef structure identifying the file. If you recently created the file (for example, if the user chose the Save As command to create a copy of the file with a different name, you would generally open the newly created copy into the existing document window, so that it becomes the active file), you can use the FSRef that you obtained from FSCreateFileUnicode. If the user chooses the Open command from the File menu, you should use Navigation Services to ask the user to identify the file to open; Navigation Services returns to your application an FSRef that identifies the file chosen by the user.

The permissions that you request depend upon the file I/O operations that you wish to perform. If you need to write to the file, you should pass the constant fsRdWrPerm to the FSOpenFork function. This requests read and write privileges for the file. If another access path is already open to the file, your request for read and write permission will be denied. If reading the file is better than nothing, you can retry the request, calling FSOpenFork again with less restrictive permissions, using the constant fsRdPerm. This constant requests read access only.

Once you have an open path to the file, you can get down to the real nitty-gritty: reading the data stored in the file on disk, and writing data to the file on disk. To read data from the file, use the File Manager function FSReadFork. To write data to the file, use the function FSWriteFork. Both functions work in a similar manner. Given a file reference number to an open file, the functions read or write the specified number of bytes into or out of a buffer that you are responsible for providing. If you are writing to a file, the buffer that you provide should contain the data that you wish to write to the file. If you are reading from the file, the File Manager places the specified number of bytes into the buffer that you provide; you are then responsible for interpreting that information. In both cases, the File Manager returns the actual number of bytes read or written. This number will match the number of bytes requested, unless an error condition was encountered. The most common error result that you will encounter while reading a file is the end-of-file error, which tells your application that there are no more bytes to be read from the file. If you are reading from the file in chunks (rather than all at once), you can use the end-of-file error to determine that you have read all of the information from the file.

You can read and write bytes to and from the file one by one, all at once, or in any amount in between. The size of the buffer that you use is up to you; however, an I/O size of 4 KB or more is recommended for local volumes. Disk accesses are time consuming; having a larger I/O size reduces the number of disk accesses that your application has to make and improves the efficiency of your file handling. When you read and write itinerary files in Section 11.2.4.5 and Section 11.2.5.4 you will notice that we use a smaller I/O size. Our itineraries are small files, and the inefficiency of our file handling isn’t even noticeable. As you develop more complex applications and manipulate larger files, however, the efficiency of your file handling code will become increasingly important. Your users don’t want to sit around waiting for your application to open a 6 MB file that you read in increments of 256 bytes.

For both FSReadFork and FSWriteFork, you can also specify the position in the file from which the operation should begin. You specify a position by providing a base location and an offset into the file from that base location. You can tell the File Manager to start counting the offset from the beginning of the file, from the logical end-of-file, or from the current position of the file mark. If you specify the constant fsAtMark in the positionMode parameter of either FSReadFork or FSWriteFork or if you do not specify a starting position, the operation begins at the current file mark.

When writing a file, the File Manager transfers the data from your application’s buffer and writes it to the disk cache in memory. Similarly, when reading a file, the File Manager transfers data from the disk to the disk cache in memory. The File Manager uses the disk cache as an intermediate buffer when reading from and writing to a file. This is useful, for instance, when certain bits of information are going to be accessed frequently. In this case, it is more efficient for the File Manager to read this information from the disk cache than to read it off of the disk itself. The same holds true for writing data to the disk. If your application is performing numerous writes, it is more efficient for the File Manager to store the data in the disk cache until it has amassed a certain number of bytes. If you know that certain information is going to be accessed often, you can tell the File Manager to cache that data by setting the pleaseCacheBit bit in the permissions parameter to either of these functions. Similarly, if you know that certain information won’t be accessed very frequently, you can request that the File Manager refrain from caching the data by setting the noCacheBit bit.

All Open, Save, and Choose dialogs share some basic user interface elements. By default, they appear in almost any dialog that you display using Navigation Services. These elements include:

The size box allows the user to resize the dialog. The Cancel button allows the user to cancel the operation, and the default button specifies the action that will be taken if the user presses Return. This is generally the action that is expected of the user, given the type of dialog that is being displayed. The Save button is the default for a Save dialog, for instance. The other two interface elements in the list above are more complex and require a bit more explanation.

The column view browser provides the primary user access to the file system from a Navigation Services dialog. An example of the browser list is shown in Figure 11.5.

Figure 11-5. The column view browser in a Navigation Services dialog

When your application first displays a Navigation Services dialog, your application can specify a default location for opening, saving, or locating files. If you do not specify a default location, the column view browser shows the Documents folder. For each type of dialog that is opened afterwards, the browser defaults to the directory location in use when the user last closed that particular dialog.

Users can select multiple files from within an Open dialog by Shift-clicking within the column view browser or using the Select All command. For discontiguous selection, the user can Command-click within the browser.

The Where pop-up menu displays the current location and allows the user to navigate the file system hierarchy. The Where pop-up menu includes Favorite Places and Recent Places. This menu is shown in Figure 11.6.

Figure 11-6. The Where pop-up menu of a Navigation Services dialog

Favorite Places includes all folders in the user’s Favorites folder; Recent Places contains the last five folders into which the user saved files. Navigation Services does not display files in the Where pop-up menu.

The Add to Favorites button allows the user to add the item or items currently selected in the browser list to the Favorite Places menu. Items may be folders, volumes, or servers.

Your application should display an Open dialog when the user selects the Open command from the File menu or when the user types the command-key equivalent, Command-O. The Open dialog allows the user to navigate to the file or files that he wishes to open. An example of the Open dialog is shown in Figure 11.7.

Figure 11-7. An Open dialog

In addition to the browser list, the Open dialog also includes a Show pop-up menu. The Show pop-up menu allows the user to choose the file types displayed by the column view browser. The list of available file types is built from information provided by your application when it calls the NavCreateGetFileDialog function. The Show pop-up menu is optional; you can specify that Navigation Services leave it out when you create the dialog.

The first section of the Show pop-up menu contains an item called “All Readable Documents.” If the user selects this item, the browser displays all files that match the types that your application can open. You will learn how to specify the types of documents that your application can open in Chapter 13.

The second section of the Show pop-up menu contains an item called “All <app name> Documents” followed by your application’s “native” file types. Native file types are those types you provide in the typeList parameter of the NavCreateGetFileDialog function.

If you choose not to specify file types in the typeList parameter, you can show all files of a particular type in the browser list by using an application-defined filter function. Using a filter function would, for example, allow you to show all text files, regardless of which application created them.

The last section of the Show pop-up menu is reserved for the “All Documents” menu item. This option allows the display of all files, regardless of your application’s ability to open them directly.

In addition to the Show pop-up menu, the Open dialog includes a Go to: text field, into which the user can type file system paths (pathnames must begin with “/” or “~”) to navigate in the dialog.

The Open dialog also supports previews. When a user navigates through the file system using the column view browser and selects a file, a preview of the document is shown, using the actual document contents, so that she can see if she has selected the correct file. An Open dialog with preview is shown in Figure 11.8.

Figure 11-8. An Open dialog with preview

When the user selects a file to open and clicks the Open button (or presses Return), Navigation Services notifies your navigation event handler of the user action. Your event handler retrieves the user’s selection in the reply record, just as in the example shown in Figure 11.4. Your application can use the FSRef structure returned in this reply record to call the File Manager and open the file.

If the user action shows that the user clicked the Cancel button, your application should return to its previous state.

For further guidelines on setting up an Open dialog, see Inside Mac OS X: Aqua Human Interface Guidelines (listed in Appendix A.)

Your application should display a Save Changes dialog when a document has unsaved changes and the user closes the document window, selects the Quit command from the application menu, or types the command key equivalent of either command. The Save Changes dialog allows users to save changes or discard changes to a particular document or application. A Save Changes dialog is shown in Figure 11.9.

Figure 11-9. A Save Changes dialog

The default button for the Save Changes dialog is the Save button. When the user clicks this button, Navigation Services notifies your navigation event handler, and your event handler retrieves the user action. If the document has been previously saved, your application should call the File Manager to save the changes to the existing file. If the document has not been saved, your application should bring up a Save Location dialog (described in the next section), to allow the user to specify where to save the document and what name to use for the file.

The Cancel button cancels the operation; if the user action that your navigation event handler retrieves indicates that the user has clicked the Cancel button, your application should return to its previous state. If the user clicked the Don’t Save button, on the other hand, your application should close the document without saving changes.

For further guidelines on setting up a Save Changes dialog, see the Inside Mac OS X: Aqua Human Interface Guidelines.

When the user chooses the Save As command from the File menu, chooses the Save command for a document that has not yet been saved, or types the command key equivalent of either command, your application should bring up a Save Location dialog. The Save Location dialog allows the user to specify a name and location for a document. The Save Location dialog should also appear if the user clicks Save in a Save Changes dialog for a previously unsaved document.

The Save Location dialog has two states, collapsed and expanded. The collapsed Save Location dialog is shown in Figure 11.10.

Figure 11-10. A collapsed Save Location dialog

When the dialog is collapsed, the user can enter a name and choose a frequently accessed location. The parts of the collapsed Save dialog are:

Clicking the disclosure button in the collapsed dialog expands the dialog and displays:

The expanded version of the Save Location dialog is shown in Figure 11.11.

Figure 11-11. An expanded Save Location dialog

When the user clicks a button in the dialog, Navigation Services notifies your navigation event handler, which then retrieves the user action. If the user has selected a folder in which to save the file, using either the Where pop-up menu or the column view browser, and has clicked the Save button, your application should retrieve the reply record. From the reply record, your application can get the FSRef structure that specifies the folder in which to save the new file. You can then use this FSRef to create the save file, as explained in Section 11.1.1.2.1 and save the document.

If the user action shows that the user clicked the Cancel button, your application should return to its previous state.

For further guidelines on setting up a Save Location dialog, see Inside Mac OS X: Aqua Human Interface Guidelines.