You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdepim/mimelib/doc/binhex.html

170 lines
7.3 KiB

<HTML>
<HEAD>
<TITLE> DwBinhex Man Page </TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2>
<FONT COLOR="navy"> NAME </FONT>
</H2>
<P>
DwBinhex -- Class for converting files to or from Binhex 4.0 format
<H2>
<FONT COLOR="navy"> SYNOPSIS </FONT>
</H2>
<PRE>
class DW_EXPORT DwBinhex {
public:
<A HREF="binhex.html#DwBinhex">DwBinhex</A>();
virtual ~DwBinhex();
void <A HREF="binhex.html#Initialize">Initialize</A>();
const char* <A HREF="binhex.html#FileName">FileName</A>() const;
void <A HREF="binhex.html#SetFileName">SetFileName</A>(const char* aName);
void <A HREF="binhex.html#FileType">FileType</A>(char* aBuf) const;
void <A HREF="binhex.html#SetFileType">SetFileType</A>(const char* aType);
void <A HREF="binhex.html#FileCreator">FileCreator</A>(char* aBuf) const;
void <A HREF="binhex.html#SetFileCreator">SetFileCreator</A>(const char* aType);
DwUint8 <A HREF="binhex.html#Flag1">Flag1</A>() const;
void <A HREF="binhex.html#SetFlag1">SetFlag1</A>(DwUint8 aFlag);
DwUint8 <A HREF="binhex.html#Flag2">Flag2</A>() const;
void <A HREF="binhex.html#SetFlag2">SetFlag2</A>(DwUint8 aFlag);
const DwString&amp; <A HREF="binhex.html#DataFork">DataFork</A>() const;
void <A HREF="binhex.html#SetDataFork">SetDataFork</A>(const DwString&amp; aStr);
const DwString&amp; <A HREF="binhex.html#ResourceFork">ResourceFork</A>() const;
void <A HREF="binhex.html#SetResourceFork">SetResourceFork</A>(const DwString&amp; aStr);
const DwString&amp; <A HREF="binhex.html#BinhexChars">BinhexChars</A>() const;
void <A HREF="binhex.html#SetBinhexChars">SetBinhexChars</A>(const DwString&amp; aStr);
void <A HREF="binhex.html#Encode">Encode</A>();
int <A HREF="binhex.html#Decode">Decode</A>();
};
</PRE>
<H2>
<FONT COLOR="navy"> DESCRIPTION </FONT>
</H2>
<P>
<B><TT>DwBinhex</TT></B> converts data to or from Binhex 4.0 format. Binhex
is a format used almost exclusively on Macintosh computers for encoding files
into text characters for transmission through the mail transport system or
for archiving on non-Macintosh systems. The format includes the file name,
file type, file creator, Macintosh Finder flags, data fork, resource fork,
and checksums. In MIME, the use of Binhex is deprecated; applesingle and
appledouble are the preferred format for encoding Macintosh files. The Binhex
4.0 format is described in RFC-1741. Binhex is a widely used, <I>de facto</I>
standard, but it is not an official Internet standard.
<P>
To use <B><TT>DwBinhex</TT></B> for converting a Macintosh file to Binex
format, call the member functions <B><TT>SetFileName()</TT></B>,
<B><TT>SetFileType()</TT></B>, <B><TT>SetFileCreator()</TT></B>,
<B><TT>SetFlag1()</TT></B>, <B><TT>SetFlag2()</TT></B>,
<B><TT>SetDataFork()</TT></B>, and <B><TT>SetResourceFork()</TT></B> to set
the elements to be encoded. Any elements that are not set by calling one
of the member functions are assigned reasonable defaults. Then call the
<B><TT>Encode()</TT></B> member function to actually perform the conversion
to Binhex. Finally, call <B><TT>BinhexChars()</TT></B> to retrieve the Binhex
characters.
<P>
To use <B><TT>DwBinhex</TT></B> for converting a Macintosh file from Binhex
format, call the member function <B><TT>SetBinhexChars()</TT></B> to assign
the Binhex characters to be converted. Then call <B><TT>Decode()</TT></B>
to actually perform the conversion. Finally, call
<B><TT>FileName()</TT></B>, <B><TT>FileType()</TT></B>,
<B><TT>FileCreator()</TT></B>, <B><TT>Flag1()</TT></B>,
<B><TT>Flag2()</TT></B>, <B><TT>DataFork()</TT></B>, and
<B><TT>ResourceFork()</TT></B> to extract the decoded elements.
<P>
Note: <B><TT>DwBinhex</TT></B> does not change the file name in any way.
When you you are dealing with file names, you should be aware of the fact
that some filenames that are valid on a Macintosh may cause problems or
unexpected results on a non-Macintosh system, and vice versa. Such problem
characters include slash ('/'), colon (':'), space and possibly other characters.
<H2>
<FONT COLOR="navy"> Public Member Functions </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> <A NAME="DwBinhex">DwBinhex</A>() </B></FONT>
<P>
This is the default constructor.
<P>
<FONT COLOR="teal"><B> void <A NAME="Initialize">Initialize</A>() </B></FONT>
<P>
Resets the object's internal state to its initial state. Call this member
function to reuse the object for more than one encode or decode operation.
<P>
<FONT COLOR="teal"><B> const char* <A NAME="FileName">FileName</A>()
const<BR>
void <A NAME="SetFileName">SetFileName</A>(const char* aName) </B></FONT>
<P>
Gets or sets the file name. The file name is restricted to a maximum length
of 63 characters.
<P>
<FONT COLOR="teal"><B> void <A NAME="FileType">FileType</A>(char* aBuf)
const<BR>
void <A NAME="SetFileType">SetFileType</A>(const char* aType) </B></FONT>
<P>
Gets or sets the file type. All Macintosh files have a file type, which is
represented by four bytes. Some examples include "TEXT" for a text file,
or "APPL" for an application. <B><TT>aBuf</TT></B> should point to an array
of at least four characters.
<P>
<FONT COLOR="teal"><B> void <A NAME="FileCreator">FileCreator</A>(char* aBuf)
const <BR>
void <A NAME="SetFileCreator">SetFileCreator</A>(const char* aType)
</B></FONT>
<P>
Gets or sets the file creator. Most Macintosh files have a creator, which
is represented by a signature of four bytes. The creator specifies which
application to launch when a file's icon is double clicked.
<B><TT>aBuf</TT></B> should point to an array of at least four characters.
<P>
<FONT COLOR="teal"><B> DwUint8 <A NAME="Flag1">Flag1</A>() const <BR>
void <A NAME="SetFlag1">SetFlag1</A>(DwUint8 aFlag) </B></FONT>
<P>
Gets or sets the first byte of the Macintosh Finder flags. For files that
originate on non-Macintosh systems, this byte should be set to zero (the
default).
<P>
<FONT COLOR="teal"><B> DwUint8 <A NAME="Flag2">Flag2</A>() const <BR>
void <A NAME="SetFlag2">SetFlag2</A>(DwUint8 aFlag) </B></FONT>
<P>
Gets or sets the second byte of the Macintosh Finder flags. For files that
originate on non-Macintosh systems, this byte should be set to zero (the
default).
<P>
<FONT COLOR="teal"><B> const DwString&amp; <A NAME="DataFork">DataFork</A>()
const <BR>
void <A NAME="SetDataFork">SetDataFork</A>(const DwString&amp; aStr)
</B></FONT>
<P>
Gets or sets the data fork for the file. For files that originate on
non-Macintosh systems, such as a GIF or JPEG file, the file data should be
set as the data fork.
<P>
<FONT COLOR="teal"><B> const DwString&amp;
<A NAME="ResourceFork">ResourceFork</A>() const<BR>
void <A NAME="SetResourceFork">SetResourceFork</A>(const DwString&amp; aStr)
</B></FONT>
<P>
Gets or sets the resource fork for the file. For files that originate on
non-Macintosh systems, such as a GIF or JPEG file, the resource should be
normally be empty.
<P>
<FONT COLOR="teal"><B> const DwString&amp;
<A NAME="BinhexChars">BinhexChars</A>() const<BR>
void <A NAME="SetBinhexChars">SetBinhexChars</A>(const DwString&amp; aStr)
</B></FONT>
<P>
Gets or sets the characters of the Binhex encoded file.
<P>
<FONT COLOR="teal"><B> void <A NAME="Encode">Encode</A>() </B></FONT>
<P>
Converts the Macintosh file information to Binhex format.
<P>
<FONT COLOR="teal"><B> int <A NAME="Decode">Decode</A>() </B></FONT>
<P>
Converts the Macintosh file information from Binhex format. Returns zero
if the decode operation completes successufully; otherwise, the function
returns -1.
<P>
</BODY></HTML>