DwField -- Class representing a MIME header field
class DW_EXPORT DwField : public DwMessageComponent {
friend class DwHeaders;
public:
DwField();
DwField(const DwField& aField);
DwField(const DwString& aStr, DwMessageComponent* aParent=0);
virtual ~DwField();
const DwField& operator = (const DwField& aField);
virtual void Parse();
virtual void Assemble();
virtual DwMessageComponent* Clone() const;
DwFieldBody* FieldBody() const;
const DwString& FieldNameStr() const;
const DwString& FieldBodyStr() const;
DwField* Next() const;
void SetFieldBody(DwFieldBody* aFieldBody);
void SetFieldNameStr(const DwString& aStr);
void SetFieldBodyStr(const DwString& aStr);
void SetNext(const DwField* aField);
static DwField* NewField(const DwString& aStr,
DwMessageComponent* aParent);
static DwFieldBody* CreateFieldBody(const DwString& aFieldName,
const DwString& aFieldBody, DwMessageComponent* aParent);
static DwFieldBody* _CreateFieldBody(const DwString& aFieldName,
const DwString& aFieldBody, DwMessageComponent* aParent);
static DwField* (*sNewField)(const DwString&, DwMessageComponent*);
static DwFieldBody* (*sCreateFieldBody)(const DwString& aFieldName,
const DwString& aFieldBody, DwMessageComponent* aParent);
protected:
DwString mFieldNameStr;
DwString mFieldBodyStr;
DwFieldBody* mFieldBody;
void _SetFieldBody(DwFieldBody* aFieldBody);
public:
virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const;
virtual void CheckInvariants() const;
protected:
void _PrintDebugInfo(ostream& aStrm) const;
};
DwField 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 DwField contains three elements: a DwString that contains its field name, a DwString that contains its field body, and a DwFieldBody object that contains a broken-down (that is, parsed) version of its field body.
In the tree (broken-down) representation of message, a DwField object is always an intermediate node, having a parent node and a single child node. The parent node is the DwHeaders object that contains it. The child node is the DwFieldBody object it contains.
To get and set the field name, use the member functions FieldNameStr() and SetFieldNameStr(). To get and set the field body, use the member functions FieldBodyStr() and SetFieldBodyStr(). To get and set the DwFieldBody object, use FieldBody() and SetFieldBody().
A DwField object can be included in a list of DwField objects; usually this is the list of DwField objects maintained by its parent DwHeaders object. To get the next DwField object in a list, use the member function Next().
DwField()
DwField(const DwField& aField)
DwField(const DwString& aStr, DwMessageComponent* aParent=0)
The first constructor is the default constructor, which sets the DwField object's field name and field body to the empty string, set its parent to NULL, and sets its DwFieldBody object to NULL.
The second constructor is the copy constructor, which performs a deep copy of aField. The parent of the new DwField object is set to NULL.
The third constructor copies aStr to the DwField object's string representation and sets aParent as its parent. The virtual member function Parse() should be called immediately after this constructor in order to parse the string representation. Unless it is NULL, aParent should point to an object of a class derived from DwHeaders.
const DwField& operator = (const DwField& aField)
This is the assignment operator, which performs a deep copy of aField. The parent node of the DwField object is not changed.
virtual void Parse()
This virtual function, inherited from DwMessageComponent, executes the parse method for DwField objects. The parse method creates or updates the broken-down representation from the string representation. For DwField 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 DwFieldBody. This member function also calls the Parse() member function of its contained DwFieldBody object.
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 DwFieldBody object.
This function clears the is-modified flag.
virtual void Assemble()
This virtual function, inherited from DwMessageComponent, executes the assemble method for DwField 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 DwFieldBody object. This member function calls the Assemble() member function of its contained DwFieldBody object.
You should call this member function after you modify either the field name or the contained DwFieldBody object, and before you retrieve the string representation.
This function clears the is-modified flag.
virtual DwMessageComponent* Clone() const
This virtual function, inherited from DwMessageComponent, creates a new DwField on the free store that has the same value as this DwField object. The basic idea is that of a virtual copy constructor.
DwFieldBody* FieldBody() const
Returns the DwFieldBody object contained by this DwField object. If there is no field body, NULL will be returned.
const DwString& FieldNameStr() const
Returns the field name of this header field as a string.
const DwString& FieldBodyStr() const
Returns the field body of this header field as a string.
DwField* Next() const
Returns the next DwField object following this DwField object in the list contained in a DwHeaders. Returns NULL if this object is last in the list.
void SetFieldBody(DwFieldBody* aFieldBody)
Sets the DwFieldBody object contained by this object.
void SetFieldNameStr(const DwString& aStr)
Sets the field name of this header field.
void SetFieldBodyStr(const DwString& aStr)
Sets the field body of this header field.
void SetNext(const DwField* aField)
This advanced function sets aField as the next field following this field in the list of fields contained in the headers. Since DwHeaders contains member functions for adding DwField objects to its list, this function should be avoided for most applications.
static DwField* NewField(const DwString& aStr, DwMessageComponent* aParent)
Creates a new DwField object on the free store. If the static data member sNewField is NULL, this member function will create a new DwField and return it. Otherwise, NewField() will call the user-supplied function pointed to by sNewField, which is assumed to return an object from a class derived from DwField, and return that object.
static DwFieldBody* CreateFieldBody(const DwString& aFieldName, const DwString& aFieldBody, DwMessageComponent* aParent)
The static member function CreateFieldBody() is called from the Parse() member function and is responsible for creating a DwFieldBody 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 DwAddressList object to contain the field body, calls the Parse() member function for the DwAddressList, and sets the DwAddressList object as this DwField object's DwFieldBody.
If you want to override the behavior of CreateFieldBody(), you can do so by setting the public data member sCreateFieldBody to point to your own function. CreateFieldBody() first checks to see if sCreateFieldBody is NULL. If it is not, CreateFieldBody() will assume that it points to a user-supplied function and will call that function. If it is NULL, CreateFieldBody() will call _CreateFieldBody(), which actually creates the DwFieldBody object. You may call _CreateFieldBody() from your own function for fields you do not wish to handle.
virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const
This virtual function, inherited from DwMessageComponent, prints debugging information about this object to aStrm. It will also call PrintDebugInfo() for any of its child components down to a level of aDepth.
This member function is available only in the debug version of the library.
virtual void CheckInvariants() const
Aborts if one of the invariants of the object fails. Use this member function to track down bugs.
This member function is available only in the debug version of the library.
static DwField* (*sNewField)(const DwString&, DwMessageComponent*)
If sNewField is not NULL, it is assumed to point to a user-supplied function that returns an object from a class derived from DwField.
static DwFieldBody* (*sCreateFieldBody)(const DwString& aFieldName, const DwString& aFieldBody, DwMessageComponent* aParent)
See CreateFieldBody().
void _SetFieldBody(DwFieldBody* aFieldBody)
Sets the DwFieldBody object contained by this object. This function differs from SetFieldBody() in that it does not set the is-modified flag.