NWC24SetMsgSubjectAndTextPublic

C Specification

#include <revolution/nwc24.h>

NWC24Err NWC24SetMsgSubjectAndTextPublic(
    NWC24MsgObj*       obj,
    const u16*         subject,
    u32                subjLen,
    const u16*         text,
    u32                textLen,
    NWC24AutoEncodingType autoEnc,
    u16                altChar,
    u8*                work,
    u32                workSize
);

Description

Specifies the public message subject and body text with strings. Conversion to external formats such as text encoding occurs automatically.

The internal character encoding is specified in the UTF-16BE strings subject and text, and their string lengths are specified in subjLen and textLen.
The encoding's auto-determination type, which serves as a hint when processing a public message, is passed to autoEnc. The external character encoding during the send from autoEnc, as well as the type of text appearing in subject and text, are automatically determined. subject and text are converted to the same external character encoding.
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 and message body to be processed. NWC24_ERR_OVERFLOW is returned when there is insufficient working memory.

The buffers given by the subject, text and work arguments must not be 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.

Arguments

`obj`	Pointer to the message object to be set.
`subject`	A pointer to the subject string expressed in UTF-16BE.
`subjLen`	The number of characters in the UTF-16BE string specified in `subject`.
`text`	A pointer to the message body string expressed in UTF-16BE.
`textLen`	The number of characters in the UTF-16BE string specified in `text`.
`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/02/15 Initial version.