1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xml:lang="en-US" lang="en-US" xmlns="http://www.w3.org/1999/xhtml">
3  <head>
4    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5    <meta http-equiv="Content-Style-Type" content="text/css" />
6    <link rel="stylesheet" href="../../../../css/manpage.css" type="text/css" />
7<title>WriteMessage</title>
8  </head>
9  <body>
10<h1><CODE><a href="../../../../nn/Overview.html">nn</a>::<a href="../../../../nn/cec/Overview.html">cec</a>::<a href="../../../../nn/cec/CTR/Overview.html">CTR</a>::<a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a>::WriteMessage</CODE> Member Function</h1>
11<h2>Syntax</h2>
12    <div class="section">
13      <pre class="definition">
14<a href="../../../../nn/Result/Overview.html">nn::Result</a> WriteMessage(
15     const <a href="../../../../nn/cec/CTR/Message/Overview.html">Message</a> & cecMessage,
16     const <a href="../../../../nn/cec/CTR/CecBoxType.html">CecBoxType</a> boxType,
17     <a href="../../../../nn/cec/CTR/MessageId/Overview.html">MessageId</a> & messageIdOut,
18     bool withWriteBoxInfo
19);
20</pre>
21    </div>
22<h2>Parameters</h2>
23    <div class="section">
24      <table class="arguments">
25        <thead>
26          <tr>
27            <td width="15" />
28<th>Name</th>
29<td>Description</td>
30          </tr>
31        </thead>
32        <tr>
33<td>in</td>
34<th>cecMessage</th>
35<td>An object of the <a href="../../../../nn/cec/CTR/Message/Overview.html"><CODE>Message</CODE></a> class.</td>
36        </tr>
37        <tr>
38<td>in</td>
39<th>boxType</th>
40<td>Inbox and outbox specification.</td>
41        </tr>
42        <tr>
43<td>out</td>
44<th>messageIdOut</th>
45<td>Returns the <a href="../../../../nn/cec/CTR/MessageId/Overview.html"><CODE>MessageId</CODE></a> that is assigned during the write operation.</td>
46        </tr>
47        <tr>
48<td>in</td>
49<th>withWriteBoxInfo</th>
50<td>Updates to the internal message list are skipped when <CODE>false</CODE> is specified. The list is updated when the <CODE><a href="../../../../nn/cec/CTR/MessageBox/CommitMessageBox.html">CommitMessageBox</a></CODE> or <CODE><a href="../../../../nn/cec/CTR/MessageBox/CloseMessageBox.html">CloseMessageBox</a></CODE> function is called.</td>
51        </tr> </table>
52    </div>
53<h2>Return Values</h2>
54<div class="section"><a href="../../../../nn/Result/Overview.html"><CODE>nn::Result</CODE></a><br /> <br />
55      <table class="arguments">
56        <thead>
57          <tr>
58<th>Value</th>
59<td>Description</td>
60          </tr>
61        </thead>
62        <tr>
63<th>Result::IsSuccess</th>
64<td>Succeeded.</td>
65        </tr>
66        <tr>
67<th>ResultNotAuthorized</th>
68<td>The box has not been opened.</td>
69        </tr>
70        <tr>
71<th>ResultMessTooLarge</th>
72<td>The message is too large.</td>
73        </tr>
74        <tr>
75<th>ResultBoxSizeFull</th>
76<td>The box's capacity has been exceeded.</td>
77        </tr>
78        <tr>
79<th>ResultBoxMessNumFull</th>
80<td>The maximum number of boxes has been exceeded.</td>
81        </tr>
82        <tr>
83<th>ResultNoData</th>
84<td>No message body or icon has been set for the message.</td>
85        </tr>
86        <tr>
87<th>ResultInvalidCombination</th>
88<td>The send count and propagation count have both been set equal to a value of <CODE>2</CODE> or greater.</td>
89        </tr>
90        <tr>
91<th><CODE>ResultNotAgreeEula</CODE></th>
92<td>The EULA has not been agreed to, or no icon file (<CODE>.icn</CODE>) is configured in the ROM.</td>
93        </tr>
94        <tr>
95<th>ResultParentalControlCec</th>
96<td>Not allowed by Parental Controls.</td>
97        </tr>
98        <tr>
99<th>ResultStateBusy</th>
100<td>Unable to access because the daemon is busy (<CODE>BUSY</CODE> state). It may succeed if you wait some time before accessing again.</td>
101        </tr>
102        <tr>
103<th>ResultBufferFull</th>
104<td>Could not allocate the memory required for the process.</td>
105        </tr>
106        <tr>
107<th>Any other value</th>
108<td>Process failed.</td>
109        </tr>
110      </table> </div>
111<h2>Description</h2>
112    <div class="section">
113<p>Writes a <a href="../../../../nn/cec/CTR/Message/Overview.html">message</a> to the system save region.</p><p>The message cannot be written if it is larger than 100 KB (including data such as the header and icon), or if it would exceed the box's maximum save capacity or maximum number of messages. You can use the <CODE><a href="../../../../nn/cec/CTR/Message/GetMessageSize.html">Message::GetMessageSize</a></CODE> function to get the message size. Because NAND memory (the save region) uses a block size of 4 KB, for some message sizes it may be impossible to write up to the maximum storage capacity. If the message size is 5 KB, a NAND memory region of 8 KB is used for storing the message. After usage exceeds 1,024 KB, messages cannot be written to memory. The number of  5 KB messages that can be stored (in the inbox and outbox combined) is 1024/8 = 128 messages.<br />Written data is committed when the <CODE><a href="../../../../nn/cec/CTR/MessageBox/CloseMessageBox.html">CloseMessageBox</a></CODE> or <CODE><a href="../../../../nn/cec/CTR/MessageBox/CommitMessageBox.html">CommitMessageBox</a></CODE> function is called after a write has been made. <br /><br />If you set <SPAN class="argument">withWriteBoxInfo</SPAN> equal to <CODE>false</CODE>, updates to the internal message list are skipped. This enables you to shorten the amount of time to write multiple consecutive messages. Note that the <CODE>GetMessageBoxXXX</CODE> functions are unable to get accurate information if the list has not been updated. <br /> The EULA version to which the user has agreed is checked when a message is written. If an icon file (<CODE>.icn</CODE>) is not set in the ROM, <CODE><a href="../../../../nn/cec/ResultNotAgreeEula/Overview.html">ResultNotAgreeEula</a></CODE> is returned. You must initialize the FS library before calling this function because the check uses <a href="../../../../nn/fs/Overview.html">FS</a> library features.</p><!-- write here --><h3>Error Handling</h3>
114The following simplified C++ code provides guidelines for error handling. <br /><code><pre>
115    nn::Result result = WriteMessage();
116    if(result.IsFailure())
117    {
118        if(result == nn::cec::ResultNotAgreeEula())
119        {
120            // The user has not agreed to the EULA.
121        }
122        else if(result == nn::cec::ResultParentalControlCec())
123        {
124            // Not permitted by Parental Controls.
125        }
126        else if(result == nn::cec::ResultNotAuthorized())
127        {
128            // Box is not open
129            //  --> OpenMessageBox
130        }
131        else if(result == nn::cec::ResultBoxSizeFull() || result == nn::cec::ResultBoxMessNumFull())
132        {
133            // Outbox capacity exceeded
134            // You must delete some outbox messages → <CODE>DeleteMessage</CODE>/<CODE>DeleteAllMessages</CODE>
135        }
136        else if(result == nn::cec::ResultMessTooLarge() || result == nn::cec::ResultNoData()
137             || result == nn::cec::ResultInvalidCombination() )
138        {
139            // Invalid message
140        }
141        else if(result == nn::cec::ResultStateBusy() )
142        {
143            // Daemon is BUSY. This state never occurs normally. It might be possible to succeed by retrying.
144        }
145        else
146        {
147            // Error
148        }
149        return result;	// Failure
150    }
151    return result;  // Success
152
153    </pre></code></div>
154<h2>Revision History</h2>
155    <div class="section">
156      <dl class="history">
157        <dt>2011/01/19</dt>
158<dd>Added a description of error handling.<br />
159        </dd>
160        <dt>2010/08/16</dt>
161<dd>Initial version.<br />
162        </dd>
163      </dl>
164    </div>
165  <hr><p>CONFIDENTIAL</p></body>
166</html>
167