1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3<HEAD>
4<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
5<META http-equiv="Content-Style-Type" content="text/css">
6<TITLE>NWC24SetMsgTextPublic</TITLE>
7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css">
8</HEAD>
9<BODY>
10<H1>NWC24SetMsgTextPublic</H1>
11
12<H2>C Specification</H2>
13<DL>
14  <DD><PRE><CODE>#include &lt;revolution/nwc24.h&gt;</CODE></PRE>
15  <DD><PRE><CODE><A HREF="../Types/NWC24Err.html">NWC24Err</A> NWC24SetMsgTextPublic(
16    <A HREF="../Types/NWC24MsgObj.html">NWC24MsgObj</A>*       <EM>obj</EM>,
17    const u16*         <EM>text</EM>,
18    u32                <EM>length</EM>,
19    <A HREF="../Types/NWC24AutoEncodingType.html">NWC24AutoEncodingType</A> <EM>autoEnc</EM>,
20    u16                <EM>altChar</EM>,
21    u8*                <EM>work</EM>,
22    u32                <EM>workSize</EM>
23);</CODE></PRE>
24</DL>
25
26<H2>Description</H2>
27<P>
28Specifies the body text of the public message as a string. Conversion to external formats such as text encoding occurs automatically.
29</P>
30<P>
31A UTF-16BE string, the internal text encoding, is specified in <CODE><EM><STRONG>text</STRONG></EM></CODE>, with the length of that string specified in <CODE><EM><STRONG>length</STRONG></EM></CODE>.<BR>The encoding's auto-determination type, which serves as a hint when processing a public message, is passed to <CODE><EM><STRONG>autoEnc</STRONG></EM></CODE>. The external text encoding at send is automatically decided by the type of text appearing in <CODE><EM><STRONG>text</STRONG></EM></CODE> and from <CODE><EM><STRONG>autoEnc</STRONG></EM></CODE>.<BR>In <CODE><EM><STRONG>altChar</STRONG></EM></CODE>, 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 <CODE><EM><STRONG>altChar</STRONG></EM></CODE>, the <CODE>NWC24_ERR_INVALID_CHAR</CODE> error will be returned when text that cannot be converted is encountered. Furthermore, under current specifications, <CODE><EM><STRONG>altChar</STRONG></EM></CODE> will not be used, as external text encoding that allows all text to be converted will be selected.<BR>Working memory must be passed to <CODE><EM><STRONG>work</STRONG></EM></CODE> 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. <CODE>NWC24_ERR_OVERFLOW</CODE> is returned when there is insufficient working memory.
32</P>
33
34<P>
35The buffer given by the <CODE><EM><STRONG>text</STRONG></EM></CODE> and <CODE><EM><STRONG>work</STRONG></EM></CODE> arguments is not deallocated until <A HREF="NWC24CommitMsg.html"><CODE>NWC24CommitMsg()</CODE></A> is called and the creation of the message is complete. Be particularly careful not to re-use the working memory buffer given by the <CODE><EM><STRONG>work</STRONG></EM></CODE> argument.
36</P>
37
38<P>
39Some 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 <A href="NWC24SetMsgSubjectAndTextPublic.html"><CODE>NWC24SetMsgSubjectAndTextPublic</CODE></A>.
40</P>
41
42<H2>Arguments</H2>
43<TABLE border="1" cellpadding="3" cellspacing="0.1">
44  <TR>
45<TD width="120" bgcolor="#ffffe8"><code><em><strong>obj</strong></em></code></TD>
46    <TD width="520">
47Pointer to the message object to be set.
48    </TD>
49  </TR>
50  <TR>
51<TD width="120" bgcolor="#ffffe8"><code><em><strong>text</strong></em></code></TD>
52    <TD width="520">
53Pointer to the body text string expressed in UTF-16BE.
54    </TD>
55  </TR>
56  <TR>
57<TD width="120" bgcolor="#ffffe8"><code><em><strong>length</strong></em></code></TD>
58    <TD width="520">
59The number of characters in the UTF-16BE string specified in <code><em><strong>text</strong></em></code>.
60    </TD>
61  </TR>
62  <TR>
63<TD width="120" bgcolor="#ffffe8"><code><em><strong>autoEnc</strong></em></code></TD>
64    <TD width="520">
65An auto-determining type of <A HREF="../Types/NWC24AutoEncodingType.html">NWC24AutoEncodingType</A>, used as a hint during conversion.<BR>
66    </TD>
67  </TR>
68  <TR>
69<TD width="120" bgcolor="#ffffe8"><code><em><strong>altChar</strong></em></code></TD>
70    <TD width="520">
71Alternate text, in UTF-16BE encoding, to be used when text that cannot be converted to external text encoding is encountered.<BR>
72    </TD>
73  </TR>
74  <TR>
75<TD width="120" bgcolor="#ffffe8"><code><em><strong>work</strong></em></code></TD>
76    <TD width="520">
77The working memory used for conversion.<BR>
78    </TD>
79  </TR>
80  <TR>
81<TD width="120" bgcolor="#ffffe8"><code><em><strong>workSize</strong></em></code></TD>
82    <TD width="520">
83The length of the work memory specified in <code><em><strong>work</strong></em></code>.<BR>
84    </TD>
85  </TR>
86</TABLE>
87
88<h2>Return Values</h2>
89<P>
90<code>NWC24_OK</code>: Normal exit.<BR><code>NWC24_ERR_PROTECTED</code>: Cannot change message object.<BR><code>NWC24_ERR_OVERFLOW</code>: Insufficient work memory region.<BR><code>NWC24_ERR_INVALID_VALUE</code>: Invalid arguments.<BR><code>NWC24_ERR_STRING_END</code>: <code><em><strong>text</strong></em></code> is not null-terminated.<BR><code>NWC24_ERR_FORMAT</code>: There are lines within the body text whose length exceed the allowable range.<BR><code>NWC24_ERR_INVALID_CHAR</code>: Cannot convert to the external character encoding.<BR>
91</P>
92
93<H2>See Also</H2>
94<P>
95<A href="NWC24InitMsgObj.html"><CODE>NWC24InitMsgObj</CODE></A><BR> <A href="NWC24SetMsgSubjectAndTextPublic.html"><CODE>NWC24SetMsgSubjectAndTextPublic</CODE></A>
96</P>
97
98<H2>Revision History</H2>
99<P>
1002007/2/15 Added note about and reference to <CODE>NWC24SetMsgSubjectAndTextPublic</CODE>.<BR>2007/01/31 Initial version.
101</P>
102
103<hr><p>CONFIDENTIAL</p></body>
104</HTML>