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 <revolution/nwc24.h></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>