DwStamp Man Page

## NAME

DwStamp -- Class representing the field-body of an RFC-822 "Received" field

## SYNOPSIS

    class DW_CORE_EXPORT DwStamp : public DwFieldBody {

    public:

        DwStamp();
        DwStamp(const DwStamp& aStamp);
        DwStamp(const DwString& aStr, DwMessageComponent* aParent=0);
        virtual ~DwStamp();
        const DwStamp& operator = (const DwStamp& aStamp);
        virtual void Parse();
        virtual void Assemble();
        virtual DwMessageComponent* Clone() const;
        const DwString& From() const;
        void SetFrom(const DwString& aSendingHost);
        const DwString& By() const;
        void SetBy(const DwString&);
        const DwString& Via() const;
        void SetVia(const DwString&);
        const DwString& With() const;
        void SetWith(const DwString&);
        const DwString& Id() const;
        void SetId(const DwString&);
        const DwString& For() const;
        void SetFor(const DwString&);
        DwDateTime& Date();
        void SetDate(const DwDateTime& aDate);
        static DwStamp* NewStamp(const DwString&, DwMessageComponent*);
        static DwStamp* (*sNewStamp)(const DwString&, DwMessageComponent*);

    protected:

        DwString   mFrom;
        DwString   mBy;
        DwString   mVia;
        DwString   mWith;
        DwString   mId;
        DwString   mFor;
        DwDateTime mDate;

    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

`DwStamp` represents a field body for the "Received" header field as described in RFC-821 and RFC-822. (RFC-821 uses the term time stamp to describe the contents of the "Received" header field.) One "Received" header field is normally added by every host that relays a message through the transport system, as required by SMTP. The field includes a time stamp indicating the time that the message was received at the host, and possibly other information.

The "Received" header field provides information that may be helpful in resolving email delivery problems. In practice, though, the most recent time stamp is often used by email client applications to obtain the time that the message was received by the client's host. The other information provided in the "Received" header field is optional and inconsistent between implementations. Some implementations do not provide much of the optional information, while other implementations provide it in non-standard forms.

The following is a sample time stamp line, which shows all the optional information:

    Received: from xyz.net by mx.org via TELENET with SMTP
       id M12345 for smith@aol.com ; Tue, 6 Oct 1998 09:23:59 -0700

`DwStamp` provides access to all the information provided in a "Received" header field body, including sending host ("xyz.net"), receiving host ("mx.org"), physical mechanism ("TELENET"), protocol ("SMTP"), internal message identifier ("M12345"), original addressee ("smith@aol.com"), and date/time the message was received ("Tue, 6 Oct 1998 09:23:59 -0700").

`DwStamp` follows the protocol for `Parse()` and `Assemble()` as required by `DwMessageComponent`.

## Public Member Functions

DwStamp()
DwStamp(const DwStamp& aStamp)
DwStamp(const DwString& aStr, DwMessageComponent* aParent=0)

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

The second constructor is the copy constructor, which performs deep copy of `aStamp`. The parent of the new `DwStamp` object is set to `NULL`.

The third constructor copies `aStr` to the `DwStamp` 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 DwStamp& operator = (const DwStamp& aStamp)

This is the assignment operator, which performs a deep copy of `aStamp`. The parent node of the `DwStamp` object is not changed.

virtual void Parse()

This virtual function, inherited from `DwMessageComponent`, executes the parse method for `DwStamp` objects. It should be called immediately after the string representation is modified and before the parts of the broken-down representation are accessed.

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from `DwMessageComponent`, executes the assemble method for `DwStamp` 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 `Assemble()` member function if the is-modified flag is set.

This function clears the is-modified flag.

virtual DwMessageComponent* Clone() const

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

const DwString& From() const

Returns the sending host if it is present. If the the sending host is not present, it returns an empty string.

void SetFrom(const DwString& aSendingHost)

Sets the sending host.

const DwString& By() const

Returns the receiving host. The receiving host is the host that added this field to the headers. If the receiving host is not preset, it returns an empty string.

void SetBy(const DwString&)

Sets the receiving host.

const DwString& Via() const

Returns the physical mechanism through which the message was received. If the physical mechanism is not preset, it returns an empty string.

void SetVia(const DwString&)

Sets the physical mechanism.

const DwString& With() const

Returns the protocol that was used to send this message (that is, the protocol by which the receiving host received it). Usually, the protocol is SMTP. If the protocol is not preset, it returns an empty string.

void SetWith(const DwString&)

Sets the protocol.

const DwString& Id() const

Returns the internal message identifier. This is a value that is meaningful to the receiving host, such as the name of a file that was used to temporarily store the message. If the identifier is not preset, it returns an empty string.

void SetId(const DwString&)

Sets the internal message identifier.

const DwString& For() const

Returns the original addressee. This information may important if some kind of address translation occurs. If the original addressee is not preset, it returns an empty string.

void SetFor(const DwString&)

Sets the original addressee.

DwDateTime& Date()

Returns the date/time that the message was received. This information is the only required information in the "Received" header field.

void SetDate(const DwDateTime& aDate)

Sets the date/time that the message was received.

static DwStamp* NewStamp(const DwString&, DwMessageComponent*)

Creates a new `DwStamp` object on the free store. If the static data member `sNewStamp` is `NULL`, this member function will create a new `DwStamp` and return it. Otherwise, `NewStamp()` will call the user-supplied function pointed to by `sNewStamp`, which is assumed to return an object from a class derived from `DwStamp`, 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`.

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 DwStamp* (*sNewStamp)(const DwString&, DwMessageComponent*)

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