NWC24SetMsgTextPublic

C Specification

#include <revolution/nwc24.h>

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

Description

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

A UTF-16BE string, the internal text encoding, is specified in text, with the length of that string 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 text 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 text to be processed. NWC24_ERR_OVERFLOW is returned when there is insufficient working memory.

The buffer given by the text 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.
`text`	Pointer to the body text string expressed in UTF-16BE.
`length`	The number of characters in the UTF-16BE string specified in `text`.
`autoEnc`	An auto-determining type of NWC24AutoEncodingType, 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: Cannot change message object.
NWC24_ERR_OVERFLOW: Insufficient work memory region.
NWC24_ERR_INVALID_VALUE: Invalid arguments.
NWC24_ERR_STRING_END: text is not null-terminated.
NWC24_ERR_FORMAT: There are lines within the body text whose length exceed the allowable range.
NWC24_ERR_INVALID_CHAR: Cannot convert to the external character encoding.

Revision History

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