diff options
| author | toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> | 2009-11-25 17:56:58 +0000 |
|---|---|---|
| committer | toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> | 2009-11-25 17:56:58 +0000 |
| commit | 460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 (patch) | |
| tree | 67208f7c145782a7e90b123b982ca78d88cc2c87 /mimelib/doc | |
| download | tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.tar.gz tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.zip | |
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923
git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'mimelib/doc')
29 files changed, 6857 insertions, 0 deletions
diff --git a/mimelib/doc/address.html b/mimelib/doc/address.html new file mode 100644 index 000000000..c85046aa7 --- /dev/null +++ b/mimelib/doc/address.html @@ -0,0 +1,153 @@ +<HTML> +<HEAD> + <TITLE> DwAddress Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwAddress -- Abstract class representing an RFC-822 address +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwAddress : public <A HREF="fieldbdy.html">DwFieldBody</A> { + + friend class DwAddressList; + +public: + + virtual ~DwAddress(); + DwBool <A HREF="address.html#IsMailbox">IsMailbox</A>() const; + DwBool <A HREF="address.html#IsGroup">IsGroup</A>() const; + inline DwBool <A HREF="address.html#IsValid">IsValid</A>() const; + DwAddress* <A HREF="address.html#Next">Next</A>() const; + void <A HREF="address.html#SetNext">SetNext</A>(DwAddress* aAddress); + +protected: + + <A HREF="address.html#DwAddress">DwAddress</A>(); + <A HREF="address.html#DwAddress">DwAddress</A>(const DwAddress& aAddr); + <A HREF="address.html#DwAddress">DwAddress</A>(const DwString& aStr, DwMessageComponent* aParent=0); + const DwAddress& <A HREF="address.html#op_eq">operator =</A> (const DwAddress& aAddr); + int mIsValid; + +public: + + virtual void <A HREF="address.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="address.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwAddress</TT></B> represents an <I>address</I> as described in RFC-822. +You may not instantiate objects of type <B><TT>DwAddress</TT></B>, since +<B><TT>DwAddress</TT></B> is an abstract base class. Instead, you must +instantiate objects of type +<B><TT><A HREF="mailbox.html">DwMailbox</A></TT></B> or +<B><TT><A HREF="group.html">DwGroup</A></TT></B>, which are subclasses of +<B><TT>DwAddress</TT></B>. +<P> +To determine the actual type of a <B><TT>DwAddress</TT></B> object, you can +use the member functions <B><TT>IsMailbox()</TT></B> and +<B><TT>IsGroup()</TT></B>. +<P> +If the string representation assigned to a <B><TT>DwAddress</TT></B> is +improperly formed, the parse method will fail. To determine if the parse +method failed, call the member function <B><TT>IsValid()</TT></B>. +<P> +A <B><TT>DwAddress</TT></B> object can be contained in list. To get the next +<B><TT>DwAddress</TT></B> object in the list, call the member function +<B><TT>Next()</TT></B> +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="IsMailbox">IsMailbox</A>() const +</B></FONT> +<P> +Returns true value if this object is a <B><TT>DwMailbox</TT></B>. +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="IsGroup">IsGroup</A>() const +</B></FONT> +<P> +Returns true value if this object is a <B><TT>DwGroup</TT></B>. +<P> +<FONT COLOR="teal"><B> inline DwBool <A NAME="IsValid">IsValid</A>() const +</B></FONT> +<P> +Returns true value if the last parse was successful. Returns false if the +last parse failed (bad address) or the <B><TT>Parse()</TT></B> member function +was never called. +<P> +<FONT COLOR="teal"><B> DwAddress* <A NAME="Next">Next</A>() const </B></FONT> +<P> +Returns the next <B><TT>DwAddress</TT></B> object in the list when the object +is included in a list of addresses. The function is used when iterating a +list. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetNext">SetNext</A>(DwAddress* aAddress) +</B></FONT> +<P> +Sets the next <B><TT>DwAddress</TT></B> object in the list. This member function +generally should not be used, since <B><TT>DwAddressList</TT></B> has member +functions to manage its list of <B><TT>DwAddress</TT></B> objects. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Protected Member Functions </FONT> +</H2> +<P> +<B><FONT COLOR="teal"> <A NAME="DwAddress">DwAddress</A>() <BR> +DwAddress(const DwAddress& aAddr) <BR> +DwAddress(const DwString& aStr, DwMessageComponent* aParent=0) +</FONT></B> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwAddress</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which copies the string +representation and all attributes from <B><TT>aAddress</TT></B>. The parent +of the new <B><TT>DwAddress</TT></B> object is set to +<B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwAddress</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B>. +<P> +<B><FONT COLOR="teal"> const DwAddress& <A NAME="op_eq">operator =</A> +(const DwAddress& aAddr) </FONT></B> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aAddr</TT></B>. The parent node of the <B><TT>DwAddress</TT></B> object +is not changed. +<P> +</BODY></HTML> diff --git a/mimelib/doc/addrlist.html b/mimelib/doc/addrlist.html new file mode 100644 index 000000000..d3a563eef --- /dev/null +++ b/mimelib/doc/addrlist.html @@ -0,0 +1,214 @@ +<HTML> +<HEAD> + <TITLE> DwAddressList Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwAddressList -- Class representing a list of RFC-822 addresses +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwAddressList : public <A HREF="fieldbdy.html">DwFieldBody</A> { + +public: + + <A HREF="addrlist.html#DwAddressList">DwAddressList</A>(); + <A HREF="addrlist.html#DwAddressList">DwAddressList</A>(const DwAddressList& aList); + <A HREF="addrlist.html#DwAddressList">DwAddressList</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwAddressList(); + const DwAddressList& <A HREF="addrlist.html#op_eq">operator =</A> (const DwAddressList& aList); + virtual void <A HREF="addrlist.html#Parse">Parse</A>(); + virtual void <A HREF="addrlist.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="addrlist.html#Clone">Clone</A>() const; + DwAddress* <A HREF="addrlist.html#FirstAddress">FirstAddress</A>() const; + void Add(DwAddress* a<A HREF="addrlist.html#Add">Add</A>r); + void <A HREF="addrlist.html#Remove">Remove</A>(DwAddress* aAddr); + void <A HREF="addrlist.html#DeleteAll">DeleteAll</A>(); + static DwAddressList* <A HREF="addrlist.html#NewAddressList">NewAddressList</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwAddressList* (*<A HREF="addrlist.html#sNewAddressList">sNewAddressList</A>)(const DwString&, + DwMessageComponent*); + +protected: + + DwAddress* <A HREF="addrlist.html#mFirstAddress">mFirstAddress</A>; + +public: + + virtual void <A HREF="addrlist.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="addrlist.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwAddressList</TT></B> represents a list of <I>addresses</I> as described +in RFC-822. In MIME++, <B><TT>DwAddressList</TT></B> is a container for objects +of type <B><TT><A HREF="address.html">DwAddress</A></TT></B>, and it contains +various member functions to manage its contained objects. +<B><TT>DwAddressList</TT></B> is also a +<B><TT><A HREF="fieldbdy.html">DwFieldBody</A></TT></B>. This reflects the +fact that certain RFC-822 header fields, such as the ``To'' header field, +have a list of addresses as their field bodies. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwAddressList">DwAddressList</A>() <BR> +DwAddressList(const DwAddressList& aList) <BR> +DwAddressList(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwAddressList</TT></B> object's string representation to the empty +string and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which copies the string +representation and all <B><TT>DwAddress</TT></B> objects from +<B><TT>aList</TT></B>. The parent of the new +<B><TT>DwAddressList</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwAddressList</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwAddressList& <A NAME="op_eq">operator +=</A> (const DwAddressList& aList) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aList</TT></B>. The parent node of the +<B><TT>DwAddressList</TT></B> object is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwAddressList</TT></B> objects. The +parse method creates or updates the broken-down representation from the string +representation. For <B><TT>DwAddressList</TT></B> objects, the parse method +parses the string representation to create a list of +<B><TT>DwAddress</TT></B> objects. This member function also calls the +<B><TT>Parse()</TT></B> member function of each <B><TT>DwAddress</TT></B> +object in its list. +<P> +You should call this member function after you set or modify the string +representation, and before you access any of the contained +<B><TT>DwAddress</TT></B> objects. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwAddressList</TT></B> objects. The +assemble method creates or updates the string representation from the broken-down +representation. That is, the assemble method builds the string representation +from its list of <B><TT>DwAddress</TT></B> objects. Before it builds the +string representation for the <B><TT>DwAddressList</TT></B> object, this +function first calls the <B><TT>Assemble()</TT></B> member function of each +<B><TT>DwAddress</TT></B> object in its list. +<P> +You should call this member function after you set or modify any of the contained +<B><TT>DwAddress</TT></B> objects, and before you retrieve the string +representation. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwAddressList</TT></B> on the free store that has the +same value as this <B><TT>DwAddressList</TT></B> object. The basic idea is +that of a virtual copy constructor. +<P> +<FONT COLOR="teal"><B> DwAddress* <A NAME="FirstAddress">FirstAddress</A>() +const </B></FONT> +<P> +Gets the first <B><TT>DwAddress</TT></B> object in the list. Use the member +function <B><TT>DwAddress::Next()</TT></B> to iterate. Returns +<B><TT>NULL</TT></B> if the list is empty. +<P> +<FONT COLOR="teal"><B> void <A NAME="Add">Add</A>(DwAddress* aAddr) +</B></FONT> +<P> +Adds <B><TT>aAddr</TT></B> to the end of the list of +<B><TT>DwAddress</TT></B> objects maintained by this +<B><TT>DwAddressList</TT></B> object. +<P> +<FONT COLOR="teal"><B> void <A NAME="Remove">Remove</A>(DwAddress* aAddr) +</B></FONT> +<P> +Removes <B><TT>aAddr</TT></B> from the list of <B><TT>DwAddress</TT></B> +objects maintained by this <B><TT>DwAddressList</TT></B> object. The +<B><TT>DwAddress</TT></B> object is not deleted by this member function. +<P> +<FONT COLOR="teal"><B> void <A NAME="DeleteAll">DeleteAll</A>() </B></FONT> +<P> +Removes and deletes all <B><TT>DwAddress</TT></B> objects from the list +maintained by this <B><TT>DwAddressList</TT></B> object. +<P> +<FONT COLOR="teal"><B> static DwAddressList* +<A NAME="NewAddressList">NewAddressList</A>(const DwString& aStr, +DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwAddressList</TT></B> object on the free store. If +the static data member <B><TT>sNewAddressList</TT></B> is +<B><TT>NULL</TT></B>, this member function will create a new +<B><TT>DwAddressList</TT></B> and return it. Otherwise, +<B><TT>NewAddressList()</TT></B> will call the user-supplied function pointed +to by <B><TT>sNewAddressList</TT></B>, which is assumed to return an object +from a class derived from <B><TT>DwAddressList</TT></B>, and return that +object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwAddressList* +(*<A NAME="sNewAddressList">sNewAddressList</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewAddressList</TT></B> is not <B><TT>NULL</TT></B>, it is assumed +to point to a user-supplied function that returns a pointer to an object +from a class derived from <B><TT>DwAddressList</TT></B>. +<H2> + <FONT COLOR="navy"> Protected Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> DwAddress* <A NAME="mFirstAddress">mFirstAddress</A> +</B></FONT> +<P> +Points to first <B><TT>DwMailbox</TT></B> object in list. +<P> +</BODY></HTML> diff --git a/mimelib/doc/binhex.html b/mimelib/doc/binhex.html new file mode 100644 index 000000000..6d7f7ffb3 --- /dev/null +++ b/mimelib/doc/binhex.html @@ -0,0 +1,169 @@ +<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& <A HREF="binhex.html#DataFork">DataFork</A>() const; + void <A HREF="binhex.html#SetDataFork">SetDataFork</A>(const DwString& aStr); + const DwString& <A HREF="binhex.html#ResourceFork">ResourceFork</A>() const; + void <A HREF="binhex.html#SetResourceFork">SetResourceFork</A>(const DwString& aStr); + const DwString& <A HREF="binhex.html#BinhexChars">BinhexChars</A>() const; + void <A HREF="binhex.html#SetBinhexChars">SetBinhexChars</A>(const DwString& 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& <A NAME="DataFork">DataFork</A>() +const <BR> +void <A NAME="SetDataFork">SetDataFork</A>(const DwString& 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& +<A NAME="ResourceFork">ResourceFork</A>() const<BR> +void <A NAME="SetResourceFork">SetResourceFork</A>(const DwString& 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& +<A NAME="BinhexChars">BinhexChars</A>() const<BR> +void <A NAME="SetBinhexChars">SetBinhexChars</A>(const DwString& 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> diff --git a/mimelib/doc/body.html b/mimelib/doc/body.html new file mode 100644 index 000000000..1526751a4 --- /dev/null +++ b/mimelib/doc/body.html @@ -0,0 +1,308 @@ +<HTML> +<HEAD> + <TITLE> DwBody Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwBody -- Class representing a MIME message body +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwBody : public <A HREF="msgcmp.html">DwMessageComponent</A> { + + friend class DwHeaders; + friend class DwEntity; + friend class DwBodyPart; + +public: + + <A HREF="body.html#DwBody">DwBody</A>(); + <A HREF="body.html#DwBody">DwBody</A>(const DwBody& aBody); + <A HREF="body.html#DwBody">DwBody</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwBody(); + const DwBody& <A HREF="body.html#op_eq">operator =</A> (const DwBody& aBody); + virtual void <A HREF="body.html#Parse">Parse</A>(); + virtual void <A HREF="body.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="body.html#Clone">Clone</A>() const; + DwBodyPart* <A HREF="body.html#FirstBodyPart">FirstBodyPart</A>() const; + void <A HREF="body.html#AddBodyPart">AddBodyPart</A>(DwBodyPart* aPart); + DwMessage* <A HREF="body.html#Message">Message</A>() const; + void <A HREF="body.html#SetMessage">SetMessage</A>(DwMessage* aMessage); + static DwBody* <A HREF="body.html#NewBody">NewBody</A>(const DwString& aStr, DwMessageComponent* aParent); + static DwBody* (*<A HREF="body.html#sNewBody">sNewBody</A>)(const DwString&, DwMessageComponent*); + +protected: + + DwString <A HREF="body.html#mBoundaryStr">mBoundaryStr</A>; + DwString <A HREF="body.html#mPreamble">mPreamble</A>; + DwString <A HREF="body.html#mEpilogue">mEpilogue</A>; + DwBodyPart* <A HREF="body.html#mFirstBodyPart">mFirstBodyPart</A>; + DwMessage* <A HREF="body.html#mMessage">mMessage</A>; + static const char* const sClassName; + void <A HREF="body.html#_AddBodyPart">_AddBodyPart</A>(DwBodyPart*); + void <A HREF="body.html#_SetMessage">_SetMessage</A>(DwMessage*); + void DeleteBodyParts(); + void CopyBodyParts(const DwBodyPart* aFirst); + +public: + + virtual void <A HREF="body.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="body.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwBody</TT></B> represents a <I>body</I>, as described in RFC-2045. +A body is always part of an <I>entity</I>, which could be either a +<I>message</I> or a <I>body part</I>. An entity has a collection of <I>header +fields</I> and a body. If the content type of a body is ``multipart,'' then +the body contains one or more body parts. If the content type is ``message,'' +then the body contains an encapsulated message. In all content types, the +body contains a string of characters. +<P> +In MIME++, a <B><TT>DwBody</TT></B> object is contained in a +<B><TT><A HREF="entity.html">DwEntity</A></TT></B> object. The +<B><TT>DwBody</TT></B> object may contain a discrete body consisting only +of a string of characters, or it may be a composite body, consisting of several +contained <B><TT><A HREF="bodypart.html">DwBodyPart</A></TT></B> objects +or a single contained +<B><TT><A HREF="message.html">DwMessage</A></TT></B> object. The only reliable +way to determine the type of <B><TT>DwBody</TT></B> is to access the Content-Type +header field from the +<B><TT><A HREF="headers.html">DwHeaders</A></TT></B> object of the +<B><TT>DwEntity</TT></B> that contains it. For this reason, a +<B><TT>DwBody</TT></B> should always be part of a +<B><TT>DwEntity</TT></B>. +<P> +In the tree (broken-down) representation of a message, a +<B><TT>DwBody</TT></B> object can be an intermediate node, having both a +parent node and one or more child nodes, or a leaf node, having a parent +but no child nodes. In either case, the parent node is the +<B><TT>DwEntity</TT></B> object that contains it. If it is an intermediate +node, it must be of type multipart with <B><TT>DwBodyPart</TT></B> objects +as child nodes, or of type message with a single +<B><TT>DwMessage</TT></B> object as its child node. +<P> +Normally, you do not create a <B><TT>DwBody</TT></B> object directly, but +you access it through the <B><TT>Body()</TT></B> member function of +<B><TT>DwEntity</TT></B>, which creates the <B><TT>DwBody</TT></B> object +for you. +<P> +To add a <B><TT>DwBodyPart</TT></B> to a multipart +<B><TT>DwBody</TT></B>, use the member function +<B><TT>AddBodyPart()</TT></B>. To iterate over the +<B><TT>DwBodyParts</TT></B> contained in multipart +<B><TT>DwBody</TT></B>, get the first <B><TT>DwBodyPart</TT></B> by calling +<B><TT>FirstBodyPart()</TT></B>. Then get the following +<B><TT>DwBodyParts</TT></B> by calling <B><TT>DwBodyPart::Next()</TT></B> +on the current <B><TT>DwBodyPart</TT></B>. To get the +<B><TT>DwMessage</TT></B> contained in a <B><TT>Body</TT></B> with message +content type, call <B><TT>Message()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwBody">DwBody</A>() <BR> +DwBody(const DwBody& aBody) <BR> +DwBody(const DwString& aStr, DwMessageComponent* aParent=0) </B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwBody</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aBody</TT></B>. The parent of the new <B><TT>DwBody</TT></B> object +is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwBody</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwEntity</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwBody& <A NAME="op_eq">operator =</A> (const +DwBody& aBody) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aBody</TT></B>. The parent node of the <B><TT>DwBody</TT></B> object +is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwBody</TT></B> objects. The parse method +creates or updates the broken-down representation from the string representation. +For a multipart <B><TT>DwBody</TT></B> object, the parse method creates a +collection of <B><TT>DwBodyPart</TT></B> objects. For a message +<B><TT>DwBody</TT></B>, the parse method creates a single +<B><TT>DwMessage</TT></B> object. For any other type of +<B><TT>DwBody</TT></B>, the parse method does nothing. This member function +calls the <B><TT>Parse()</TT></B> member function of any objects it creates. +<P> +Note: If the <B><TT>DwBody</TT></B> object has no parent node -- that is, +it is not contained by a <B><TT>DwEntity</TT></B> object -- then the parse +method does nothing, since it is unable to determine the type of body. +<P> +You should call this member function after you set or modify the string +representation, and before you access a contained +<B><TT>DwBodyPart</TT></B> or <B><TT>DwMessage</TT></B>. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwBody</TT></B> objects. The assemble +method creates or updates the string representation from the broken-down +representation. Only <B><TT>DwBody</TT></B> objects with content type of +multipart or message require assembling. In either case, the +<B><TT>DwBody</TT></B> object must be able to find the headers of the message +or body part that contains it. Therefore, if the <B><TT>DwBody</TT></B> object +is not the child of a <B><TT>DwEntity</TT></B> (<I>i.e.</I>, +<B><TT>DwMessage</TT></B> or <B><TT>DwBodyPart</TT></B>) object, the +<B><TT>DwBody</TT></B> cannot be assembled because the content type cannot +be determined. +<P> +This function calls the <B><TT>Parse()</TT></B> member function of any +<B><TT>DwBodyPart</TT></B> or <B><TT>DwMessage</TT></B> object it contains. +<P> +You should call this member function after you add a +<B><TT>DwBodyPart</TT></B> object to a multipart body, or add a +<B><TT>DwMessage</TT></B> object to a message body, and before you access +the object's string representation. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwBody</TT></B> on the free store that has the same +value as this <B><TT>DwBody</TT></B> object. The basic idea is that of a +virtual copy constructor. +<P> +<FONT COLOR="teal"><B> DwBodyPart* +<A NAME="FirstBodyPart">FirstBodyPart</A>() const </B></FONT> +<P> +For a multipart <B><TT>DwBody</TT></B>, this member function returns the +first contained <B><TT>DwBodyPart</TT></B> object. Use +<B><TT>DwBodyPart::Next()</TT></B> to iterate through the list of +<B><TT>DwBodyPart</TT></B>s. +<P> +<FONT COLOR="teal"><B> void <A NAME="AddBodyPart">AddBodyPart</A>(DwBodyPart* +aPart) </B></FONT> +<P> +For a multipart <B><TT>DwBody</TT></B>, this member function appends a +<B><TT>DwBodyPart</TT></B> object to the list. Any +<B><TT>DwBodyPart</TT></B> objects added to a <B><TT>DwBody</TT></B> object's +list will be deleted by the <B><TT>DwBody</TT></B> object's destructor. +<P> +<FONT COLOR="teal"><B> Dw<A NAME="Message">Message</A>* Message() const +</B></FONT> +<P> +For a <B><TT>DwBody</TT></B> with content type of message, this member function +returns the <B><TT>DwMessage</TT></B> encapsulated in it. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetMessage">SetMessage</A>(DwMessage* +aMessage) </B></FONT> +<P> +For a <B><TT>DwBody</TT></B> with content type of message, this member function +sets the <B><TT>DwMessage</TT></B> object it contains. +<P> +<FONT COLOR="teal"><B> static DwBody* <A NAME="NewBody">NewBody</A>(const +DwString& aStr, DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwBody</TT></B> object on the free store. If the static +data member <B><TT>sNewBody</TT></B> is <B><TT>NULL</TT></B>, this member +function will create a new <B><TT>DwBody</TT></B> and return it. Otherwise, +<B><TT>NewBody()</TT></B> will call the user-supplied function pointed to +by <B><TT>sNewBody</TT></B>, which is assumed to return an object from a +class derived from <B><TT>DwBody</TT></B>, and return that object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwBody* +(*<A NAME="sNewBody">sNewBody</A>)(const DwString&, DwMessageComponent*) +</B></FONT> +<P> +If <B><TT>sNewBody</TT></B> is not <B><TT>NULL</TT></B>, it is assumed to +point to a user-supplied function that returns an object from a class derived +from <B><TT>DwBody</TT></B>. +<H2> + <FONT COLOR="navy"> Protected Member Functions </FONT> +</H2> +<P> +<B><FONT COLOR="teal"> void +<A NAME="_AddBodyPart">_AddBodyPart</A>(DwBodyPart*) </FONT></B> +<P> +Adds a body part to a multipart body. This function differs from +<B><TT>AddBodyPart</TT></B> in that it does not set the is-modified flag. +<P> +<B><FONT COLOR="teal"> void <A NAME="_SetMessage">_SetMessage</A>(DwMessage*) +</FONT></B> +<P> +Sets a message to a body. This function differs from +<B><TT>SetMessage()</TT></B> in that it does not set the is-modified flag. +<H2> + <FONT COLOR="navy"> Protected Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> DwString <A NAME="mBoundaryStr">mBoundaryStr</A> +</B></FONT> +<P> +A cache for the boundary string, which is obtained from the headers associated +with this body. +<P> +<FONT COLOR="teal"><B> DwString <A NAME="mPreamble">mPreamble</A> </B></FONT> +<P> +Contains the preamble -- the text preceding the first boundary -- in a +``multipart/*'' media type. +<P> +<FONT COLOR="teal"><B> DwString <A NAME="mEpilogue">mEpilogue</A> </B></FONT> +<P> +Contains the epilogue -- the text following the last boundary -- in a +``multipart/*'' media type. +<P> +<FONT COLOR="teal"><B> DwBodyPart* +<A NAME="mFirstBodyPart">mFirstBodyPart</A> </B></FONT> +<P> +Points to the first body part in a ``multipart/*'' media type. Is +<B><TT>NULL</TT></B> if there are no body parts. +<P> +<FONT COLOR="teal"><B> DwMessage* <A NAME="mMessage">mMessage</A> </B></FONT> +<P> +Points to the contained message, in a ``message/*'' media type. +<P> +</BODY></HTML> diff --git a/mimelib/doc/bodypart.html b/mimelib/doc/bodypart.html new file mode 100644 index 000000000..6a3a29b6e --- /dev/null +++ b/mimelib/doc/bodypart.html @@ -0,0 +1,157 @@ +<HTML> +<HEAD> + <TITLE> DwBodyPart Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwBodyPart -- Class representing a MIME body-part +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwBodyPart : public <A HREF="entity.html">DwEntity</A> { + +public: + + <A HREF="bodypart.html#DwBodyPart">DwBodyPart</A>(); + <A HREF="bodypart.html#DwBodyPart">DwBodyPart</A>(const DwBodyPart& aPart); + <A HREF="bodypart.html#DwBodyPart">DwBodyPart</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwBodyPart(); + const DwBodyPart& <A HREF="bodypart.html#op_eq">operator =</A> (const DwBodyPart& aPart); + virtual DwMessageComponent* <A HREF="bodypart.html#Clone">Clone</A>() const; + static DwBodyPart* <A HREF="bodypart.html#NewBodyPart">NewBodyPart</A>(const DwString& aStr, + DwMessageComponent* aParent); + DwBodyPart* <A HREF="bodypart.html#Next">Next</A>() const; + void <A HREF="bodypart.html#SetNext">SetNext</A>(const DwBodyPart* aPart); + static DwBodyPart* (*<A HREF="bodypart.html#sNewBodyPart">sNewBodyPart</A>)(const DwString&, DwMessageComponent*); + +public: + + virtual void <A HREF="bodypart.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="bodypart.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwBodyPart</TT></B> represents a <I>body part</I>, as described in +RFC-2045 and RFC-2046. A body part is an <I>entity</I>, so it has a collection +of headers and a <I>body</I>. A body part is different from a <I>message</I> +in that a body part is part of a multipart body. +<P> +In MIME++, a <B><TT>DwBodyPart</TT></B> is a subclass of +<B><TT><A HREF="entity.html">DwEntity</A></TT></B>; therefore, it contains +both a <B><TT><A HREF="headers.html">DwHeaders</A></TT></B> object and a +<B><TT><A HREF="body.html">DwBody</A></TT></B> object, and it is contained +in a multipart <B><TT>DwBody</TT></B> object. +<P> +As with <B><TT><A HREF="message.html">DwMessage</A></TT></B>, most of the +functionality of <B><TT>DwBodyPart</TT></B> is implemented by the abstract +class <B><TT>DwEntity</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwBodyPart">DwBodyPart</A>() <BR> +DwBodyPart(const DwBodyPart& aPart) <BR> +DwBodyPart(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwBodyPart</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aPart</TT></B>. The parent of the new +<B><TT>DwBodyPart</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwBodyPart</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwBody</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwBodyPart& <A NAME="op_eq">operator =</A> +(const DwBodyPart& aPart) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aPart</TT></B>. The parent node of the <B><TT>DwBodyPart</TT></B> +object is not changed. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwBodyPart</TT></B> on the free store that has the same +value as this <B><TT>DwBodyPart</TT></B> object. The basic idea is that of +a virtual copy constructor. +<P> +<FONT COLOR="teal"><B> static DwBodyPart* +<A NAME="NewBodyPart">NewBodyPart</A>(const DwString& aStr, +DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwBodyPart</TT></B> on the free store. If the static +data member <B><TT>sNewBodyPart</TT></B> is <B><TT>NULL</TT></B>, this member +function will create a new <B><TT>DwBodyPart</TT></B> and return it. Otherwise, +<B><TT>NewBodyPart()</TT></B> will call the user-supplied function pointed +to by <B><TT>sNewBodyPart</TT></B>, which is assumed to return an object +from a class derived from <B><TT>DwBodyPart</TT></B>, and return that object. +<P> +<FONT COLOR="teal"><B> DwBodyPart* <A NAME="Next">Next</A>() const +</B></FONT> +<P> +This member function returns the next <B><TT>DwBodyPart</TT></B> object following +this <B><TT>DwBodyPart</TT></B> in the list of <B><TT>DwBodyPart</TT></B> +objects contained in a multipart <B><TT>DwBody</TT></B>. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetNext">SetNext</A>(const DwBodyPart* +aPart) </B></FONT> +<P> +This advanced function sets <B><TT>aPart</TT></B> as the next +<B><TT>DwBodyPart</TT></B> object following this +<B><TT>DwBodyPart</TT></B> in the list of <B><TT>DwBodyPart</TT></B> objects +contained in a multipart <B><TT>DwBody</TT></B>. Since +<B><TT>DwBody</TT></B> contains a member function for adding a +<B><TT>DwBodyPart</TT></B> object to its list, this function should be avoided +for most applications. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwBodyPart* +(*<A NAME="sNewBodyPart">sNewBodyPart</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewBodyPart</TT></B> is not <B><TT>NULL</TT></B>, it is assumed +to point to a user-supplied function that returns an object from a class +derived from <B><TT>DwBodyPart</TT></B>. +<P> +</BODY></HTML> diff --git a/mimelib/doc/boyermor.html b/mimelib/doc/boyermor.html new file mode 100644 index 000000000..12606e350 --- /dev/null +++ b/mimelib/doc/boyermor.html @@ -0,0 +1,57 @@ +<HTML> +<HEAD> + <TITLE> DwBoyerMoore Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwBoyerMoore -- Class for executing Boyer-Moore string search algorithm +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwBoyerMoore { + +public: + + <A HREF="boyermor.html#DwBoyerMoore">DwBoyerMoore</A>(const char* aCstr); + <A HREF="boyermor.html#DwBoyerMoore">DwBoyerMoore</A>(const DwString& aStr); + virtual ~DwBoyerMoore(); + void <A HREF="boyermor.html#Assign">Assign</A>(const char* aCstr); + void <A HREF="boyermor.html#Assign">Assign</A>(const DwString& aStr); + size_t <A HREF="boyermor.html#FindIn">FindIn</A>(const DwString& aStr, size_t aPos); +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwBoyerMoore</TT></B> implements the Boyer-Moore algorithm for searching +for a string. The Boyer-Moore algorithm is fast, but requires a bit of start-up +overhead compared to a brute force algorithm. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwBoyerMoore">DwBoyerMoore</A>(const char* +aCstr) <BR> +DwBoyerMoore(const DwString& aStr) </B></FONT> +<P> +Constructs a <B><TT>DwBoyerMoore</TT></B> object for searching for a particular +string. +<P> +<FONT COLOR="teal"><B> void <A NAME="Assign">Assign</A>(const char* aCstr) +<BR> +void Assign(const DwString& aStr) </B></FONT> +<P> +Sets the string to search for. +<P> +<FONT COLOR="teal"><B> size_t <A NAME="FindIn">FindIn</A>(const DwString& +aStr, size_t aPos) </B></FONT> +<P> +Searches for the search string in <B><TT>aStr</TT></B> starting at position +<B><TT>aPos</TT></B>. If found, the function returns the first position in +<B><TT>aStr</TT></B> where the search string was found. If not found, the +function returns <B><TT>DwString::npos</TT></B>. +</BODY></HTML> diff --git a/mimelib/doc/datetime.html b/mimelib/doc/datetime.html new file mode 100644 index 000000000..0516d9292 --- /dev/null +++ b/mimelib/doc/datetime.html @@ -0,0 +1,340 @@ +<HTML> +<HEAD> + <TITLE> DwDateTime Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwDateTime -- Class representing an RFC-822 date-time +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwDateTime : public <A HREF="fieldbdy.html">DwFieldBody</A> { + +public: + + <A HREF="datetime.html#DwDateTime">DwDateTime</A>(); + <A HREF="datetime.html#DwDateTime">DwDateTime</A>(const DwDateTime& aDateTime); + <A HREF="datetime.html#DwDateTime">DwDateTime</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwDateTime(); + const DwDateTime& <A HREF="datetime.html#op_eq">operator =</A> (const DwDateTime& aDateTime); + virtual void <A HREF="datetime.html#Parse">Parse</A>(); + virtual void <A HREF="datetime.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="datetime.html#Clone">Clone</A>() const; + DwUint32 <A HREF="datetime.html#AsUnixTime">AsUnixTime</A>() const; + void <A HREF="datetime.html#FromUnixTime">FromUnixTime</A>(DwUint32 aTime); + time_t <A HREF="datetime.html#AsCalendarTime">AsCalendarTime</A>() const; + void <A HREF="datetime.html#FromCalendarTime">FromCalendarTime</A>(time_t aTime); + DwInt32 <A HREF="datetime.html#DateAsJulianDayNum">DateAsJulianDayNum</A>() const; + void <A HREF="datetime.html#DateFromJulianDayNum">DateFromJulianDayNum</A>(DwInt32 aJdn); + DwInt32 <A HREF="datetime.html#TimeAsSecsPastMidnight">TimeAsSecsPastMidnight</A>() const; + void <A HREF="datetime.html#TimeFromSecsPastMidnight">TimeFromSecsPastMidnight</A>(DwInt32 aSecs); + int <A HREF="datetime.html#Year">Year</A>() const; + void <A HREF="datetime.html#SetYear">SetYear</A>(int aYear); + int <A HREF="datetime.html#Month">Month</A>() const; + void <A HREF="datetime.html#SetMonth">SetMonth</A>(int aMonth); + int <A HREF="datetime.html#Day">Day</A>() const; + void <A HREF="datetime.html#SetDay">SetDay</A>(int aDay); + int <A HREF="datetime.html#Hour">Hour</A>() const; + void <A HREF="datetime.html#SetHour">SetHour</A>(int aHour); + int <A HREF="datetime.html#Minute">Minute</A>() const; + void <A HREF="datetime.html#SetMinute">SetMinute</A>(int aMinute); + int <A HREF="datetime.html#Second">Second</A>() const; + void <A HREF="datetime.html#SetSecond">SetSecond</A>(int aSecond); + int <A HREF="datetime.html#Zone">Zone</A>() const; + void <A HREF="datetime.html#SetZone">SetZone</A>(int aZone); + static void <A HREF="datetime.html#SetDefaultZone">SetDefaultZone</A>(int aZone); + static DwDateTime* <A HREF="datetime.html#NewDateTime">NewDateTime</A>(const DwString&, DwMessageComponent*); + static DwDateTime* (*<A HREF="datetime.html#sNewDateTime">sNewDateTime</A>)(const DwString&, DwMessageComponent*); + +protected: + + void <A HREF="datetime.html#_FromUnixTime">_FromUnixTime</A>(DwUint32 aTime); + void <A HREF="datetime.html#_FromCalendarTime">_FromCalendarTime</A>(time_t aTime); + int mYear; + int mMonth; + int mDay; + int mHour; + int mMinute; + int mSecond; + int mZone; + static int sDefaultZone; + static int sIsDefaultZoneSet; + +public: + + virtual void <A HREF="datetime.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="datetime.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwDatetime</TT></B> represents a <I>date-time</I> as described in +RFC-822 and RFC-1123. The parse method for <B><TT>DwDateTime</TT></B> parses +the string representation to extract the year, month, day, hour, minute, +second, and time zone. <B><TT>DwDateTime</TT></B> provides member functions +to set or get the individual components of the date-time. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwDateTime">DwDateTime</A>() <BR> +DwDateTime(const DwDateTime& aDateTime) <BR> +DwDateTime(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which assigns the current +date and time as reported by the operating system. +<P> +The second constructor is the copy constructor. The parent of the new +<B><TT>DwDateTime</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor sets <B><TT>aStr</TT></B> as the +<B><TT>DwDateTime</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called after this constructor to extract +the date and time information from the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwDateTime& <A NAME="op_eq">operator =</A> +(const DwDateTime& aDateTime) </B></FONT> +<P> +This is the assignment operator, which sets this +<B><TT>DwDateTime</TT></B> object to the same value as +<B><TT>aDateTime</TT></B>. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwDateTime</TT></B> objects. The parse +method creates or updates the broken-down representation from the string +representation. For <B><TT>DwDateTime</TT></B> objects, the parse method +parses the string representation to extract the year, month, day, hour, minute, +second, and time zone. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwDateTime</TT></B> objects. It should +be called whenever one of the object's attributes is changed in order to +assemble the string representation from its broken-down representation. It +will be called automatically for this object by the parent object's +<B><TT>Assemble()</TT></B> member function if the is-modified flag is set. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwDateTime</TT></B> on the free store that has the same +value as this <B><TT>DwDateTime</TT></B> object. The basic idea is that of +a virtual copy constructor. +<P> +<FONT COLOR="teal"><B> DwUint32 <A NAME="AsUnixTime">AsUnixTime</A>() const +</B></FONT> +<P> +Returns the date and time as a UNIX (POSIX) time, defined as the number of +seconds elapsed since 1 Jan 1970 00:00:00 UTC. +<P> +<FONT COLOR="teal"><B> void <A NAME="FromUnixTime">FromUnixTime</A>(DwUint32 +aTime) </B></FONT> +<P> +Sets the date and time from <B><TT>aTime</TT></B>, interpreted as the number +of of seconds elapsed since 1 Jan 1970 00:00:00 UTC. +<P> +<FONT COLOR="teal"><B> time_t <A NAME="AsCalendarTime">AsCalendarTime</A>() +const </B></FONT> +<P> +Returns the date and time as a value of type <B><TT>time_t</TT></B> that +conforms to the native format returned by the <B><TT>time()</TT></B> ANSI +C function. On most UNIX systems, this function returns the same value as +<B><TT>AsUnixTime()</TT></B>. (For efficiency, use +<B><TT>AsUnixTime()</TT></B> instead of <B><TT>AsCalendarTime()</TT></B> +if possible). +<P> +<FONT COLOR="teal"><B> void +<A NAME="FromCalendarTime">FromCalendarTime</A>(time_t aTime) </B></FONT> +<P> +Sets the date and time from <B><TT>aTime</TT></B>, which is assumed to be +in a format compatible with the native <B><TT>time()</TT></B> ANSI C function. +For most UNIX systems, this function is the same as the function +<B><TT>FromUnixTime()</TT></B>. (For efficiency, use +<B><TT>FromUnixTime()</TT></B> instead of +<B><TT>FromCalendarTime()</TT></B> if possible). +<P> +<FONT COLOR="teal"><B> DwInt32 +<A NAME="DateAsJulianDayNum">DateAsJulianDayNum</A>() const </B></FONT> +<P> +Returns the Julian Day Number, defined as the number of days elapsed since +1 Jan 4713 BC. The JDN is calculated directly from the values of the year, +month, and day; time zone information is ignored. +<P> +<FONT COLOR="teal"><B> void +<A NAME="DateFromJulianDayNum">DateFromJulianDayNum</A>(DwInt32 aJdn) +</B></FONT> +<P> +Sets the year, month, and day from <B><TT>aJdn</TT></B>, interpreted as a +Julian Day Number. By definition, the JDN is the number of days elapsed since +1 Jan 4713 BC. This member function ignores time zone information. +<P> +<FONT COLOR="teal"><B> DwInt32 +<A NAME="TimeAsSecsPastMidnight">TimeAsSecsPastMidnight</A>() const +</B></FONT> +<P> +Returns the number of seconds past midnight. The value is calculated directly +from the values of the hour, minute, and second; time zone information is +ignored. +<P> +<FONT COLOR="teal"><B> void +<A NAME="TimeFromSecsPastMidnight">TimeFromSecsPastMidnight</A>(DwInt32 aSecs) +</B></FONT> +<P> +Sets the hour, minute, and second from <B><TT>aSecs</TT></B>, interpreted +as the number of seconds elapsed since midnight. This member function ignores +time zone information. The argument <B><TT>aSecs</TT></B> should be in the +range 0 to 86399, inclusive. +<P> +<FONT COLOR="teal"><B> int <A NAME="Year">Year</A>() const </B></FONT> +<P> +Returns the four digit year, e.g. 1997. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetYear">SetYear</A>(int aYear) +</B></FONT> +<P> +Sets the year from <B><TT>aYear</TT></B>, which should be a four digit year. +<P> +<FONT COLOR="teal"><B> int <A NAME="Month">Month</A>() const </B></FONT> +<P> +Returns the month. Values range from 1 to 12. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetMonth">SetMonth</A>(int aMonth) +</B></FONT> +<P> +Sets the month from <B><TT>aMonth</TT></B>, which should be in the range +1 to 12. +<P> +<FONT COLOR="teal"><B> int <A NAME="Day">Day</A>() const </B></FONT> +<P> +Returns the day of the month. Values range from 1 to 31. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetDay">SetDay</A>(int aDay) </B></FONT> +<P> +Sets the day of the month from <B><TT>aDay</TT></B>. +<P> +<FONT COLOR="teal"><B> int <A NAME="Hour">Hour</A>() const </B></FONT> +<P> +Returns the hour according to the 24 hour clock. Values range from 0 to 23. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetHour">SetHour</A>(int aHour) +</B></FONT> +<P> +Sets the hour from <B><TT>aHour</TT></B> based on the 24-hour clock. +<B><TT>aHour</TT></B> should be in the range 0 to 23. +<P> +<FONT COLOR="teal"><B> int <A NAME="Minute">Minute</A>() const </B></FONT> +<P> +Returns the minute. Values range from 0 to 59. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetMinute">SetMinute</A>(int aMinute) +</B></FONT> +<P> +Sets the minute from <B><TT>aMinute</TT></B>, which should be in the range +0 to 59. +<P> +<FONT COLOR="teal"><B> int <A NAME="Second">Second</A>() const </B></FONT> +<P> +Returns the second. Values range from 0 to 59. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetSecond">SetSecond</A>(int aSecond) +</B></FONT> +<P> +Sets the second from <B><TT>aSecond</TT></B>, which should be in the range +0 to 59. +<P> +<FONT COLOR="teal"><B> int <A NAME="Zone">Zone</A>() const </B></FONT> +<P> +Returns the time zone as the diffence in minutes between local time and +Coordinated Universal Time (UTC or GMT). +<P> +<FONT COLOR="teal"><B> void <A NAME="SetZone">SetZone</A>(int aZone) +</B></FONT> +<P> +Sets the time zone from <B><TT>aZone</TT></B>, interpreted as the time difference +in minutes between local time and Coordinated Universal Time (UTC, or GMT). +<P> +<FONT COLOR="teal"><B> static void +<A NAME="SetDefaultZone">SetDefaultZone</A>(int aZone) </B></FONT> +<P> +Sets the default time zone. <B><TT>aZone</TT></B> should be the time difference +in minutes between local time and Coordinated Universal Time (UTC, or GMT). +The value is used to set the time zone for any objects created using the +default constructor. +<P> +<FONT COLOR="teal"><B> static DwDateTime* +<A NAME="NewDateTime">NewDateTime</A>(const DwString&, DwMessageComponent*) +</B></FONT> +<P> +Creates a new <B><TT>DwDateTime</TT></B> object on the free store. If the +static data member <B><TT>sNewDateTime</TT></B> is <B><TT>NULL</TT></B>, +this member function will create a new <B><TT>DwDateTime</TT></B> and return +it. Otherwise, <B><TT>NewDateTime()</TT></B> will call the user-supplied +function pointed to by <B><TT>sNewDateTime</TT></B>, which is assumed to +return an object from a class derived from <B><TT>DwDateTime</TT></B>, and +return that object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwDateTime* +(*<A NAME="sNewDateTime">sNewDateTime</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewDateTime</TT></B> is not <B><TT>NULL</TT></B>, it is assumed +to point to a user-supplied function that returns an object from a class +derived from <B><TT>DwDateTime</TT></B>. +<H2> + <FONT COLOR="navy"> Protected Member Functions </FONT> +</H2> +<P> +<B><FONT COLOR="teal"> void +<A NAME="_FromUnixTime">_FromUnixTime</A>(DwUint32 aTime) </FONT></B> +<P> +Like <B><TT>FromUnixTime()</TT></B>, but doesn't set the is-modified flag. +<P> +<B><FONT COLOR="teal"> void +<A NAME="_FromCalendarTime">_FromCalendarTime</A>(time_t aTime) </FONT></B> +<P> +Like <B><TT>FromCalendarTime()</TT></B>, but doesn't set the is-modified +flag. +<P> +</BODY></HTML> diff --git a/mimelib/doc/disptype.html b/mimelib/doc/disptype.html new file mode 100644 index 000000000..c64b1dc13 --- /dev/null +++ b/mimelib/doc/disptype.html @@ -0,0 +1,224 @@ +<HTML> +<HEAD> + <TITLE> DwDispositionType Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwDispositionType -- Class representing a MIME content-disposition field +body +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwDispositionType : public <A HREF="fieldbdy.html">DwFieldBody</A> { + +public: + + <A HREF="disptype.html#DwDispositionType">DwDispositionType</A>(); + <A HREF="disptype.html#DwDispositionType">DwDispositionType</A>(const DwDispositionType& aDispType); + <A HREF="disptype.html#DwDispositionType">DwDispositionType</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwDispositionType(); + const DwDispositionType& <A HREF="disptype.html#op_eq">operator =</A> (const DwDispositionType& aDispType); + virtual void <A HREF="disptype.html#Parse">Parse</A>(); + virtual void <A HREF="disptype.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="disptype.html#Clone">Clone</A>() const; + int <A HREF="disptype.html#DispositionType">DispositionType</A>() const; + void <A HREF="disptype.html#SetDispositionType">SetDispositionType</A>(int aType); + const DwString& <A HREF="disptype.html#DispositionTypeStr">DispositionTypeStr</A>() const; + void <A HREF="disptype.html#SetDispositionTypeStr">SetDispositionTypeStr</A>(const DwString& aStr); + const DwString& <A HREF="disptype.html#Filename">Filename</A>() const; + void <A HREF="disptype.html#SetFilename">SetFilename</A>(const DwString& aStr); + DwParameter* <A HREF="disptype.html#FirstParameter">FirstParameter</A>() const; + void <A HREF="disptype.html#AddParameter">AddParameter</A>(DwParameter* aParam); + static DwDispositionType* <A HREF="disptype.html#NewDispositionType">NewDispositionType</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwDispositionType* (*<A HREF="disptype.html#sNewDispositionType">sNewDispositionType</A>)(const DwString&, + DwMessageComponent*); + +protected: + + void _AddParameter(DwParameter* aParam); + virtual void EnumToStr(); + virtual void StrToEnum(); + void DeleteParameterList(); + void CopyParameterList(DwParameter* aFirst); + int mDispositionType; + DwString mDispositionTypeStr; + DwString mFilenameStr; + DwParameter* mFirstParameter; + +public: + + virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const; + virtual void CheckInvariants() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwDispositionType</TT></B> represents a field body for the +Content-Disposition header field as described in RFC-1806. This header field +specifies whether the content of a message or body part should be displayed +automatically to a user. A disposition-type of inline indicates that the +content should be displayed; a disposition-type of attachment indicates that +it should not be. RFC-1806 specifies that a filename parameter may be optionally +included in the field body; the filename parameter suggests a file name for +saving the message or body part's content. +<P> +<B><TT>DwDispositionType</TT></B> provides convenience functions that allow +you to set or get the disposition-type as an enumerated value, to set or +get the filename parameter, or to manage a list of parameters. +<P> +RFC-1806 specifically states that the Content-Disposition header field is +experimental and not a proposed standard. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwDispositionType">DwDispositionType</A>() +<BR> +DwDispositionType(const DwDispositionType& aDispType) <BR> +DwDispositionType(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwDispositionType</TT></B> object's string representation to the empty +string and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs deep copy +of <B><TT>aDispType</TT></B>. The parent of the new +<B><TT>DwDispositionType</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwDispositionType</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwDispositionType& <A NAME="op_eq">operator +=</A> (const DwDispositionType& aDispType) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aDispType</TT></B>. The parent node of the +<B><TT>DwDipositionType</TT></B> object is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwDispositionType</TT></B> objects. +It should be called immediately after the string representation is modified +and before the parts of the broken-down representation are accessed. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwDispositionType</TT></B> objects. +It should be called whenever one of the object's attributes is changed in +order to assemble the string representation from its broken-down representation. +It will be called automatically for this object by the parent object's +<B><TT>Assemble()</TT></B> member function if the is-modified flag is set. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwDispositionType</TT></B> object on the free store +that has the same value as this <B><TT>DwDispositionType</TT></B> object. +The basic idea is that of a virtual copy constructor. +<P> +<FONT COLOR="teal"><B> int <A NAME="DispositionType">DispositionType</A>() +const </B></FONT> +<P> +Returns the disposition-type as an enumerated value. Valid enumerated types, +which are defined in enum.h, include +<B><TT>DwMime::kDispTypeNull</TT></B>, +<B><TT>DwMime::kDispTypeUnknown</TT></B>, +<B><TT>DwMime::kDispTypeInline</TT></B>, and +<B><TT>DwMime::kDispTypeAttachment</TT></B>. +<P> +<FONT COLOR="teal"><B> void +<A NAME="SetDispositionType">SetDispositionType</A>(int aType) </B></FONT> +<P> +Sets the disposition-type from the enumerated value +<B><TT>aType</TT></B>. Valid enumerated types, which are defined in enum.h, +include <B><TT>DwMime::kDispTypeNull</TT></B>, +<B><TT>DwMime::kDispTypeUnknown</TT></B>, +<B><TT>DwMime::kDispTypeInline</TT></B>, and +<B><TT>DwMime::kDispTypeAttachment</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="DispositionTypeStr">DispositionTypeStr</A>() const </B></FONT> +<P> +Returns the disposition-type as a string. +<P> +<FONT COLOR="teal"><B> void +<A NAME="SetDispositionTypeStr">SetDispositionTypeStr</A>(const DwString& +aStr) </B></FONT> +<P> +Sets the disposition-type from a string. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="Filename">Filename</A>() +const </B></FONT> +<P> +This convenience function returns the value from the filename parameter, +if present. If no filename parameter is present, an empty string is returned. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetFilename">SetFilename</A>(const +DwString& aStr) </B></FONT> +<P> +This convenience function sets the value of the filename parameter to +<B><TT>aStr</TT></B>. +<P> +<FONT COLOR="teal"><B> DwParameter* +<A NAME="FirstParameter">FirstParameter</A>() const </B></FONT> +<P> +Returns the first <B><TT>DwParameter</TT></B> object in the list managed +by this <B><TT>DwDispositionType</TT></B> object, or <B><TT>NULL</TT></B> +if no parameters are present. Use <B><TT>DwParameter::Next()</TT></B> to +iterate through the list. +<P> +<FONT COLOR="teal"><B> void +<A NAME="AddParameter">AddParameter</A>(DwParameter* aParam) </B></FONT> +<P> +Adds a <B><TT>DwParameter</TT></B> object to the list managed by this +<B><TT>DwDispositionType</TT></B> object. +<P> +<FONT COLOR="teal"><B> static DwDispositionType* +<A NAME="NewDispositionType">NewDispositionType</A>(const DwString& aStr, +DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwDispositionType</TT></B> object on the free store. +If the static data member <B><TT>sNewDispositionType</TT></B> is +<B><TT>NULL</TT></B>, this member function will create a new +<B><TT>DwDispositionType</TT></B> and return it. Otherwise, +<B><TT>NewDispositionType()</TT></B> will call the user-supplied function +pointed to by <B><TT>sNewDispositionType</TT></B>, which is assumed to return +an object from a class derived from <B><TT>DwDispositionType</TT></B>, and +return that object. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwDispositionType* +(*<A NAME="sNewDispositionType">sNewDispositionType</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewDispositionType</TT></B> is not <B><TT>NULL</TT></B>, it is +assumed to point to a user-supplied function that returns an object from +a class derived from <B><TT>DwDispositionType</TT></B>. +<P> +</BODY></HTML> diff --git a/mimelib/doc/entity.html b/mimelib/doc/entity.html new file mode 100644 index 000000000..08cf8b753 --- /dev/null +++ b/mimelib/doc/entity.html @@ -0,0 +1,168 @@ +<HTML> +<HEAD> + <TITLE> DwEntity Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwEntity -- Abstract class representing a MIME entity +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwEntity : public <A HREF="msgcmp.html">DwMessageComponent</A> { + +public: + + <A HREF="entity.html#DwEntity">DwEntity</A>(); + <A HREF="entity.html#DwEntity">DwEntity</A>(const DwEntity& aEntity); + <A HREF="entity.html#DwEntity">DwEntity</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwEntity(); + const DwEntity& <A HREF="entity.html#op_eq">operator =</A> (const DwEntity& aEntity); + virtual void <A HREF="entity.html#Parse">Parse</A>(); + virtual void <A HREF="entity.html#Assemble">Assemble</A>(); + DwHeaders& <A HREF="entity.html#Headers">Headers</A>() const; + DwBody& <A HREF="entity.html#Body">Body</A>() const; + +protected: + + DwHeaders* mHeaders; + DwBody* mBody; + +public: + + virtual void <A HREF="entity.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="entity.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +RFC-2045 defines an <I>entity</I> as either a <I>message</I> or a <I>body +part</I>, both of which have a collection of headers and a <I>body</I>. In +MIME++, an entity is represented by the class <B><TT>DwEntity</TT></B>, which +contains both a <B><TT><A HREF="headers.html">DwHeaders</A></TT></B> object +and a <B><TT><A HREF="body.html">DwBody</A></TT></B> object. +<P> +In the tree (broken-down) representation of message, a +<B><TT>DwEntity</TT></B> object may be either a root node, having child nodes +but no parent node, or an intermediate node, having both a parent node and +child nodes. A <B><TT>DwEntity</TT></B> object that is a root node must also +be a <B><TT><A HREF="message.html">DwMessage</A></TT></B> object. If a +<B><TT>DwEntity</TT></B> object is an intermediate node, its parent must +be a <B><TT>DwBody</TT></B> object. The child nodes of a +<B><TT>DwEntity</TT></B> object are the <B><TT>DwHeaders</TT></B> and +<B><TT>DwBody</TT></B> objects it contains. +<P> +Since <B><TT>DwEntity</TT></B> is an abstract base class, you cannot create +instances of it directly. <B><TT>DwEntity</TT></B> has two derived classes, +<B><TT><A HREF="message.html">DwMessage</A></TT></B> and +<B><TT><A HREF="bodypart.html">DwBodyPart</A></TT></B>, which are concrete +classes. +<P> +To access the contained <B><TT>DwHeaders</TT></B> object, use the member +function <B><TT>Headers()</TT></B>. To access the contained +<B><TT>DwBody</TT></B> object, use the member function +<B><TT>Body()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwEntity">DwEntity</A>() <BR> +DwEntity(const DwEntity& aEntity) <BR> +DwEntity(const DwString& aStr, DwMessageComponent* aParent=0) </B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwEntity</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aEntity</TT></B>. The parent of the new +<B><TT>DwEntity</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwEntity</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwBody</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwEntity& <A NAME="op_eq">operator =</A> +(const DwEntity& aEntity) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aEntity</TT></B>. The parent node of the <B><TT>DwEntity</TT></B> +object is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwEntity</TT></B> objects. The parse +method creates or updates the broken-down representation from the string +representation. For <B><TT>DwEntity</TT></B> objects, the parse method parses +the string representation and sets the values of the +<B><TT>DwHeaders</TT></B> and <B><TT>DwBody</TT></B> objects it contains. +This member function also calls the <B><TT>Parse()</TT></B> member functions +of the contained <B><TT>DwHeaders</TT></B> and <B><TT>DwBody</TT></B> objects. +<P> +You should call this member function after you set or modify the string +representation, and before you access either the contained headers or body. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwEntity</TT></B> objects. The assemble +method creates or updates the string representation from the broken-down +representation. In more concrete terms, the assemble method builds the string +representation from the string representations of the contained +<B><TT>DwHeaders</TT></B> and <B><TT>DwBody</TT></B> objects. This member +function calls the <B><TT>Assemble()</TT></B> member functions of its +<B><TT>DwHeaders</TT></B> and <B><TT>DwBody</TT></B> objects. +<P> +You should call this member function after you modify either the contained +headers or body, and before you retrieve the string representation. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> Dw<A NAME="Headers">Headers</A>& Headers() const +</B></FONT> +<P> +This function returns the <B><TT>DwHeaders</TT></B> object contained by this +object. +<P> +<FONT COLOR="teal"><B> Dw<A NAME="Body">Body</A>& Body() const +</B></FONT> +<P> +This function returns the <B><TT>DwBody</TT></B> object contained by this +object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<P> +</BODY></HTML> diff --git a/mimelib/doc/field.html b/mimelib/doc/field.html new file mode 100644 index 000000000..19736f271 --- /dev/null +++ b/mimelib/doc/field.html @@ -0,0 +1,305 @@ +<HTML> +<HEAD> + <TITLE> DwField Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwField -- Class representing a MIME header field +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwField : public <A HREF="msgcmp.html">DwMessageComponent</A> { + + friend class DwHeaders; + +public: + + <A HREF="field.html#DwField">DwField</A>(); + <A HREF="field.html#DwField">DwField</A>(const DwField& aField); + <A HREF="field.html#DwField">DwField</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwField(); + const DwField& <A HREF="field.html#op_eq">operator =</A> (const DwField& aField); + virtual void <A HREF="field.html#Parse">Parse</A>(); + virtual void <A HREF="field.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="field.html#Clone">Clone</A>() const; + DwFieldBody* <A HREF="field.html#FieldBody">FieldBody</A>() const; + const DwString& <A HREF="field.html#FieldNameStr">FieldNameStr</A>() const; + const DwString& <A HREF="field.html#FieldBodyStr">FieldBodyStr</A>() const; + DwField* <A HREF="field.html#Next">Next</A>() const; + void <A HREF="field.html#SetFieldBody">SetFieldBody</A>(DwFieldBody* aFieldBody); + void <A HREF="field.html#SetFieldNameStr">SetFieldNameStr</A>(const DwString& aStr); + void <A HREF="field.html#SetFieldBodyStr">SetFieldBodyStr</A>(const DwString& aStr); + void <A HREF="field.html#SetNext">SetNext</A>(const DwField* aField); + static DwField* <A HREF="field.html#NewField">NewField</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwFieldBody* <A HREF="field.html#CreateFieldBody">CreateFieldBody</A>(const DwString& aFieldName, + const DwString& aFieldBody, DwMessageComponent* aParent); + static DwFieldBody* _CreateFieldBody(const DwString& aFieldName, + const DwString& aFieldBody, DwMessageComponent* aParent); + static DwField* (*<A HREF="field.html#sNewField">sNewField</A>)(const DwString&, DwMessageComponent*); + static DwFieldBody* (*<A HREF="field.html#sCreateFieldBody">sCreateFieldBody</A>)(const DwString& aFieldName, + const DwString& aFieldBody, DwMessageComponent* aParent); + +protected: + + DwString mFieldNameStr; + DwString mFieldBodyStr; + DwFieldBody* mFieldBody; + void <A HREF="field.html#_SetFieldBody">_SetFieldBody</A>(DwFieldBody* aFieldBody); + +public: + + virtual void <A HREF="field.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="field.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwField</TT></B> represents a header field as described in RFC-822. +According to RFC-822, a field contains a field name and a field body. In +MIME++, a <B><TT>DwField</TT></B> contains three elements: a +<B><TT><A HREF="string.html">DwString</A></TT></B> that contains its field +name, a <B><TT>DwString</TT></B> that contains its field body, and a +<B><TT><A HREF="fieldbdy.html">DwFieldBody</A></TT></B> object that contains +a broken-down (that is, parsed) version of its field body. +<P> +In the tree (broken-down) representation of message, a +<B><TT>DwField</TT></B> object is always an intermediate node, having a parent +node and a single child node. The parent node is the +<B><TT><A HREF="headers.html">DwHeaders</A></TT></B> object that contains +it. The child node is the <B><TT>DwFieldBody</TT></B> object it contains. +<P> +To get and set the field name, use the member functions +<B><TT>FieldNameStr()</TT></B> and <B><TT>SetFieldNameStr()</TT></B>. To +get and set the field body, use the member functions +<B><TT>FieldBodyStr()</TT></B> and <B><TT>SetFieldBodyStr()</TT></B>. To +get and set the <B><TT>DwFieldBody</TT></B> object, use +<B><TT>FieldBody()</TT></B> and <B><TT>SetFieldBody()</TT></B>. +<P> +A <B><TT>DwField</TT></B> object can be included in a list of +<B><TT>DwField</TT></B> objects; usually this is the list of +<B><TT>DwField</TT></B> objects maintained by its parent +<B><TT>DwHeaders</TT></B> object. To get the next <B><TT>DwField</TT></B> +object in a list, use the member function <B><TT>Next()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwField">DwField</A>() <BR> +DwField(const DwField& aField) <BR> +DwField(const DwString& aStr, DwMessageComponent* aParent=0) </B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwField</TT></B> object's field name and field body to the empty string, +set its parent to <B><TT>NULL</TT></B>, and sets its +<B><TT>DwFieldBody</TT></B> object to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aField</TT></B>. The parent of the new <B><TT>DwField</TT></B> +object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwField</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwHeaders</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwField& <A NAME="op_eq">operator =</A> +(const DwField& aField) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aField</TT></B>. The parent node of the <B><TT>DwField</TT></B> object +is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwField</TT></B> objects. The parse +method creates or updates the broken-down representation from the string +representation. For <B><TT>DwField</TT></B> objects, the parse method parses +the string representation, sets the values of the field name string and the +field body string, and creates an instance of the appropriate subclass of +<B><TT>DwFieldBody</TT></B>. This member function also calls the +<B><TT>Parse()</TT></B> member function of its contained +<B><TT>DwFieldBody</TT></B> object. +<P> +You should call this member function after you set or modify the string +representation, and before you access the field name, the field body, or +the contained <B><TT>DwFieldBody</TT></B> object. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwField</TT></B> objects. The assemble +method creates or updates the string representation from the broken-down +representation. In more concrete terms, the assemble method builds the string +representation from the field name and the string representation of the contained +<B><TT>DwFieldBody</TT></B> object. This member function calls the +<B><TT>Assemble()</TT></B> member function of its contained +<B><TT>DwFieldBody</TT></B> object. +<P> +You should call this member function after you modify either the field name +or the contained <B><TT>DwFieldBody</TT></B> object, and before you retrieve +the string representation. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwField</TT></B> on the free store that has the same +value as this <B><TT>DwField</TT></B> object. The basic idea is that of a +virtual copy constructor. +<P> +<FONT COLOR="teal"><B> Dw<A NAME="FieldBody">FieldBody</A>* FieldBody() const +</B></FONT> +<P> +Returns the <B><TT>DwFieldBody</TT></B> object contained by this +<B><TT>DwField</TT></B> object. If there is no field body, +<B><TT>NULL</TT></B> will be returned. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="FieldNameStr">FieldNameStr</A>() const </B></FONT> +<P> +Returns the field name of this header field as a string. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="FieldBodyStr">FieldBodyStr</A>() const </B></FONT> +<P> +Returns the field body of this header field as a string. +<P> +<FONT COLOR="teal"><B> DwField* <A NAME="Next">Next</A>() const </B></FONT> +<P> +Returns the next <B><TT>DwField</TT></B> object following this +<B><TT>DwField</TT></B> object in the list contained in a +<B><TT>DwHeaders</TT></B>. Returns <B><TT>NULL</TT></B> if this object is +last in the list. +<P> +<FONT COLOR="teal"><B> void +<A NAME="SetFieldBody">SetFieldBody</A>(DwFieldBody* aFieldBody) </B></FONT> +<P> +Sets the <B><TT>DwFieldBody</TT></B> object contained by this object. +<P> +<FONT COLOR="teal"><B> void +<A NAME="SetFieldNameStr">SetFieldNameStr</A>(const DwString& aStr) +</B></FONT> +<P> +Sets the field name of this header field. +<P> +<FONT COLOR="teal"><B> void +<A NAME="SetFieldBodyStr">SetFieldBodyStr</A>(const DwString& aStr) +</B></FONT> +<P> +Sets the field body of this header field. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetNext">SetNext</A>(const DwField* +aField) </B></FONT> +<P> +This <I>advanced</I> function sets <B><TT>aField</TT></B> as the next field +following this field in the list of fields contained in the headers. Since +<B><TT>DwHeaders</TT></B> contains member functions for adding +<B><TT>DwField</TT></B> objects to its list, this function should be avoided +for most applications. +<P> +<FONT COLOR="teal"><B> static DwField* <A NAME="NewField">NewField</A>(const +DwString& aStr, DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwField</TT></B> object on the free store. If the static +data member <B><TT>sNewField</TT></B> is <B><TT>NULL</TT></B>, this member +function will create a new <B><TT>DwField</TT></B> and return it. Otherwise, +<B><TT>NewField()</TT></B> will call the user-supplied function pointed to +by <B><TT>sNewField</TT></B>, which is assumed to return an object from a +class derived from <B><TT>DwField</TT></B>, and return that object. +<P> +<FONT COLOR="teal"><B> static DwFieldBody* +<A NAME="CreateFieldBody">CreateFieldBody</A>(const DwString& aFieldName, +const DwString& aFieldBody, DwMessageComponent* aParent) </B></FONT> +<P> +The static member function <B><TT>CreateFieldBody()</TT></B> is called from +the <B><TT>Parse()</TT></B> member function and is responsible for creating +a <B><TT>DwFieldBody</TT></B> object for this particular field. A typical +scenario might go as follows: This member function examines the field name +for this field, finds that it contains "To", creates a +<B><TT>DwAddressList</TT></B> object to contain the field body, calls the +<B><TT>Parse()</TT></B> member function for the +<B><TT>DwAddressList</TT></B>, and sets the <B><TT>DwAddressList</TT></B> +object as this <B><TT>DwField</TT></B> object's +<B><TT>DwFieldBody</TT></B>. +<P> +If you want to override the behavior of +<B><TT>CreateFieldBody()</TT></B>, you can do so by setting the public data +member <B><TT>sCreateFieldBody</TT></B> to point to your own function. +<B><TT>CreateFieldBody()</TT></B> first checks to see if +<B><TT>sCreateFieldBody</TT></B> is <B><TT>NULL</TT></B>. If it is not, +<B><TT>CreateFieldBody()</TT></B> will assume that it points to a user-supplied +function and will call that function. If it is <B><TT>NULL</TT></B>, +<B><TT>CreateFieldBody()</TT></B> will call +<B><TT>_CreateFieldBody()</TT></B>, which actually creates the +<B><TT>DwFieldBody</TT></B> object. You may call +<B><TT>_CreateFieldBody()</TT></B> from your own function for fields you +do not wish to handle. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwField* +(*<A NAME="sNewField">sNewField</A>)(const DwString&, DwMessageComponent*) +</B></FONT> +<P> +If <B><TT>sNewField</TT></B> is not <B><TT>NULL</TT></B>, it is assumed to +point to a user-supplied function that returns an object from a class derived +from <B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> static DwFieldBody* +(*<A NAME="sCreateFieldBody">sCreateFieldBody</A>)(const DwString& +aFieldName, const DwString& aFieldBody, DwMessageComponent* aParent) +</B></FONT> +<P> +See <B><TT><A HREF="#CreateFieldBody">CreateFieldBody</A>()</TT></B>. +<H2> + <FONT COLOR="navy"> Protected Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> void +<A NAME="_SetFieldBody">_SetFieldBody</A>(DwFieldBody* aFieldBody) +</B></FONT> +<P> +Sets the <B><TT>DwFieldBody</TT></B> object contained by this object. This +function differs from <B><TT>SetFieldBody()</TT></B> in that it does not +set the is-modified flag. +<P> +</BODY></HTML> diff --git a/mimelib/doc/fieldbdy.html b/mimelib/doc/fieldbdy.html new file mode 100644 index 000000000..856fd5330 --- /dev/null +++ b/mimelib/doc/fieldbdy.html @@ -0,0 +1,144 @@ +<HTML> +<HEAD> + <TITLE> DwFieldBody Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwFieldBody -- Class representing a MIME header field body +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwFieldBody : public <A HREF="msgcmp.html">DwMessageComponent</A> { + + friend class DwField; + +public: + + <A HREF="fieldbdy.html#DwFieldBody">DwFieldBody</A>(); + <A HREF="fieldbdy.html#DwFieldBody">DwFieldBody</A>(const DwFieldBody& aFieldBody); + <A HREF="fieldbdy.html#DwFieldBody">DwFieldBody</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwFieldBody(); + const DwFieldBody& <A HREF="fieldbdy.html#op_eq">operator =</A> (const DwFieldBody& aFieldBody); + void <A HREF="fieldbdy.html#SetOffset">SetOffset</A>(int aOffset); + void <A HREF="fieldbdy.html#SetFolding">SetFolding</A>(DwBool aTrueOrFalse); + DwBool <A HREF="fieldbdy.html#IsFolding">IsFolding</A>() const; + +protected: + + int mLineOffset; + DwBool mDoFolding; + +public: + + virtual void <A HREF="fieldbdy.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="fieldbdy.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwFieldBody</TT></B> represents the field-body element in the BNF +grammar specified by RFC-822. It is an abstract base class that defines the +interface common to all structured field bodies. +<P> +In the tree (broken-down) representation of a message, a +<B><TT>DwFieldBody</TT></B> object may be either a leaf node, having a parent +but no child nodes, or an intermediate node, having a parent and one or more +child nodes. The parent node is the +<B><TT><A HREF="field.html">DwField</A></TT></B> object that contains it. +Child nodes, if present, depend on the particular subclass of +<B><TT>DwFieldBody</TT></B> that is instantiated. A +<B><TT>DwAddressList</TT></B> object, for example, has +<B><TT>DwAddress</TT></B> objects as its child nodes. +<P> +Since <B><TT>DwFieldBody</TT></B> is an abstract base class, you cannot create +instances of it directly. Normally, objects of classes derived from +<B><TT>DwFieldBody</TT></B> are obtained by calling convenience member functions +in the class <B><TT><A HREF="headers.html">DwHeaders</A></TT></B>. +<P> +Some MIME parsers are broken in that they do not handle the folding of some +fields properly. <B><TT>DwFieldBody</TT></B> folds its string representation +by default. You can disable folding, however, by calling the +<B><TT>SetFolding()</TT></B> member function. To determine if folding is +enabled, call <B><TT>IsFolding()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwFieldBody">DwFieldBody</A>() <BR> +DwFieldBody(const DwFieldBody& aFieldBody) <BR> +DwFieldBody(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwFieldBody</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aFieldBody</TT></B>. The parent of the new +<B><TT>DwFieldBody</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwFieldBody</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwFieldBody& <A NAME="op_eq">operator =</A> +(const DwFieldBody& aFieldBody) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aFieldBody</TT></B>. The parent node of the +<B><TT>DwFieldBody</TT></B> object is not changed. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetOffset">SetOffset</A>(int aOffset) +</B></FONT> +<P> +Sets the offset to <B><TT>aOffset</TT></B>. The offset is used when folding +lines. It indicates how much the first line should be offset to account for +the field name, colon, and initial white space. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetFolding">SetFolding</A>(DwBool +aTrueOrFalse) </B></FONT> +<P> +Enables (<B><TT>aTrueOrFalse = DwTrue</TT></B>) or disables +(<B><TT>aTrueOrFalse = DwFalse</TT></B>) the folding of fields. The default +is to fold fields. Unfortunately, some parsers are broke and do not handle +folded lines properly. This function allows a kludge to deal with these broken +parsers. +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="IsFolding">IsFolding</A>() const +</B></FONT> +<P> +Returns a boolean indicating if folding of fields is enabled. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<P> +</BODY></HTML> diff --git a/mimelib/doc/group.html b/mimelib/doc/group.html new file mode 100644 index 000000000..1d374d874 --- /dev/null +++ b/mimelib/doc/group.html @@ -0,0 +1,221 @@ +<HTML> +<HEAD> + <TITLE> DwGroup Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwGroup -- Class representing an RFC-822 address group +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwGroup : public <A HREF="address.html">DwAddress</A> { + +public: + + <A HREF="group.html#DwGroup">DwGroup</A>(); + <A HREF="group.html#DwGroup">DwGroup</A>(const DwGroup& aGroup); + <A HREF="group.html#DwGroup">DwGroup</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwGroup(); + const DwGroup& <A HREF="group.html#op_eq">operator =</A> (const DwGroup& aGroup); + virtual void <A HREF="group.html#Parse">Parse</A>(); + virtual void <A HREF="group.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="group.html#Clone">Clone</A>() const; + const DwString& <A HREF="group.html#GroupName">GroupName</A>() const; + const DwString& <A HREF="group.html#Phrase">Phrase</A>() const; + void <A HREF="group.html#SetGroupName">SetGroupName</A>(const DwString& aName); + void <A HREF="group.html#SetPhrase">SetPhrase</A>(const DwString& aPhrase); + DwMailboxList& <A HREF="group.html#MailboxList">MailboxList</A>() const; + static DwGroup* <A HREF="group.html#NewGroup">NewGroup</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwGroup* (*<A HREF="group.html#sNewGroup">sNewGroup</A>)(const DwString&, DwMessageComponent*); + +protected: + + DwMailboxList* <A HREF="group.html#mMailboxList">mMailboxList</A>; + +public: + + virtual void <A HREF="group.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="group.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwGroup</TT></B> represents a <I>group</I> as described in RFC-822. +A group contains a group name and a (possibly empty) list of +<I>mailboxes</I>. In MIME++, a <B><TT>DwGroup</TT></B> object contains a +string for the group name and a +<B><TT><A HREF="mboxlist.html">DwMailboxList</A></TT></B> object for the +list of mailboxes. +<P> +In the tree (broken-down) representation of message, a +<B><TT>DwGroup</TT></B> object may be only an intermediate node, having both +a parent and a single child node. Its parent node must be a +<B><TT><A HREF="field.html">DwField</A></TT></B> or a +<B><TT><A HREF="addrlist.html">DwAddressList</A></TT></B>. Its child is a +<B><TT>DwMailboxList</TT></B>. +<P> +A <B><TT>DwGroup</TT></B> is a +<B><TT><A HREF="address.html">DwAddress</A></TT></B>, and therefore it can +be included in a list of <B><TT>DwAddress</TT></B> objects. To get the next +<B><TT>DwAddress</TT></B> object in a list, use the inherited member function +<B><TT>DwAddress::Next()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwGroup">DwGroup</A>() <BR> +DwGroup(const DwGroup& aGroup) <BR> +DwGroup(const DwString& aStr, DwMessageComponent* aParent=0) </B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwGroup</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aGroup</TT></B>. The parent of the new <B><TT>DwGroup</TT></B> +object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwGroup</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B> or +<B><TT>DwAddressList</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwGroup& <A NAME="op_eq">operator =</A> +(const DwGroup& aGroup) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aGroup</TT></B>. The parent node of the <B><TT>DwGroup</TT></B> object +is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwGroup</TT></B> objects. The parse +method creates or updates the broken-down representation from the string +representation. For <B><TT>DwGroup</TT></B> objects, the parse method parses +the string representation to extract the group name and to create a +<B><TT>DwMailboxList</TT></B> object from the list of mailboxes. This member +function also calls the <B><TT>Parse()</TT></B> member function of the +<B><TT>DwMailboxList</TT></B> object it creates. +<P> +You should call this member function after you set or modify the string +representation, and before you access the group name or the mailbox list. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwGroup</TT></B> objects. The assemble +method creates or updates the string representation from the broken-down +representation. That is, the assemble method builds the string representation +from its group name and mailbox list. Before it builds the string representation, +this function calls the <B><TT>Assemble()</TT></B> member function of its +contained <B><TT>DwMailboxList</TT></B> object. +<P> +You should call this member function after you set or modify either the group +name or the contained <B><TT>DwMailboxList</TT></B> object, and before you +retrieve the string representation. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwGroup</TT></B> on the free store that has the same +value as this <B><TT>DwGroup</TT></B> object. The basic idea is that of a +virtual copy constructor. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="GroupName">GroupName</A>() const </B></FONT> +<P> +Returns the name of the group. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="Phrase">Phrase</A>() +const </B></FONT> +<P> +Returns the name of the phrase part of a group as described in RFC-822. The +phrase is the same as the group name. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetGroupName">SetGroupName</A>(const +DwString& aName) </B></FONT> +<P> +Sets the name of the group. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetPhrase">SetPhrase</A>(const +DwString& aPhrase) </B></FONT> +<P> +Sets the name of the phrase part of a group as described in RFC-822. The +phrase is the same as the group name. +<P> +<FONT COLOR="teal"><B> Dw<A NAME="MailboxList">MailboxList</A>& MailboxList() +const </B></FONT> +<P> +Provides access to the list of mailboxes that is part of a group as described +in RFC-822. +<P> +<FONT COLOR="teal"><B> static DwGroup* <A NAME="NewGroup">NewGroup</A>(const +DwString& aStr, DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwGroup</TT></B> object on the free store. If the static +data member <B><TT>sNewGroup</TT></B> is <B><TT>NULL</TT></B>, this member +function will create a new <B><TT>DwGroup</TT></B> and return it. Otherwise, +<B><TT>NewGroup()</TT></B> will call the user-supplied function pointed to +by <B><TT>sNewGroup</TT></B>, which is assumed to return an object from a +class derived from <B><TT>DwGroup</TT></B>, and return that object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwGroup* +(*<A NAME="sNewGroup">sNewGroup</A>)(const DwString&, DwMessageComponent*) +</B></FONT> +<P> +If <B><TT>sNewGroup</TT></B> is not <B><TT>NULL</TT></B>, it is assumed to +point to a user-supplied function that returns an object from a class derived +from <B><TT>DwGroup</TT></B>. +<H2> + <FONT COLOR="navy"> Protected Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> DwMailboxList* <A NAME="mMailboxList">mMailboxList</A> +</B></FONT> +<P> +Points to the <B><TT>DwMailboxList</TT></B> object. +<P> +</BODY></HTML> diff --git a/mimelib/doc/headers.html b/mimelib/doc/headers.html new file mode 100644 index 000000000..8bf94ad98 --- /dev/null +++ b/mimelib/doc/headers.html @@ -0,0 +1,512 @@ +<HTML> +<HEAD> + <TITLE> DwHeaders Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwHeaders -- Class representing the collection of header fields in a message +or body part +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE> +class DW_EXPORT DwHeaders : public <A HREF="msgcmp.html">DwMessageComponent</A> { + +public: + + <A HREF="headers.html#DwHeaders">DwHeaders</A>(); + <A HREF="headers.html#DwHeaders">DwHeaders</A>(const DwHeaders& aHeaders); + <A HREF="headers.html#DwHeaders">DwHeaders</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwHeaders(); + const DwHeaders& <A HREF="headers.html#op_eq">operator =</A> (const DwHeaders& aHeaders); + virtual void <A HREF="headers.html#Parse">Parse</A>(); + virtual void <A HREF="headers.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="headers.html#Clone">Clone</A>() const; + DwBool <A HREF="headers.html#HasBcc">HasBcc</A>() const; + DwBool <A HREF="headers.html#HasCc">HasCc</A>() const; + DwBool <A HREF="headers.html#HasComments">HasComments</A>() const; + DwBool <A HREF="headers.html#HasDate">HasDate</A>() const; + DwBool <A HREF="headers.html#HasEncrypted">HasEncrypted</A>() const; + DwBool <A HREF="headers.html#HasFrom">HasFrom</A>() const; + DwBool <A HREF="headers.html#HasInReplyTo">HasInReplyTo</A>() const; + DwBool <A HREF="headers.html#HasKeywords">HasKeywords</A>() const; + DwBool <A HREF="headers.html#HasMessageId">HasMessageId</A>() const; + DwBool <A HREF="headers.html#HasReceived">HasReceived</A>() const; + DwBool <A HREF="headers.html#HasReferences">HasReferences</A>() const; + DwBool <A HREF="headers.html#HasReplyTo">HasReplyTo</A>() const; + DwBool <A HREF="headers.html#HasResentBcc">HasResentBcc</A>() const; + DwBool <A HREF="headers.html#HasResentCc">HasResentCc</A>() const; + DwBool <A HREF="headers.html#HasResentDate">HasResentDate</A>() const; + DwBool <A HREF="headers.html#HasResentFrom">HasResentFrom</A>() const; + DwBool <A HREF="headers.html#HasResentMessageId">HasResentMessageId</A>() const; + DwBool <A HREF="headers.html#HasResentReplyTo">HasResentReplyTo</A>() const; + DwBool <A HREF="headers.html#HasResentSender">HasResentSender</A>() const; + DwBool <A HREF="headers.html#HasResentTo">HasResentTo</A>() const; + DwBool <A HREF="headers.html#HasReturnPath">HasReturnPath</A>() const; + DwBool <A HREF="headers.html#HasSender">HasSender</A>() const; + DwBool <A HREF="headers.html#HasSubject">HasSubject</A>() const; + DwBool <A HREF="headers.html#HasTo">HasTo</A>() const; + DwBool <A HREF="headers.html#HasApproved">HasApproved</A>() const; + DwBool <A HREF="headers.html#HasControl">HasControl</A>() const; + DwBool <A HREF="headers.html#HasDistribution">HasDistribution</A>() const; + DwBool <A HREF="headers.html#HasExpires">HasExpires</A>() const; + DwBool <A HREF="headers.html#HasFollowupTo">HasFollowupTo</A>() const; + DwBool <A HREF="headers.html#HasLines">HasLines</A>() const; + DwBool <A HREF="headers.html#HasNewsgroups">HasNewsgroups</A>() const; + DwBool <A HREF="headers.html#HasOrganization">HasOrganization</A>() const; + DwBool <A HREF="headers.html#HasPath">HasPath</A>() const; + DwBool <A HREF="headers.html#HasSummary">HasSummary</A>() const; + DwBool <A HREF="headers.html#HasXref">HasXref</A>() const; + DwBool <A HREF="headers.html#HasContentDescription">HasContentDescription</A>() const; + DwBool <A HREF="headers.html#HasContentId">HasContentId</A>() const; + DwBool <A HREF="headers.html#HasContentTransferEncoding">HasContentTransferEncoding</A>() const; + DwBool <A HREF="headers.html#HasCte">HasCte</A>() const; + DwBool <A HREF="headers.html#HasContentType">HasContentType</A>() const; + DwBool <A HREF="headers.html#HasMimeVersion">HasMimeVersion</A>() const; + DwBool <A HREF="headers.html#HasContentDisposition">HasContentDisposition</A>() const; + DwBool <A HREF="headers.html#HasField">HasField</A>(const char* aFieldName) const; + DwBool <A HREF="headers.html#HasField">HasField</A>(const DwString& aFieldName) const; + DwAddressList& <A HREF="headers.html#Bcc">Bcc</A>(); + DwAddressList& <A HREF="headers.html#Cc">Cc</A>(); + DwText& <A HREF="headers.html#Comments">Comments</A>(); + DwDateTime& <A HREF="headers.html#Date">Date</A>(); + DwText& <A HREF="headers.html#Encrypted">Encrypted</A>(); + DwMailboxList& <A HREF="headers.html#From">From</A>(); + DwText& <A HREF="headers.html#InReplyTo">InReplyTo</A>(); + DwText& <A HREF="headers.html#Keywords">Keywords</A>(); + DwMsgId& <A HREF="headers.html#MessageId">MessageId</A>(); + DwText& <A HREF="headers.html#Received">Received</A>(); + DwText& <A HREF="headers.html#References">References</A>(); + DwAddressList& <A HREF="headers.html#ReplyTo">ReplyTo</A>(); + DwAddressList& <A HREF="headers.html#ResentBcc">ResentBcc</A>(); + DwAddressList& <A HREF="headers.html#ResentCc">ResentCc</A>(); + DwDateTime& <A HREF="headers.html#ResentDate">ResentDate</A>(); + DwMailboxList& <A HREF="headers.html#ResentFrom">ResentFrom</A>(); + DwMsgId& <A HREF="headers.html#ResentMessageId">ResentMessageId</A>(); + DwAddressList& <A HREF="headers.html#ResentReplyTo">ResentReplyTo</A>(); + DwMailbox& <A HREF="headers.html#ResentSender">ResentSender</A>(); + DwAddressList& <A HREF="headers.html#ResentTo">ResentTo</A>(); + DwAddress& <A HREF="headers.html#ReturnPath">ReturnPath</A>(); + DwMailbox& <A HREF="headers.html#Sender">Sender</A>(); + DwText& <A HREF="headers.html#Subject">Subject</A>(); + DwAddressList& <A HREF="headers.html#To">To</A>(); + DwText& <A HREF="headers.html#Approved">Approved</A>(); + DwText& <A HREF="headers.html#Control">Control</A>(); + DwText& <A HREF="headers.html#Distribution">Distribution</A>(); + DwText& <A HREF="headers.html#Expires">Expires</A>(); + DwText& <A HREF="headers.html#FollowupTo">FollowupTo</A>(); + DwText& <A HREF="headers.html#Lines">Lines</A>(); + DwText& <A HREF="headers.html#Newsgroups">Newsgroups</A>(); + DwText& <A HREF="headers.html#Organization">Organization</A>(); + DwText& <A HREF="headers.html#Path">Path</A>(); + DwText& <A HREF="headers.html#Summary">Summary</A>(); + DwText& <A HREF="headers.html#Xref">Xref</A>(); + DwText& <A HREF="headers.html#ContentDescription">ContentDescription</A>(); + DwMsgId& <A HREF="headers.html#ContentId">ContentId</A>(); + DwMechanism& <A HREF="headers.html#ContentTransferEncoding">ContentTransferEncoding</A>(); + DwMechanism& <A HREF="headers.html#Cte">Cte</A>(); + DwMediaType& <A HREF="headers.html#ContentType">ContentType</A>(); + DwText& <A HREF="headers.html#MimeVersion">MimeVersion</A>(); + DwDispositionType& <A HREF="headers.html#ContentDisposition">ContentDisposition</A>(); + DwFieldBody& <A HREF="headers.html#FieldBody">FieldBody</A>(const DwString& aFieldName); + int <A HREF="headers.html#NumFields">NumFields</A>() const; + DwField* <A HREF="headers.html#FirstField">FirstField</A>() const; + DwField* <A HREF="headers.html#FindField">FindField</A>(const char* aFieldName) const; + DwField* <A HREF="headers.html#FindField">FindField</A>(const DwString& aFieldName) const; + void <A HREF="headers.html#AddOrReplaceField">AddOrReplaceField</A>(DwField* aField); + void <A HREF="headers.html#AddField">AddField</A>(DwField* aField); + void <A HREF="headers.html#AddFieldAt">AddFieldAt</A>(int aPos, DwField* aField); + void <A HREF="headers.html#RemoveField">RemoveField</A>(DwField* aField); + void <A HREF="headers.html#DeleteAllFields">DeleteAllFields</A>(); + static DwHeaders* <A HREF="headers.html#NewHeaders">NewHeaders</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwHeaders* (*<A HREF="headers.html#sNewHeaders">sNewHeaders</A>)(const DwString&, DwMessageComponent*); + +protected: + + void _AddField(DwField* aField); + DwField* mFirstField; + +protected: + + static const char* const sClassName; + void CopyFields(DwField* aFirst); + +public: + + virtual void <A HREF="headers.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="headers.html#CheckInvariants">CheckInvariants</A>() const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwHeaders</TT></B> represents the collection of <I>header fields</I> +(often called just <I>headers</I>) in an <I>entity</I> (either a message +or body part), as described in RFC-822 and RFC-2045. A +<B><TT>DwHeaders</TT></B> object manages a list of +<A HREF="field.html"><B><TT>DwField</TT></B> </A>objects, which represent +the individual header fields. +<P> +In the tree (broken-down) representation of a message, a +<B><TT>DwHeaders</TT></B> object is an intermediate node, having both a parent +node and several child nodes. The parent node is the +<B><TT><A HREF="entity.html">DwEntity</A></TT></B> object that contains it. +The child nodes are the <B><TT>DwField</TT></B> objects in the list it manages. +(See the man page for +<B><TT><A HREF="msgcmp.html">DwMessageComponent</A></TT></B> for a discussion +of the tree representation of a message.) +<P> +Normally, you do not create a <B><TT>DwHeaders</TT></B> object directly, +but you access it through the <B><TT>Headers()</TT></B> member function of +<B><TT>DwEntity</TT></B>, which creates the <B><TT>DwHeaders</TT></B> object +for you. +<P> +While <B><TT>DwHeaders</TT></B> has public member functions for managing +the list of <B><TT>DwField</TT></B> objects it contains, you will normally +use convenience functions to access the field bodies of the header fields +directly. You can access the field body for a specific well-known header +field by using the member function +<B><TT><Field><Field>()</TT></B>, where <B><TT><Field></TT></B> +<B><TT><Field></TT></B> is the field name of the header field with +hyphens removed and the first word following a hyphen capitalized. For example, +to access the field body for the "MIME-version" header field, use +<B><TT>MimeVersion()</TT></B>. The member function +<B><TT><Field><Field>()</TT></B> will create a header field with field +name <B><TT><Field></TT></B> <B><TT><Field></TT></B> if such a header +field does not already exist. You can check for the existence of a particular +well-known header field by using the member function +<B><TT>Has<Field><Field>()</TT></B>. For example, to check for the +existence of the MIME-version header field, use +<B><TT>HasMimeVersion()</TT></B>. Well-known header fields are those documented +in RFC-822 (standard email), RFC-1036 (USENET messages), RFC-2045 (MIME +messages), and possibly other RFCs. +<P> +In the case of an extension field or user-defined field, you can access the +field body of the header field by calling the member function +<B><TT>FieldBody()</TT></B> with the field name as its argument. If the extension +field or user-defined field does not exist, <B><TT>FieldBody()</TT></B> will +create it. You can check for the existence of an extension field or user-defined +field by using the member function <B><TT>HasField()</TT></B> with the field +name as its argument. +<P> +<B><TT>DwHeaders</TT></B> has several other member functions provided for +the sake of completeness that are not required for most applications. These +functions are documented below. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwHeaders">DwHeaders</A>() <BR> +DwHeaders(const DwHeaders& aHeaders) <BR> +DwHeaders(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwHeaders</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aHeaders</TT></B>. The parent of the new +<B><TT>DwHeaders</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwHeaders</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwEntity</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwHeaders& <A NAME="op_eq">operator =</A> +(const DwHeaders& aHeaders) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aHeaders</TT></B>. The parent node of the +<B><TT>DwHeaders</TT></B> object is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwHeaders</TT></B> objects. The parse +method creates or updates the broken-down representation from the string +representation. For <B><TT>DwHeaders</TT></B> objects, +<B><TT>DwHeaders::Parse()</TT></B> parses the string representation to create +a list of <B><TT>DwField</TT></B> objects. This member function also calls +the <B><TT>Parse()</TT></B> member function of each +<B><TT>DwField</TT></B> object in its list. +<P> +You should call this member function after you set or modify the string +representation, and before you access any of the header fields. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwHeaders</TT></B> objects. The assemble +method creates or updates the string representation from the broken-down +representation. That is, the assemble method builds the string representation +from its list of <B><TT>DwField</TT></B> objects. Before it builds the string +representation, this function first calls the <B><TT>Assemble()</TT></B> +member function of each <B><TT>DwField</TT></B> object in its list. +<P> +You should call this member function after you set or modify any of the header +fields, and before you retrieve the string representation. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwHeaders</TT></B> on the free store that has the same +value as this <B><TT>DwHeaders</TT></B> object. The basic idea is that of +a virtual copy constructor. +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="HasBcc">HasBcc</A>() const<BR> +DwBool <A NAME="HasCc">HasCc</A>() const<BR> +DwBool <A NAME="HasComments">HasComments</A>() const<BR> +DwBool <A NAME="HasDate">HasDate</A>() const<BR> +DwBool <A NAME="HasEncrypted">HasEncrypted</A>() const<BR> +DwBool <A NAME="HasFrom">HasFrom</A>() const<BR> +DwBool <A NAME="HasInReplyTo">HasInReplyTo</A>() const<BR> +DwBool <A NAME="HasKeywords">HasKeywords</A>() const<BR> +DwBool <A NAME="HasMessageId">HasMessageId</A>() const<BR> +DwBool <A NAME="HasReceived">HasReceived</A>() const<BR> +DwBool <A NAME="HasReferences">HasReferences</A>() const<BR> +DwBool <A NAME="HasReplyTo">HasReplyTo</A>() const<BR> +DwBool <A NAME="HasResentBcc">HasResentBcc</A>() const<BR> +DwBool <A NAME="HasResentCc">HasResentCc</A>() const<BR> +DwBool <A NAME="HasResentDate">HasResentDate</A>() const<BR> +DwBool <A NAME="HasResentFrom">HasResentFrom</A>() const<BR> +DwBool <A NAME="HasResentMessageId">HasResentMessageId</A>() const<BR> +DwBool <A NAME="HasResentReplyTo">HasResentReplyTo</A>() const<BR> +DwBool <A NAME="HasResentSender">HasResentSender</A>() const<BR> +DwBool <A NAME="HasResentTo">HasResentTo</A>() const<BR> +DwBool <A NAME="HasReturnPath">HasReturnPath</A>() const<BR> +DwBool <A NAME="HasSender">HasSender</A>() const<BR> +DwBool <A NAME="HasSubject">HasSubject</A>() const<BR> +DwBool <A NAME="HasTo">HasTo</A>() const<BR> +DwBool <A NAME="HasApproved">HasApproved</A>() const<BR> +DwBool <A NAME="HasControl">HasControl</A>() const<BR> +DwBool <A NAME="HasDistribution">HasDistribution</A>() const<BR> +DwBool <A NAME="HasExpires">HasExpires</A>() const<BR> +DwBool <A NAME="HasFollowupTo">HasFollowupTo</A>() const<BR> +DwBool <A NAME="HasLines">HasLines</A>() const<BR> +DwBool <A NAME="HasNewsgroups">HasNewsgroups</A>() const<BR> +DwBool <A NAME="HasOrganization">HasOrganization</A>() const<BR> +DwBool <A NAME="HasPath">HasPath</A>() const<BR> +DwBool <A NAME="HasSummary">HasSummary</A>() const<BR> +DwBool <A NAME="HasXref">HasXref</A>() const<BR> +DwBool <A NAME="HasContentDescription">HasContentDescription</A>() const<BR> +DwBool <A NAME="HasContentId">HasContentId</A>() const<BR> +DwBool <A NAME="HasContentTransferEncoding">HasContentTransferEncoding</A>() +const<BR> +DwBool <A NAME="HasCte">HasCte</A>() const<BR> +DwBool <A NAME="HasContentType">HasContentType</A>() const<BR> +DwBool <A NAME="HasMimeVersion">HasMimeVersion</A>() const<BR> +DwBool <A NAME="HasContentDisposition">HasContentDisposition</A>() const +</B></FONT> +<P> +Each member function in this group returns a boolean value indicating whether +a particular well-known header field is present in this object's collection +of header fields. +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="HasField">HasField</A>(const char* +aFieldName) const <BR> +DwBool HasField(const DwString& aFieldName) const </B></FONT> +<P> +Returns true if the header field specified by <B><TT>aFieldName</TT></B> +is present in this object's collection of header fields. These member functions +are used for extension fields or user-defined fields. +<P> +<FONT COLOR="teal"><B> DwAddressList& <A NAME="Bcc">Bcc</A>()<BR> +DwAddressList& <A NAME="Cc">Cc</A>()<BR> +DwText& <A NAME="Comments">Comments</A>()<BR> +Dw<A NAME="Date">Date</A>Time& Date()<BR> +DwText& <A NAME="Encrypted">Encrypted</A>()<BR> +DwMailboxList& <A NAME="From">From</A>()<BR> +DwText& <A NAME="InReplyTo">InReplyTo</A>()<BR> +DwText& <A NAME="Keywords">Keywords</A>()<BR> +DwMsgId& <A NAME="MessageId">MessageId</A>()<BR> +DwText& <A NAME="Received">Received</A>()<BR> +DwText& <A NAME="References">References</A>()<BR> +DwAddressList& <A NAME="ReplyTo">ReplyTo</A>()<BR> +DwAddressList& <A NAME="ResentBcc">ResentBcc</A>()<BR> +DwAddressList& <A NAME="ResentCc">ResentCc</A>()<BR> +DwDateTime& <A NAME="ResentDate">ResentDate</A>()<BR> +DwMailboxList& <A NAME="ResentFrom">ResentFrom</A>()<BR> +DwMsgId& <A NAME="ResentMessageId">ResentMessageId</A>()<BR> +DwAddressList& <A NAME="ResentReplyTo">ResentReplyTo</A>()<BR> +DwMailbox& <A NAME="ResentSender">ResentSender</A>()<BR> +DwAddressList& <A NAME="ResentTo">ResentTo</A>()<BR> +DwAddress& <A NAME="ReturnPath">ReturnPath</A>()<BR> +DwMailbox& <A NAME="Sender">Sender</A>()<BR> +DwText& <A NAME="Subject">Subject</A>()<BR> +DwAddressList& <A NAME="To">To</A>()<BR> +DwText& <A NAME="Approved">Approved</A>()<BR> +DwText& <A NAME="Control">Control</A>()<BR> +DwText& <A NAME="Distribution">Distribution</A>()<BR> +DwText& <A NAME="Expires">Expires</A>()<BR> +DwText& <A NAME="FollowupTo">FollowupTo</A>()<BR> +DwText& <A NAME="Lines">Lines</A>()<BR> +DwText& <A NAME="Newsgroups">Newsgroups</A>()<BR> +DwText& <A NAME="Organization">Organization</A>()<BR> +DwText& <A NAME="Path">Path</A>()<BR> +DwText& <A NAME="Summary">Summary</A>()<BR> +DwText& <A NAME="Xref">Xref</A>()<BR> +DwText& <A NAME="ContentDescription">ContentDescription</A>()<BR> +DwMsgId& <A NAME="ContentId">ContentId</A>()<BR> +DwMechanism& +<A NAME="ContentTransferEncoding">ContentTransferEncoding</A>()<BR> +DwMechanism& <A NAME="Cte">Cte</A>()<BR> +DwMediaType& <A NAME="ContentType">ContentType</A>()<BR> +DwText& <A NAME="MimeVersion">MimeVersion</A>()<BR> +DwDispositionType& <A NAME="ContentDisposition">ContentDisposition</A>() +</B></FONT> +<P> +Each member function in this group returns a reference to a +<B><TT>DwFieldBody</TT></B> object for a particular header field. If the +header field does not already exist, it is created. Use the corresponding +<B><TT>Has<Field><Field>()</TT></B> function to test if the header +field already exists without creating it. +<P> +<FONT COLOR="teal"><B> Dw<A NAME="FieldBody">FieldBody</A>& FieldBody(const +DwString& aFieldName) </B></FONT> +<P> +Returns a reference to the <B><TT>DwFieldBody</TT></B> object for a particular +header field with field name <B><TT>aFieldName</TT></B>. If the header field +does not already exist, it is created. Use <B><TT>HasField()</TT></B> to +test if the header field already exists without creating it. This member +function allows access to extension fields or user-defined fields. +<P> +<FONT COLOR="teal"><B> int <A NAME="NumFields">NumFields</A>() const +</B></FONT> +<P> +Returns the number of <B><TT>DwField</TT></B> objects contained by this +<B><TT>DwHeaders</TT></B> object. +<P> +<FONT COLOR="teal"><B> DwField* <A NAME="FirstField">FirstField</A>() const +</B></FONT> +<P> +Returns a pointer to the first <B><TT>DwField</TT></B> object contained by +this <B><TT>DwHeaders</TT></B> object. Use this member function to begin +an iteration over the entire list of <B><TT>DwField</TT></B> objects. Continue +the iteration by calling <B><TT>DwField::Next()</TT></B> on each +<B><TT>DwField</TT></B> object. +<P> +<FONT COLOR="teal"><B> DwField* <A NAME="FindField">FindField</A>(const char* +aFieldName) const <BR> +DwField* FindField(const DwString& aFieldName) const </B></FONT> +<P> +Searches for a header field by its field name. Returns +<B><TT>NULL</TT></B> if the field is not found. This is an <I>advanced</I> +function: most applications should use the +<B><TT><Field><Field>()</TT></B> or +<B><TT>Has<Field>()</TT></B> family of functions. +<P> +<FONT COLOR="teal"><B> void +<A NAME="AddOrReplaceField">AddOrReplaceField</A>(DwField* aField) +</B></FONT> +<P> +Adds a <B><TT>DwField</TT></B> object to the list. If a header field with +the same field name already exists, it is replaced by the new header field. +<P> +<B><TT>DwHeaders</TT></B> takes responsibility for deleting the added +<B><TT>DwField</TT></B> object. +<P> +This is an advanced function. Consider using the member functions +<B><TT><Field><Field>()</TT></B> (e.g. <B><TT>To()</TT></B>, +<B><TT>ContentType()</TT></B>, and so on) and <B><TT>FieldBody()</TT></B> +to add header fields. +<P> +<FONT COLOR="teal"><B> void <A NAME="AddField">AddField</A>(DwField* aField) +</B></FONT> +<P> +Adds a <B><TT>DwField</TT></B> object to the list. If a header field with +the same field name already exists, it is <I>not</I> replaced; thus, duplicate +header fields may occur when using this member function. (This is what you +want for some header fields, such as the "Received" header field). +<P> +<B><TT>DwHeaders</TT></B> takes responsibility for deleting the added +<B><TT>DwField</TT></B> object. +<P> +This is an advanced function. Consider using the member functions +<B><TT><Field><Field>()</TT></B> (e.g. <B><TT>To()</TT></B>, +<B><TT>ContentType()</TT></B>, and so on) and <B><TT>FieldBody()</TT></B> +for adding header fields. +<P> +<FONT COLOR="teal"><B> void <A NAME="AddFieldAt">AddFieldAt</A>(int aPos, +DwField* aField) </B></FONT> +<P> +This member functions follows the semantics of <B><TT>AddField()</TT></B> +except that <B><TT>aPos</TT></B> specifies a position for adding the field. +A position of 1 indicates the beginning of the list. A position of 0 indicates +the end of the list. +<P> +This is an advanced function. Consider using the member functions +<B><TT><Field><Field>()</TT></B> (e.g. <B><TT>To()</TT></B>, +<B><TT>ContentType()</TT></B>, and so on) and <B><TT>FieldBody()</TT></B> +for adding header fields. +<P> +<FONT COLOR="teal"><B> void <A NAME="RemoveField">RemoveField</A>(DwField* +aField) </B></FONT> +<P> +Removes the <B><TT>DwField</TT></B> object from the list. The +<B><TT>DwField</TT></B> object is not deleted. +<P> +<FONT COLOR="teal"><B> void <A NAME="DeleteAllFields">DeleteAllFields</A>() +</B></FONT> +<P> +Removes all <B><TT>DwField</TT></B> objects from the list and deletes them. +<P> +<FONT COLOR="teal"><B> static DwHeaders* +<A NAME="NewHeaders">NewHeaders</A>(const DwString& aStr, DwMessageComponent* +aParent) </B></FONT> +<P> +Creates a new <B><TT>DwHeaders</TT></B> object on the free store. If the +static data member <B><TT>sNewHeaders</TT></B> is <B><TT>NULL</TT></B>, this +member function will create a new <B><TT>DwHeaders</TT></B> and return it. +Otherwise, <B><TT>NewHeaders()</TT></B> will call the user-supplied function +pointed to by <B><TT>sNewHeaders</TT></B>, which is assumed to return an +object from a class derived from <B><TT>DwHeaders</TT></B>, and return that +object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<P> +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwHeaders* +(*<A NAME="sNewHeaders">sNewHeaders</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewHeaders</TT></B> is not <B><TT>NULL</TT></B>, it is assumed +to point to a user-supplied function that returns an object from a class +derived from <B><TT>DwHeaders</TT></B>. +<P> +</BODY></HTML> diff --git a/mimelib/doc/mailbox.html b/mimelib/doc/mailbox.html new file mode 100644 index 000000000..492070ccb --- /dev/null +++ b/mimelib/doc/mailbox.html @@ -0,0 +1,238 @@ +<HTML> +<HEAD> + <TITLE> DwMailbox Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwMailbox -- Class representing an RFC-822 mailbox +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwMailbox : public <A HREF="address.html">DwAddress</A> { + + friend class DwMailboxList; + +public: + + <A HREF="mailbox.html#DwMailbox">DwMailbox</A>(); + <A HREF="mailbox.html#DwMailbox">DwMailbox</A>(const DwMailbox& aMailbox); + <A HREF="mailbox.html#DwMailbox">DwMailbox</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwMailbox(); + const DwMailbox& <A HREF="mailbox.html#op_eq">operator =</A> (const DwMailbox& aMailbox); + virtual void <A HREF="mailbox.html#Parse">Parse</A>(); + virtual void <A HREF="mailbox.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="mailbox.html#Clone">Clone</A>() const; + const DwString& <A HREF="mailbox.html#FullName">FullName</A>() const; + void <A HREF="mailbox.html#SetFullName">SetFullName</A>(const DwString& aFullName); + const DwString& <A HREF="mailbox.html#Route">Route</A>() const; + void <A HREF="mailbox.html#SetRoute">SetRoute</A>(const DwString& aRoute); + const DwString& <A HREF="mailbox.html#LocalPart">LocalPart</A>() const; + void <A HREF="mailbox.html#SetLocalPart">SetLocalPart</A>(const DwString& aLocalPart); + const DwString& <A HREF="mailbox.html#Domain">Domain</A>() const; + void <A HREF="mailbox.html#SetDomain">SetDomain</A>(const DwString& aDomain); + static DwMailbox* <A HREF="mailbox.html#NewMailbox">NewMailbox</A>(const DwString& aStr, DwMessageComponent* + aParent); + static DwMailbox* (*<A HREF="mailbox.html#sNewMailbox">sNewMailbox</A>)(const DwString&, DwMessageComponent*); + +public: + + virtual void <A HREF="mailbox.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="mailbox.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +RFC-822 defines a <I>mailbox</I> as an entity that can be the recipient of +a message. A mailbox is more specific than an <I>address</I>, which may be +either a mailbox or a <I>group</I>. An RFC-822 mailbox contains a full name, +a <I>local-part</I>, an optional <I>route</I>, and a <I>domain</I>. For example, +in the mailbox +<P> +Joe Schmoe <jschmoe@aol.co> +<P> +"Joe Schmoe" is the full name, "jschmoe" is the local-part, and "aol.com" +is the domain. The optional route is rarely seen in current usage, and is +deprecated according to RFC-1123. +<P> +In MIME++, an RFC-822 mailbox is represented by a +<B><TT>DwMailbox</TT></B> object. <B><TT>DwMailbox</TT></B> is a subclass +of <B><TT><A HREF="address.html">DwAddress</A></TT></B>, which reflects the +fact that a mailbox is also an address. A <B><TT>DwMailbox</TT></B> contains +strings representing the full name, local-part, route, and domain of a mailbox. +<P> +In the tree (broken-down) representation of message, a +<B><TT>DwMailbox</TT></B> object may be only a leaf node, having a parent +but no child nodes. Its parent node must be a +<B><TT><A HREF="field.html">DwField</A></TT></B>, a +<B><TT><A HREF="addrlist.html">DwAddressList</A></TT></B>, or a +<B><TT><A HREF="mboxlist.html">DwMailboxList</A></TT></B> object. +<P> +<B><TT>DwMailbox</TT></B> has member functions for getting or setting the +strings it contains. +<P> +<B><TT>DwMailbox</TT></B> object can be included in a list of +<B><TT>DwMailbox</TT></B> objects. To get the next +<B><TT>DwMailbox</TT></B> object in a list, use the inherited member function +<B><TT>DwAddress::Next()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwMailbox">DwMailbox</A>() <BR> +DwMailbox(const DwMailbox& aMailbox) <BR> +DwMailbox(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwMailbox</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aMailbox</TT></B>. The parent of the new +<B><TT>DwMailbox</TT></B> is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwMailbox</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwMailbox& <A NAME="op_eq">operator =</A> +(const DwMailbox& aMailbox) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aMailbox</TT></B>. The parent node of the +<B><TT>DwMailbox</TT></B> object is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwMailbox</TT></B> objects. The parse +method creates or updates the broken-down representation from the string +representation. For <B><TT>DwMailbox</TT></B> objects, the parse method parses +the string representation into the substrings for the full name, local-part, +route, and domain. +<P> +You should call this member function after you set or modify the string +representation, and before you retrieve the full name, local-part, route, +or domain. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwMailbox</TT></B> objects. The assemble +method creates or updates the string representation from the broken-down +representation. For <B><TT>DwMailbox</TT></B> objects, the assemble method +builds the string representation from the full name, local-part, route, and +domain strings. +<P> +You should call this member function after you modify the full name, local-part, +route, or domain, and before you retrieve the string representation. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwMailbox</TT></B> on the free store that has the same +value as this <B><TT>DwMailbox</TT></B> object. The basic idea is that of +a virtual copy constructor. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="FullName">FullName</A>() +const </B></FONT> +<P> +Returns the full name for this <B><TT>DwMailbox</TT></B> object. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetFullName">SetFullName</A>(const +DwString& aFullName) </B></FONT> +<P> +Sets the full name for this <B><TT>DwMailbox</TT></B> object. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="Route">Route</A>() const +</B></FONT> +<P> +Returns the route for this <B><TT>DwMailbox</TT></B> object. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetRoute">SetRoute</A>(const DwString& +aRoute) </B></FONT> +<P> +Sets the route for this <B><TT>DwMailbox</TT></B> object. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="LocalPart">LocalPart</A>() const </B></FONT> +<P> +Returns the local-part for this <B><TT>DwMailbox</TT></B> object. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetLocalPart">SetLocalPart</A>(const +DwString& aLocalPart) </B></FONT> +<P> +Sets the local-part for this <B><TT>DwMailbox</TT></B> object. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="Domain">Domain</A>() +const </B></FONT> +<P> +Returns the domain for this <B><TT>DwMailbox</TT></B> object. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetDomain">SetDomain</A>(const +DwString& aDomain) </B></FONT> +<P> +Sets the domain for this <B><TT>DwMailbox</TT></B> object. +<P> +<FONT COLOR="teal"><B> static DwMailbox* +<A NAME="NewMailbox">NewMailbox</A>(const DwString& aStr, DwMessageComponent* +aParent) </B></FONT> +<P> +Creates a new <B><TT>DwMailbox</TT></B> object on the free store. If the +static data member <B><TT>sNewMailbox</TT></B> is <B><TT>NULL</TT></B>, this +member function will create a new <B><TT>DwMailbox</TT></B> and return it. +Otherwise, <B><TT>NewMailbox()</TT></B> will call the user-supplied function +pointed to by <B><TT>sNewMailbox</TT></B>, which is assumed to return an +object from a class derived from <B><TT>DwMailbox</TT></B>, and return that +object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwMailbox* +(*<A NAME="sNewMailbox">sNewMailbox</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewMailbox</TT></B> is not <B><TT>NULL</TT></B>, it is assumed +to point to a user-supplied function that returns an object from a class +derived from <B><TT>DwMailbox</TT></B>. +<P> +</BODY></HTML> diff --git a/mimelib/doc/mboxlist.html b/mimelib/doc/mboxlist.html new file mode 100644 index 000000000..2bae2b4e3 --- /dev/null +++ b/mimelib/doc/mboxlist.html @@ -0,0 +1,232 @@ +<HTML> +<HEAD> + <TITLE> DwMailboxList Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwMailboxList -- Class representing a list of RFC-822 mailboxes +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwMailboxList : public <A HREF="fieldbdy.html">DwFieldBody</A> { + +public: + + <A HREF="mboxlist.html#DwMailboxList">DwMailboxList</A>(); + <A HREF="mboxlist.html#DwMailboxList">DwMailboxList</A>(const DwMailboxList& aList); + <A HREF="mboxlist.html#DwMailboxList">DwMailboxList</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwMailboxList(); + const DwMailboxList& <A HREF="mboxlist.html#op_eq">operator =</A> (const DwMailboxList& aList); + virtual void <A HREF="mboxlist.html#Parse">Parse</A>(); + virtual void <A HREF="mboxlist.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="mboxlist.html#Clone">Clone</A>() const; + DwMailbox* <A HREF="mboxlist.html#FirstMailbox">FirstMailbox</A>() const; + void <A HREF="mboxlist.html#Add">Add</A>(DwMailbox* aMailbox); + void <A HREF="mboxlist.html#Remove">Remove</A>(DwMailbox* aMailbox); + void <A HREF="mboxlist.html#DeleteAll">DeleteAll</A>(); + static DwMailboxList* <A HREF="mboxlist.html#NewMailboxList">NewMailboxList</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwMailboxList* (*<A HREF="mboxlist.html#sNewMailboxList">sNewMailboxList</A>)(const DwString&, + DwMessageComponent*); + +protected: + + DwMailbox* <A HREF="mboxlist.html#mFirstMailbox">mFirstMailbox</A>; + void <A HREF="mboxlist.html#_AddMailbox">_AddMailbox</A>(DwMailbox* aMailbox); + void <A HREF="mboxlist.html#_DeleteAll">_DeleteAll</A>(); + +public: + + virtual void <A HREF="mboxlist.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="mboxlist.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwMailboxList</TT></B> represents a list of <I>mailboxes</I> as described +in RFC-822. In MIME++, <B><TT>DwMailboxList</TT></B> is a container for objects +of type <B><TT><A HREF="mailbox.html">DwMailbox</A></TT></B>, and it contains +various member functions to manage its contained objects. +<B><TT><A HREF="addrlist.html">DwAddressList</A></TT></B> is also a +<B><TT><A HREF="fieldbdy.html">DwFieldBody</A></TT></B>. This reflects the +fact that certain RFC-822 header fields, such as the "From" header field, +have a list of mailboxes as their field bodies. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwMailboxList">DwMailboxList</A>() <BR> +DwMailboxList(const DwMailboxList& aList) <BR> +DwMailboxList(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwMailboxList</TT></B> object's string representation to the empty +string and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which copies the string +representation and all <B><TT>DwMailbox</TT></B> objects from +<B><TT>aList</TT></B>. The parent of the new +<B><TT>DwMailboxList</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwMailboxList</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwMailboxList& <A NAME="op_eq">operator +=</A> (const DwMailboxList& aList) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aList</TT></B>. The parent node of the +<B><TT>DwMailboxList</TT></B> object is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwMailboxList</TT></B> objects. The +parse method creates or updates the broken-down representation from the string +representation. For <B><TT>DwMailboxList</TT></B> objects, the parse method +parses the string representation to create a list of +<B><TT>DwMailbox</TT></B> objects. This member function also calls the +<B><TT>Parse()</TT></B> member function of each <B><TT>DwMailbox</TT></B> +object in its list. +<P> +You should call this member function after you set or modify the string +representation, and before you access any of the contained +<B><TT>DwMailbox</TT></B> objects. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwMailboxList</TT></B> objects. The +assemble method creates or updates the string representation from the broken-down +representation. For <B><TT>DwMailboxList</TT></B> objects, the assemble method +builds the string representation from its list of +<B><TT>DwMailbox</TT></B> objects. Before it builds the string representation +for the <B><TT>DwMailboxList</TT></B> object, this function first calls the +<B><TT>Assemble()</TT></B> member function of each +<B><TT>DwMailbox</TT></B> object in its list. +<P> +You should call this member function after you set or modify any of the contained +<B><TT>DwMailbox</TT></B> objects, and before you retrieve the string +representation. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwMailboxList</TT></B> on the free store that has the +same value as this <B><TT>DwMailboxList</TT></B> object. The basic idea is +that of a virtual copy constructor. +<P> +<FONT COLOR="teal"><B> DwMailbox* <A NAME="FirstMailbox">FirstMailbox</A>() +const </B></FONT> +<P> +Gets the first <B><TT>DwMailbox</TT></B> object in the list. Use the member +function <B><TT>DwMailbox::Next()</TT></B> to iterate. Returns +<B><TT>NULL</TT></B> if the list is empty. +<P> +<FONT COLOR="teal"><B> void <A NAME="Add">Add</A>(DwMailbox* aMailbox) +</B></FONT> +<P> +Adds <B><TT>aMailbox</TT></B> to the end of the list of +<B><TT>DwMailbox</TT></B> objects maintained by this +<B><TT>DwMailboxList</TT></B> object. +<P> +<FONT COLOR="teal"><B> void <A NAME="Remove">Remove</A>(DwMailbox* aMailbox) +</B></FONT> +<P> +Removes <B><TT>aMailbox</TT></B> from the list of +<B><TT>DwMailbox</TT></B> objects maintained by this +<B><TT>DwMailboxList</TT></B> object. The <B><TT>DwMailbox</TT></B> object +is not deleted by this member function. +<P> +<FONT COLOR="teal"><B> void <A NAME="DeleteAll">DeleteAll</A>() </B></FONT> +<P> +Removes and deletes all <B><TT>DwMailbox</TT></B> objects from the list +maintained by this <B><TT>DwMailboxList</TT></B> object. +<P> +<FONT COLOR="teal"><B> static DwMailboxList* +<A NAME="NewMailboxList">NewMailboxList</A>(const DwString& aStr, +DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwMailboxList</TT></B> object on the free store. If +the static data member <B><TT>sNewMailboxList</TT></B> is +<B><TT>NULL</TT></B>, this member function will create a new +<B><TT>DwMailboxList</TT></B> and return it. Otherwise, +<B><TT>NewMailboxList()</TT></B> will call the user-supplied function pointed +to by <B><TT>sNewMailboxList</TT></B>, which is assumed to return an object +from a class derived from <B><TT>DwMailboxList</TT></B>, and return that +object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwMailboxList* +(*<A NAME="sNewMailboxList">sNewMailboxList</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewMailboxList</TT></B> is not <B><TT>NULL</TT></B>, it is assumed +to point to a user-supplied function that returns an object from a class +derived from <B><TT>DwMailboxList</TT></B>. +<H2> + <FONT COLOR="navy"> Protected Member Functions </FONT> +</H2> +<P> +<B><FONT COLOR="teal"> void <A NAME="_AddMailbox">_AddMailbox</A>(DwMailbox* +aMailbox) </FONT></B> +<P> +Adds a mailbox, but does not set the is-modified flag. +<P> +<B><FONT COLOR="teal"> void <A NAME="_DeleteAll">_DeleteAll</A>() </FONT></B> +<P> +Removes and deletes all <B><TT>DwMailbox</TT></B> objects from the list +maintained by this <B><TT>DwMailboxList</TT></B> object. Doesn't set the +is-modified flag. +<H2> + <FONT COLOR="navy"> Protected Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> DwMailbox* <A NAME="mFirstMailbox">mFirstMailbox</A> +</B></FONT> +<P> +Points to first <B><TT>DwMailbox</TT></B> object in list. +<P> +</BODY></HTML> diff --git a/mimelib/doc/mechansm.html b/mimelib/doc/mechansm.html new file mode 100644 index 000000000..9880b5fa2 --- /dev/null +++ b/mimelib/doc/mechansm.html @@ -0,0 +1,172 @@ +<HTML> +<HEAD> + <TITLE> DwMechanism Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwMechanism -- Class representing a MIME content-transfer-encoding field-body +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwMechanism : public <A HREF="fieldbdy.html">DwFieldBody</A> { + +public: + + <A HREF="mechansm.html#DwMechanism">DwMechanism</A>(); + <A HREF="mechansm.html#DwMechanism">DwMechanism</A>(const DwMechanism& aCte); + <A HREF="mechansm.html#DwMechanism">DwMechanism</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwMechanism(); + const DwMechanism& <A HREF="mechansm.html#op_eq">operator =</A> (const DwMechanism& aCte); + virtual void <A HREF="mechansm.html#Parse">Parse</A>(); + virtual void <A HREF="mechansm.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="mechansm.html#Clone">Clone</A>() const; + int <A HREF="mechansm.html#AsEnum">AsEnum</A>() const; + void <A HREF="mechansm.html#FromEnum">FromEnum</A>(int aCte); + static DwMechanism* + <A HREF="mechansm.html#NewMechanism">NewMechanism</A>(const DwString& aStr, DwMessageComponent* aParent); + static DwMechanism* + (*<A HREF="mechansm.html#sNewMechanism">sNewMechanism</A>)(const DwString&, DwMessageComponent*); + +public: + + virtual void <A HREF="mechansm.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="mechansm.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwMechanism</TT></B> represents a field body for the +Content-Transfer-Encoding header field as described in RFC-2045. +<B><TT>DwMechanism</TT></B> provides convenience functions that allow you +to set or get the content-transfer-encoding attribute as an enumerated value. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwMechanism">DwMechanism</A>() <BR> +DwMechanism(const DwMechanism& aCte) <BR> +DwMechanism(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwMechanism</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which copies the string +representation from <B><TT>aCte</TT></B>. The parent of the new +<B><TT>DwMechanism</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwMechanism</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwMechanism& <A NAME="op_eq">operator =</A> +(const DwMechanism& aCte) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aCte</TT></B>. The parent node of the <B><TT>DwMechanism</TT></B> +object is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwMechanism</TT></B> objects. It should +be called immediately after the string representation is modified and before +any of the object's attributes are retrieved. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwMechanism</TT></B> objects. It +should be called whenever one of the object's attributes is changed in order +to assemble the string representation. It will be called automatically for +this object by the parent object's <B><TT>Assemble()</TT></B> member function +if the is-modified flag is set. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwMechanism</TT></B> object on the free store that has +the same value as this <B><TT>DwMechanism</TT></B> object. The basic idea +is that of a virtual copy constructor. +<P> +<FONT COLOR="teal"><B> int <A NAME="AsEnum">AsEnum</A>() const </B></FONT> +<P> +Returns the content transfer encoding as an enumerated value. Enumerated +values are defined for all standard content transfer encodings in the file +enum.h. If the content transfer encoding is non-standard +<B><TT>DwMime::kCteUnknown</TT></B> is returned. The inherited member function +<B><TT>DwMessageComponent::AsString()</TT></B> may be used to get the content +transfer encoding, standard or non-standard, as a string. +<P> +<FONT COLOR="teal"><B> void <A NAME="FromEnum">FromEnum</A>(int aCte) +</B></FONT> +<P> +Sets the content transfer encoding from an enumerated value. Enumerated values +are defined for all standard content transfer encodings in the file enum.h. +You may set the content transfer encoding to any string value, standard or +non-standard, by using the inherited member function +<B><TT>DwMessageComponent::FromString()</TT></B>. +<P> +<FONT COLOR="teal"><B> static DwMechanism* +<A NAME="NewMechanism">NewMechanism</A>(const DwString& aStr, +DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwMechanism</TT></B> object on the free store. If the +static data member <B><TT>sNewMechanism</TT></B> is <B><TT>NULL</TT></B>, +this member function will create a new <B><TT>DwMechanism</TT></B> and return +it. Otherwise, <B><TT>NewMechanism()</TT></B> will call the user-supplied +function pointed to by <B><TT>sNewMechanism</TT></B>, which is assumed to +return an object from a class derived from <B><TT>DwMechanism</TT></B>, and +return that object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwMechanism* +(*<A NAME="sNewMechanism">sNewMechanism</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewMechanism</TT></B> is not <B><TT>NULL</TT></B>, it is assumed +to point to a user-supplied function that returns an object from a class +derived from <B><TT>DwMechanism</TT></B>. +<P> +</BODY></HTML> diff --git a/mimelib/doc/mediatyp.html b/mimelib/doc/mediatyp.html new file mode 100644 index 000000000..01696084b --- /dev/null +++ b/mimelib/doc/mediatyp.html @@ -0,0 +1,311 @@ +<HTML> +<HEAD> + <TITLE> DwMediaType Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwMediaType -- Class representing a MIME media-type +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwMediaType : public <A HREF="fieldbdy.html">DwFieldBody</A> { + +public: + + <A HREF="mediatyp.html#DwMediaType">DwMediaType</A>(); + <A HREF="mediatyp.html#DwMediaType">DwMediaType</A>(const DwMediaType& aMediaType); + <A HREF="mediatyp.html#DwMediaType">DwMediaType</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwMediaType(); + const DwMediaType& <A HREF="mediatyp.html#op_eq">operator =</A> (const DwMediaType& aMediaType); + virtual void <A HREF="mediatyp.html#Parse">Parse</A>(); + virtual void <A HREF="mediatyp.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="mediatyp.html#Clone">Clone</A>() const; + int <A HREF="mediatyp.html#Type">Type</A>() const; + void <A HREF="mediatyp.html#SetType">SetType</A>(int aType); + const DwString& <A HREF="mediatyp.html#TypeStr">TypeStr</A>() const; + void <A HREF="mediatyp.html#SetTypeStr">SetTypeStr</A>(const DwString& aStr); + int <A HREF="mediatyp.html#Subtype">Subtype</A>() const; + void <A HREF="mediatyp.html#SetSubtype">SetSubtype</A>(int aSubtype); + const DwString& <A HREF="mediatyp.html#SubtypeStr">SubtypeStr</A>() const; + void <A HREF="mediatyp.html#SetSubtypeStr">SetSubtypeStr</A>(const DwString& aStr); + const DwString& <A HREF="mediatyp.html#Boundary">Boundary</A>() const; + void <A HREF="mediatyp.html#SetBoundary">SetBoundary</A>(const DwString& aStr); + virtual void <A HREF="mediatyp.html#CreateBoundary">CreateBoundary</A>(unsigned aLevel=0); + const DwString& <A HREF="mediatyp.html#Name">Name</A>() const; + void <A HREF="mediatyp.html#SetName">SetName</A>(const DwString& aStr); + DwParameter* <A HREF="mediatyp.html#FirstParameter">FirstParameter</A>() const; + void <A HREF="mediatyp.html#AddParameter">AddParameter</A>(DwParameter* aParam); + static DwMediaType* <A HREF="mediatyp.html#NewMediaType">NewMediaType</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwMediaType* (*<A HREF="mediatyp.html#sNewMediaType">sNewMediaType</A>)(const DwString&, + DwMessageComponent*); + +protected: + + void _AddParameter(DwParameter* aParam); + virtual void TypeEnumToStr(); + virtual void TypeStrToEnum(); + virtual void SubtypeEnumToStr(); + virtual void SubtypeStrToEnum(); + void DeleteParameterList(); + void CopyParameterList(DwParameter* aFirst); + int mType; + int mSubtype; + DwString mTypeStr; + DwString mSubtypeStr; + DwString mBoundaryStr; + DwString <A HREF="mediatyp.html#mNameStr">mNameStr</A>; + DwParameter* mFirstParameter; + +public: + + virtual void <A HREF="mediatyp.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="mediatyp.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwMediaType</TT></B> represents a field body for the Content-Type +header field as described in RFC-2045. This field body specifies the kind +of data contained in the body of a message or a body part. A media type is +described by two keywords: a primary type (or just <I>type</I>) and a +<I>subtype</I>. RFC-2046 specifies the seven primary types text, multipart, +message, image, audio, video, and application. RFC-2077 adds the new primary +type model. +<P> +<B><TT>DwMediaType</TT></B> has member functions that allow you to set or +get the type and subtype as either enumerated values or as strings. It also +contains a list of +<B><TT><A HREF="param.html">DwParameter</A></TT></B> objects that represent +the parameters of the field body. You can use convenience functions to directly +access the boundary parameter of a multipart media type, or to access the +name parameter that is often used with several media types, such as +application/octet-stream. +<P> +Some MIME parsers have problems with folded header fields, and this especially +seems to be a problem with the Content-Type field. To disable folding when +the <B><TT>DwMediaType</TT></B> object is assembled, call the inherited member +function <B><TT>DwFieldBody::SetFolding()</TT></B> with an argument of +<B><TT>DwFalse</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwMediaType">DwMediaType</A>() <BR> +DwMediaType(const DwMediaType& aMediaType) <BR> +DwMediaType(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwMediaType</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs deep copy +of <B><TT>aMediaType</TT></B>. The parent of the new +<B><TT>DwMediaType</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwMediaType</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is +<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of +a class derived from <B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwMediaType& <A NAME="op_eq">operator =</A> +(const DwMediaType& aMediaType) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aMediaType</TT></B>. The parent node of the +<B><TT>DwMediaType</TT></B> object is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwMediaType</TT></B> objects. It should +be called immediately after the string representation is modified and before +the parts of the broken-down representation are accessed. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwMediaType</TT></B> objects. It +should be called whenever one of the object's attributes is changed in order +to assemble the string representation from its broken-down representation. +It will be called automatically for this object by the parent object's +<B><TT>Assemble()</TT></B> member function if the is-modified flag is set. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwMediaType</TT></B> object on the free store that has +the same value as this <B><TT>DwMediaType</TT></B> object. The basic idea +is that of a virtual copy constructor. +<P> +<FONT COLOR="teal"><B> int <A NAME="Type">Type</A>() const </B></FONT> +<P> +Returns the primary type as an enumerated value. Enumerated values are defined +for all standard types in the file enum.h. If the type is non-standard, +<B><TT>DwMime::kTypeUnknown</TT></B> is returned. The member function +<B><TT>TypeStr()</TT></B> may be used to get the value of any type, standard +or non-standard, as a string. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetType">SetType</A>(int aType) +</B></FONT> +<P> +Sets the primary type from the enumerated value <B><TT>aType</TT></B>. Enumerated +values are defined for all standard types in the file enum.h. The member +function <B><TT>SetTypeStr()</TT></B> may be used to set the value of any +type, standard or non-standard, from a string. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="TypeStr">TypeStr</A>() +const </B></FONT> +<P> +Returns the primary type as a string. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetTypeStr">SetTypeStr</A>(const +DwString& aStr) </B></FONT> +<P> +Sets the primary type from a string. +<P> +<FONT COLOR="teal"><B> int <A NAME="Subtype">Subtype</A>() const </B></FONT> +<P> +Returns the subtype as an enumerated value. Enumerated values are defined +for all standard subtypes in the file enum.h. If the subtype is non-standard, +<B><TT>DwMime::kSubtypeUnknown</TT></B> is returned. The member function +<B><TT>SubtypeStr()</TT></B> may be used to get the value of any subtype, +standard or non-standard, as a string. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetSubtype">SetSubtype</A>(int aSubtype) +</B></FONT> +<P> +Sets the subtype from the enumerated value <B><TT>aSubtype</TT></B>. Enumerated +values are defined for all standard subtypes in the file enum.h. The member +function <B><TT>SetSubtypeStr()</TT></B> may be used to set the value of +any subtype, standard or non-standard, from a string. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="SubtypeStr">SubtypeStr</A>() const </B></FONT> +<P> +Returns the subtype as a string. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetSubtypeStr">SetSubtypeStr</A>(const +DwString& aStr) </B></FONT> +<P> +Sets the subtype from a string. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="Boundary">Boundary</A>() +const </B></FONT> +<P> +For the multipart type only, returns the value of the boundary parameter. +This member function is a convenience function that searches the list of +<B><TT>DwParameter</TT></B> objects. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetBoundary">SetBoundary</A>(const +DwString& aStr) </B></FONT> +<P> +For the multipart type only, sets the value of the boundary parameter. This +member function is a convenience function that accesses the list of +<B><TT>DwParameter</TT></B> objects. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CreateBoundary">CreateBoundary</A>(unsigned aLevel=0) </B></FONT> +<P> +For the multipart type only, creates a boundary string. +<B><TT>aLevel</TT></B> indicates the level of a nested multipart body part; +if it is positive, it is used to form part of the created boundary string. +This member function is a convenience function that accesses the list of +child <B><TT>DwParameter</TT></B> objects. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="Name">Name</A>() const +</B></FONT> +<P> +Returns the value of the "name" parameter, if such a parameter is present. +The name parameter is often found in several media types, including the +application/octet-stream media type; it suggests a file name for saving to +a disk file. (The filename parameter in the Content-Disposition header field +is an alternative way to indicate a file name.) This member function is a +convenience function that searches the list of +<B><TT>DwParameter</TT></B> objects. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetName">SetName</A>(const DwString& +aStr) </B></FONT> +<P> +Sets the value of the "name" parameter. If a name parameter is not already +present, it is added. The name parameter is often found in several media +types, including the application/octet-stream media type; it suggests a file +name for saving to a disk file. (The filename parameter in the +Content-Disposition header field is an alternative way to indicate a file +name.) This member function is a convenience function that accesses the list +of <B><TT>DwParameter</TT></B> objects. +<P> +<FONT COLOR="teal"><B> DwParameter* +<A NAME="FirstParameter">FirstParameter</A>() const </B></FONT> +<P> +Returns the first <B><TT>DwParameter</TT></B> object in the list managed +by this <B><TT>DwMediaType</TT></B> object. Use +<B><TT>DwParameter::Next()</TT></B> to iterate through the list. +<P> +<FONT COLOR="teal"><B> void +<A NAME="AddParameter">AddParameter</A>(DwParameter* aParam) </B></FONT> +<P> +Adds a <B><TT>DwParameter</TT></B> object to the list managed by this +<B><TT>DwMediaType</TT></B> object. +<P> +<FONT COLOR="teal"><B> static DwMediaType* +<A NAME="NewMediaType">NewMediaType</A>(const DwString& aStr, +DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwMediaType</TT></B> object on the free store. If the +static data member <B><TT>sNewMediaType</TT></B> is <B><TT>NULL</TT></B>, +this member function will create a new <B><TT>DwMediaType</TT></B> and return +it. Otherwise, <B><TT>NewMediaType()</TT></B> will call the user-supplied +function pointed to by <B><TT>sNewMediaType</TT></B>, which is assumed to +return an object from a class derived from <B><TT>DwMediaType</TT></B>, and +return that object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwMediaType* +(*<A NAME="sNewMediaType">sNewMediaType</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewMediaType</TT></B> is not <B><TT>NULL</TT></B>, it is assumed +to point to a user-supplied function that returns an object from a class +derived from <B><TT>DwMediaType</TT></B>. +</BODY></HTML> diff --git a/mimelib/doc/message.html b/mimelib/doc/message.html new file mode 100644 index 000000000..d08d5af4e --- /dev/null +++ b/mimelib/doc/message.html @@ -0,0 +1,136 @@ +<HTML> +<HEAD> + <TITLE> DwMessage Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwMessage -- Class representing an RFC-822/MIME message +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwMessage : public <A HREF="entity.html">DwEntity</A> { + +public: + + <A HREF="message.html#DwMessage">DwMessage</A>(); + <A HREF="message.html#DwMessage">DwMessage</A>(const DwMessage& aMessage); + <A HREF="message.html#DwMessage">DwMessage</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwMessage(); + const DwMessage& <A HREF="message.html#op_eq">operator =</A> (const DwMessage& aMessage); + virtual DwMessageComponent* <A HREF="message.html#Clone">Clone</A>() const; + static DwMessage* <A HREF="message.html#NewMessage">NewMessage</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwMessage* (*<A HREF="message.html#sNewMessage">sNewMessage</A>)(const DwString&, DwMessageComponent*); + +public: + + virtual void <A HREF="message.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwMessage</TT></B> represents an RFC-822/MIME <I>message</I>. +<P> +A <I>message</I> contains both a collection of <I>header fields</I> and a +<I>body</I>. In the terminology of RFC-2045, the general term for the +headers-body combination is <I>entity</I>. In MIME++, +<B><TT>DwMessage</TT></B> is a direct subclass of +<B><TT><A HREF="entity.html">DwEntity</A></TT></B>, and therefore contains +both a <B><TT><A HREF="headers.html">DwHeaders</A></TT></B> object and a +<B><TT><A HREF="body.html">DwBody</A></TT></B> object. +<P> +In the tree (broken-down) representation of message, a +<B><TT>DwMessage</TT></B> object is almost always a root node, having child +nodes but no parent node. The child nodes are the +<B><TT>DwHeaders</TT></B> object and the <B><TT>DwBody</TT></B> object it +contains. A <B><TT>DwMessage</TT></B> may sometimes be an intermediate node. +In this special case, the parent node is a <B><TT>DwBody</TT></B> object +of type "message/*" and the <B><TT>DwMessage</TT></B> object represents an +encapsulated message. +<P> +To access the contained <B><TT>DwHeaders</TT></B> object, use the inherited +member function <B><TT>DwEntity::Headers()</TT></B>. To access the contained +<B><TT>DwBody</TT></B> object, use the inherited member function +<B><TT>DwEntity::Body()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwMessage">DwMessage</A>() <BR> +DwMessage(const DwMessage& aMessage) <BR> +DwMessage(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwMessage</TT></B> object's string representation to the empty string +and sets its parent to <B><TT>NULL</TT></B>. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aMessage</TT></B>. The parent of the new +<B><TT>DwMessage</TT></B> object is set to <B><TT>NULL</TT></B>. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwMessage</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. +<P> +<FONT COLOR="teal"><B> const DwMessage& <A NAME="op_eq">operator =</A> +(const DwMessage& aMessage) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aMessage</TT></B>. The parent node of the +<B><TT>DwMessage</TT></B> object is not changed. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwMessage</TT></B> on the free store that has the same +value as this <B><TT>DwMessage</TT></B> object. The basic idea is that of +a ``virtual copy constructor.'' +<P> +<FONT COLOR="teal"><B> static DwMessage* +<A NAME="NewMessage">NewMessage</A>(const DwString& aStr, DwMessageComponent* +aParent) </B></FONT> +<P> +Creates a new <B><TT>DwMessage</TT></B> object on the free store. If the +static data member <B><TT>sNewMessage</TT></B> is <B><TT>NULL</TT></B>, this +member function will create a new <B><TT>DwMessage</TT></B> and return it. +Otherwise, <B><TT>NewMessage()</TT></B> will call the user-supplied function +pointed to by <B><TT>sNewMessage</TT></B>, which is assumed to return an +object from a class derived from <B><TT>DwMessage</TT></B>, and return that +object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwMessage* +(*<A NAME="sNewMessage">sNewMessage</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewMessage</TT></B> is not <B><TT>NULL</TT></B>, it is assumed +to point to a user supplied function that returns an object from a class +derived from <B><TT>DwMessage</TT></B>. +<P> +</BODY></HTML> diff --git a/mimelib/doc/mimepp.html b/mimelib/doc/mimepp.html new file mode 100644 index 000000000..3545ccfbe --- /dev/null +++ b/mimelib/doc/mimepp.html @@ -0,0 +1,80 @@ +<!-- $Revision$ --> +<!-- $Date$ --> +<HTML> +<HEAD> +<TITLE> + MIME++ Man Page +</TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> + +<FONT COLOR="navy"> +<H2>NAME</H2> +</FONT> +MIME++ -- C++ class library for creating, parsing, or modifying messages +in MIME format + +<FONT COLOR="navy"> +<H2>SYNOPSIS</H2> +</FONT> +<PRE> +#include <mimepp/mimepp.h> +</PRE> + +<FONT COLOR="navy"> +<H2>DESCRIPTION</H2> +</FONT> +MIME++ is a C++ class library for creating, parsing, or modifying messages +in Multipurpose Internet Mail Extensions (MIME) format. For information +on the MIME standards, see RFC-822, RFC-1123, RFC-1521, RFC-1522, and +RFC-1523. + +<FONT COLOR="navy"> +<H3>Class Inheritance</H3> +</FONT> +<UL> +<LI><A HREF="string.html">DwString</A> +<LI><A HREF="msgcmp.html">DwMessageComponent</A> + <UL> + <LI><A HREF="body.html">DwBody</A> + <LI><A HREF="entity.html">DwEntity</A> + <UL> + <LI><A HREF="bodypart.html">DwBodyPart</A> + <LI><A HREF="message.html">DwMessage</A> + </UL> + <LI><A HREF="field.html">DwField</A> + <LI><A HREF="fieldbdy.html">DwFieldBody</A> + <UL> + <LI><A HREF="address.html">DwAddress</A> + <UL> + <LI><A HREF="group.html">DwGroup</A> + <LI><A HREF="mailbox.html">DwMailbox</A> + </UL> + <LI><A HREF="addrlist.html">DwAddressList</A> + <LI><A HREF="disptype.html">DwDispositionType</A> + <LI><A HREF="mediatyp.html">DwMediaType</A> + <LI><A HREF="mechansm.html">DwMechanism</A> + <LI><A HREF="datetime.html">DwDateTime</A> + <LI><A HREF="mboxlist.html">DwMailboxList</A> + <LI><A HREF="msgid.html">DwMsgId</A> + <LI><A HREF="text.html">DwText</A> + </UL> + <LI><A HREF="headers.html">DwHeader</A> + <LI><A HREF="param.html">DwParameter</A> + </UL> +<LI><A HREF="protocol.html">DwProtocolClient</A> + <UL> + <LI><A HREF="smtp.html">DwSmtpClient</A> + <LI><A HREF="nntp.html">DwNntpClient</A> + <LI><A HREF="pop.html">DwPopClient</A> +</UL> +<LI><A HREF="binhex.html">DwBinhex</A> +<LI><A HREF="binhex.html">DwUuencode</A> +<LI><A HREF="boyermor.html">DwBoyerMoore</A> + +<FONT COLOR="navy"> +<H3><A HREF="util.html">Utility Functions</A></H3> +</FONT> + +</BODY> +</HTML> diff --git a/mimelib/doc/msgcmp.html b/mimelib/doc/msgcmp.html new file mode 100644 index 000000000..48a7ab549 --- /dev/null +++ b/mimelib/doc/msgcmp.html @@ -0,0 +1,298 @@ +<HTML> +<HEAD> + <TITLE> DwMessageComponent Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwMessageComponent -- Abstract base class for all message components +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwMessageComponent { + +public: + + enum componentType { + kCidError=-1, + kCidUnknown=0, + kCidAddress, + kCidAddressList, + kCidBody, + kCidBodyPart, + kCidDispositionType, + kCidMechanism, + kCidMediaType, + kCidParameter, + kCidDateTime, + kCidEntity, + kCidField, + kCidFieldBody, + kCidGroup, + kCidHeaders, + kCidMailbox, + kCidMailboxList, + kCidMessage, + kCidMessageComponent, + kCidMsgId, + kCidText + }; + <A HREF="msgcmp.html#DwMessageComponent">DwMessageComponent</A>(); + <A HREF="msgcmp.html#DwMessageComponent">DwMessageComponent</A>(const DwMessageComponent& aCmp); + <A HREF="msgcmp.html#DwMessageComponent">DwMessageComponent</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwMessageComponent(); + const DwMessageComponent& <A HREF="msgcmp.html#op_eq">operator =</A> (const DwMessageComponent& aCmp); + virtual void <A HREF="msgcmp.html#Parse">Parse</A>() = 0; + virtual void <A HREF="msgcmp.html#Assemble">Assemble</A>() = 0; + virtual DwMessageComponent* <A HREF="msgcmp.html#Clone">Clone</A>() const = 0; + void <A HREF="msgcmp.html#FromString">FromString</A>(const DwString& aStr); + void <A HREF="msgcmp.html#FromString">FromString</A>(const char* aCstr); + const DwString& <A HREF="msgcmp.html#AsString">AsString</A>(); + DwMessageComponent* <A HREF="msgcmp.html#Parent">Parent</A>(); + void <A HREF="msgcmp.html#SetParent">SetParent</A>(DwMessageComponent* aParent); + DwBool <A HREF="msgcmp.html#IsModified">IsModified</A>() const; + void <A HREF="msgcmp.html#SetModified">SetModified</A>(); + int <A HREF="msgcmp.html#ClassId">ClassId</A>() const; + const char* <A HREF="msgcmp.html#ClassName">ClassName</A>() const; + int <A HREF="msgcmp.html#ObjectId">ObjectId</A>() const; + +protected: + + DwString mString; + DwBool mIsModified; + DwMessageComponent* mParent; + componentType mClassId; + const char* mClassName; + +public: + + virtual void <A HREF="msgcmp.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="msgcmp.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwMessageComponent</TT></B> is the root of an inheritance hierarchy +from which all MIME message components are derived. Thus, +<B><TT>DwMessageComponent</TT></B> defines important features that are inherited +by nearly all other classes that represent components of a MIME message. +These features are the following: +<P> +<UL> + <LI> + A string representation. The <B><TT>DwMessageComponent</TT></B> class provides + a member function <B><TT>FromString(const DwString&)</TT></B> to set + the string representation and a member function + <B><TT>AsString()</TT></B> to get the string representation. + <P> + <LI> + A broken-down, or parsed, representation. An RFC-822 date-time, for example, + has a year, month, day, hour, minute, second, and time zone as elements of + its broken-down representation. <B><TT>DwMessageComponent</TT></B> does not + deal directly with the broken-down representation, since it is + component-specific. Derived classes bear all the responsibility for their + broken-down representations. + <P> + <LI> + A parse method to extract the broken-down representation from the string + representation. In the <B><TT>DwDateTime</TT></B> class, for example, the + parse method extracts the year, month, day, hour, minute, second, and time + zone from the RFC-822 <I>date-time</I> contained in the string representation. + <B><TT>DwMessageComponent</TT></B> provides a pure virtual function + <B><TT>Parse()</TT></B>, which executes the parse method for a derived class. + <P> + <LI> + An assemble method to convert the broken-down representation to a string + representation. This is the opposite of the parse method. In the + <B><TT>DwDateTime</TT></B> class, for example, the assemble method creates + an RFC-822 <I>date-time</I> string from values of the year, month, day, hour, + minute, second, and time zone. <B><TT>DwMessageComponent</TT></B> provides + a pure virtual function <B><TT>Assemble()</TT></B>, which executes the assemble + method for a derived class. + <P> + <LI> + An is-modified flag. When the string representation and the broken-down + representation are consistent, the assemble method does not need to be executed. + The is-modified flag is cleared when the two representations are consistent, + and is set when they are inconsistent. The flag is set automatically whenever + a <B><TT>DwMessageComponent</TT></B> object's broken-down representation + is changed by calling one of the object's member functions, and it is cleared + when the assemble or parse method is executed. + <B><TT>DwMessageComponent</TT></B> also provides a member function + <B><TT>SetModified()</TT></B> which forces the is-modified flag to be set. + <P> + <LI> + A parent. Most message components are part of another component. A collection + of headers is part of a message or body part, a header field is part of a + collection of headers, a field-body is part of a header field, and so on. + The parent of a component is the component that contains it. This tree structure + is important, since a component's parent must be parsed before the component + can be. Also, a component's string representation must be assembled before + its parent's. To maintain consistency in the tree, whenever a component's + is-modified flag is set, the component notifies its parent to also set its + is-modified flag. In this way, an is-modified flag set anywhere in the tree + always propagates up to the root component. + <P> + <LI> + Children. The preceding discussion about a component's parent is relevant + to an understanding of a component's children. A component's parse method + calls the parse methods of its children after it has executed its own parse + method (and, in some cases, created all of its children). Also, a component + typically calls the assemble method of its children before it executes its + own. A component's child may request that the component set its is-modified + flag. <B><TT>DwMessageComponent</TT></B> does not deal directly with children. + Derived classes bear all the responsibility for handling their children. +</UL> +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwMessageComponent">DwMessageComponent</A>() +<BR> +DwMessageComponent(const DwMessageComponent& aCmp) <BR> +DwMessageComponent(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwMessageComponent</TT></B> object's string representation to the +empty string and sets its parent to NULL. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aCmp</TT></B>. The parent of the new +<B><TT>DwMessageComponent</TT></B> object is set to NULL. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the new +<B><TT>DwMessageComponent</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. In typical cases, the virtual member +function <B><TT>Parse()</TT></B> should be called immediately after this +constructor to parse the new <B><TT>DwMessageComponent</TT></B> object and +all of its children into their broken-down representations. +<P> +<FONT COLOR="teal"><B> const DwMessageComponent& <A NAME="op_eq">operator +=</A> (const DwMessageComponent& aCmp) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aCmp</TT></B>. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() = 0 +</B></FONT> +<P> +A pure virtual function which provides an interface to the parse method. +The parse method, implemented in derived classes, is responsible for extracting +the broken-down representation from the string representation. In some derived +classes, such as <B><TT>DwHeaders</TT></B>, the parse method is also responsible +for creating the children of the object. (In the case of +<B><TT>DwHeaders</TT></B>, the children created are the +<B><TT>DwField</TT></B> objects that represent the <I>field</I>s contained +in the <I>headers</I>.) The <B><TT>Parse()</TT></B> function always calls +the <B><TT>Parse()</TT></B> function of all of its children. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() = 0 +</B></FONT> +<P> +A pure virtual function which provides an interface to the assemble method. +The assemble method, implemented in derived classes, is responsible for creating +the string representation from the broken-down representation. In other words, +the assemble method is the opposite of the parse method. Before assembling +its string representation, the assemble method calls the assemble method +of each of its children. In this way, the entire tree structure that represents +a message may be traversed. If the is-modifed flag for a +<B><TT>DwMessageComponent</TT></B> is cleared, the +<B><TT>Assemble()</TT></B> function will return immediately without calling +the <B><TT>Assemble()</TT></B> function of any of its children. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const = 0 </B></FONT> +<P> +Creates a new <B><TT>DwMessageComponent</TT></B> on the free store that is +of the same type as, and has the same value as, this object. The basic idea +is that of a ``virtual copy constructor.'' +<P> +<FONT COLOR="teal"><B> void <A NAME="FromString">FromString</A>(const +DwString& aStr) <BR> +void FromString(const char* aCstr) </B></FONT> +<P> +Sets the object's string representation. <B><TT>aCstr</TT></B> must be +NUL-terminated. This member function does not invoke the parse method. Typically, +the virtual member function <B><TT>Parse()</TT></B> should be called immediately +after this member function to parse the +<B><TT>DwMessageComponent</TT></B> object and all of its children into their +broken-down representations. See also +<B><TT>DwMessageComponent::Parse()</TT></B> +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="AsString">AsString</A>() +</B></FONT> +<P> +Returns the <B><TT>DwMessageComponent</TT></B> object's string representation. +The assemble method is not called automatically. Typically, the +<B><TT>Assemble()</TT></B> member function should be called immediately before +this member function to insure that the broken-down representation and the +string representation are consistent. See also +<B><TT>DwMessageComponent::Assemble()</TT></B>. +<P> +<FONT COLOR="teal"><B> DwMessageComponent* <A NAME="Parent">Parent</A>() +</B></FONT> +<P> +Returns the <B><TT>DwMessageComponent</TT></B> object that is the parent +of this object. +<P> +<FONT COLOR="teal"><B> void +<A NAME="SetParent">SetParent</A>(DwMessageComponent* aParent) </B></FONT> +<P> +Sets <B><TT>aParent</TT></B> as the <B><TT>DwMessageComponent</TT></B> object's +parent. +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="IsModified">IsModified</A>() const +</B></FONT> +<P> +Returns 1 if the is-modified flag is set for this +<B><TT>DwMessageComponent</TT></B> object. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetModified">SetModified</A>() +</B></FONT> +<P> +Sets the is-modified (dirty) flag for this +<B><TT>DwMessageComponent</TT></B> object and notifies the object's parent +to also set its is-modified flag. +<P> +<FONT COLOR="teal"><B> int <A NAME="ClassId">ClassId</A>() const </B></FONT> +<P> +Returns an integer id for the object's class. +<P> +<FONT COLOR="teal"><B> const char* <A NAME="ClassName">ClassName</A>() const +</B></FONT> +<P> +Returns the name of the class as a NUL-terminated char string. +<P> +<FONT COLOR="teal"><B> int <A NAME="ObjectId">ObjectId</A>() const +</B></FONT> +<P> +Returns a object id that is unique among all DwMessageComponent objects. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function prints debugging information about this object to +<B><TT>aStrm</TT></B>. It will also call <B><TT>PrintDebugInfo()</TT></B> +for any of its child components down to a level of +<B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +</BODY></HTML> diff --git a/mimelib/doc/msgid.html b/mimelib/doc/msgid.html new file mode 100644 index 000000000..69d10ef59 --- /dev/null +++ b/mimelib/doc/msgid.html @@ -0,0 +1,198 @@ +<HTML> +<HEAD> + <TITLE> DwMsgId Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwMsgId -- Class representing an RFC-822 msg-id +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwMsgId : public <A HREF="fieldbdy.html">DwFieldBody</A> { + +public: + + <A HREF="msgid.html#DwMsgId">DwMsgId</A>(); + <A HREF="msgid.html#DwMsgId">DwMsgId</A>(const DwMsgId& aMsgId); + <A HREF="msgid.html#DwMsgId">DwMsgId</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwMsgId(); + const DwMsgId& <A HREF="msgid.html#op_eq">operator =</A> (const DwMsgId& aMsgId); + virtual void <A HREF="msgid.html#Parse">Parse</A>(); + virtual void <A HREF="msgid.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="msgid.html#Clone">Clone</A>() const; + virtual void <A HREF="msgid.html#CreateDefault">CreateDefault</A>(); + const DwString& <A HREF="msgid.html#LocalPart">LocalPart</A>() const; + void <A HREF="msgid.html#SetLocalPart">SetLocalPart</A>(const DwString& aLocalPart); + const DwString& <A HREF="msgid.html#Domain">Domain</A>() const; + void <A HREF="msgid.html#SetDomain">SetDomain</A>(const DwString& aDomain); + static DwMsgId* <A HREF="msgid.html#NewMsgId">NewMsgId</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwMsgId* (*<A HREF="msgid.html#sNewMsgId">sNewMsgId</A>)(const DwString&, DwMessageComponent*); + static const char* <A HREF="msgid.html#sHostName">sHostName</A>; + +public: + + virtual void <A HREF="msgid.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="msgid.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwMsgId</TT></B> represents a <I>msg-id</I> as described in RFC-822. +In the BNF grammar in RFC-822, a msg-id has a <I>local-part</I> and a +<I>domain</I>. In MIME++, a <B><TT>DwMsgId</TT></B> contains strings that +contain the local-part and the domain. +<P> +In the tree (broken-down) representation of message, a +<B><TT>DwMsgId</TT></B> object may only be a leaf node, having a parent but +no child nodes. Its parent node must be a +<A HREF="field.html"><B><TT>DwField</TT></B> </A>object. +<P> +<B><TT>DwMsgId</TT></B> has member functions for getting or setting its +local-part and its domain. You can have the library to create the contents +of a <B><TT>DwMsgId</TT></B> object for you by calling the member function +<B><TT>CreateDefault()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwMsgId">DwMsgId</A>() <BR> +DwMsgId(const DwMsgId& aMsgId) <BR> +DwMsgId(const DwString& aStr, DwMessageComponent* aParent=0) </B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwMsgId</TT></B> object's string representation to the empty string +and sets its parent to NULL. +<P> +The second constructor is the copy constructor, which performs a deep copy +of <B><TT>aMsgId</TT></B>. The parent of the new <B><TT>DwMsgId</TT></B> +object is set to NULL. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwMsgId</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is NULL, +<B><TT>aParent</TT></B> should point to an object of a class derived from +<B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwMsgId& <A NAME="op_eq">operator =</A> +(const DwMsgId& aMsgId) </B></FONT> +<P> +This is the assignment operator, which performs a deep copy of +<B><TT>aMsgId</TT></B>. The parent node of the <B><TT>DwMsgId</TT></B> object +is not changed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwMsgId</TT></B> objects. The parse +method parses the local-part and the domain from the string representation. +<P> +You should call this member function after you set or modify the string +representation, and before you retrieve local-part or domain. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwMsgId</TT></B> objects. The assemble +method creates or updates the string representation from the local-part and +the domain. +<P> +You should call this member function after you modify the local-part or the +domain, and before you retrieve the string representation. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwMsgId</TT></B> on the free store that has the same +value as this <B><TT>DwMsgId</TT></B> object. The basic idea is that of a +``virtual copy constructor.'' +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CreateDefault">CreateDefault</A>() </B></FONT> +<P> +Creates a value for the msg-id. Uses the current time, process id, and fully +qualified domain name for the host. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="LocalPart">LocalPart</A>() const </B></FONT> +<P> +Returns the local-part of the msg-id. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetLocalPart">SetLocalPart</A>(const +DwString& aLocalPart) </B></FONT> +<P> +Sets the local-part of the msg-id. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="Domain">Domain</A>() +const </B></FONT> +<P> +Returns the domain of the msg-id. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetDomain">SetDomain</A>(const +DwString& aDomain) </B></FONT> +<P> +Sets the domain of the msg-id. +<P> +<FONT COLOR="teal"><B> static DwMsgId* <A NAME="NewMsgId">NewMsgId</A>(const +DwString& aStr, DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwMsgId</TT></B> object on the free store. If the static +data member <B><TT>sNewMsgId</TT></B> is NULL, this member function will +create a new <B><TT>DwMsgId</TT></B> and return it. Otherwise, +<B><TT>NewMsgId()</TT></B> will call the user-supplied function pointed to +by <B><TT>sNewMsgId</TT></B>, which is assumed to return an object from a +class derived from <B><TT>DwMsgId</TT></B>, and return that object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwMsgId* +(*<A NAME="sNewMsgId">sNewMsgId</A>)(const DwString&, DwMessageComponent*) +</B></FONT> +<P> +If <B><TT>sNewMsgId</TT></B> is not NULL, it is assumed to point to a +user-supplied function that returns an object from a class derived from +<B><TT>DwMsgId</TT></B>. +<P> +<FONT COLOR="teal"><B> static const char* <A NAME="sHostName">sHostName</A> +</B></FONT> +<P> +Host name of machine, used to create msg-id string. This data member is ignored +if the platform supports a gethostname() function call. +</BODY></HTML> diff --git a/mimelib/doc/nntp.html b/mimelib/doc/nntp.html new file mode 100644 index 000000000..75b8b71fb --- /dev/null +++ b/mimelib/doc/nntp.html @@ -0,0 +1,384 @@ +<HTML> +<HEAD> + <TITLE> DwNntpClient Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwNntpClient -- Class for handling the client side of an NNTP session +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwNntpClient : public <A HREF="protocol.html">DwProtocolClient</A> { + +public: + + enum { + kCmdNoCommand=0, + kCmdArticle, + kCmdBody, + kCmdHead, + kCmdStat, + kCmdGroup, + kCmdHelp, + kCmdIhave, + kCmdLast, + kCmdList, + kCmdNewgroups, + kCmdNewnews, + kCmdNext, + kCmdPost, + kCmdQuit, + kCmdSlave + }; + <A HREF="nntp.html#DwNntpClient">DwNntpClient</A>(); + virtual ~DwNntpClient(); + virtual int <A HREF="nntp.html#Open">Open</A>(const char* aServer, DwUint16 aPort=119); + DwObserver* <A HREF="nntp.html#SetObserver">SetObserver</A>(DwObserver* aObserver); + int <A HREF="nntp.html#ReplyCode">ReplyCode</A>() const; + const DwString& <A HREF="nntp.html#StatusResponse">StatusResponse</A>() const; + const DwString& <A HREF="nntp.html#TextResponse">TextResponse</A>() const; + int <A HREF="nntp.html#Article">Article</A>(int aNumber=(-1)); + int <A HREF="nntp.html#Article">Article</A>(const char* aMsgid); + int <A HREF="nntp.html#Body">Body</A>(int aNumber=(-1)); + int <A HREF="nntp.html#Body">Body</A>(const char* aMsgid); + int <A HREF="nntp.html#Head">Head</A>(int aNumber=(-1)); + int <A HREF="nntp.html#Head">Head</A>(const char* aMsgid); + int <A HREF="nntp.html#Stat">Stat</A>(int aNumber=(-1)); + int <A HREF="nntp.html#Stat">Stat</A>(const char* aMsgid); + int <A HREF="nntp.html#Group">Group</A>(const char* aNewsgroupName); + int <A HREF="nntp.html#Help">Help</A>(); + int <A HREF="nntp.html#Ihave">Ihave</A>(const char* aMsgId); + int <A HREF="nntp.html#Last">Last</A>(); + int <A HREF="nntp.html#List">List</A>(); + int <A HREF="nntp.html#Newgroups">Newgroups</A>(const char* aDate, const char* aTime, + DwBool aIsGmt=DwFalse, const char* aDistributions=0); + int <A HREF="nntp.html#Newnews">Newnews</A>(const char* aNewsgroups, const char* aDate, + const char* aTime, DwBool aIsGmt=DwFalse, const char* aDistribution=0); + int <A HREF="nntp.html#Next">Next</A>(); + int <A HREF="nntp.html#Post">Post</A>(); + int <A HREF="nntp.html#Quit">Quit</A>(); + int <A HREF="nntp.html#Slave">Slave</A>(); + int <A HREF="nntp.html#SendData">SendData</A>(const DwString& aStr); + int <A HREF="nntp.html#SendData">SendData</A>(const char* aBuf, int aBufLen); +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwNntpClient</TT></B> is a class that handles the client side of an +NNTP session. Specifically, <B><TT>DwNntpClient</TT></B> provides facilities +for opening a connection to an NNTP server, sending commands and data to +the server, receiving responses and data from the server, and closing the +connection. The protocol implemented is the Network News Transport Protocol, +as specified in RFC-977. +<P> +<B><TT>DwNntpClient</TT></B> is derived from +<B><TT><A HREF="protocol.html">DwProtocolClient</A></TT></B>. For information +about inherited member functions, especially member functions for detecting +failures or errors, see the man page for +<B><TT>DwProtocolClient</TT></B>. +<P> +In an NNTP session, the client sends commands to the server and receives +responses from the server. A client command consists of a command word and +zero or more argument words. A server response consists of a status line +and possibly some additional lines of text. The status line consists of a +three-digit numeric reply code followed by additional information. The reply +code indicates a success or failure condition. In some cases, the server +sends lines of text immediately after the status line. +<B><TT>DwNntpClient</TT></B> provides facilities for you to send commands +to the server and receive responses from the server. +<P> +<B><TT>DwNntpClient</TT></B> has only a default constructor. On Win32 platforms, +it is possible for the constructor to fail. (It calls WSAStartup().) You +should verify that the constructor succeeded by calling the inherited member +function <B><TT>DwProtocolClient::LastError()</TT></B> and checking for a +zero return value. +<P> +To open a connection to the server, call the member function +<B><TT>Open()</TT></B> with the name of the server as an argument. +<B><TT>Open()</TT></B> accepts an optional argument that specifies the TCP +port that the server listens to. The default port is the standard NNTP port +(119). <B><TT>Open()</TT></B> may fail, so you should check the return value +to verify that it succeeded. To close the connection, call the inherited +member function <B><TT>DwProtocolClient::Close()</TT></B>. To check if a +connection is open, call the inherited member function +<B><TT>DwProtocolClient::IsOpen()</TT></B>. <B><TT>IsOpen()</TT></B> returns +a boolean value that indicates whether or not a call to +<B><TT>Open()</TT></B> was successful; it will not detect failure in the +network or a close operation by the remote host. +<P> +For each NNTP command, <B><TT>DwNntpClient</TT></B> has a member function +that sends that command and receives the server's response. If the command +takes any arguments, then those arguments are passed as function arguments +to the command function. The command functions return the numeric value of +the three-digit reply code returned by the server. Your program must check +the reply code to determine whether or not the command was accepted and performed +by the server. In some cases, because of a communications error or some other +error, it is not possible for the command function to send the command or +receive the response. When this happens, the command function will return +0. You can determine the precise error or failure by calling the inherited +member functions <B><TT>DwProtocolClient::LastError()</TT></B> or +<B><TT>DwProtocolClient::LastFailure()</TT></B>. +<P> +After each command is sent, <B><TT>DwNntpClient</TT></B> receives the server's +response and remembers it. The member function +<B><TT>ReplyCode()</TT></B> returns the numeric value of the reply code received +in response to the last command. <B><TT>StatusResponse()</TT></B> returns +the entire status response from the server, including the reply code. If +no status response is received, possibly because of a communications error +or failure, <B><TT>ReplyCode()</TT></B> returns zero and +<B><TT>StatusResponse()</TT></B> returns an empty string. +<P> +The server sends a status response, including a reply code, for all all NNTP +commands. For some commands, such as when the client requests an article +body, the server sends a multi-line text response immediately following the +status response. Multi-line text responses can be received in either of two +ways. The simplest way is to call the member function +<B><TT>TextResponse()</TT></B> after a command completes successfully. This +simple method works fine for non-interactive applications. It can be a problem +in interactive applications, however, because there is no data to display +to a user until the entire text response is retrieved. An alternative method +allows your program to retrieve the text response one line at a time as it +is received. To use this method, you must define a subclass of +<B><TT>DwObserver</TT></B> and assign an object of that class to the +<B><TT>DwNntpClient</TT></B> object using the member function +<B><TT>SetObserver()</TT></B>. <B><TT>DwObserver</TT></B> is an abstract +class, declared in protocol.h, that has just one pure virtual member function +<B><TT>Notify()</TT></B>. After each line of the text response is received, +<B><TT>DwNntpClient</TT></B> will call the <B><TT>Notify()</TT></B> member +function of its assigned <B><TT>DwObserver</TT></B> object. Each invocation +of <B><TT>Notify()</TT></B> should call the <B><TT>DwNntpClient</TT></B> +member function <B><TT>TextResponse()</TT></B> to retrieve the next line +of the text response. Note that you cannot use both of these methods at the +same time: if an observer is assigned, <B><TT>TextResponse()</TT></B> returns +only the last line received, not the entire multi-line text response. +<P> +Certain NNTP commands, such as the POST command, require the NNTP client +to send multiple lines of text to the server. To perform this bulk data transfer, +<B><TT>DwNntpClient</TT></B> provides the member function +<B><TT>SendData()</TT></B>. In the current implementation, +<B><TT>SendData()</TT></B> does not convert end of line characters, so it +is your responsibility to convert the end of line characters to CR LF, if +necessary. (You may use the utility function +<B><TT>DwToCrLfEol()</TT></B> to do the conversion.) +<B><TT>SendData()</TT></B> will perform the character stuffing to protect +'.' at the beginning of a line, and it will append the final [CR LF] '.' +CR LF. It is possible to divide data and make multiple calls to +<B><TT>SendData()</TT></B>; however, if you do so, please note the following +paragraph. +<P> +Note: Because of a feature (some might say bug) in the current implementation, +<B><TT>SendData()</TT></B> will not detect a '.' at the beginning of a line +if the CR LF '.' sequence is split between two calls to +<B><TT>SendData()</TT></B>. This problem will probably be resolved in a future +version, but be aware that such a change will require a change in +<B><TT>DwNntpClient</TT></B>'s interface. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwNntpClient">DwNntpClient</A>() </B></FONT> +<P> +Initializes the <B><TT>DwNntpClient</TT></B> object. It is possible for the +constructor to fail. To verify that the constructor succeeded, call the member +function <B><TT>LastError()</TT></B> and check that it returns zero. (In +the Win32 implementation, the constructor calls the Winsock function +<B><TT>WSAStartup()</TT></B>, which may fail.) +<P> +<FONT COLOR="teal"><B> virtual int <A NAME="Open">Open</A>(const char* aServer, +DwUint16 aPort=119) </B></FONT> +<P> +Opens a TCP connection to the server <B><TT>aServer</TT></B> at port +<B><TT>aPort</TT></B>. <B><TT>aServer</TT></B> may be either a host name, +such as "news.acme.com" or an IP number in dotted decimal format, such as +"147.81.64.60". The default value for <B><TT>aPort</TT></B> is 119, the +well-known port for NNTP assigned by the Internet Assigned Numbers Authority +(IANA). +<P> +If the connection attempt succeeds, the server sends a response. +<B><TT>Open()</TT></B> returns the server's numeric reply code. The full +response from the server can be retrieved by calling +<B><TT>StatusResponse()</TT></B>. +<P> +If the connection attempt fails, <B><TT>Open()</TT></B> returns 0. To determine +what error occurred when a connection attempt fails, call the inherited member +function <B><TT>DwProtocolClient::LastError()</TT></B>. To determine if a +failure also occurred, call the inherited member function +<B><TT>DwProtocolClient::LastFailure()</TT></B>. +<P> +<FONT COLOR="teal"><B> DwObserver* +<A NAME="SetObserver">SetObserver</A>(DwObserver* aObserver) </B></FONT> +<P> +Sets the observer object that interacts with the +<B><TT>DwNntpClient</TT></B> object to retrieve a multi-line text response. +If an observer is set, <B><TT>DwNntpClient</TT></B> will call the observer's +<B><TT>Notify()</TT></B> method after each line of the text response is received. +To remove an observer, call <B><TT>SetObserver()</TT></B> with a NULL argument. +<B><TT>SetObserver()</TT></B> returns the previously set observer, or NULL +if no observer was previously set. +<P> +<FONT COLOR="teal"><B> int <A NAME="ReplyCode">ReplyCode</A>() const +</B></FONT> +<P> +Returns the numeric value of the three-digit reply code received from the +server in response to the last client command. If no response was received, +<B><TT>ReplyCode()</TT></B> returns zero. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="StatusResponse">StatusResponse</A>() const </B></FONT> +<P> +Returns the entire status response last received from the server. If no response +was received, perhaps because of a communications failure, +<B><TT>StatusResponse()</TT></B> returns an empty string. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="TextResponse">TextResponse</A>() const </B></FONT> +<P> +If no observer is set for this object, <B><TT>TextResponse()</TT></B> returns +a string that comprises the entire sequence of lines received from the server. +Otherwise, if an observer <B><TT>is</TT></B> set for this object, +<B><TT>TextResponse()</TT></B> returns only the most recent line received. +<P> +<FONT COLOR="teal"><B> int <A NAME="Article">Article</A>(int aNumber=(-1)) +<BR> +int Article(const char* aMsgid) </B></FONT> +<P> +Sends the NNTP ARTICLE command and returns the reply code received from the +server. If no response is received, the function returns zero. The optional +argument <B><TT>aNumber</TT></B> specifies the number of an article to retrieve. +If <B><TT>Article()</TT></B> is called with the default argument, the ARTICLE +command is sent to the server with no argument. <B><TT>aMsgId</TT></B> specifies +the message id of an article to retrieve. +<P> +<FONT COLOR="teal"><B> int <A NAME="Body">Body</A>(int aNumber=(-1)) <BR> +int Body(const char* aMsgid) </B></FONT> +<P> +Sends the NNTP BODY command and returns the reply code received from the +server. If no response is received, the function returns zero. The optional +argument <B><TT>aNumber</TT></B> specifies the number of an article whose +body should be retrieved. If <B><TT>Body()</TT></B> is called with the default +argument, the BODY command is sent to the server with no argument. +<B><TT>aMsgId</TT></B> specifies the message id of the article to access. +<P> +<FONT COLOR="teal"><B> int <A NAME="Head">Head</A>(int aNumber=(-1)) <BR> +int Head(const char* aMsgid) </B></FONT> +<P> +Sends the NNTP HEAD command and returns the reply code received from the +server. If no response is received, the function returns zero. The optional +argument <B><TT>aNumber</TT></B> specifies the number of an article whose +header lines should be retrieved. If <B><TT>Head()</TT></B> is called with +the default argument, the HEAD command is sent to the server with no argument. +<B><TT>aMsgId</TT></B> specifies the message id of the article to access. +<P> +<FONT COLOR="teal"><B> int <A NAME="Stat">Stat</A>(int aNumber=(-1)) <BR> +int Stat(const char* aMsgid) </B></FONT> +<P> +Sends the NNTP STAT command and returns the reply code received from the +server. If no response is received, the function returns zero. The optional +argument <B><TT>aNumber</TT></B> specifies the number of an article to access. +If <B><TT>Stat()</TT></B> is called with the default argument, the STAT command +is sent to the server with no argument. <B><TT>aMsgId</TT></B> specifies +the message id of the article to access. +<P> +<FONT COLOR="teal"><B> int <A NAME="Group">Group</A>(const char* aNewsgroupName) +</B></FONT> +<P> +Sends the NNTP GROUP command and returns the reply code received from the +server. The argument <B><TT>aNewsgroupName</TT></B> specifies the newgroup +to be selected. If no response is received, the function returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Help">Help</A>() </B></FONT> +<P> +Sends the NNTP HELP command and returns the reply code received from the +server. If no response is received, the function returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Ihave">Ihave</A>(const char* aMsgId) +</B></FONT> +<P> +Sends the NNTP IHAVE command and returns the reply code received from the +server. <B><TT>aMsgId</TT></B> specifies the message id of the article to +be sent. If no response is received, the function returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Last">Last</A>() </B></FONT> +<P> +Sends the NNTP LAST command and returns the reply code received from the +server. If no response is received, the function returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="List">List</A>() </B></FONT> +<P> +Sends the NNTP LIST command and returns the reply code received from the +server. If no response is received, the function returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Newgroups">Newgroups</A>(const char* +aDate, const char* aTime, DwBool aIsGmt=DwFalse, const char* aDistributions=0) +</B></FONT> +<P> +Sends the NNTP NEWGROUPS command and returns the reply code received from +the server. If no response is received, the function returns zero. +<B><TT>aDate</TT></B> is the date in the form YYMMDD, where YY is the two +digit year, MM is the month, and DD is the day of the month. +<B><TT>aTime</TT></B> is the time in the form HHMMSS, where HH is hours, +MM is minutes, and SS is seconds. If <B><TT>aIsGmt</TT></B> is true, the +optional GMT argument will be sent. <B><TT>aDistributions</TT></B> specifies +the optional list of distribution groups. +<P> +<FONT COLOR="teal"><B> int <A NAME="Newnews">Newnews</A>(const char* aNewsgroups, +const char* aDate, const char* aTime, DwBool aIsGmt=DwFalse, const char* +aDistribution=0) </B></FONT> +<P> +Sends the NNTP NEWNEWS command and returns the reply code received from the +server. If no response is received, the function returns zero. +<B><TT>aNewsgroups</TT></B> is the newsgroups argument for the command. +<B><TT>aDate</TT></B> is the date in the form YYMMDD, where YY is the two +digit year, MM is the month, and DD is the day of the month. +<B><TT>aTime</TT></B> is the time in the form HHMMSS, where HH is hours, +MM is minutes, and SS is seconds. If <B><TT>aIsGmt</TT></B> is true, the +optional GMT argument will be sent. <B><TT>aDistributions</TT></B> specifies +the optional list of distribution groups. +<P> +<FONT COLOR="teal"><B> int <A NAME="Next">Next</A>() </B></FONT> +<P> +Sends the NNTP NEXT command and returns the reply code received from the +server. If no response is received, perhaps because of an error, the function +returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Post">Post</A>() </B></FONT> +<P> +Sends the NNTP POST command and returns the reply code received from the +server. If no response is received, perhaps because of an error, the function +returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Quit">Quit</A>() </B></FONT> +<P> +Sends the NNTP QUIT command and returns the reply code received from the +server. If no response is received, perhaps because of an error, the function +returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Slave">Slave</A>() </B></FONT> +<P> +Sends the NNTP SLAVE command and returns the reply code received from the +server. If no response is received, perhaps because of an error, the function +returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="SendData">SendData</A>(const DwString& +aStr) <BR> +int SendData(const char* aBuf, int aBufLen) </B></FONT> +<P> +Sends bulk data to the server and returns the reply code received. A bulk +data transfer follows a POST or IHAVE command and is used to send a complete +article to the server. +<P> +In the current implementation, <B><TT>SendData()</TT></B> does not convert +end of line characters, so it is your responsibility to convert the end of +line characters to CR LF, if necessary. (You may use the utility function +<B><TT>DwToCrLfEol()</TT></B> to do the conversion.) +<B><TT>SendData()</TT></B> will perform the character stuffing to protect +'.' at the beginning of a line, and it will append the final [CR LF] '.' +CR LF. It is possible to divide the data and make multiple calls to +<B><TT>SendData()</TT></B>; however, this may cause problems in the current +implementation if a CR LF '.' sequence is split between calls. +</BODY></HTML> diff --git a/mimelib/doc/param.html b/mimelib/doc/param.html new file mode 100644 index 000000000..786f65bc5 --- /dev/null +++ b/mimelib/doc/param.html @@ -0,0 +1,189 @@ +<HTML> +<HEAD> + <TITLE> DwParameter Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwParameter -- Class representing a MIME field body parameter +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwParameter : public <A HREF="msgcmp.html">DwMessageComponent</A> { + + friend class DwMediaType; + +public: + + <A HREF="param.html#DwParameter">DwParameter</A>(); + <A HREF="param.html#DwParameter">DwParameter</A>(const DwParameter& aParam); + <A HREF="param.html#DwParameter">DwParameter</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwParameter(); + const DwParameter& <A HREF="param.html#op_eq">operator =</A> (const DwParameter& aParam); + virtual void <A HREF="param.html#Parse">Parse</A>(); + virtual void <A HREF="param.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="param.html#Clone">Clone</A>() const; + const DwString& <A HREF="param.html#Attribute">Attribute</A>() const; + void <A HREF="param.html#SetAttribute">SetAttribute</A>(const DwString& aAttribute); + const DwString& <A HREF="param.html#Value">Value</A>() const; + void <A HREF="param.html#SetValue">SetValue</A>(const DwString& aValue); + DwParameter* <A HREF="param.html#Next">Next</A>() const ; + void <A HREF="param.html#SetNext">SetNext</A>(DwParameter* aParam); + static DwParameter* <A HREF="param.html#NewParameter">NewParameter</A>(const DwString& aStr, + DwMessageComponent* aParent); + static DwParameter* (*<A HREF="param.html#sNewParameter">sNewParameter</A>)(const DwString&, DwMessageComponent*); + +public: + + virtual void <A HREF="param.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="param.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwParameter</TT></B> represents the <I>parameter</I> component of +the Content-Type header field as described in RFC-2045. A parameter consists +of an attribute/value pair. <B><TT>DwParameter</TT></B> has member functions +for getting or setting a parameter's attribute and value. +<P> +A <B><TT>DwParameter</TT></B> object may be included in a list of +<B><TT>DwParameter</TT></B> objects. You can get the next +<B><TT>DwParameter</TT></B> object in the list by calling the member function +<B><TT>Next()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwParameter">DwParameter</A>() <BR> +DwParameter(const DwParameter& aParam) <BR> +DwParameter(const DwString& aStr, DwMessageComponent* aParent=0) +</B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwParameter</TT></B> object's string representation to the empty string +and sets its parent to NULL. +<P> +The second constructor is the copy constructor, which copies the string +representation, attribute, and value from <B><TT>aParam</TT></B>. The parent +of the new <B><TT>DwParameter</TT></B> object is set to NULL. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwParameter</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is NULL, +<B><TT>aParent</TT></B> should point to an object of a class derived from +<B><TT>DwMediaType</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwParameter& <A NAME="op_eq">operator =</A> +(const DwParameter& aParam) </B></FONT> +<P> +This is the assignment operator. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the parse method for <B><TT>DwParameter</TT></B> objects. It should +be called immediately after the string representation is modified and before +the parts of the broken-down representation are accessed. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +executes the assemble method for <B><TT>DwParameter</TT></B> objects. It +should be called whenever one of the object's attributes is changed in order +to assemble the string representation from its broken-down representation. +It will be called automatically for this object by the parent object's +<B><TT>Assemble()</TT></B> member function if the is-modified flag is set. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwParameter</TT></B> on the free store that has the +same value as this <B><TT>DwParameter</TT></B> object. The basic idea is +that of a ``virtual copy constructor.'' +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="Attribute">Attribute</A>() const </B></FONT> +<P> +Returns the attribute contained by this parameter. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetAttribute">SetAttribute</A>(const +DwString& aAttribute) </B></FONT> +<P> +Sets the attribute contained by this parameter. +<P> +<FONT COLOR="teal"><B> const DwString& <A NAME="Value">Value</A>() const +</B></FONT> +<P> +Returns the value contained by this parameter. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetValue">SetValue</A>(const DwString& +aValue) </B></FONT> +<P> +Sets the value contained by this parameter. +<P> +<FONT COLOR="teal"><B> DwParameter* <A NAME="Next">Next</A>() const +</B></FONT> +<P> +Returns the next <B><TT>DwParameter</TT></B> object in the list. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetNext">SetNext</A>(DwParameter* aParam) +</B></FONT> +<P> +Returns the next <B><TT>DwParameter</TT></B> object in the list. Since +<B><TT>DwMediaType</TT></B> has member functions for adding +<B><TT>DwParameter</TT></B> objects to its list, you should avoid using this +function. +<P> +<FONT COLOR="teal"><B> static DwParameter* +<A NAME="NewParameter">NewParameter</A>(const DwString& aStr, +DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwParameter</TT></B> object on the free store. If the +static data member <B><TT>sNewParameter</TT></B> is NULL, this member function +will create a new <B><TT>DwParameter</TT></B> and return it. Otherwise, +<B><TT>NewParameter()</TT></B> will call the user-supplied function pointed +to by <B><TT>sNewParameter</TT></B>, which is assumed to return an object +from a class derived from <B><TT>DwParameter</TT></B>, and return that object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwParameter* +(*<A NAME="sNewParameter">sNewParameter</A>)(const DwString&, +DwMessageComponent*) </B></FONT> +<P> +If <B><TT>sNewParameter</TT></B> is not NULL, it is assumed to point to a +user-supplied function that returns an object from a class derived from +<B><TT>DwParameter</TT></B>. +</BODY></HTML> diff --git a/mimelib/doc/pop.html b/mimelib/doc/pop.html new file mode 100644 index 000000000..5bb4ed67c --- /dev/null +++ b/mimelib/doc/pop.html @@ -0,0 +1,286 @@ +<HTML> +<HEAD> + <TITLE> DwPopClient Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwPopClient -- Class for handling the client side of a POP session +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwPopClient : public <A HREF="protocol.html">DwProtocolClient</A> { + +public: + + enum { + kCmdNoCommand=0, + kCmdUser, + kCmdPass, + kCmdQuit, + kCmdStat, + kCmdList, + kCmdRetr, + kCmdDele, + kCmdNoop, + kCmdRset, + kCmdApop, + kCmdTop, + kCmdUidl + }; + <A HREF="pop.html#DwPopClient">DwPopClient</A>(); + virtual ~DwPopClient(); + virtual int <A HREF="pop.html#Open">Open</A>(const char* aServer, DwUint16 aPort=110); + DwObserver* <A HREF="pop.html#SetObserver">SetObserver</A>(DwObserver* aObserver); + int <A HREF="pop.html#StatusCode">StatusCode</A>() const; + const DwString& <A HREF="pop.html#SingleLineResponse">SingleLineResponse</A>() const; + const DwString& <A HREF="pop.html#MultiLineResponse">MultiLineResponse</A>() const; + int <A HREF="pop.html#User">User</A>(const char* aName); + int Pass(const char* a<A HREF="pop.html#Pass">Pass</A>wd); + int <A HREF="pop.html#Quit">Quit</A>(); + int <A HREF="pop.html#Stat">Stat</A>(); + int <A HREF="pop.html#List">List</A>(); + int <A HREF="pop.html#List">List</A>(int aMsg); + int <A HREF="pop.html#Retr">Retr</A>(int aMsg); + int <A HREF="pop.html#Dele">Dele</A>(int aMsg); + int <A HREF="pop.html#Noop">Noop</A>(); + int <A HREF="pop.html#Rset">Rset</A>(); + int <A HREF="pop.html#Apop">Apop</A>(const char* aName, const char* aDigest); + int <A HREF="pop.html#Top">Top</A>(int aMsg, int aNumLines); + int <A HREF="pop.html#Uidl">Uidl</A>(); + int <A HREF="pop.html#Uidl">Uidl</A>(int aMsg); +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwPopClient</TT></B> is a class that handles the client side of a +POP session. Specifically, <B><TT>DwPopClient</TT></B> provides facilities +for opening a connection to a POP server, sending commands to the server, +receiving responses from the server, and closing the connection. The protocol +implemented is the Post Office Protocol version 3, as specified in RFC-1939. +<P> +<B><TT>DwPopClient</TT></B> is derived from +<B><TT><A HREF="protocol.html">DwProtocolClient</A></TT></B>. For information +about inherited member functions, especially member functions for detecting +failures or errors, see the man page for +<B><TT>DwProtocolClient</TT></B>. +<P> +In a POP session, the client sends commands to the server and receives responses +from the server. A client command consists of a command word and zero or +more argument words. A server response consists of a single line status response, +which may be followed immediately by a multi-line response. The first word +of the status response is either +OK or -ERR, indicating the success or failure +of the command. The status line may also contain other information requested +by the client. +<P> +<B><TT>DwPopClient</TT></B> has only a default constructor. On Win32 platforms, +it is possible for the constructor to fail. (It calls WSAStartup().) You +should verify that the constructor succeeded by calling the inherited member +function <B><TT>DwProtocolClient::LastError()</TT></B> and checking for a +zero return value. +<P> +To open a connection to the server, call the member function +<B><TT>Open()</TT></B> with the name of the server as an argument. +<B><TT>Open()</TT></B> accepts an optional argument that specifies the TCP +port that the server listens to. The default port is the standard POP port +(110). <B><TT>Open()</TT></B> may fail, so you should check the return value +to verify that it succeeded. To close the connection, call the inherited +member function <B><TT>DwProtocolClient::Close()</TT></B>. To check if a +connection is open, call the inherited member function +<B><TT>DwProtocolClient::IsOpen()</TT></B>. <B><TT>IsOpen()</TT></B> returns +a boolean value that indicates whether or not a call to +<B><TT>Open()</TT></B> was successful; it will not detect failure in the +network or a close operation by the remote host. +<P> +For each POP command, <B><TT>DwPopClient</TT></B> has a member function that +sends that command and receives the server's response. If the command takes +any arguments, then those arguments are passed as function arguments to the +command function. The command functions return the first character of the +server's response, which will be '+' if the command succeeded or '-' if the +command failed. In some cases, because of a communications error or some +other error, it is not possible for the command function to send the command +or receive the response. When this happens, the command function will return +0. You can determine the precise error or failure by calling the inherited +member functions <B><TT>DwProtocolClient::LastError()</TT></B> or +<B><TT>DwProtocolClient::LastFailure()</TT></B>. +<P> +After each command is sent, <B><TT>DwPopClient</TT></B> receives the server's +response and remembers it. The member function +<B><TT>StatusCode()</TT></B> returns the first character of the server's +status response; it will be '+' or '-', indicating success or failure, or +zero if no response was received from the server. +<B><TT>SingleLineResponse()</TT></B> returns the entire single line status +response from the server, including the initial "+OK" or "-ERR" status word. +<P> +The server sends a single-line response, including a status code, for all +POP commands. For some commands, such as when the client requests a mail +message, the server sends a multi-line text response immediately following +the single-line status response. Multi-line text responses can be received +in either of two ways. The simplest way is to call the member function +<B><TT>MultiLineResponse()</TT></B> after a command completes successfully. +This simple method works fine for non-interactive applications. It can be +a problem in interactive applications, however, because there is no data +to display to a user until the entire multi-line response is retrieved. An +alternative method allows your program to retrieve the multi-line response +one line at a time as it is received. To use this method, you must define +a subclass of <B><TT>DwObserver</TT></B> and assign an object of that class +to the <B><TT>DwPopClient</TT></B> object using the member function +<B><TT>SetObserver()</TT></B>. <B><TT>DwObserver</TT></B> is an abstract +class, declared in protocol.h, that has just one pure virtual member function +<B><TT>Notify()</TT></B>. After each line of the multi-line response is received, +<B><TT>DwPopClient</TT></B> will call the <B><TT>Notify()</TT></B> member +function of its assigned <B><TT>DwObserver</TT></B> object. Each invocation +of <B><TT>Notify()</TT></B> should call the <B><TT>DwPopClient</TT></B> member +function <B><TT>MultiLineResponse()</TT></B> to retrieve the next line of +the text response. Note that you cannot use both of these methods at the +same time: if an observer is assigned, +<B><TT>MultiLineResponse()</TT></B> returns only the last line received, +not the entire multi-line response. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwPopClient">DwPopClient</A>() </B></FONT> +<P> +Initializes the <B><TT>DwPopClient</TT></B> object. It is possible for the +constructor to fail. To verify that the constructor succeeded, call the member +function <B><TT>LastError()</TT></B> and check that it returns zero. (In +the Win32 implementation, the constructor calls the Winsock function +<B><TT>WSAStartup()</TT></B>, which may fail.) +<P> +<FONT COLOR="teal"><B> virtual int <A NAME="Open">Open</A>(const char* aServer, +DwUint16 aPort=110) </B></FONT> +<P> +Opens a TCP connection to the server <B><TT>aServer</TT></B> at port +<B><TT>aPort</TT></B>. <B><TT>aServer</TT></B> may be either a host name, +such as "news.acme.com" or an IP number in dotted decimal format, such as +"147.81.64.60". The default value for <B><TT>aPort</TT></B> is 110, the +well-known port for POP3 assigned by the Internet Assigned Numbers Authority +(IANA). +<P> +If the connection attempt succeeds, the server sends a response. +<B><TT>Open()</TT></B> returns the server's status code ('+' or '-'). The +full response from the server can be retrieved by calling +<B><TT>SingleLineResponse()</TT></B>. +<P> +If the connection attempt fails, <B><TT>Open()</TT></B> returns 0. To determine +what error occurred when a connection attempt fails, call the inherited member +function <B><TT>DwProtocolClient::LastError()</TT></B>. To determine if a +failure also occurred, call the inherited member function +<B><TT>DwProtocolClient::LastFailure()</TT></B>. +<P> +<FONT COLOR="teal"><B> DwObserver* +<A NAME="SetObserver">SetObserver</A>(DwObserver* aObserver) </B></FONT> +<P> +Sets the observer object that interacts with the +<B><TT>DwPopClient</TT></B> object to retrieve a multi-line response. If +an observer is set, <B><TT>DwPopClient</TT></B> will call the observer's +<B><TT>Notify()</TT></B> method after each line of the multi-line response +is received. To remove an observer, call <B><TT>SetObserver()</TT></B> with +a NULL argument. <B><TT>SetObserver()</TT></B> returns the previously set +observer, or NULL if no observer was previously set. +<P> +<FONT COLOR="teal"><B> int <A NAME="StatusCode">StatusCode</A>() const +</B></FONT> +<P> +Returns the status code received from the server in response to the last +client command. The status codes in POP3 are '+', indicating success, and +'-', indicating failure. If no response was received, +<B><TT>StatusCode()</TT></B> returns zero. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="SingleLineResponse">SingleLineResponse</A>() const </B></FONT> +<P> +Returns the single line status response last received from the server. If +no response was received, perhaps because of a communications failure, +<B><TT>SingleLineResponse()</TT></B> returns an empty string. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="MultiLineResponse">MultiLineResponse</A>() const </B></FONT> +<P> +If no observer is set for this object, +<B><TT>MultiLineResponse()</TT></B> returns a string that comprises the entire +sequence of lines received from the server. Otherwise, if an observer +<I>is</I> set for this object, <B><TT>MultiLineResponse()</TT></B> returns +only the most recent line received. +<P> +<FONT COLOR="teal"><B> int <A NAME="User">User</A>(const char* aName) +</B></FONT> +<P> +Sends the USER command and returns the status code received from the server. +If no response is received, the function returns zero. +<B><TT>aName</TT></B> is the name of the user, which is sent in the command. +<P> +<FONT COLOR="teal"><B> int <A NAME="Pass">Pass</A>(const char* aPasswd) +</B></FONT> +<P> +Sends the PASS command and returns the status code received from the server. +If no response is received, the function returns zero. +<B><TT>aPasswd</TT></B> is the password, which is sent in the command. +<P> +<FONT COLOR="teal"><B> int <A NAME="Quit">Quit</A>() </B></FONT> +<P> +Sends the QUIT command and returns the status code received from the server. +If no response is received, the function returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Stat">Stat</A>() </B></FONT> +<P> +Sends the STAT command and returns the status code received from the server. +If no response is received, the function returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="List">List</A>() <BR> +int List(int aMsg) </B></FONT> +<P> +Sends the LIST command, with or without a message number, and returns the +status code received from the server. If no response is received, the function +returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Retr">Retr</A>(int aMsg) </B></FONT> +<P> +Sends the RETR command and returns the status code received from the server. +If no response is received, the function returns zero. +<B><TT>aMsg</TT></B> is the message number, which is sent in the command. +<P> +<FONT COLOR="teal"><B> int <A NAME="Dele">Dele</A>(int aMsg) </B></FONT> +<P> +Sends the DELE command and returns the status code received from the server. +If no response is received, the function returns zero. +<B><TT>aMsg</TT></B> is the message number, which is sent in the command. +<P> +<FONT COLOR="teal"><B> int <A NAME="Noop">Noop</A>() </B></FONT> +<P> +Sends the NOOP command and returns the status code received from the server. +If no response is received, the function returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Rset">Rset</A>() </B></FONT> +<P> +Sends the RSET command and returns the status code received from the server. +If no response is received, the function returns zero. +<P> +<FONT COLOR="teal"><B> int <A NAME="Apop">Apop</A>(const char* aName, const +char* aDigest) </B></FONT> +<P> +Sends the APOP command and returns the status code received from the server. +If no response is received, the function returns zero. +<B><TT>aName</TT></B> is the name of the user, which is sent in the command. +<B><TT>aDigest</TT></B> is the digest argument for the command. +<P> +<FONT COLOR="teal"><B> int <A NAME="Top">Top</A>(int aMsg, int aNumLines) +</B></FONT> +<P> +Sends the TOP command and returns the status code received from the server. +If no response is received, the function returns zero. +<B><TT>aMsg</TT></B> is the message number. <B><TT>aNumLines</TT></B> is +the number of lines to send. +<P> +<FONT COLOR="teal"><B> int <A NAME="Uidl">Uidl</A>() <BR> +int Uidl(int aMsg) </B></FONT> +<P> +Sends the TOP command, with or without a message number, and returns the +status code received from the server. If no response is received, the function +returns zero. +</BODY></HTML> diff --git a/mimelib/doc/protocol.html b/mimelib/doc/protocol.html new file mode 100644 index 000000000..28bb81db6 --- /dev/null +++ b/mimelib/doc/protocol.html @@ -0,0 +1,274 @@ +<HTML> +<HEAD> + <TITLE> DwProtocolClient Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwProtocolClient -- Base class for all protocol clients +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwProtocolClient { + +public: + + enum Failure { + kFailNoFailure = 0, // No failure + kFailNoWinsock = 1, // A usable Winsock DLL could not be found + kFailNetDown = 2, // The network is down + kFailHostNotFound = 3, // The server was not found + kFailConnReset = 4, // The connection was reset + kFailNetUnreachable = 5, // The network is unreachable + kFailTimedOut = 6, // Timed out while waiting for an operation + // to complete + kFailConnDropped = 7, + kFailConnRefused = 8, + kFailNoResources = 9 + }; + + enum Error { + kErrNoError = 0, + kErrUnknownError = 0x4000, + kErrBadParameter = 0x4001, + kErrBadUsage = 0x4002, + kErrNoWinsock = 0x4003, // Win32 + kErrHostNotFound = 0x5000, // UNIX + kErrTryAgain = 0x5001, // UNIX + kErrNoRecovery = 0x5002, // UNIX + kErrNoData = 0x5003, // UNIX + kErrNoAddress = 0x5004, // UNIX + }; + +protected: + + <A HREF="protocol.html#DwProtocolClient">DwProtocolClient</A>(); + +public: + + virtual <A HREF="protocol.html#~DwProtocolClient">~DwProtocolClient</A>(); + virtual int <A HREF="protocol.html#Open">Open</A>(const char* aServer, DwUint16 aPort); + DwBool <A HREF="protocol.html#IsOpen">IsOpen</A>() const; + int <A HREF="protocol.html#Close">Close</A>(); + int <A HREF="protocol.html#SetReceiveTimeout">SetReceiveTimeout</A>(int aSecs); + int <A HREF="protocol.html#LastCommand">LastCommand</A>() const; + int <A HREF="protocol.html#LastFailure">LastFailure</A>() const; + const char* <A HREF="protocol.html#LastFailureStr">LastFailureStr</A>() const; + int <A HREF="protocol.html#LastError">LastError</A>() const; + const char* <A HREF="protocol.html#LastErrorStr">LastErrorStr</A>() const; + +protected: + + enum { + kWSAStartup=1, // Win32 + kgethostbyname, + ksocket, + ksetsockopt, + kconnect, + ksend, + krecv, + kclose, // UNIX + kclosesocket, // Win32 + kselect + }; + DwBool mIsDllOpen; + DwBool mIsOpen; + SOCKET mSocket; + DwUint16 mPort; + char* mServerName; + int mReceiveTimeout; + int mLastCommand; + int mFailureCode; + const char* mFailureStr; + int mErrorCode; + const char* mErrorStr; + virtual void <A HREF="protocol.html#HandleError">HandleError</A>(int aErrorCode, int aSystemCall); + int <A HREF="protocol.html#PSend">PSend</A>(const char* aBuf, int aBufLen); + int <A HREF="protocol.html#PReceive">PReceive</A>(char* aBuf, int aBufSize); +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwProtocolClient</TT></B> is the base class for other classes that +implement specific protocols, such as SMTP, POP, and NNTP. +<B><TT>DwProtocolClient</TT></B> serves two purposes. First, It combines +operations common to all its derived classes, such as opening a TCP connection +to the server. Second, it provides a platform-independent interface to the +network services required by its subclasses. +<P> +There are two separate implementations of +<B><TT>DwProtocolClient</TT></B>: one for Berkeley sockets under UNIX, and +one for Winsock under Win32. The interface is the same for both implementations, +thus providing platform independence. +<P> +There are two platform-specific details that you should be aware of. First, +if you are writing a UNIX program, you should be sure to handle the SIGPIPE +signal. This signal is raised when a program tries to write to a TCP connection +that was shutdown by the remote host. The default action for this signal +is to terminate the program. To prevent this from happening in your program, +you should either catch the signal or tell the operating system to ignore +it. Second, if you are writing a Win32 application for Windows NT or Windows95, +you should be aware of the fact that the constructor calls the Winsock function +<B><TT>WSAStartup()</TT></B> to initialize the Winsock DLL. (The destructor +calls <B><TT>WSACleanup()</TT></B>.) Because it is possible for +<B><TT>WSAStartup()</TT></B> to fail, it is also possible that the constructor +may fail. To verify that the constructor has succeeded, call the member function +<B><TT>LastError()</TT></B> and check that it returns zero. +<P> +To open a connection to a server, call <B><TT>Open()</TT></B> with the server +name and TCP port number as arguments. <B><TT>Open()</TT></B> is declared +virtual; derived classes may override this member function. +<B><TT>Open()</TT></B> may fail, so you should check the return value to +verify that it succeeded. To close the connection, call +<B><TT>Close()</TT></B>. To check if a connection is open, call +<B><TT>IsOpen()</TT></B>. <B><TT>IsOpen()</TT></B> returns a value that indicates +whether or not a call to <B><TT>Open()</TT></B> was successful; it will not +detect failure in the network or a close operation by the remote host. +<P> +<B><TT>DwProtocolClient</TT></B> sets a timeout on receive operations on +the TCP connection. The default value of the timeout period is 90 seconds. +To change the default value, call <B><TT>SetReceiveTimeout()</TT></B> and +pass the new value as an argument. +<P> +Whenever <B><TT>DwProtocolClient</TT></B> cannot complete an operation, it +is because an error has occurred. Most member functions indicate that an +error has occurred via their return values. For most member functions, a +return value of -1 indicates an error. To get the specific error that has +occurred, call <B><TT>LastError()</TT></B>, which returns either the system +error code or a MIME++ defined error code. To get a text string that describes +the error, call <B><TT>LastErrorStr()</TT></B>. +<P> +Some errors are also considered "failures." A failure occurs when an operation +cannot be completed because of conditions external to the program. For example, +a failure occurs when the network is down or when an application's user enters +bad input. Errors that occur because of programmer error are not considered +failures. If an error occurs, you should call <B><TT>LastError()</TT></B> +to determine the error, but you should also call +<B><TT>LastFailure()</TT></B> to determine if a failure occurred. In interactive +applications, failures should always be reported to the application's user. +To get a text string that describes a failure, call +<B><TT>LastFailureStr()</TT></B>. +<P> +It is possible to translate the error and failure message strings to a language +other than English. To do this, you may override the virtual function +<B><TT>HandleError()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> virtual +<A NAME="~DwProtocolClient">~DwProtocolClient</A>() </B></FONT> +<P> +Frees the resources used by this object. In a Win32 environment, the destructor +calls <B><TT>WSACleanup()</TT></B>. +<P> +<FONT COLOR="teal"><B> virtual int <A NAME="Open">Open</A>(const char* aServer, +DwUint16 aPort) </B></FONT> +<P> +Opens a TCP connection to the server <B><TT>aServer</TT></B> at port +<B><TT>aPort</TT></B>. <B><TT>aServer</TT></B> may be either a host name, +such as "smtp.acme.com" or an IP number in dotted decimal format, such as +"147.81.64.59". If the connection attempt succeeds, +<B><TT>Open()</TT></B> returns 0; othewise, it returns -1. To determine what +error occurred when the connection attempt fails, call the member function +<B><TT>LastError()</TT></B>. To determine if a failure also occurred, call +the member function <B><TT>LastFailure()</TT></B>. +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="IsOpen">IsOpen</A>() const </B></FONT> +<P> +Returns true value if a connection to the server is open. +<B><TT>IsOpen()</TT></B> will return a true value if a call to +<B><TT>Open()</TT></B> was successful; it will not detect failure in the +network or a close operation by the remote host. +<P> +<FONT COLOR="teal"><B> int <A NAME="Close">Close</A>() </B></FONT> +<P> +Closes the connection to the server. Returns 0 if successful, or returns +-1 if unsuccessful. +<P> +<FONT COLOR="teal"><B> int +<A NAME="SetReceiveTimeout">SetReceiveTimeout</A>(int aSecs) </B></FONT> +<P> +Changes the default timeout for receive operations on the socket to +<B><TT>aSecs</TT></B> seconds. The default value is 90 seconds. +<P> +<FONT COLOR="teal"><B> int <A NAME="LastCommand">LastCommand</A>() const +</B></FONT> +<P> +Returns an enumerated value indicating the last command sent to the server. +Enumerated values are defined in subclasses of +<B><TT>DwProtocolClient</TT></B>. +<P> +<FONT COLOR="teal"><B> int <A NAME="LastFailure">LastFailure</A>() const +</B></FONT> +<P> +Returns an enumerated value indicating what failure last occurred. +<P> +<FONT COLOR="teal"><B> const char* +<A NAME="LastFailureStr">LastFailureStr</A>() const </B></FONT> +<P> +Returns a failure message string associated with the failure code returned +by <B><TT>LastFailure()</TT></B>. +<P> +<FONT COLOR="teal"><B> int <A NAME="LastError">LastError</A>() const +</B></FONT> +<P> +Returns an error code for the last error that occurred. Normally, the error +code returned is an error code returned by a system call; +<B><TT>DwProtocolClient</TT></B> does no translation of error codes returned +by system calls. In some cases, an error code defined by MIME++ may returned +to indicate improper use of the <B><TT>DwProtocolClient</TT></B> class. +<P> +<FONT COLOR="teal"><B> const char* <A NAME="LastErrorStr">LastErrorStr</A>() +const </B></FONT> +<P> +Returns an error message string associated with the error code returned by +<B><TT>LastError()</TT></B>. +<H2> + <FONT COLOR="navy"> Protected Member Functions </FONT> +</H2> +<P> +<B><FONT COLOR="teal"> <A NAME="DwProtocolClient">DwProtocolClient</A>() +</FONT></B> +<P> +Initializes the <B><TT>DwProtocolClient</TT></B> object. In a Win32 environment, +this constructor calls <B><TT>WSAStartup()</TT></B> to initialize the Winsock +DLL. To verify that the DLL was initialized successfully, call the member +function <B><TT>LastError()</TT></B> and verify that it returns zero. +<P> +<B><FONT COLOR="teal"> virtual void <A NAME="HandleError">HandleError</A>(int +aErrorCode, int aSystemCall) </FONT></B> +<P> +Interprets error codes. <B><TT>aErrorCode</TT></B> is an error code, which +may be a system error code, or an error code defined by +<B><TT>DwProtocolClient</TT></B>. <B><TT>aSystemCall</TT></B> is an enumerated +value defined by <B><TT>DwProtocolClient</TT></B> that indicates the last +system call made, which should be the system call that set the error code. +<B><TT>HandleError()</TT></B> sets values for <B><TT>mErrorStr</TT></B>, +<B><TT>mFailureCode</TT></B>, and <B><TT>mFailureStr</TT></B>. +<P> +<B><FONT COLOR="teal"> int <A NAME="PSend">PSend</A>(const char* aBuf, int +aBufLen) </FONT></B> +<P> +Sends <B><TT>aBufLen</TT></B> characters from the buffer +<B><TT>aBuf</TT></B>. Returns the number of characters sent. If the number +of characters sent is less than the number of characters specified in +<B><TT>aBufLen</TT></B>, the caller should call +<B><TT>LastError()</TT></B> to determine what, if any, error occurred. To +determine if a failure also occurred, call the member function +<B><TT>LastFailure()</TT></B>. +<P> +<B><FONT COLOR="teal"> int <A NAME="PReceive">PReceive</A>(char* aBuf, int +aBufSize) </FONT></B> +<P> +Receives up to <B><TT>aBufSize</TT></B> characters into the buffer +<B><TT>aBuf</TT></B>. Returns the number of characters received. If zero +is returned, the caller should call the member function +<B><TT>LastError()</TT></B> to determine what, if any, error occurred. To +determine if a failure also occurred, call the member function +<B><TT>LastFailure()</TT></B>. +</BODY></HTML> diff --git a/mimelib/doc/string.html b/mimelib/doc/string.html new file mode 100644 index 000000000..80db3700c --- /dev/null +++ b/mimelib/doc/string.html @@ -0,0 +1,717 @@ +<HTML> +<HEAD> + <TITLE> DwString Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwString -- String class +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwString { + +public: + + static const size_t <A HREF="string.html#npos">npos</A>; + <A HREF="string.html#DwString">DwString</A>(); + <A HREF="string.html#DwString">DwString</A>(const DwString& aStr, size_t aPos=0, size_t aLen=npos); + <A HREF="string.html#DwString">DwString</A>(const char* aBuf, size_t aLen); + <A HREF="string.html#DwString">DwString</A>(const char* aCstr); + <A HREF="string.html#DwString">DwString</A>(size_t aLen, char aChar); + <A HREF="string.html#DwString">DwString</A>(char* aBuf, size_t aSize, size_t aStart, size_t aLen); + virtual ~DwString(); + DwString& <A HREF="string.html#op_eq">operator =</A> (const DwString& aStr); + DwString& <A HREF="string.html#op_eq">operator =</A> (const char* aCstr); + DwString& <A HREF="string.html#op_eq">operator =</A> (char aChar); + size_t <A HREF="string.html#size">size</A>() const; + size_t <A HREF="string.html#length">length</A>() const; + size_t <A HREF="string.html#max_size">max_size</A>() const; + void <A HREF="string.html#resize">resize</A>(size_t aLen, char aChar); + void <A HREF="string.html#resize">resize</A>(size_t aLen); + size_t <A HREF="string.html#capacity">capacity</A>() const; + void <A HREF="string.html#reserve">reserve</A>(size_t aSize); + void <A HREF="string.html#clear">clear</A>(); + DwBool <A HREF="string.html#empty">empty</A>() const; + const char& <A HREF="string.html#op_brackets">operator []</A> (size_t aPos) const; + char& <A HREF="string.html#op_brackets">operator []</A> (size_t aPos); + const char& <A HREF="string.html#at">at</A>(size_t aPos) const; + char& <A HREF="string.html#at">at</A>(size_t aPos); + DwString& <A HREF="string.html#op_plus_eq">operator +=</A> (const DwString& aStr); + DwString& <A HREF="string.html#op_plus_eq">operator +=</A> (const char* aCstr); + DwString& <A HREF="string.html#op_plus_eq">operator +=</A> (char aChar); + DwString& <A HREF="string.html#append">append</A>(const DwString& aStr); + DwString& <A HREF="string.html#append">append</A>(const DwString& aStr, size_t aPos, size_t aLen); + DwString& <A HREF="string.html#append">append</A>(const char* aBuf, size_t aLen); + DwString& <A HREF="string.html#append">append</A>(const char* aCstr); + DwString& <A HREF="string.html#append">append</A>(size_t aLen, char aChar); + DwString& <A HREF="string.html#assign">assign</A>(const DwString& aStr); + DwString& <A HREF="string.html#assign">assign</A>(const DwString& aStr, size_t aPos, size_t aLen); + DwString& <A HREF="string.html#assign">assign</A>(const char* aBuf, size_t aLen); + DwString& <A HREF="string.html#assign">assign</A>(const char* aCstr); + DwString& <A HREF="string.html#assign">assign</A>(size_t aLen, char aChar); + DwString& <A HREF="string.html#insert">insert</A>(size_t aPos1, const DwString& aStr); + DwString& <A HREF="string.html#insert">insert</A>(size_t aPos1, const DwString& aStr, size_t aPos2, + size_t aLen2); + DwString& <A HREF="string.html#insert">insert</A>(size_t aPos1, const char* aBuf, size_t aLen2); + DwString& <A HREF="string.html#insert">insert</A>(size_t aPos1, const char* aCstr); + DwString& <A HREF="string.html#insert">insert</A>(size_t aPos1, size_t aLen2, char aChar); + DwString& <A HREF="string.html#erase">erase</A>(size_t aPos=0, size_t aLen=npos); + DwString& <A HREF="string.html#replace">replace</A>(size_t aPos1, size_t aLen1, const DwString& aStr); + DwString& <A HREF="string.html#replace">replace</A>(size_t aPos1, size_t aLen1, const DwString& aStr, + size_t aPos2, size_t aLen2); + DwString& <A HREF="string.html#replace">replace</A>(size_t aPos1, size_t aLen1, const char* aBuf, + size_t aLen2); + DwString& <A HREF="string.html#replace">replace</A>(size_t aPos1, size_t aLen1, const char* aCstr); + DwString& <A HREF="string.html#replace">replace</A>(size_t aPos1, size_t aLen1, size_t aLen2, char aChar); + size_t <A HREF="string.html#copy">copy</A>(char* aBuf, size_t aLen, size_t aPos=0) const; + void <A HREF="string.html#swap">swap</A>(DwString& aStr); + const char* <A HREF="string.html#c_str">c_str</A>() const; + const char* <A HREF="string.html#data">data</A>() const; + size_t <A HREF="string.html#find">find</A>(const DwString& aStr, size_t aPos=0) const; + size_t <A HREF="string.html#find">find</A>(const char* aBuf, size_t aPos, size_t aLen) const; + size_t <A HREF="string.html#find">find</A>(const char* aCstr, size_t aPos=0) const; + size_t <A HREF="string.html#find">find</A>(char aChar, size_t aPos=0) const; + size_t <A HREF="string.html#rfind">rfind</A>(const DwString& aStr, size_t aPos=npos) const; + size_t <A HREF="string.html#rfind">rfind</A>(const char* aBuf, size_t aPos, size_t aLen) const; + size_t <A HREF="string.html#rfind">rfind</A>(const char* aCstr, size_t aPos=npos) const; + size_t <A HREF="string.html#rfind">rfind</A>(char aChar, size_t aPos=npos) const; + size_t <A HREF="string.html#find_first_of">find_first_of</A>(const DwString& aStr, size_t aPos=0) const; + size_t <A HREF="string.html#find_first_of">find_first_of</A>(const char* aBuf, size_t aPos, size_t aLen) const; + size_t <A HREF="string.html#find_first_of">find_first_of</A>(const char* aCstr, size_t aPos=0) const; + size_t <A HREF="string.html#find_last_of">find_last_of</A>(const DwString& aStr, size_t aPos=npos) const; + size_t <A HREF="string.html#find_last_of">find_last_of</A>(const char* aBuf, size_t aPos, size_t aLen) const; + size_t <A HREF="string.html#find_last_of">find_last_of</A>(const char* aCstr, size_t aPos=npos) const; + size_t <A HREF="string.html#find_first_not_of">find_first_not_of</A>(const DwString& aStr, size_t aPos=0) const; + size_t <A HREF="string.html#find_first_not_of">find_first_not_of</A>(const char* aBuf, size_t aPos, size_t aLen) const; + size_t <A HREF="string.html#find_first_not_of">find_first_not_of</A>(const char* aCstr, size_t aPos=0) const; + size_t <A HREF="string.html#find_last_not_of">find_last_not_of</A>(const DwString& aStr, size_t aPos=npos) const; + size_t <A HREF="string.html#find_last_not_of">find_last_not_of</A>(const char* aBuf, size_t aPos, size_t aLen) const; + size_t <A HREF="string.html#find_last_not_of">find_last_not_of</A>(const char* aCstr, size_t aPos=npos) const; + DwString <A HREF="string.html#substr">substr</A>(size_t aPos=0, size_t aLen=npos) const; + int <A HREF="string.html#compare">compare</A>(const DwString& aStr) const; + int <A HREF="string.html#compare">compare</A>(size_t aPos1, size_t aLen1, const DwString& aStr) const; + int <A HREF="string.html#compare">compare</A>(size_t aPos1, size_t aLen1, const DwString& aStr, + size_t aPos2, size_t aLen2) const; + int <A HREF="string.html#compare">compare</A>(const char* aCstr) const; + int <A HREF="string.html#compare">compare</A>(size_t aPos1, size_t aLen1, const char* aBuf, + size_t aLen2=npos) const; + virtual const char* <A HREF="string.html#ClassName">ClassName</A>() const; + int <A HREF="string.html#ObjectId">ObjectId</A>() const; + void <A HREF="string.html#ConvertToLowerCase">ConvertToLowerCase</A>(); + void <A HREF="string.html#ConvertToUpperCase">ConvertToUpperCase</A>(); + void <A HREF="string.html#Trim">Trim</A>(); + void <A HREF="string.html#WriteTo">WriteTo</A>(ostream& aStrm) const; + int <A HREF="string.html#RefCount">RefCount</A>() const; + void <A HREF="string.html#TakeBuffer">TakeBuffer</A>(char* aBuf, size_t aSize, size_t aStart, size_t aLen); + void <A HREF="string.html#ReleaseBuffer">ReleaseBuffer</A>(char** aBuf, size_t* aSize, size_t* aStart, size_t* aLen); + void <A HREF="string.html#CopyTo">CopyTo</A>(DwString* aStr) const; + +protected: + + DwStringRep* mRep; + size_t mStart; + size_t mLength; + void _copy(); + void _replace(size_t aPos1, size_t aLen1, const char* aBuf, size_t aLen2); + void _replace(size_t aPos1, size_t aLen1, size_t aLen2, char aChar); + friend void mem_free(char*); + +public: + + virtual void <A HREF="string.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm) const; + virtual void <A HREF="string.html#CheckInvariants">CheckInvariants</A>() const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwString</TT></B> is the workhorse of the MIME++ library. Creating, +parsing, or otherwise manipulating MIME messages is basically a matter of +manipulating strings. <B><TT>DwString</TT></B> provides all the basic +functionality required of a string object, including copying, comparing, +concatenating, and so on. +<P> +<B><TT>DwString</TT></B> is similar to the <B><TT>string</TT></B> class that +is part of the proposed ANSI standard C++ library. Some of the member functions +present in the ANSI <B><TT>string</TT></B> are not present in +<B><TT>DwString</TT></B>: mostly these are the functions that deal with +iterators. <B><TT>DwString</TT></B> also includes some member functions and +class utility functions that are not a part of the ANSI +<B><TT>string</TT></B> class. These non-ANSI functions are easy to distinguish: +they all begin with upper-case letters, and all ANSI functions begin with +lower-case letters. The library classes themselves use only the ANSI +<B><TT>string</TT></B> functions. At some point in the future, MIME++ will +probably allow the option to substitute the ANSI <B><TT>string</TT></B> class +for <B><TT>DwString</TT></B>. +<P> +<B><TT>DwString</TT></B> makes extensive use of copy-on-write, even when +extracting substrings. It is this feature that distiguishes +<B><TT>DwString</TT></B> from most other string classes. +<B><TT>DwString</TT></B> also handles binary data, which can contain embedded +NUL characters. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwString">DwString</A>() <BR> +DwString(const DwString& aStr, size_t aPos=0, size_t aLen=npos) <BR> +DwString(const char* aBuf, size_t aLen) <BR> +DwString(const char* aCstr) <BR> +DwString(size_t aLen, char aChar) <BR> +DwString(char* aBuf, size_t aSize, size_t aStart, size_t aLen) </B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwString</TT></B> object's contents to be empty. +<P> +The second constructor is the copy constructor, which copies at most +<B><TT>aLen</TT></B> characters beginning at position +<B><TT>aPos</TT></B> from <B><TT>aStr</TT></B> to the new +<B><TT>DwString</TT></B> object. It will not copy more characters than what +are available in <B><TT>aStr</TT></B>. <B><TT>aPos</TT></B> must be less +than or equal to <B><TT>aStr.size()</TT></B>. +<P> +The third constructor copies <B><TT>aLen</TT></B> characters from the buffer +<B><TT>aBuf</TT></B> into the new <B><TT>DwString</TT></B> object. +<B><TT>aBuf</TT></B> need not be NUL-terminated and may contain NUL characters. +<P> +The fourth constructor copies the contents of the NUL-terminated string +<B><TT>aCstr</TT></B> into the new <B><TT>DwString</TT></B> object. +<P> +The fifth constructor sets the contents of the new +<B><TT>DwString</TT></B> object to be the character <B><TT>aChar</TT></B> +repeated <B><TT>aLen</TT></B> times. +<P> +The sixth constructor is an <I>advanced</I> constructor that sets the contents +of the new <B><TT>DwString</TT></B> object to the <B><TT>aLen</TT></B> characters +starting at offset <B><TT>aStart</TT></B> in the buffer +<B><TT>aBuf</TT></B>. <B><TT>aSize</TT></B> is the allocated size of +<B><TT>aBuf</TT></B>. This constructor is provided for efficiency in setting +a new <B><TT>DwString</TT></B>'s contents from a large buffer. It is efficient +because no copying takes place. Instead, <B><TT>aBuf</TT></B> becomes the +buffer used internally by the <B><TT>DwString</TT></B> object, which takes +responsibility for deleting the buffer. Because <B><TT>DwString</TT></B> +will free the buffer using <B><TT>delete []</TT></B>, the buffer should have +been allocated using <B><TT>new</TT></B>. See also: TakeBuffer(), and +ReleaseBuffer(). +<P> +<FONT COLOR="teal"><B> DwString& <A NAME="op_eq">operator =</A> (const +DwString& aStr) <BR> +DwString& operator = (const char* aCstr) <BR> +DwString& operator = (char aChar) </B></FONT> +<P> +Assigns the contents of the operand to this string. <B><TT>aCstr</TT></B> +must point to a NUL-terminated array of characters (a C string). Returns +<B><TT>*this</TT></B>. +<P> +<FONT COLOR="teal"><B> <A NAME="size">size</A>_t size() const </B></FONT> +<P> +Returns the number of characters in this string's contents. This member function +is identical to <B><TT>length()</TT></B> +<P> +<FONT COLOR="teal"><B> size_t <A NAME="length">length</A>() const </B></FONT> +<P> +Returns the number of characters in this string's contents. This member function +is identical to <B><TT>size()</TT></B> +<P> +<FONT COLOR="teal"><B> size_t <A NAME="max_size">max_size</A>() const +</B></FONT> +<P> +Returns the maximum length that this string can ever attain. +<P> +<FONT COLOR="teal"><B> void <A NAME="resize">resize</A>(size_t aLen, char +aChar) <BR> +void resize(size_t aLen) </B></FONT> +<P> +Changes the length of this string. If the string shortened, the final characters +are truncated. If the string is expanded, the added characters will be NULs +or the character specified by <B><TT>aChar</TT></B>. +<P> +<FONT COLOR="teal"><B> size_t <A NAME="capacity">capacity</A>() const +</B></FONT> +<P> +Returns the size of the internal buffer used for this string, which will +always be greater than or equal to the length of the string. +<P> +<FONT COLOR="teal"><B> void <A NAME="reserve">reserve</A>(size_t aSize) +</B></FONT> +<P> +If <B><TT>aSize</TT></B> is greater than the current capacity of this string, +this member function will increase the capacity to be at least +<B><TT>aSize</TT></B>. +<P> +<FONT COLOR="teal"><B> void <A NAME="clear">clear</A>() </B></FONT> +<P> +Sets this string's contents to be empty. +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="empty">empty</A>() const </B></FONT> +<P> +Returns a true value if and only if the contents of this string are empty. +<P> +<FONT COLOR="teal"><B> const char& <A NAME="op_brackets">operator []</A> +(size_t aPos) const <BR> +char& operator [] (size_t aPos) </B></FONT> +<P> +Returns <B><TT>DwString::at(aPos) const</TT></B> or +<B><TT>DwString::at(aPos)</TT></B>. Note that the non-const version always +assumes that the contents will be modified and therefore always copies a +shared internal buffer before it returns. +<P> +<FONT COLOR="teal"><B> const char& <A NAME="at">at</A>(size_t aPos) const +<BR> +char& at(size_t aPos) </B></FONT> +<P> +Returns the character at position <B><TT>aPos</TT></B> in the string's contents. +The non-const version returns an lvalue that may be assigned to. Note that +the non-const version always assumes that the contents will be modified and +therefore always copies a shared internal buffer before it returns. +<P> +<FONT COLOR="teal"><B> DwString& <A NAME="op_plus_eq">operator +=</A> +(const DwString& aStr) <BR> +DwString& operator += (const char* aCstr) <BR> +DwString& operator += (char aChar) </B></FONT> +<P> +Appends the contents of the operand to this string. <B><TT>aCstr</TT></B> +must point to a NUL-terminated array of characters (a C string). Returns +<B><TT>*this</TT></B>. +<P> +<FONT COLOR="teal"><B> DwString& <A NAME="append">append</A>(const +DwString& aStr) <BR> +DwString& append(const DwString& aStr, size_t aPos, size_t aLen) +<BR> +DwString& append(const char* aBuf, size_t aLen) <BR> +DwString& append(const char* aCstr) <BR> +DwString& append(size_t aLen, char aChar) </B></FONT> +<P> +Appends characters to (the end of) this string. Returns +<B><TT>*this</TT></B>. +<P> +The first version appends all of the characters from +<B><TT>aStr</TT></B>. +<P> +The second version appends at most <B><TT>aLen</TT></B> characters from +<B><TT>aStr</TT></B> beginning at position <B><TT>aPos</TT></B>. +<B><TT>aPos</TT></B> must be less than or equal to +<B><TT>aStr.size()</TT></B>. The function will not append more characters +than what are available in <B><TT>aStr</TT></B>. +<P> +The third version appends <B><TT>aLen</TT></B> characters from +<B><TT>aBuf</TT></B>, which is not assumed to be NUL-terminated and can contain +embedded NULs. +<P> +The fourth version appends characters from the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +The fifth version appends <B><TT>aChar</TT></B> repeated +<B><TT>aLen</TT></B> times. +<P> +<FONT COLOR="teal"><B> DwString& <A NAME="assign">assign</A>(const +DwString& aStr) <BR> +DwString& assign(const DwString& aStr, size_t aPos, size_t aLen) +<BR> +DwString& assign(const char* aBuf, size_t aLen) <BR> +DwString& assign(const char* aCstr) <BR> +DwString& assign(size_t aLen, char aChar) </B></FONT> +<P> +Assigns characters to this string. Returns <B><TT>*this</TT></B>. +<P> +The first version assigns all of the characters from +<B><TT>aStr</TT></B>. +<P> +The second version assigns at most <B><TT>aLen</TT></B> characters from +<B><TT>aStr</TT></B> beginning at position <B><TT>aPos</TT></B>. +<B><TT>aPos</TT></B> must be less than or equal to +<B><TT>aStr.size()</TT></B>. The function will not assign more characters +than what are available in <B><TT>aStr</TT></B>. +<P> +The third version assigns <B><TT>aLen</TT></B> characters from +<B><TT>aBuf</TT></B>, which is not assumed to be NUL-terminated and can contain +embedded NULs. +<P> +The fourth version assigns characters from the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +The fifth version assigns <B><TT>aChar</TT></B> repeated +<B><TT>aLen</TT></B> times. +<P> +<FONT COLOR="teal"><B> DwString& <A NAME="insert">insert</A>(size_t aPos1, +const DwString& aStr) <BR> +DwString& insert(size_t aPos1, const DwString& aStr, size_t aPos2, +size_t aLen2) <BR> +DwString& insert(size_t aPos1, const char* aBuf, size_t aLen2) <BR> +DwString& insert(size_t aPos1, const char* aCstr) <BR> +DwString& insert(size_t aPos1, size_t aLen2, char aChar) </B></FONT> +<P> +Inserts characters into this string beginning at position +<B><TT>aPos1</TT></B>. Returns <B><TT>*this</TT></B>. +<P> +The first version inserts all of the characters from +<B><TT>aStr</TT></B>. +<P> +The second version inserts at most <B><TT>aLen2</TT></B> characters from +<B><TT>aStr</TT></B> beginning at position <B><TT>aPos2</TT></B>. +<B><TT>aPos1</TT></B> must be less than or equal to +<B><TT>aStr.size()</TT></B>. The function will not assign more characters +than what are available in <B><TT>aStr</TT></B>. +<P> +The third version inserts <B><TT>aLen2</TT></B> characters from +<B><TT>aBuf</TT></B>, which is not assumed to be NUL-terminated and can contain +embedded NULs. +<P> +The fourth version inserts characters from the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +The fifth version inserts <B><TT>aChar</TT></B> repeated +<B><TT>aLen2</TT></B> times. +<P> +<FONT COLOR="teal"><B> DwString& <A NAME="erase">erase</A>(size_t aPos=0, +size_t aLen=npos) </B></FONT> +<P> +Erases (removes) at most <B><TT>aLen</TT></B> characters beginning at position +<B><TT>aPos</TT></B> from this string. The function will not erase more +characters than what are available. Returns <B><TT>*this</TT></B>. +<P> +<FONT COLOR="teal"><B> DwString& <A NAME="replace">replace</A>(size_t +aPos1, size_t aLen1, const DwString& aStr) <BR> +DwString& replace(size_t aPos1, size_t aLen1, const DwString& aStr, +size_t aPos2, size_t aLen2) <BR> +DwString& replace(size_t aPos1, size_t aLen1, const char* aBuf, size_t +aLen2) <BR> +DwString& replace(size_t aPos1, size_t aLen1, const char* aCstr) <BR> +DwString& replace(size_t aPos1, size_t aLen1, size_t aLen2, char aChar) +</B></FONT> +<P> +Removes <B><TT>aLen1</TT></B> characters beginning at position +<B><TT>aPos1</TT></B> and inserts other characters. Returns +<B><TT>*this</TT></B>. +<P> +The first version inserts all of the characters from +<B><TT>aStr</TT></B>. +<P> +The second version inserts at most <B><TT>aLen2</TT></B> characters from +<B><TT>aStr</TT></B> beginning at position <B><TT>aPos2</TT></B>. +<B><TT>aPos1</TT></B> must be less than or equal to +<B><TT>aStr.size()</TT></B>. The function will not assign more characters +than what are available in <B><TT>aStr</TT></B>. +<P> +The third version inserts <B><TT>aLen2</TT></B> characters from +<B><TT>aBuf</TT></B>, which is not assumed to be NUL-terminated and can contain +embedded NULs. +<P> +The fourth version inserts characters from the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +The fifth version inserts <B><TT>aChar</TT></B> repeated +<B><TT>aLen2</TT></B> times. +<P> +<FONT COLOR="teal"><B> size_t <A NAME="copy">copy</A>(char* aBuf, size_t +aLen, size_t aPos=0) const </B></FONT> +<P> +Copies at most <B><TT>aLen</TT></B> characters beginning at position +<B><TT>aPos</TT></B> from this string to the buffer pointed to by +<B><TT>aBuf</TT></B>. Returns the number of characters copied. +<P> +<FONT COLOR="teal"><B> void <A NAME="swap">swap</A>(DwString& aStr) +</B></FONT> +<P> +Swaps the contents of this string and <B><TT>aStr</TT></B>. +<P> +<FONT COLOR="teal"><B> const char* <A NAME="c_str">c_str</A>() const +</B></FONT> +<P> +<P> +<FONT COLOR="teal"><B> const char* <A NAME="data">data</A>() const +</B></FONT> +<P> +These member functions permit access to the internal buffer used by the +<B><TT>DwString</TT></B> object. <B><TT>c_str()</TT></B> returns a NUL-terminated +string suitable for use in C library functions. <B><TT>data()</TT></B> returns +a pointer to the internal buffer, which may not be NUL-terminated. +<P> +<B><TT>c_str()</TT></B> may copy the internal buffer in order to place the +terminating NUL. This is not a violation of the const declaration: it is +a logical const, not a bit-representation const. It could have the side effect +of invalidating a pointer previously returned by <B><TT>c_str()</TT></B> +or <B><TT>data()</TT></B>. +<P> +The characters in the returned string should not be modified, and should +be considered invalid after any call to a non-const member function or another +call to <B><TT>c_str()</TT></B>. +<P> +<FONT COLOR="teal"><B> size_t <A NAME="find">find</A>(const DwString& +aStr, size_t aPos=0) const <BR> +size_t find(const char* aBuf, size_t aPos, size_t aLen) const <BR> +size_t find(const char* aCstr, size_t aPos=0) const <BR> +size_t find(char aChar, size_t aPos=0) const </B></FONT> +<P> +Performs a forward search for a sequence of characters in the +<B><TT>DwString</TT></B> object. The return value is the position of the +sequence in the string if found, or <B><TT>DwString::npos</TT></B> if not +found. +<P> +The first version searches beginning at position <B><TT>aPos</TT></B> for +the sequence of characters in <B><TT>aStr</TT></B>. +<P> +The second version searches beginning at position <B><TT>aPos</TT></B> for +the sequence of <B><TT>aLen</TT></B> characters in <B><TT>aBuf</TT></B>, +which need not be NUL-terminated and can contain embedded NULs. +<P> +The third version searches beginning at position <B><TT>aPos</TT></B> for +the sequence of characters in the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +The fourth version searches beginning at position <B><TT>aPos</TT></B> for +the character <B><TT>aChar</TT></B>. +<P> +<FONT COLOR="teal"><B> size_t <A NAME="rfind">rfind</A>(const DwString& +aStr, size_t aPos=npos) const <BR> +size_t rfind(const char* aBuf, size_t aPos, size_t aLen) const <BR> +size_t rfind(const char* aCstr, size_t aPos=npos) const <BR> +size_t rfind(char aChar, size_t aPos=npos) const </B></FONT> +<P> +Performs a reverse search for a sequence of characters in the +<B><TT>DwString</TT></B> object. The return value is the position of the +sequence in the string if found, or <B><TT>DwString::npos</TT></B> if not +found. +<P> +The first version searches beginning at position <B><TT>aPos</TT></B> for +the sequence of characters in <B><TT>aStr</TT></B>. +<P> +The second version searches beginning at position <B><TT>aPos</TT></B> for +the sequence of <B><TT>aLen</TT></B> characters in <B><TT>aBuf</TT></B>, +which need not be NUL-terminated and can contain embedded NULs. +<P> +The third version searches beginning at position <B><TT>aPos</TT></B> for +the sequence of characters in the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +The fourth version searches beginning at position <B><TT>aPos</TT></B> for +the character <B><TT>aChar</TT></B>. +<P> +<FONT COLOR="teal"><B> size_t <A NAME="find_first_of">find_first_of</A>(const +DwString& aStr, size_t aPos=0) const <BR> +size_t find_first_of(const char* aBuf, size_t aPos, size_t aLen) const <BR> +size_t find_first_of(const char* aCstr, size_t aPos=0) const </B></FONT> +<P> +Performs a forward search beginning at position <B><TT>aPos</TT></B> for +the first occurrence of any character from a specified set of characters. +The return value is the position of the character if found, or +<B><TT>DwString::npos</TT></B> if not found. +<P> +The first version searches for any character in the string +<B><TT>aStr</TT></B>. +<P> +The second version searches for any of the <B><TT>aLen</TT></B> characters +in <B><TT>aBuf</TT></B>. +<P> +The third version searches for any character in the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +<FONT COLOR="teal"><B> size_t <A NAME="find_last_of">find_last_of</A>(const +DwString& aStr, size_t aPos=npos) const <BR> +size_t find_last_of(const char* aBuf, size_t aPos, size_t aLen) const <BR> +size_t find_last_of(const char* aCstr, size_t aPos=npos) const </B></FONT> +<P> +Performs a reverse search beginning at position <B><TT>aPos</TT></B> for +the first occurrence of any character from a specified set of characters. +If <B><TT>aPos</TT></B> is greater than or equal to the number of characters +in the string, then the search starts at the end of the string. The return +value is the position of the character if found, or +<B><TT>DwString::npos</TT></B> if not found. +<P> +The first version searches for any character in the string +<B><TT>aStr</TT></B>. +<P> +The second version searches for any of the <B><TT>aLen</TT></B> characters +in <B><TT>aBuf</TT></B>. +<P> +The third version searches for any character in the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +<FONT COLOR="teal"><B> size_t +<A NAME="find_first_not_of">find_first_not_of</A>(const DwString& aStr, +size_t aPos=0) const <BR> +size_t find_first_not_of(const char* aBuf, size_t aPos, size_t aLen) const +<BR> +size_t find_first_not_of(const char* aCstr, size_t aPos=0) const </B></FONT> +<P> +Performs a forward search beginning at position <B><TT>aPos</TT></B> for +the first occurrence of any character <I>not</I> in a specified set of +characters. The return value is the position of the character if found, or +<B><TT>DwString::npos</TT></B> if not found. +<P> +The first version searches for any character not in the string +<B><TT>aStr</TT></B>. +<P> +The second version searches for any character not among the +<B><TT>aLen</TT></B> characters in <B><TT>aBuf</TT></B>. +<P> +The third version searches for any character not in the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +<FONT COLOR="teal"><B> size_t +<A NAME="find_last_not_of">find_last_not_of</A>(const DwString& aStr, +size_t aPos=npos) const <BR> +size_t find_last_not_of(const char* aBuf, size_t aPos, size_t aLen) const +<BR> +size_t find_last_not_of(const char* aCstr, size_t aPos=npos) const +</B></FONT> +<P> +Performs a reverse search beginning at position <B><TT>aPos</TT></B> for +the first occurrence of any character <I>not</I> in a specified set of +characters. If <B><TT>aPos</TT></B> is greater than or equal to the number +of characters in the string, then the search starts at the end of the string. +The return value is the position of the character if found, or +<B><TT>DwString::npos</TT></B> if not found. +<P> +The first version searches for any character not in the string +<B><TT>aStr</TT></B>. +<P> +The second version searches for any character not among the +<B><TT>aLen</TT></B> characters in <B><TT>aBuf</TT></B>. +<P> +The third version searches for any character not in the NUL-terminated string +<B><TT>aCstr</TT></B>. +<P> +<FONT COLOR="teal"><B> DwString <A NAME="substr">substr</A>(size_t aPos=0, +size_t aLen=npos) const </B></FONT> +<P> +Returns a string that contains at most <B><TT>aLen</TT></B> characters from +the <B><TT>DwString</TT></B> object beginning at position +<B><TT>aPos</TT></B>. The returned substring will not contain more characters +than what are available in the superstring <B><TT>DwString</TT></B> object. +<P> +<FONT COLOR="teal"><B> int <A NAME="compare">compare</A>(const DwString& +aStr) const <BR> +int compare(size_t aPos1, size_t aLen1, const DwString& aStr) const <BR> +int compare(size_t aPos1, size_t aLen1, const DwString& aStr, size_t +aPos2, size_t aLen2) const <BR> +int compare(const char* aCstr) const <BR> +int compare(size_t aPos1, size_t aLen1, const char* aBuf, size_t aLen2=npos) +const </B></FONT> +<P> +These member functions compare a sequence of characters to this +<B><TT>DwString</TT></B> object, or a segment of this +<B><TT>DwString</TT></B> object. They return -1, 0, or 1, depending on whether +this <B><TT>DwString</TT></B> object is less than, equal to, or greater than +the compared sequence of characters, respectively. +<P> +The first version compares <B><TT>aStr</TT></B> to this string. +<P> +The second version compares <B><TT>aStr</TT></B> to the segment of this string +of length <B><TT>aLen</TT></B> beginning at position +<B><TT>aPos</TT></B>. +<P> +The third version compares the {tt aLen2} characters beginning at position +<B><TT>aPos2</TT></B> in <B><TT>aStr</TT></B> with the +<B><TT>aLen1</TT></B> characters beginning at position +<B><TT>aPos1</TT></B> in this <B><TT>DwString</TT></B> object. +<P> +The fourth version compares the NUL-terminated string +<B><TT>aCstr</TT></B> to this <B><TT>DwString</TT></B>. +<P> +The fifth version compares the <B><TT>aLen2</TT></B> characters in +<B><TT>aBuf</TT></B> with this <B><TT>DwString</TT></B>. +<P> +<FONT COLOR="teal"><B> virtual const char* +<A NAME="ClassName">ClassName</A>() const </B></FONT> +<P> +This virtual function returns the name of the class as a NUL-terminated char +string. +<P> +<FONT COLOR="teal"><B> int <A NAME="ObjectId">ObjectId</A>() const +</B></FONT> +<P> +Returns the unique object id for this <B><TT>DwString</TT></B>. +<P> +<FONT COLOR="teal"><B> void +<A NAME="ConvertToLowerCase">ConvertToLowerCase</A>() <BR> +void <A NAME="ConvertToUpperCase">ConvertToUpperCase</A>() </B></FONT> +<P> +Converts this <B><TT>DwString</TT></B> object's characters to all lower case +or all upper case. +<P> +<FONT COLOR="teal"><B> void <A NAME="Trim">Trim</A>() </B></FONT> +<P> +Removes all white space from the beginning and the end of this +<B><TT>DwString</TT></B> object. White space characters include ASCII HT, +LF, and SPACE. +<P> +<FONT COLOR="teal"><B> void <A NAME="WriteTo">WriteTo</A>(ostream& aStrm) +const </B></FONT> +<P> +Writes the contents of this <B><TT>DwString</TT></B> object to the stream +<B><TT>aStrm</TT></B>. +<P> +<FONT COLOR="teal"><B> int <A NAME="RefCount">RefCount</A>() const +</B></FONT> +<P> +This <I>advanced</I> member function returns the number of references to +the internal buffer used by the <B><TT>DwString</TT></B> object. +<P> +<FONT COLOR="teal"><B> void <A NAME="TakeBuffer">TakeBuffer</A>(char* aBuf, +size_t aSize, size_t aStart, size_t aLen) </B></FONT> +<P> +This <I>advanced</I> member function sets the contents of the +<B><TT>DwString</TT></B> object to the <B><TT>aLen</TT></B> characters starting +at offset <B><TT>aStart</TT></B> in the buffer <B><TT>aBuf</TT></B>. +<B><TT>aSize</TT></B> is the allocated size of <B><TT>aBuf</TT></B>. This +member function is provided for efficiency in setting a +<B><TT>DwString</TT></B>'s contents from a large buffer. It is efficient +because no copying takes place. Instead, <B><TT>aBuf</TT></B> becomes the +buffer used internally by the <B><TT>DwString</TT></B> object, which takes +responsibility for deleting the buffer. Because DwString will free the buffer +using <B><TT>delete []</TT></B>, the buffer should have been allocated using +<B><TT>new</TT></B>. See also: ReleaseBuffer(). +<P> +<FONT COLOR="teal"><B> void <A NAME="ReleaseBuffer">ReleaseBuffer</A>(char** +aBuf, size_t* aSize, size_t* aStart, size_t* aLen) </B></FONT> +<P> +This <I>advanced</I> member function is the symmetric opposite of +<B><TT>TakeBuffer()</TT></B>, to the extent that such an opposite is possible. +It provides a way to ``export'' the buffer used internally by the +<B><TT>DwString</TT></B> object. Note, however, that because of the +copy-on-modify feature of <B><TT>DwString</TT></B>, the +<B><TT>DwString</TT></B> object may not have sole ownership of its internal +buffer. When that is case, <B><TT>ReleaseBuffer()</TT></B> will return a +copy of the buffer. You can check to see if the internal buffer is shared +by calling <B><TT>RefCount()</TT></B>. On return from this member function, +the <B><TT>DwString</TT></B> object will have valid, but empty, contents. +It is recommended that you use this function only on rare occasions where +you need to export efficiently a large buffer. +<P> +<FONT COLOR="teal"><B> void <A NAME="CopyTo">CopyTo</A>(DwString* aStr) const +</B></FONT> +<P> +This <I>advanced</I> member function copies this <B><TT>DwString</TT></B> +object to <B><TT>aStr</TT></B>. This member function is different from the +assignment operator, because it physically copies the buffer instead of just +duplicating a reference to it. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm) const +</B></FONT> +<P> +Prints debugging information about the object to <B><TT>aStrm</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static const size_t <A NAME="npos">npos</A> +</B></FONT> +<P> +<B><TT>npos</TT></B> is assigned the value (size_t)-1. +</BODY></HTML> diff --git a/mimelib/doc/text.html b/mimelib/doc/text.html new file mode 100644 index 000000000..3fc637cac --- /dev/null +++ b/mimelib/doc/text.html @@ -0,0 +1,149 @@ +<HTML> +<HEAD> + <TITLE> DwText Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwText -- Class representing text in a RFC-822 header field-body +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwText : public <A HREF="fieldbdy.html">DwFieldBody</A> { + +public: + + <A HREF="text.html#DwText">DwText</A>(); + <A HREF="text.html#DwText">DwText</A>(const DwText& aText); + <A HREF="text.html#DwText">DwText</A>(const DwString& aStr, DwMessageComponent* aParent=0); + virtual ~DwText(); + const DwText& <A HREF="text.html#op_eq">operator =</A> (const DwText& aText); + virtual void <A HREF="text.html#Parse">Parse</A>(); + virtual void <A HREF="text.html#Assemble">Assemble</A>(); + virtual DwMessageComponent* <A HREF="text.html#Clone">Clone</A>() const; + static DwText* <A HREF="text.html#NewText">NewText</A>(const DwString& aStr, DwMessageComponent* aParent); + static DwText* (*<A HREF="text.html#sNewText">sNewText</A>)(const DwString&, DwMessageComponent*); + +public: + + virtual void <A HREF="text.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const; + virtual void <A HREF="text.html#CheckInvariants">CheckInvariants</A>() const; + +protected: + + void _PrintDebugInfo(ostream& aStrm) const; +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwText</TT></B> represents an unstructured field body in a header +field. It roughly corresponds to the <I>text</I> element of the BNF grammar +defined in RFC-822. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> <A NAME="DwText">DwText</A>() <BR> +DwText(const DwText& aText) <BR> +DwText(const DwString& aStr, DwMessageComponent* aParent=0) </B></FONT> +<P> +The first constructor is the default constructor, which sets the +<B><TT>DwText</TT></B> object's string representation to the empty string +and sets its parent to NULL. +<P> +The second constructor is the copy constructor, which copies the string +representation from <B><TT>aText</TT></B>. The parent of the new +<B><TT>DwText</TT></B> object is set to NULL. +<P> +The third constructor copies <B><TT>aStr</TT></B> to the +<B><TT>DwText</TT></B> object's string representation and sets +<B><TT>aParent</TT></B> as its parent. The virtual member function +<B><TT>Parse()</TT></B> should be called immediately after this constructor +in order to parse the string representation. Unless it is NULL, +<B><TT>aParent</TT></B> should point to an object of a class derived from +<B><TT>DwField</TT></B>. +<P> +<FONT COLOR="teal"><B> const DwText& <A NAME="op_eq">operator =</A> (const +DwText& aText) </B></FONT> +<P> +This is the assignment operator. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT> +<P> +This virtual member function is inherited from +<B><TT>DwMessageComponent</TT></B>, where it is declared a pure virtual function. +For a <B><TT>DwText</TT></B> object, this member function does nothing, since +<B><TT>DwText</TT></B> represents an unstructured field body (like the Subject +header field) that does not have a broken-down form. +<P> +Note, however, that this function should still be called consistently, since +a subclass of <B><TT>DwText</TT></B> may implement a parse method. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() +</B></FONT> +<P> +This virtual member function is inherited from +<B><TT>DwMessageComponent</TT></B>, where it is declared a pure virtual function. +For a <B><TT>DwText</TT></B> object, this member function does nothing, since +<B><TT>DwText</TT></B> represents an unstructured field body (like the Subject +header field) that does not have a broken-down form. +<P> +Note, however, that this function should still be called consistently, since +a subclass of <B><TT>DwText</TT></B> may implement an assemble method. +<P> +This function clears the is-modified flag. +<P> +<FONT COLOR="teal"><B> virtual DwMessageComponent* +<A NAME="Clone">Clone</A>() const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +creates a new <B><TT>DwText</TT></B> on the free store that has the same +value as this <B><TT>DwText</TT></B> object. The basic idea is that of a +``virtual copy constructor.'' +<P> +<FONT COLOR="teal"><B> static DwText* <A NAME="NewText">NewText</A>(const +DwString& aStr, DwMessageComponent* aParent) </B></FONT> +<P> +Creates a new <B><TT>DwText</TT></B> object on the free store. If the static +data member <B><TT>sNewText</TT></B> is NULL, this member function will create +a new <B><TT>DwText</TT></B> and return it. Otherwise, +<B><TT>NewText()</TT></B> will call the user-supplied function pointed to +by <B><TT>sNewText</TT></B>, which is assumed to return an object from a +class derived from <B><TT>DwText</TT></B>, and return that object. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) +const </B></FONT> +<P> +This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>, +prints debugging information about this object to <B><TT>aStrm</TT></B>. +It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child +components down to a level of <B><TT>aDepth</TT></B>. +<P> +This member function is available only in the debug version of the library. +<P> +<FONT COLOR="teal"><B> virtual void +<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT> +<P> +Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +<P> +This member function is available only in the debug version of the library. +<H2> + <FONT COLOR="navy"> Public Data Members </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> static DwText* +(*<A NAME="sNewText">sNewText</A>)(const DwString&, DwMessageComponent*) +</B></FONT> +<P> +If <B><TT>sNewText</TT></B> is not NULL, it is assumed to point to a +user-supplied function that returns an object from a class derived from +<B><TT>DwText</TT></B>. +</BODY></HTML> diff --git a/mimelib/doc/util.html b/mimelib/doc/util.html new file mode 100644 index 000000000..1ae75acf1 --- /dev/null +++ b/mimelib/doc/util.html @@ -0,0 +1,111 @@ +<!-- $Revision$ --> +<!-- $Date$ --> +<HTML> +<HEAD> + <TITLE> MIME++ Utility Functions </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +MIME++ Utilities +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>#include &ltmimepp/mimepp.h> + +void <A HREF="#DwInitialize">DwInitialize</A>(); +int <A HREF="#DwToCrLfEol">DwToCrLfEol</A>(const DwString& aSrcStr, DwString& aDestStr); +int <A HREF="#DwToLfEol">DwToLfEol</A>(const DwString& aSrcStr, DwString& aDestStr); +int <A HREF="#DwToCrEol">DwToCrEol</A>(const DwString& aSrcStr, DwString& aDestStr); +int <A HREF="#DwToLocalEol">DwToLocalEol</A>(const DwString& aSrcStr, DwString& aDestStr); +int <A HREF="#DwEncodeBase64">DwEncodeBase64</A>(const DwString& aSrcStr, DwString& aDestStr); +int <A HREF="#DwDecodeBase64">DwDecodeBase64</A>(const DwString& aSrcStr, DwString& aDestStr); +int <A HREF="#DwEncodeQuotedPrintable">DwEncodeQuotedPrintable</A>(const DwString& aSrcStr, DwString& aDestStr); +int <A HREF="#DwDecodeQuotedPrintable">DwEncodeQuotedPrintable</A>(const DwString& aSrcStr, DwString& aDestStr); +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> void <A NAME="DwInitialize">DwInitialize</A>(); +</B></FONT> +<P> +Initializes the class library. Call this member function before creating +any objects from MIME++ classes. +<P> +<FONT COLOR="teal"><B> int <A NAME="DwToCrLfEol">DwToCrLfEol</A>(const +DwString& aSrcStr, DwString& aDestStr); </B></FONT> +<P> +Converts all end-of-line markers in <B><TT>aSrcStr</TT></B> to CR LF and +puts the result in <B><TT>aDestStr</TT></B>. The contract explicitly allows +<B><TT>aSrcStr</TT></B> and <B><TT>aDestStr</TT></B> to be references to +the same string. +<P> +<FONT COLOR="teal"><B> int <A NAME="DwToLfEol">DwToLfEol</A>(const +DwString& aSrcStr, DwString& aDestStr); </B></FONT> +<P> +Converts all end-of-line markers in <B><TT>aSrcStr</TT></B> to LF ('\n') +and puts the result in <B><TT>aDestStr</TT></B>. The contract explicitly +allows <B><TT>aSrcStr</TT></B> and <B><TT>aDestStr</TT></B> to be references +to the same string. +<P> +<FONT COLOR="teal"><B> int <A NAME="DwToCrEol">DwToCrEol</A>(const +DwString& aSrcStr, DwString& aDestStr); </B></FONT> +<P> +Converts all end-of-line markers in <B><TT>aSrcStr</TT></B> to CR ('\r') +and puts the result in <B><TT>aDestStr</TT></B>. The contract explicitly +allows <B><TT>aSrcStr</TT></B> and <B><TT>aDestStr</TT></B> to be references +to the same string. +<P> +<FONT COLOR="teal"><B> int <A NAME="DwToLocalEol">DwToLocalEol</A>(const +DwString& aSrcStr, DwString& aDestStr); </B></FONT> +<P> +Converts all end-of-line markers in <B><TT>aSrcStr</TT></B> to the end-of-line +marker native to the operating system and puts the result in +<B><TT>aDestStr</TT></B>. The contract explicitly allows +<B><TT>aSrcStr</TT></B> and <B><TT>aDestStr</TT></B> to be references to +the same string. +<P> +The end-of-line markers for various operating systems are the following: +<PRE> + MS-DOS, WIN32 CR LF + UNIX LF + Macintosh CR +</PRE> +<P> +<FONT COLOR="teal"><B> int <A NAME="DwEncodeBase64">DwEncodeBase64</A>(const +DwString& aSrcStr, DwString& aDestStr); </B></FONT> +<P> +Encodes the characters in <B><TT>aSrcStr</TT></B> using the base64 encoding +and puts the result into <B><TT>aDestStr</TT></B>. The contract explicitly +allows <B><TT>aSrcStr</TT></B> and <B><TT>aDestStr</TT></B> to be references +to the same string. +<P> +<FONT COLOR="teal"><B> int <A NAME="DwDecodeBase64">DwDecodeBase64</A>(const +DwString& aSrcStr, DwString& aDestStr); </B></FONT> +<P> +Decodes the characters in <B><TT>aSrcStr</TT></B> from the base64 encoding +and puts the result into <B><TT>aDestStr</TT></B>. The contract explicitly +allows <B><TT>aSrcStr</TT></B> and <B><TT>aDestStr</TT></B> to be references +to the same string. +<P> +<FONT COLOR="teal"><B> int +<A NAME="DwEncodeQuotedPrintable">DwEncodeQuotedPrintable</A>(const +DwString& aSrcStr, DwString& aDestStr); </B></FONT> +<P> +Encodes the characters in <B><TT>aSrcStr</TT></B> using the quoted-printable +encoding and puts the result into <B><TT>aDestStr</TT></B>. The contract +explicitly allows <B><TT>aSrcStr</TT></B> and <B><TT>aDestStr</TT></B> to +be references to the same string. +<P> +<FONT COLOR="teal"><B> int +<A NAME="DwDecodeQuotedPrintable">DwDecodeQuotedPrintable</A>(const +DwString& aSrcStr, DwString& aDestStr); </B></FONT> +<P> +Decodes the characters in <B><TT>aSrcStr</TT></B> from the quoted-printable +encoding and puts the result into <B><TT>aDestStr</TT></B>. The contract +explicitly allows <B><TT>aSrcStr</TT></B> and <B><TT>aDestStr</TT></B> to +be references to the same string. +</BODY></HTML> diff --git a/mimelib/doc/uuencode.html b/mimelib/doc/uuencode.html new file mode 100644 index 000000000..b7ba1fd2f --- /dev/null +++ b/mimelib/doc/uuencode.html @@ -0,0 +1,110 @@ +<HTML> +<HEAD> + <TITLE> DwUuencode Man Page </TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF"> +<H2> + <FONT COLOR="navy"> NAME </FONT> +</H2> +<P> +DwUuencode -- Class for performing uuencode or uudecode operations +<H2> + <FONT COLOR="navy"> SYNOPSIS </FONT> +</H2> +<PRE>class DW_EXPORT DwUuencode { + +public: + + DwUuencode(); + virtual ~DwUuencode(); + void <A HREF="uuencode.html#SetFileName">SetFileName</A>(const char* aName); + const char* <A HREF="uuencode.html#FileName">FileName</A>() const; + void <A HREF="uuencode.html#SetFileMode">SetFileMode</A>(DwUint16 aMode); + DwUint16 <A HREF="uuencode.html#FileMode">FileMode</A>() const; + void <A HREF="uuencode.html#SetBinaryChars">SetBinaryChars</A>(const DwString& aStr); + const DwString& <A HREF="uuencode.html#BinaryChars">BinaryChars</A>() const; + void <A HREF="uuencode.html#SetAsciiChars">SetAsciiChars</A>(const DwString& aStr); + const DwString& <A HREF="uuencode.html#AsciiChars">AsciiChars</A>() const; + DwBool <A HREF="uuencode.html#Encode">Encode</A>(); + DwBool <A HREF="uuencode.html#Decode">Decode</A>(); +}; +</PRE> +<H2> + <FONT COLOR="navy"> DESCRIPTION </FONT> +</H2> +<P> +<B><TT>DwUuencode</TT></B> performs uuencode or uudecode operations. Uuencode +is a format for encoding binary data into text characters for transmission +through the mail system. The format also includes the file name and the file +mode. (Note: The file mode is significant only in UNIX.) In MIME, the use +of uuencode is deprecated; base64 is the preferred encoding for sending binary +data. +<P> +To use <B><TT>DwUuencode</TT></B> for encoding binary data into uuencode +format, set the file name, file mode, and binary data string using the member +functions <B><TT>SetFileName()</TT></B>, <B><TT>SetFileMode()</TT></B>, and +<B><TT>SetBinaryChars()</TT></B>. Then call the member function +<B><TT>Encode()</TT></B>. Finally, retrieve the uuencoded text characters +by calling <B><TT>AsciiChars()</TT></B>. +<P> +To use <B><TT>DwUuencode</TT></B> to decode uuencoded data, set the ASCII +characters using the member function <B><TT>SetAsciiChars()</TT></B>, then +call <B><TT>Decode()</TT></B>. Finally, retrieve the file name, file mode, +and binary characters by calling <B><TT>FileName()</TT></B>, +<B><TT>FileMode()</TT></B>, and <B><TT>BinaryChars()</TT></B>. +<H2> + <FONT COLOR="navy"> Public Member Functions </FONT> +</H2> +<P> +<FONT COLOR="teal"><B> void <A NAME="SetFileName">SetFileName</A>(const char* +aName) </B></FONT> +<P> +Sets the file name to be included in the uuencoded output. +<P> +<FONT COLOR="teal"><B> const char* <A NAME="FileName">FileName</A>() const +</B></FONT> +<P> +Returns the file name extracted while uudecoding. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetFileMode">SetFileMode</A>(DwUint16 +aMode) </B></FONT> +<P> +Sets the file mode to be included in the uuencoded output. If the file mode +is not explicitly set using this member function, a default value of 0644 +(octal) is assumed. +<P> +<FONT COLOR="teal"><B> DwUint16 <A NAME="FileMode">FileMode</A>() const +</B></FONT> +<P> +Returns the file mode extracted while uudecoding. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetBinaryChars">SetBinaryChars</A>(const +DwString& aStr) </B></FONT> +<P> +Sets the string of binary data to be used in the uuencode operation. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="BinaryChars">BinaryChars</A>() const </B></FONT> +<P> +Returns the string of binary data extracted during a uudecode operation. +<P> +<FONT COLOR="teal"><B> void <A NAME="SetAsciiChars">SetAsciiChars</A>(const +DwString& aStr) </B></FONT> +<P> +Sets the string of ASCII characters to used in the decode operation. +<P> +<FONT COLOR="teal"><B> const DwString& +<A NAME="AsciiChars">AsciiChars</A>() const </B></FONT> +<P> +Returns the string of ASCII characters created during a uuencode operation. +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="Encode">Encode</A>() </B></FONT> +<P> +Creates an ASCII string of characters by uuencoding the file name, file mode, +and binary data. +<P> +<FONT COLOR="teal"><B> DwBool <A NAME="Decode">Decode</A>() </B></FONT> +<P> +Extracts the file name, file mode, and binary data from the ASCII characters +via a uudecode operation. +</BODY></HTML> |