SFXMailField

Class for encoding and decoding the mail header.

#include <SFXMailField.h.hpp>

class SFXMailField;

SFMTYPEDEFCLASS(SFXMailField)

Description

The Base64 encode(B encode) and the Quoted-Printable encode(Q encode) defined in RFC2045 (MIME Part One: Format of Internet Message Bodies) are supported.

Reference

SFXMailMessage

Member

Constructor/Destructor
SFXMailField( `Void` ) Constructor of SFXMailField class.
~SFXMailField( `Void` ) Destructor of SFXMailField class.

Public Functions
`SFCError`	Add( `SFXAnsiStringConstRef` charset , `SFXAnsiStringConstRef` text ) Add a specified string in a specified encoding to the mail header.
`Void`	Clear( `Void` ) Clear the string of the mail header.
`SFCError`	Decode( `SFXAnsiStringConstRef` string ) Decode a specified string of the mail header.
`SFCError`	Encode( `SFXAnsiStringPtr` string ) Encode the internal expression as the string of the mail header.
`CharsetTextPtr`	GetCharsetText( `SInt32` index ) Get the data in the internal expression.
`SInt32`	GetSize( `Void` ) Get the number of fragments of the mail header in the internal expression.

Protected Functions
`SFCError`	AddNonEncodedText( `ACharConstPtr` start , `ACharConstPtr` end ) AddNonEncodedText( `SFXAnsiStringConstRef` text ) Add the non-encoded character string to the mail header
`SFCError`	DecodeTextB( `SFXAnsiStringPtr` decoded , `ACharConstPtr` start , `ACharConstPtr` end ) Decode the string encoded in the Base64.
`SFCError`	DecodeTextQ( `SFXAnsiStringPtr` decoded , `ACharConstPtr` start , `ACharConstPtr` end ) Decode the string encoded in the Quoted-Printable.
static `Bool`	IsLWSP( `AChar` c ) Check whether or not the character is LWSP (null, horizontal tab, line-feed or carriage return character).
static `Void`	SkipLWSP( `ACharConstHandle` start , `ACharConstPtr` end ) Advance the pointer to the character other than LWSP(null, horizontal tab, line-feed or carriage return character).

Types
CharsetText The internal expression of the SFXMailField class.

SFXMailField::SFXMailField

Constructor of SFXMailField class.

[ public, explicit ]
SFXMailField(Void);

SFXMailField::~SFXMailField

Destructor of SFXMailField class.

[ public ]
~SFXMailField(Void);

SFXMailField::Add

Add a specified string in a specified encoding to the mail header.

[ public ]
SFCError Add(
    SFXAnsiStringConstRef charset   // encoding
    SFXAnsiStringConstRef text      // string to add
);

Argument

charset: Specify an encoding.
text: Specify a string to add to the mail header.

Return value

Success : SFERR_NO_ERROR
If failed : SFERR_FAILED
If insufficient memory : SFERR_NO_MEMORY

Description

The value specified by the "charset" argument needs to be one of the strings registered to IANA such as "US-ASCII" and "ISO-2022-JP". And the string specified by the "text" argument also needs to be encoded in this encoding.

For example, when adding a string in "ISO-2022-JP" to the mail header, convert it into JIS code using the SFXMailUtility::ShiftJISToJIS function before passing it to the "text" argument.

Example

SFXMailField::Encode example

Reference

SFXMailField::AddNonEncodedText

SFXMailField::AddNonEncodedText

Add the non-encoded character string to the mail header

[ protected ]
SFCError AddNonEncodedText(
    ACharConstPtr start   // pointer to the head of string to add
    ACharConstPtr end     // pointer to the end of string to add
);

[ protected ]
SFCError AddNonEncodedText(
    SFXAnsiStringConstRef text   // string to add
);

Argument

text: Specify a string to add.
textStart: Specify a pointer to the head of string to add.
textEnd: Specify a pointer to the end of string to add.

Return value

Success : SFERR_NO_ERROR
If failed : SFERR_FAILED
If insufficient memory : SFERR_NO_MEMORY

Description

Specify a string which consists of the "US-ASCII" characters.

Reference

SFXMailField::Add

SFXMailField::Clear

Clear the string of the mail header.

[ public ]
Void Clear(Void);

SFXMailField::Decode

Decode a specified string of the mail header.

[ public ]
SFCError Decode(
    SFXAnsiStringConstRef string   // string to be decoded
);

Argument

string: Specify a string to be decoded.

Return value

Success : SFERR_NO_ERROR
If invalid character : SFERR_INVALID_FORMAT
If invalid argument : SFERR_INVALID_PARAM
If insufficient memory : SFERR_NO_MEMORY
If failed : SFERR_FAILED

Description

The SFXMailField::Decode function decodes the string encoded by RFC2047 ( MIME : Message Header Extensions for Non-ASCII Text ) and convert it into the internal expression.

Each fragment of the string is maintained as a pair of "encode name and string".

To get the number of fragments, call the SFXMailField::GetSize function. And to get a fragment of the string, call the SFXMailField::GetCharsetText function.

Example

When the character code of the mail header is "ISO-2022-JP", it needs to be converted into the Shift_JIS code. Strictly, the return value of the SFXMailField::Decode function needs to be checked.

