DwField Man Page

From b479c22c713be413b9135be8f1d4e108d33f17f6 Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Sun, 6 Oct 2013 10:33:05 -0700 Subject: lurker-2.3 mimelib-3.1.1 --- mimelib/doc/field.html | 305 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 mimelib/doc/field.html (limited to 'mimelib/doc/field.html') diff --git a/mimelib/doc/field.html b/mimelib/doc/field.html new file mode 100644 index 0000000..19736f2 --- /dev/null +++ b/mimelib/doc/field.html @@ -0,0 +1,305 @@ + + + DwField Man Page + + +

+ NAME +

+DwField -- Class representing a MIME header field +

+ SYNOPSIS +

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;
+};
+

+ DESCRIPTION +

+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(). +

+ Public Member Functions +

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

+ Public Data Members +

+ 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(). +

+ Protected Member Functions +

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

+ -- cgit v1.2.3