NWC24ReadMsgTextPublic

C Specification

#include <revolution/nwc24.h>

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

Description

Reads the string data of the body text portion of a message from the message data. In order to read a public message, text encoding conversion to an internal format will occur automatically.
The actual message data is opened and the string is extracted into memory. The body text included in the message data, converted to the internal encoding (UTF-16BE) is stored in the u16 array indicated by text. The string to be retrieved is terminated with L'\0' (the UTF-16BE null character). In addition, the number of characters that can be stored in text (in u16) including the terminator is passed to length; after processing, the number of UTF-16BE characters without the null-terminator is overwritten and returned.
The encoding's auto-determination type, which serves as a hint when processing a public message, is passed to autoEnc. When a public message is received with the encoding omitted, the encoding is deduced using autoEnc.
altChar specifies the substitute character to use when a character cannot be converted to internal text encoding. This substitute character is specified in UTF-16BE character code. If 0 is specified for altChar, the NWC24_ERR_INVALID_CHAR error will be returned when text that cannot be converted is encountered. 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.

Arguments

`obj`	Message object from which settings are to be extracted.
`text`	Pointer to the u16 array where the read string is stored.
`length`	When this function stores a message of the size specified in `text`, the actual number of stored characters (excluding the terminator) are overwritten and returned.
`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 internal 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_LIB_NOT_OPENED: Library is not open.
NWC24_ERR_PROTECTED: Cannot read message object.
NWC24_ERR_NULL: Message data not set.
NWC24_ERR_OVERFLOW: Either the message body set for message object overflowed buffer, or the work memory region was insufficient.
NWC24_ERR_NOT_SUPPORTED: Unsupported character code or MIME encoding type set for message object.
NWC24_ERR_INVALID_VALUE: Invalid argument.
NWC24_ERR_INVALID_CHAR: Cannot convert to internal character encoding.
NWC24_ERR_FILE_*: Internal file operation error.

Revision History

2007/01/31 Initial version.