NWC24SetMsgSubjectPublic

C Specification

#include <revolution/nwc24.h>

NWC24Err NWC24SetMsgSubjectPublic(
    NWC24MsgObj*       obj,
    const u16*         subject,
    u32                length,
    NWC24AutoEncodingType autoEnc,
    u16                altChar,
    u8*                work,
    u32                workSize
);

Description

Specifies the public message subject with a string. Conversion to external formats such as text encoding occurs automatically.

A UTF-16BE string, the internal text encoding, is specified in subject, and the length of that string is specified in length.
The encoding's auto-determination type, which serves as a hint when processing a public message, is passed to autoEnc. The external text encoding at send is automatically decided by the type of text appearing in
subject and from autoEnc. In altChar, using UTF-16BE encoded text, specify the text to be used as an alternate when the external text encoding cannot be converted. If 0 is specified for altChar, the NWC24_ERR_INVALID_CHAR error will be returned when text that cannot be converted is encountered. Furthermore, under current specifications, altChar will not be used, as external text encoding that allows all text to be converted will be selected.
Working memory must be passed to work for the conversion process. You must allocate a working memory size that is roughly twice as long as the string data expressed in external encoding for the subject to be processed. NWC24_ERR_OVERFLOW is returned when there is insufficient working memory.

The buffer given by the subject and work arguments is not deallocated until NWC24CommitMsg() is called and the creation of the message is complete. Be particularly careful not to re-use the working memory buffer given by the work argument.

Some mail clients may cause garbled characters if the character encodings of the subject and the message body are different. As a workaround for this, specify the subject and the message body simultaneously using NWC24SetMsgSubjectAndTextPublic.

Arguments

`obj`	Pointer to the message object to be set.
`subject`	A pointer to the subject string expressed in UTF-16BE.
`length`	the number of characters in the UTF-16BE string specified in `subject`.
`autoEnc`	An auto-determining type of NWC24AutoEncodingType type, used as a hint during conversion.
`altChar`	Alternate text, in UTF-16BE encoding, to be used when text that cannot be converted to external text encoding is encountered.
`work`	The working memory used for conversion.
`workSize`	The length of the work memory specified in `work`.

Return Values

NWC24_OK: Normal exit.
NWC24_ERR_PROTECTED: Message object cannot be changed.
NWC24_ERR_NULL: Either subject is a null pointer or the subject string is empty.
NWC24_ERR_OVERFLOW: Insufficient work memory region.
NWC24_ERR_STRING_END: Either subject or text is not null-terminated.
NWC24_ERR_INVALID_VALUE: Invalid argument.
NWC24_ERR_INVALID_CHAR: Unable to convert to external character encoding.

Revision History

2007/2/15 Added note about and reference to NWC24SetMsgSubjectAndTextPublic.
2007/01/31 Initial version.