Hunny Software Home || Hunny MIME++ Home || Hunny Mail++ Home

AppleFile Class Reference

Detailed Description

AppleFile packs or unpacks file data to or from AppleSingle or AppleDouble format. The AppleSingle format allows a file's contents to be packed 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 AppleFile for packing file data to the AppleDouble header format, first call setFormat(AppleFile::APPLE_DOUBLE_HEADER) 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 pack all the file information into a single buffer. Finally, call packedData() to get the packed AppleDouble header data.

To use AppleFile for packing file data to the AppleSingle format, first call setFormat(AppleFile::APPLE_SINGLE) 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 pack all the file information into a single buffer. Finally, call packedData() to get the packed AppleSingle data.

To use AppleFile to unpack AppleSingle or AppleDouble file data, first call setPackedData() to set the packed data into the AppleFile object. Then call unpack() to unpack the file data. Finally, call format(), fileName(), createTime(), and other member functions to get the file data.

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

Public Member Functions

AppleFile ()

Default constructor.

int format () const

Gets the format type.

void setFormat (int formatType)

Sets the format type.

bool hasFileName () const

Returns true if the AppleFile data contains a file name.

const char * fileName () const

Gets the file name.

void setFileName (const char *name)

Sets the file name.

bool hasFileTimes () const

Returns true if the AppleFile data contains a file times entry.

int32_t createTime () const

Gets the create time.

void setCreateTime (int32_t time)

Sets the create time.

int32_t modifyTime () const

Gets the modify time.

void setModifyTime (int32_t time)

Sets the modify time.

int32_t backupTime () const

Gets the backup time.

void setBackupTime (int32_t time)

Sets the backup time.

int32_t accessTime () const

Gets the access time.

void setAccessTime (int32_t time)

Sets the access time.

bool hasDataFork () const

Returns true if the AppleFile data contains a data fork entry.

const String & dataFork () const

Gets the data fork.

void setDataFork (const String &bytes)

Sets the data fork.

bool hasResourceFork () const

Returns true if the AppleFile data contains a resource fork entry.

const String & resourceFork () const

Gets the resource fork.

void setResourceFork (const String &bytes)

Sets the resource fork.

const String & packedData () const

Gets the buffer of packed file data.

void setPackedData (const String &str)

Sets the buffer of packed file data.

void pack ()

Packs the file data into a single buffer.

int unpack ()

Unpacks the packed file data.

Static Public Member Functions

int32_t unixTimeToAppleFileTime (uint32_t unixTime)

Converts from Unix time to AppleFile time.

uint32_t appleFileTimeToUnixTime (int32_t afTime)

Converts from AppleFile time to Unix time.

Constructor & Destructor Documentation

AppleFile ( )

Default constructor.

Member Function Documentation

int32_t accessTime ( ) const

Gets the access time.
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 may 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).

Returns:
the file access time

uint32_t appleFileTimeToUnixTime ( int32_t afTime ) [static]

Converts from the scalar time used in the AppleSingle and AppleDouble formats ("Apple file time") to 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.

Parameters:

afTime an AppleFile time

Returns:
a UNIX time

int32_t backupTime ( ) const

Gets the backup time.
The backup time is the time the file was last saved to a backup medium.
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 may 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).

Returns:
the file backup time

int32_t createTime ( ) const

Gets the create time.
The create time is the time that the file was created.
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 may 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).

Returns:
the file create time

const String & dataFork ( ) const

Gets 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.

Returns:
the bytes of the data fork

const char * fileName ( ) const

Gets the file name.

Returns:
file name

int format ( ) const

Gets the format type.
The format type can be AppleFile::APPLE_SINGLE or AppleFile::APPLE_DOUBLE_HEADER. When using AppleFile to unpack file data, the format type is determined by interpreting a magic number in the packed 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.

Returns:
AppleFile::APPLE_SINGLE or AppleFile::APPLE_DOUBLE_HEADER

bool hasDataFork ( ) const

Returns true if the AppleFile data contains a data fork entry.
If it does contain a data fork, you may get the data fork by calling dataFork().
An AppleDouble header does not contain a data fork entry.

Returns:
true if the AppleFile data contains a data fork entry

bool hasFileName ( ) const

Returns true if the AppleFile data contains a file name.
If it does contain a file name, you may get the file name by calling fileName().

Returns:
true if the AppleFile data contains a file name

bool hasFileTimes ( ) const

Returns true if the AppleFile data contains a file times entry.
If it does contain a file times entry, you may get the file times by calling createTime(), modifyTime(), 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 valid. An invalid time is indicated by a value of 0x80000000.

Returns:
true if the AppleFile data contains a file times entry

bool hasResourceFork ( ) const

