SFXMailField

Class for encoding and decoding the mail header.

#include <SFXMailField.h.hpp>

class SFXMailField;

SFMTYPEDEFCLASS(SFXMailField)

Description

The B / Q encoding defined in RFC2047: 4.1. The "B" encoding / RFC2047: 4.2. The "Q" encoding are supported.

Reference

SFXMailMessage

Member

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

Public Functions
`SFCError`	Add( `SFXAnsiStringConstRef` charset , `SFXAnsiStringConstRef` text ) Add the specified string in the specified encoding to the mail header.
`Void`	Clear( `Void` ) Release the array of the (encode name, text) pairs contained internally.
`SFCError`	Decode( `SFXAnsiStringConstRef` string ) Decode the specified string of the mail header and contain it as the array of the (encode name, text) pairs.
`SFCError`	Encode( `SFXAnsiStringPtr` string ) Encode the internal array of the (encode name, text) pairs into the string of the mail header.
`CharsetTextPtr`	GetCharsetText( `SInt32` index ) Get the data from the internal array of the (encode name, text) pairs.
`SInt32`	GetSize( `Void` ) Get the number of elements of the internal array of the (encode name, text) pairs.

Protected Functions
`SFCError`	AddNonEncodedText( `ACharConstPtr` start , `ACharConstPtr` end ) Add the non-encoded character string to the mail header
`SFCError`	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 "B" encoding.
`SFCError`	DecodeTextQ( `SFXAnsiStringPtr` decoded , `ACharConstPtr` start , `ACharConstPtr` end ) Decode the string encoded in the "Q" encoding.
static `Bool`	IsLWSP( `AChar` c ) Check whether or not the character is LWSP (space, horizontal tab, line-feed or carriage return character).
static `Void`	SkipLWSP( `ACharConstHandle` start , `ACharConstPtr` end ) Advance the pointer to the character other than LWSP(space, horizontal tab, line-feed or carriage return character).

Types
CharsetText Structure that represents the (encode name, text) pair.

SFXMailField::SFXMailField

Constructor of the SFXMailField class.

[ public, explicit ]
SFXMailField(Void);

Description

This constructor does nothing.

SFXMailField::~SFXMailField

Destructor of the SFXMailField class.

[ public ]
~SFXMailField(Void);

Description

This destructor calls the SFXMailField::Clear function to release the array of the (encode name, text) pairs contained internally.

Reference

SFXMailField::Clear

SFXMailField::Add

Add the specified string in the 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

If succeeds: SFERR_NO_ERROR
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::GetCharsetText | SFXMailField::CharsetText

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

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMORY

Description

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

Reference

SFXMailField::Add | SFXMailField::GetCharsetText | SFXMailField::CharsetText

SFXMailField::Clear

Release the array of the (encode name, text) pairs contained internally.

[ public ]
Void Clear(Void);

Description

This function releases the array of the (encode name, text) pairs contained internally.

Reference

SFXMailField::~SFXMailField

SFXMailField::Decode

Decode the specified string of the mail header and contain it as the array of the (encode name, text) pairs.

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

Argument

string: Specify a string to be decoded.

Return value

If succeeds: SFERR_NO_ERROR
If invalid characters are included: SFERR_INVALID_FORMAT
If insufficient memory: SFERR_NO_MEMORY

Description

This function decodes the string encoded by RFC2047 ( MIME : Message Header Extensions for Non-ASCII Text ) and contain it as the array of the (encode name, text) pairs.

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::DecodeTextB

Decode the string encoded in the "B" encoding.

[ 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

If succeeds: SFERR_NO_ERROR
If invalid characters are included: SFERR_INVALID_FORMAT
If the decoded argument is null: SFERR_INVALID_PARAM
If insufficient memory: SFERR_NO_MEMORY

Description

	About the "B" encoding
	Reference: RFC2047: 4.1. The "B" encoding

Reference

SFXMailField::Decode | SFXMailField::DecodeTextQ | RFC2047: 4.1. The "B" encoding

SFXMailField::DecodeTextQ

Decode the string encoded in the "Q" encoding.

[ 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

If succeeds: SFERR_NO_ERROR
If invalid characters are included: SFERR_INVALID_FORMAT
If the decoded argument is null: SFERR_INVALID_PARAM
If insufficient memory: SFERR_NO_MEMORY

Description

	About the "Q" encoding
	Reference: RFC2047: 4.2. The "Q" encoding

Reference

SFXMailField::Decode | SFXMailField::DecodeTextB | RFC2047: 4.2. The "Q" encoding

SFXMailField::Encode

Encode the internal array of the (encode name, text) pairs into 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

If succeeds: SFERR_NO_ERROR
If the string argument is null: SFERR_INVALID_PARAM
If insufficient memory: SFERR_NO_MEMORY

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

SFXMailUtility::EncodeBase64 | SFXMailField::Decode | SFXMailField::Add

SFXMailField::GetCharsetText

Get the data from the internal array of the (encode name, text) pairs.

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

Argument

index: Specify an index number of the internal expression.

Return value

Return the internal array of the (encode name, text) pairs represented with the SFXMailField::CharsetText.

Description

This function gets the internal array of the (encode name, text) pairs represented with the SFXMailField::CharsetText. The index number from 0 to the return value of the SFXMailField::GetSize function can be specified .

Reference

SFXMailField::Add | SFXMailField::AddNonEncodedText | SFXMailField::GetSize | SFXMailField::CharsetText

SFXMailField::GetSize

Get the number of elements of the internal array of the (encode name, text) pairs.

[ public, const ]
SInt32 GetSize(Void);

Return value

Number of elements of the internal array of the (encode name, text) pairs

Reference

SFXMailField::Add | SFXMailField::AddNonEncodedText | SFXMailField::CharsetText

SFXMailField::IsLWSP

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

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

Return value

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

Reference

SFXMailField::SkipLWSP

SFXMailField::SkipLWSP

Advance the pointer to the character other than LWSP(space, 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(space, horizontal tab, line-feed or carriage return character) or to the end position (end).

Nothing happens when the pointer is beyond the end position.

Reference

SFXMailField::IsLWSP

SFXMailField::CharsetText

Structure that represents the (encode name, text) pair.

SFMTYPEDEFCLASS(CharsetText)
struct CharsetText {
  SFXAnsiString charset;  // encode name
  SFXAnsiString text;     // text
};

Description

This structure represents the (encode name, text) pair.

Reference

SFXMailField::Add | SFXMailField::AddNonEncodedText | SFXMailField::GetCharsetText