NAME

DwText -- Class representing text in a RFC-822 header field-body

SYNOPSIS

class DW_CORE_EXPORT DwText : public DwFieldBody {

public:

    DwText();
    DwText(const DwText& aText);
    DwText(const DwString& aStr, DwMessageComponent* aParent=0);
    virtual ~DwText();
    const DwText& operator = (const DwText& aText);
    virtual void Parse();
    virtual void Assemble();
    virtual DwMessageComponent* Clone() const;
    int NumEncodedWords() const;
    void AddEncodedWord(DwEncodedWord* aWord);
    void DeleteAllEncodedWords();
    DwEncodedWord& EncodedWordAt(int aIndex) const;
    void InsertEncodedWordAt(int aIndex, DwEncodedWord* aWord);
    DwEncodedWord* RemoveEncodedWordAt(int aIndex);
    static DwText* NewText(const DwString& aStr, DwMessageComponent* aParent);
    static DwText* (*sNewText)(const DwString&, DwMessageComponent*);

public:

    virtual void PrintDebugInfo(DW_STD ostream& aStrm, int aDepth=0) const;
    virtual void CheckInvariants() const;

protected:

    void _PrintDebugInfo(DW_STD ostream& aStrm) const;
};

DESCRIPTION

DwText represents an unstructured field body in a header field. It roughly corresponds to the text element of the BNF grammar defined in RFC-822.

If non-ASCII text is not a concern, you can get or set the entire text of the DwText object by using the inherited member functions DwMessageComponent::AsString() and DwMessageComponent::FromString(). However, DwText also supports non-ASCII text via the encoded words specified in RFC 2047. The encoded words are represented by objects of the class DwEncodedWord. DwText contains a list of DwEncodedWord objects and provides member functions to manage the list.

To create a text field body that contains encoded words, create one or more DwEncodedWord objects and add them, in order, to the DwText object. When the Assemble() method is called, the text field body is built from the contained DwEncodedWord objects. (Note that the Assemble() member function is normally not called directly, but is called by the parent DwMessageComponent object.) To create a text field body that contains no encoded words (it must contain only US-ASCII characters), use the inherited DwMessageComponent::FromString() member function.

Note: In the examples directory you can find code that demonstrates how to use DwText and DwEncodedWord classes to set non-ASCII text into the Subject header field of a message.

Public Member Functions

DwText()
DwText(const DwText& aText)
DwText(const DwString& aStr, DwMessageComponent* aParent=0)

The first constructor is the default constructor, which sets the DwText object's string representation to the empty string and sets its parent to NULL.

The second constructor is the copy constructor, which copies the string representation from aText. The parent of the new DwText object is set to NULL.

The third constructor copies aStr to the DwText 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 DwField.

const DwText& operator = (const DwText& aText)

This is the assignment operator.

virtual void Parse()

This virtual member function is inherited from DwMessageComponent, where it is declared a pure virtual function. For a DwText object, this member function does nothing, since DwText represents an unstructured field body (like the Subject header field) that does not have a broken-down form.

Note, however, that this function should still be called consistently, since a subclass of DwText may implement a parse method.

This function clears the is-modified flag.

virtual void Assemble()

This virtual member function is inherited from DwMessageComponent, where it is declared a pure virtual function. For a DwText object, this member function does nothing, since DwText represents an unstructured field body (like the Subject header field) that does not have a broken-down form.

Note, however, that this function should still be called consistently, since a subclass of DwText may implement an assemble method.

This function clears the is-modified flag.

virtual DwMessageComponent* Clone() const

This virtual function, inherited from DwMessageComponent, creates a new DwText on the free store that has the same value as this DwText object. The basic idea is that of a ``virtual copy constructor.''

int NumEncodedWords() const

Returns the number of DwEncodedWord objects contained in this DwText object.

void AddEncodedWord(DwEncodedWord* aWord)

Appends a DwEncodedWord object to the list managed by this DwText object.

Any DwEncodedWord objects contained in a DwText object's list will be deleted by the DwText object's destructor.

void DeleteAllEncodedWords()

Removes and deletes all DwEncodedWord objects contained in this DwText object.

DwEncodedWord& EncodedWordAt(int aIndex) const

Returns the DwEncodedWord object at position aIndex in this DwText object's list.

If the library is compiled to throw exceptions, the function will throw a DwBoundsException if aIndex is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if aIndex is out of range. Valid values for aIndex are 0 <= aIndex < NumEncodedWords().

void InsertEncodedWordAt(int aIndex, DwEncodedWord* aWord)

Inserts aWord into the list of DwEncodedWord objects at the position given by aIndex. A value of zero for aIndex will insert aWord as the first one in the list; a value of NumEncodedWords() will insert it as the last one in the list. If aIndex is less than NumEncodedWords(), the DwEncodedWord objects at position aIndex or greater will be shifted down the list to make room to insert aWord.

Any DwEncodedWord objects contained in a DwText object's list will be deleted by the DwText object's destructor.

If the library is compiled to throw exceptions, the function will throw a DwBoundsException if aIndex is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if aIndex is out of range. Valid values for aIndex are 0 <= aIndex <= NumEncodedWords().

DwEncodedWord* RemoveEncodedWordAt(int aIndex)

Removes the DwEncodedWord object at position aIndex from the list and returns it. If aIndex is less than NumEncodedWords()-1, then any DwEncodedWord objects at a position greater than aIndex will be shifted up in the list after the requested DwEncodedWord is removed.

If the library is compiled to throw exceptions, the function will throw a DwBoundsException if aIndex is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if aIndex is out of range. Valid values for aIndex are 0 <= aIndex < NumEncodedWords().

static DwText* NewText(const DwString& aStr, DwMessageComponent* aParent)

Creates a new DwText object on the free store. If the static data member sNewText is NULL, this member function will create a new DwText and return it. Otherwise, NewText() will call the user-supplied function pointed to by sNewText, which is assumed to return an object from a class derived from DwText, and return that object.

virtual void PrintDebugInfo(DW_STD 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 DwText* (*sNewText)(const DwString&, DwMessageComponent*)

If sNewText is not NULL, it is assumed to point to a user-supplied function that returns an object from a class derived from DwText.