SFXAnsiString DecodeHeader(SFXAnsiStringConstRef str) {
    SFXAnsiString result;
    SFXMailField decoder;

    // decode
    decoder.Decode(str);

    for (SInt32 i = 0; i < decoder.GetSize(); ++i) {
        // get the data in the internal expression
        SFXMailField::CharsetTextConstPtr f = decoder.GetCharsetText(i);
         if character code is JIS CODE (iso-2022-jp)
        if (f->charset.Equals("iso-2022-jp", false)) { 
            
            SFXAnsiString temp;

            // convert string in JIS code (iso-2022-jp)  into Shift JIS code
            SFXMailUtility::JISToShiftJIS(f->text, &temp, '\0');

            // append it to result
            result += temp;
        }
        else if (f->charset.Equals("us-ascii", false)) { // ascii
            result += f->text;
        }
        else { // otherwise ... skip it 
            /* IMPLEMENT HERE Error Handling */
        }
    }
    return result;
}

Reference

SFXMailField::Encode | SFXMailField::CharsetText | SFXMailField::GetSize | SFXMailField::GetCharsetText

SFXMailField::DecodeTextB

Decode the string encoded in the Base64.

[ protected, const ]
SFCError DecodeTextB(
    SFXAnsiStringPtr decoded   // decoded string
    ACharConstPtr start        //  pointer to the head of string to be decoded
    ACharConstPtr end          //  pointer to the end of string to be decoded
);

Return value

Success : SFERR_NO_ERROR
If invalid character : SFERR_INVALID_FORMAT
If invalid argument : SFERR_INVALID_PARAM
If insufficient memory : SFERR_NO_MEMORY
If failed : SFERR_FAILED

Description

	About Base64 encode
	Detailed information : RFC2045 (MIME Part One: Format of Internet Message Bodies)

Reference

SFXMailField::DecodeTextQ

SFXMailField::DecodeTextQ

Decode the string encoded in the Quoted-Printable.

[ protected, const ]
SFCError DecodeTextQ(
    SFXAnsiStringPtr decoded   // decoded string
    ACharConstPtr start        // pointer to the head of string to be decoded
    ACharConstPtr end          // pointer to the end of string to be decoded
);

Return value

Success : SFERR_NO_ERROR
If invalid character : SFERR_INVALID_FORMAT
If invalid argument : SFERR_INVALID_PARAM
If insufficient memory : SFERR_NO_MEMORY

Description

	About Quoted-Printable endcode
	Detailed information : RFC2045 (MIME Part One: Format of Internet Message Bodies)

Reference

SFXMailField::DecodeTextB

SFXMailField::Encode

Encode the internal expression as the string of the mail header.

[ public, const ]
SFCError Encode(
    SFXAnsiStringPtr string   // output destination
);

Argument

string: Specify a pointer to the output destination.

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If insufficient memory : SFERR_NO_MEMORY
If failed : SFERR_FAILED

Example

Convert a string in the Shift JIS into the string of the mail header. Strictly, the return value of the SFXMailField::Encode function needs to be checked.

// after converting Shift_JIS into JIS, perform B encode
// EncodeHeader function does not support ASCII string
SFXAnsiString EncodeHeader(SFXAnsiStringConstRef str) {
    SFXAnsiString jis;
    SFXAnsiString result;
    SFXMailField encoder;

    // convert SJIS -> JIS
    SFXMailUtility::ShiftJISToJIS(str, &jis, '\0');

    encoder.Add("ISO-2022-JP", jis);
    encoder.Encode(&result);
    return result;
}

Reference

SFXMailField::Add

SFXMailField::GetCharsetText

Get the data in the internal expression.

[ public, const ]
CharsetTextPtr GetCharsetText(
    SInt32 index   // index number
);

Argument

index: Specify an index number of the internal expression.

Return value

Return the internal expression represented with the SFXMailField::CharsetText.

Description

The SFXMailField::GetCharsetText function gets the internal expression represented with the SFXMailField::CharsetText. The index number from 0 to the return value of the SFXMailField::GetSize function can be specified .

Reference

SFXMailField::Decode | SFXMailField::CharsetText | SFXMailField::GetSize

SFXMailField::GetSize

Get the number of fragments of the mail header in the internal expression.

[ public, const ]
SInt32 GetSize(Void);

Return value

The number of fragments of the mail header in the internal expression.

Reference

SFXMailField::GetCharsetText | SFXMailField::Decode

SFXMailField::IsLWSP

Check whether or not the character is LWSP (null, horizontal tab, line-feed or carriage return character).

[ protected, static ]
Bool IsLWSP(
    AChar c   // chacracter to check
);

Return value

If character is LWSP (null, horizontal tab, line-feed or carriage return character) : true
Otherwise : false

SFXMailField::SkipLWSP

Advance the pointer to the character other than LWSP(null, horizontal tab, line-feed or carriage return character).

[ protected, static ]
Void SkipLWSP(
    ACharConstHandle start   // pointer that advances

    ACharConstPtr end        // end position
);

Description

The pointer specified by the argument advances to the character other than LWSP(null, horizontal tab, line-feed or carriage return character) or to the end position (end).

Nothing happens when the pointer is beyond the end position.

SFXMailField::CharsetText

The internal expression of the SFXMailField class.

SFMTYPEDEFCLASS(CharsetText)
struct CharsetText {
  SFXAnsiString charset;
  SFXAnsiString text;
};

Description

The internal expression of the SFXMailField class consists of the "charset" instance that maintains the character set and the "text" intance that maintains the data.

Reference

SFXMailField | SFXMailField::GetCharsetText