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>NWC24ReadMsgSubjectPublic</TITLE>
7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css">
8</HEAD>
9<BODY>
10<H1>NWC24ReadMsgSubjectPublic</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> NWC24ReadMsgSubjectPublic(
16    const <A HREF="../Types/NWC24MsgObj.html">NWC24MsgObj</A>* <EM>obj</EM>,
17    u16*               <EM>subject</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>
28Reads the subject of the message from message data. In order to read a public message, text encoding conversion to an internal format will occur automatically.<BR>The actual message data is opened, and the string is extracted into memory.<BR>The string data for the message subject included in the message data, converted to the internal encoding (UTF-16BE), is stored in the u16 array indicated by <CODE><EM><STRONG>subject</STRONG></EM></CODE>. The string to be retrieved is terminated with L'\0' (the UTF-16BE null character). In addition, the number of characters including the terminator that can be stored in <CODE><EM><STRONG>subject</STRONG></EM></CODE> (in u16) is passed to <CODE><EM><STRONG>length</STRONG></EM></CODE>; after processing, the number of UTF-16BE characters without the null-terminator is overwritten and returned.<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>. When a public message is received with the encoding omitted, the encoding is deduced using <CODE><EM><STRONG>autoEnc</STRONG></EM></CODE>. <BR><CODE><EM><STRONG>altChar</STRONG></EM></CODE> 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 <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. 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 subject to be processed. <CODE>NWC24_ERR_OVERFLOW</CODE> is returned when there is insufficient working memory.
29</P>
30
31<H2>Arguments</H2>
32<TABLE border="1" cellpadding="3" cellspacing="0.1">
33  <TR>
34<TD width="120" bgcolor="#ffffe8"><code><em><strong>obj</strong></em></code></TD>
35    <TD width="520">
36Message object from which settings are to be extracted.
37    </TD>
38  </TR>
39  <TR>
40<TD width="120" bgcolor="#ffffe8"><code><em><strong>subject</strong></em></code></TD>
41    <TD width="520">
42Pointer to the u16 array where the read string is stored.<BR>
43    </TD>
44  </TR>
45  <TR>
46<TD width="120" bgcolor="#ffffe8"><code><em><strong>length</strong></em></code></TD>
47    <TD width="520">
48When this function stores a message of the size specified in <code><em><strong>subject</strong></em></code>, the actual number of stored characters (excluding the terminator) are overwritten and returned.<BR>
49    </TD>
50  </TR>
51  <TR>
52<TD width="120" bgcolor="#ffffe8"><code><em><strong>autoEnc</strong></em></code></TD>
53    <TD width="520">
54An auto-determining type of <A HREF="../Types/NWC24AutoEncodingType.html"><CODE>NWC24AutoEncodingType</CODE></A>, used as a hint during conversion.<BR>
55    </TD>
56  </TR>
57  <TR>
58<TD width="120" bgcolor="#ffffe8"><code><em><strong>altChar</strong></em></code></TD>
59    <TD width="520">
60Alternate text, in UTF-16BE encoding, to be used when text that cannot be converted to internal text encoding is encountered.<BR>
61    </TD>
62  </TR>
63  <TR>
64<TD width="120" bgcolor="#ffffe8"><code><em><strong>work</strong></em></code></TD>
65    <TD width="520">
66The working memory used for conversion.<BR>
67    </TD>
68  </TR>
69  <TR>
70<TD width="120" bgcolor="#ffffe8"><code><em><strong>workSize</strong></em></code></TD>
71    <TD width="520">
72The length of the work memory specified in <code><em><strong>work</strong></em></code>.<BR>
73    </TD>
74  </TR>
75</TABLE>
76
77<h2>Return Values</h2>
78<P>
79<code>NWC24_OK</code>: Normal exit.<BR><code>NWC24_ERR_LIB_NOT_OPENED</code>: Library is not open.<BR><code>NWC24_ERR_PROTECTED</code>: Cannot read message object.<BR><code>NWC24_ERR_NULL</code>: Message data not set.<BR><code>NWC24_ERR_OVERFLOW</code>: Either the subject set for the message object overflowed buffer, or the work memory region was insufficient.<BR><code>NWC24_ERR_NOT_SUPPORTED</code>: Unsupported character code or MIME encoding type set for message object.<BR><code>NWC24_ERR_INVALID_VALUE</code>: Invalid argument.<BR><code>NWC24_ERR_INVALID_CHAR</code>: Cannot convert to internal character encoding.<BR><code>NWC24_ERR_FILE_*</code>: Internal file operation error.<BR>
80</P>
81
82<H2>See Also</H2>
83<P>
84None.
85</P>
86
87<H2>Revision History</H2>
88<P>
892007/01/31 Initial version.
90</P>
91
92<hr><p>CONFIDENTIAL</p></body>
93</HTML>