NWC24SetMsgText

C Specification

#include <revolution/nwc24.h>

NWC24Err NWC24SetMsgText(
    NWC24MsgObj*  obj,
    const char*   text,
    u32           size,
    NWC24Charset  charset,
    NWC24Encoding encoding
);

Description

Specifies the body text of the message with a character string.

Specifies character code format and MIME encoding type as an argument. The character code format indicates the character code used for the sent text. It is used to convert that text into a displayable format when the message is received. In addition, the MIME encoding type specifies the encoding method when transferring the text. MIME encoding is carried out inside the library.

When the body comprises text that can all be 7-bit encoded, NWC24_ENC_7BIT is specified, and it can be sent without MIME encoding. If character codes that require 8-bit representation are to be mixed in, you must specify NWC24_ENC_BASE64 or NWC24_ENC_QUOTED_PRINTABLE and perform MIME encoding. In addition, if message is to be sent only to a local console message box, you can specify the NWC24_ENC_8BIT format, which does not perform MIME encoding.

Example
When sending English text consisting of only ASCII code:
  charset = NWC24_US_ASCII / encoding = NWC24_ENC_7BIT

When sending Japanese text consisting of ISO-2022-JP code:
  charset = NWC24_ISO_2022_JP / encoding = NWC24_ENC_7BIT
MIME encoding is not needed for ISO-2022-JP as it is a 7-bit capable format.

When sending European text consisting of ISO-8859-1 character code:
  charset = NWC24_ISO_8859_1 / encoding = NWC24_ENC_QUOTED_PRINTABLE
Since the ISO-8859 character codes includes characters that cannot be expressed in 7-bits, a different format must be specified. In this situation, Quoted-Printable MIME encoding is usually appropriate.

If sending a string in UTF-16 character code supporting multiple languages (for example to the Wii Message Board):

  charset = NWC24_UTF_16 / encoding = NWC24_ENC_BASE64
UTF-16 is not based on 7-bit expressions, so apply Base64 format MIME encoding.

In addition, the lines of text must be no longer than 998 characters. CRLF (0x0D, 0x0A) must be used as the newline code.

The buffer given by the text argument must not be freed until NWC24CommitMsg() is called and creation of the message is complete.

Arguments

`obj`	Pointer to the message object to be set.
`text`	Pointer to the message body string.
`size`	Length (in bytes) of the string specified in `text`.
`charset`	Character code (Charset) format.
`encoding`	MIME encoding type.

Return Values

NWC24_OK: Normal termination.
NWC24_ERR_PROTECTED: Cannot change message object.
NWC24_ERR_INVALID_VALUE: Invalid value specified for charset or encoding.
NWC24_ERR_NOT_SUPPORTED: A non-supported encoding format has been specified for the message.
NWC24_ERR_FORMAT: The length of the message exceeds the allowable range.

Revision History

2007/06/13 Updated the settings example, deleted NWC24_ERR_STRING_END from the Return Values and added NWC24_ERR_NOT_SUPPORTED.
2007/05/03 Revised the description of size.
2006/12/05 Made corrections.
2006/11/13 Added descriptions about handling buffers and the NWC24_ERR_FORMAT error code.
2006/10/10 Made revisions in line with support for MIME encoding inside the library.
2006/10/06 Updated the list of return values.
2006/08/01 Initial version.