DwAppleFile Man Page

## NAME

DwAppleFile -- Class for packing/unpacking AppleSingle and AppleDouble data

## SYNOPSIS

    class DW_UTIL_EXPORT DwAppleFile {

    public:

        enum Error {
            kErrNoError = 0,
            kErrTooShort,
            kErrBadMagicNumber,
            kErrWrongVersion,
            kErrCorruptData
        };
        enum FormatType {
            kAppleSingle,
            kAppleDoubleHeader
        };
        DwAppleFile();
        int Format() const;
        void SetFormat(int aFormatType);
        DwBool HasFileName() const;
        const char* FileName() const;
        void SetFileName(const char* aName);
        DwBool HasFileTimes() const;
        DwInt32 CreateTime() const;
        void SetCreateTime(DwInt32 aTime);
        DwInt32 ModifyTime() const;
        void SetModifyTime(DwInt32 aTime);
        DwInt32 BackupTime() const;
        void SetBackupTime(DwInt32 aTime);
        DwInt32 AccessTime() const;
        void SetAccessTime(DwInt32 aTime);
        DwBool HasDataFork() const;
        const DwString& DataFork() const;
        void SetDataFork(const DwString& aStr);
        DwBool HasResourceFork() const;
        const DwString& ResourceFork() const;
        void SetResourceFork(const DwString& aStr);
        const DwString& PackagedData() const;
        void SetPackagedData(const DwString& aStr);
        void Pack();
        int Unpack();
        static DwInt32 UnixTimeToAppleFileTime(DwUint32 aUnixTime);
        static DwUint32 AppleFileTimeToUnixTime(DwInt32 aASTime);
    };

## DESCRIPTION

`DwAppleFile` packs or unpacks file data to or from AppleSingle or AppleDouble format. The AppleSingle format allows a file's contents to be packaged together with related file information, such as file dates, resources, icons, and so forth, into a single file. The AppleDouble format is similar, but different in that the file's contents are stored in one file, and the remaining file information (dates, resources, icons, and so forth) is stored in a separate AppleDouble header file.

In the MIME world, AppleSingle and AppleDouble are the preferred ways to transfer Macintosh files, with AppleDouble preferred over AppleSingle where possible. In actual practice, the Binhex format is common (most likely due to the fact that most Macintosh archives store files in Binhex format). The use of AppleSingle and AppleDouble in MIME is described in RFC-1740 and is referred to as MacMIME. MacMIME is an official Internet standards track protocol.

To use `DwAppleFile` for packing file data to the AppleDouble header format, first call `SetFormat(DwAppleFile::kAppleDoubleHeader)` to set the format type to AppleDouble header, then call one or more of the following functions to set the file data: `SetFileName()`, `SetCreateTime()`, `SetModifyTime()`, `SetBackupTime()`, `SetAccessTime()` `SetResourceFork()`. Next, call `Pack()` to package all the file information into a single buffer. Finally, call `PackagedData()` to get the packaged AppleDouble header data.

To use `DwAppleFile` for packing file data to the AppleSingle format, first call `SetFormat(DwAppleFile::kAppleSingle)` to set the format type to AppleSingle, then call one or more of the following functions to set the file data: `SetFileName()`, `SetCreateTime()`, `SetModifyTime()`, `SetBackupTime()`, `SetAccessTime()` `SetResourceFork()`, `SetDataFork()`. Next, call `Pack()` to package all the file information into a single buffer. Finally, call `PackagedData()` to get the packaged AppleSingle data.

Note: The definitive reference for AppleSingle and AppleDouble is AppleSingle/AppleDouble Formats: Developer's Note, available from Apple Computer.

## Public Member Functions

DwAppleFile()

Default constructor.

int Format() const
void SetFormat(int aFormatType)

Gets or sets the format type. When using `DwAppleFile` to pack file data, you should specify a format type of `kAppleSingle` or `kAppleDoubleHeader`. When using `DwAppleFile` to unpack file data, the format type is determined by interpreting a magic number in the packaged data.

The AppleDouble header and AppleSingle formats are almost identical. They are different in two respects: the magic number is different, and an AppleDouble header is not permitted to contain a data fork.

DwBool HasFileName() const

Returns a true value if the packaged file data contains a file name. If it does contain a file name, you can get the file name by calling `FileName()`.