Returns true if the AppleFile data contains a Macintosh resource fork entry.
If it does contain a resource fork, you may get the resource fork by calling resourceFork().

Returns:
true if the AppleFile data contains a resource fork entry

int32_t modifyTime ( ) const

Gets the modify time.
The modify time is the time the file was last modified.
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 may 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).

Returns:
the file modify time

void pack ( )

Packs the AppleFile data into a single buffer.
After calling pack(), you may get the packed data by calling packedData().

const String & packedData ( ) const

Gets the buffer of packed AppleFile data.

Returns:
the packed file data

const String & resourceFork ( ) const

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

Returns:
the bytes of the resource fork

void setAccessTime ( int32_t time )

Sets the access time.
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 may 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).

Parameters:

time the file access time

void setBackupTime ( int32_t time )

Sets the backup time.
The backup time is the time the file was last saved to a backup medium.
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 may 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).

Parameters:

time the file backup time

void setCreateTime ( int32_t time )

Sets the create time.
The create time is the time that the file was created.
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 may 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).

Parameters:

time the file create time

void setDataFork ( const String & bytes )

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.

Parameters:

bytes the bytes of the data fork

void setFileName ( const char * name )

Sets the file name.

Parameters:

name file name

void setFormat ( int formatType )

Sets the format type.
When using AppleFile to pack file data, you should specify a format type of AppleFile::APPLE_SINGLE or AppleFile::APPLE_DOUBLE_HEADER. When using AppleFile to unpack file data, the format type is determined by interpreting a magic number in the packed 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.

Parameters:

formatType AppleFile::APPLE_SINGLE or AppleFile::APPLE_DOUBLE_HEADER

void setModifyTime ( int32_t time )

Sets the modify time.
The modify time is the time the file was last modified.
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 may 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).

Parameters:

time the file modify time

void setPackedData ( const String & str )

Sets the buffer of packed file data.

Parameters:

str packed file data

void setResourceFork ( const String & bytes )

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

Parameters:

bytes the bytes of the resource fork

int32_t unixTimeToAppleFileTime ( uint32_t unixTime ) [static]

Converts from the scalar time used in Unix ("Unix time") to the scalar time used in the AppleSingle and AppleDouble formats ("Apple file 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.

Parameters:

unixTime a UNIX time

Returns:
an AppleFile time

int unpack ( )

Unpacks the packed file data.
Before calling unpack(), you should call setPackedData() to set the buffer of packed file data. After calling unpack(), you may call other functions to retrieve the unpacked file information.
If the packed file data is successfully unpacked, unpack() returns 0. If an error occurs, it returns an error code:

TOO_SHORT premature end of file detected

BAD_MAGIC_NUMBER the magic number indicates that the data is not in AppleDouble or AppleSingle format

WRONG_VERSION the version number indicates a version of the AppleDouble or AppleSingle format that is not understood

CORRUPT_DATA that data is corrupted in some way

Returns:
0 on success; error code on failure


Public Member Functions
	AppleFile ()
	Default constructor.
int	format () const
	Gets the format type.
void	setFormat (int formatType)
	Sets the format type.
bool	hasFileName () const
	Returns true if the AppleFile data contains a file name.
const char *	fileName () const
	Gets the file name.
void	setFileName (const char *name)
	Sets the file name.
bool	hasFileTimes () const
	Returns true if the AppleFile data contains a file times entry.
int32_t	createTime () const
	Gets the create time.
void	setCreateTime (int32_t time)
	Sets the create time.
int32_t	modifyTime () const
	Gets the modify time.
void	setModifyTime (int32_t time)
	Sets the modify time.
int32_t	backupTime () const
	Gets the backup time.
void	setBackupTime (int32_t time)
	Sets the backup time.
int32_t	accessTime () const
	Gets the access time.
void	setAccessTime (int32_t time)
	Sets the access time.
bool	hasDataFork () const
	Returns true if the AppleFile data contains a data fork entry.
const String &	dataFork () const
	Gets the data fork.
void	setDataFork (const String &bytes)
	Sets the data fork.
bool	hasResourceFork () const
	Returns true if the AppleFile data contains a resource fork entry.
const String &	resourceFork () const
	Gets the resource fork.
void	setResourceFork (const String &bytes)
	Sets the resource fork.
const String &	packedData () const
	Gets the buffer of packed file data.
void	setPackedData (const String &str)
	Sets the buffer of packed file data.
void	pack ()
	Packs the file data into a single buffer.
int	unpack ()
	Unpacks the packed file data.
Static Public Member Functions
int32_t	unixTimeToAppleFileTime (uint32_t unixTime)
	Converts from Unix time to AppleFile time.
uint32_t	appleFileTimeToUnixTime (int32_t afTime)
	Converts from AppleFile time to Unix time.