const char* FileName() const
void SetFileName(const char* aName)

Gets or sets the file name that is included in the packaged file data.

DwBool HasFileTimes() const

Returns true value if the packaged file data contains a file times entry. If it does contain a file times entry, you can get the file times by calling `CreateTime()`, `ModificationTime()`, `BackupTime()`, and `AccessTime()`.

If a file times entry is present, that does not mean that all the times (create time, modify time, backup time, and access time) are all valid. An invalid time is indicated by a value of 0x80000000.

DwInt32 CreateTime() const
void SetCreateTime(DwInt32 aTime)
DwInt32 ModifyTime() const
void SetModifyTime(DwInt32 aTime)
DwInt32 BackupTime() const
void SetBackupTime(DwInt32 aTime)
DwInt32 AccessTime() const
void SetAccessTime(DwInt32 aTime)

Gets or sets file times that are included in the packaged file data. The create time is the time that the file was created. The modify time is the time the file was last modified. The backup time is the time the file was last saved to a backup medium. The access time is the time the file was last accessed.

A file time's value represents the number of seconds before or after 1 Jan 2000 00:00:00 UTC. The value 0 represents 1 Jan 2000 00:00:00 UTC; a negative time represents the number of seconds until 1 Jan 2000 00:00:00 UTC; and a positive value represents the number of seconds after 1 Jan 2000 00:00:00 UTC. The value 0x80000000 is a special value that indicates an invalid value.

You can use the functions `UnixTimeToAppleFileTime()` and `AppleFileTimeToUnixTime()` to convert between the apple file time representation (signed number of seconds since 1 Jan 2000) and the Unix time representation (unsigned number of seconds since 1 Jan 1970).

DwBool HasDataFork() const

Returns a true value if the packaged file data contains a Macintosh data fork entry. If it does contain a data fork, you can get the data fork by calling `DataFork()`.

An AppleDouble header does not contain a data fork entry.

const DwString& DataFork() const
void SetDataFork(const DwString& aStr)

Gets or sets the data fork. The data fork contains the file's "data," such as the text in a text file, or the image data in a GIF file. In contrast, the resource fork contains resources that are used only by the Macintosh operating system (font information, code, icons, and so forth). An AppleDouble header does not contain a data fork entry.

DwBool HasResourceFork() const

Returns a true value if the packaged file data contains a Macintosh resource fork entry. If it does contain a resource fork, you can get the resource fork by calling `ResourceFork()`.

const DwString& ResourceFork() const
void SetResourceFork(const DwString& aStr)

Gets or sets the resource fork. The resource fork contains resources that are used only by Macintosh operating system (font information, code, icons, and so forth).

const DwString& PackagedData() const
void SetPackagedData(const DwString& aStr)

Gets or sets the buffer of packaged file data.

void Pack()

Packages the file data into a single buffer. After calling `Pack()`, you can get the packaged data by calling `PackagedData()`.

int Unpack()

Unpacks the packaged file data. Before calling `Unpack()`, you should call `SetPackagedData()` to set the buffer of packaged file data. After calling `Unpack()`, you can call other functions to retrieve the unpacked file information.

If the packaged file data is successfully unpacked, `Unpack()` returns 0. If an error occurs, it returns an error code:

         kErrTooShort        premature end of file detected
         kErrBadMagicNumber  the magic number indicates that the data is not in
                             AppleDouble or AppleSingle format
         kErrWrongVersion    the version number indicates a version of the AppleDouble
                             or AppleSingle format that is not understood
         kErrCorruptData     that data is corrupted in some way

static DwInt32 UnixTimeToAppleFileTime(DwUint32 aUnixTime)
static DwUint32 AppleFileTimeToUnixTime(DwInt32 aASTime)

Converts between the scalar time used in the AppleSingle and AppleDouble formats ("Apple file time") and the scalar time used in Unix ("Unix time"). An Apple file time is defined to be the signed number of seconds before or after 1 Jan 2000 00:00:00 UTC. The value 0 represents 1 Jan 2000 00:00:00 UTC; a negative time represents the number of seconds until 1 Jan 2000 00:00:00 UTC; and a positive value represents the number of seconds after 1 Jan 2000 00:00:00 UTC. A Unix time is the number of seconds since 1 Jan 1970 00:00:00 UTC.