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 <style type="text/css"><!-- 8 span.static_style 9 { 10 font-size : 8pt; 11 color : white; 12 font-weight : bold; 13 background : #44f; 14 border-left : solid 1px #aaf; 15 border-top : solid 1px #aaf; 16 border-right : solid 1px #00c; 17 border-bottom : solid 1px #00c; 18 padding-left : 2px; 19 padding-right : 2px; 20 } 21 22 span.virtual_style 23 { 24 font-size : 8pt; 25 color : white; 26 font-weight : bold; 27 background : #0a0; 28 border-left : solid 1px #0f0; 29 border-top : solid 1px #0f0; 30 border-right : solid 1px #060; 31 border-bottom : solid 1px #060; 32 padding-left : 2px; 33 padding-right : 2px; 34 } 35 36 span.protected_style 37 { 38 font-size : 8pt; 39 color : white; 40 font-weight : bold; 41 background : #444; 42 border-left : solid 1px #ccc; 43 border-top : solid 1px #ccc; 44 border-right : solid 1px #222; 45 border-bottom : solid 1px #222; 46 padding-left : 2px; 47 padding-right : 2px; 48 } 49 --></style> 50<title>nn::cec::CTR::MessageBox</title> 51 </head> 52 <body> 53<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>::MessageBox</CODE> Class</h1> 54<h2>Syntax</h2> 55 <div class="section"> 56 <pre class="definition">class MessageBox</pre> 57 </div> 58<h2>Description</h2> 59 <div class="section"> 60<p>This class is used to access CEC <CODE>MessageBox</CODE> objects.</p><p>This allows you to create and delete boxes, write and load messages, get box information, and so forth. By creating a box with the <a href="../../../../nn/cec/CTR/MessageBox/CreateMessageBox.html"><CODE>CreateMessageBox</CODE></a> function and then opening it with the <a href="../../../../nn/cec/CTR/MessageBox/OpenMessageBox.html"><CODE>OpenMessageBox</CODE></a> function, you can access the messages in that box. You can use the <a href="../../../../nn/cec/CTR/MessageBox/WriteMessage.html"><CODE>WriteMessage</CODE></a> function to write messages to a box. Messages written to the outbox are sent. Received messages are stored in the inbox and can be read with the <a href="../../../../nn/cec/CTR/MessageBox/ReadMessage.html"><CODE>ReadMessage</CODE></a> function.<br /><BR>Call the <CODE><a href="../../../../nn/cec/CTR/MessageBox/CloseMessageBox.html">CloseMessageBox</a></CODE> function when you have finished accessing the box. Changes are committed when you call the <CODE>CloseMessageBox</CODE>/<CODE><a href="../../../../nn/cec/CTR/MessageBox/CommitMessageBox.html">CommitMessageBox</a></CODE> pair. If the program is ended before changes are committed, all changes up to that point are reverted. Changes may also be reverted due to system operations, even when communication control returns to the system, such as when transitioning to Sleep Mode/Home Menu.<br />Treat the interval from <CODE>Open/Create</CODE> to <CODE>Close</CODE> as a single unit of processing and block entry to Sleep Mode/Home Menu during that time.<br /><br />When a message is created and written, a <a href="../../../../nn/cec/CTR/MessageId/Overview.html"><CODE>MessageId</CODE></a> is given to the message. The <CODE>MessageId</CODE> is a randomly generated unique value, and each message is accessed using this value as the key.<br /><br />Use the <CODE>GetMessageXXX</CODE> functions to get various information, such as the attributes of individual messages. Because the <CODE>GetMessageXXX</CODE> functions retrieve information from the message list stored in the system, they can get information faster than the message itself can be accessed with <CODE>ReadMessage</CODE>. This information is read from the system when the <CODE>OpenMessageBox</CODE> function is called. It is possible that the message list stored in the system and the information in the messages themselves may become unsynchronized due to an unexpected power outage or other interruption. (For example, you may be able to get the message ID but <CODE>ReadMessage</CODE> may fail.) The message list is regenerated when a message is written with <CODE>WriteMessage</CODE>, but if processing enters an irrecoverable state, delete it using <CODE><a href="../../../../nn/cec/CTR/MessageBox/DeleteAllMessages.html">DeleteAllMessages</a></CODE> and then <CODE><a href="../../../../nn/cec/CTR/MessageBox/DeleteMessageBox.html">DeleteMessageBox</a></CODE>.<br /><br />Do not adopt implementations that periodically call the <CODE>OpenMessageBox</CODE> and <CODE>CloseMessageBox</CODE> functions to check the arrival of messages in real time. Because communication stops whenever the <CODE>OpenMessageBox</CODE> function is called, send and receive processes cannot be executed in the background. Use the <CODE>GetCecEvent</CODE> and <CODE>GetCecInfoBuffer</CODE> functions to find out if there has been communication.<br /><br />The EULA version to which the user has agreed is checked when a message is written by the <a href="../../../../nn/cec/CTR/MessageBox/WriteMessage.html"><CODE>WriteMessage</CODE></a> function.<br />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 --></div> 61 <a name="function" id="function"> 62<h2>Member Functions</h2> 63 <div class="section"> 64 <table class="members"> 65 <tr> 66<th class="category" colspan="3">Create/Delete a Message Box</th> 67 </tr> 68 <tr> 69 <td width="100"> </td> 70 <th> 71<a href="../../../../nn/cec/CTR/MessageBox/CreateMessageBox.html"><CODE>CreateMessageBox</CODE></a> 72 </th> 73<td>Creates a <CODE>MessageBox</CODE>. An inbox and outbox are created within the message box. Any <a href="../../../../nn/cec/CTR/Message/Overview.html">message</a> set in the outbox is automatically sent during StreetPass communication, and any received data is stored in the inbox.</td> 74 </tr> 75 <tr> 76 <td width="100"> </td> 77 <th> 78<a href="../../../../nn/cec/CTR/MessageBox/DeleteMessageBox.html"><CODE>DeleteMessageBox</CODE></a> 79 </th> 80<td>Deletes a <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>.</td> 81 </tr> 82 <tr> 83 <td width="100"> </td> 84 <th> 85<a href="../../../../nn/cec/CTR/MessageBox/OpenMessageBox.html"><CODE>OpenMessageBox</CODE></a> 86 </th> 87<td>Opens a <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>. You must use this function to open a box before you can access the messages within it.</td> 88 </tr> 89 <tr> 90 <td width="100"> </td> 91 <th> 92<a href="../../../../nn/cec/CTR/MessageBox/CloseMessageBox.html"><CODE>CloseMessageBox</CODE></a> 93 </th> 94<td>Closes the <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>. This function is called when you have finished accessing the box.</td> 95 </tr> 96 <tr> 97 <td width="100"> </td> 98 <th> 99<a href="../../../../nn/cec/CTR/MessageBox/IsOpened.html"><CODE>IsOpened</CODE></a> 100 </th> 101<td>Gets whether a <CODE>MessageBox</CODE> is already opened.</td> 102 </tr> 103 <tr> 104<th class="category" colspan="3">Message Operations</th> 105 </tr> 106 <tr> 107 <td width="100"> </td> 108 <th> 109<a href="../../../../nn/cec/CTR/MessageBox/ReadMessage.html"><CODE>ReadMessage</CODE></a> 110 </th> 111<td>Reads a <a href="../../../../nn/cec/CTR/Message/Overview.html">message</a>.</td> 112 </tr> 113 <tr> 114 <td width="100"> </td> 115 <th> 116<a href="../../../../nn/cec/CTR/MessageBox/WriteMessage.html"><CODE>WriteMessage</CODE></a> 117 </th> 118<td>Writes a <a href="../../../../nn/cec/CTR/Message/Overview.html">message</a> to the system save region.</td> 119 </tr> 120 <tr> 121 <td width="100"> </td> 122 <th> 123<a href="../../../../nn/cec/CTR/MessageBox/DeleteMessage.html"><CODE>DeleteMessage</CODE></a> 124 </th> 125<td>Deletes a <a href="../../../../nn/cec/CTR/Message/Overview.html">message</a>.</td> 126 </tr> 127 <tr> 128 <td width="100"> </td> 129 <th> 130<a href="../../../../nn/cec/CTR/MessageBox/DeleteAllMessages.html"><CODE>DeleteAllMessages</CODE></a> 131 </th> 132<td>Deletes all messages in the box.</td> 133 </tr> 134 <tr> 135 <td width="100"> </td> 136 <th> 137<a href="../../../../nn/cec/CTR/MessageBox/CommitMessageBox.html"><CODE>CommitMessageBox</CODE></a> 138 </th> 139<td>Commits the data written in the system save region.</td> 140 </tr> 141 <tr> 142<th class="category" colspan="3">Controlling Boxes and Getting Information</th> 143 </tr> 144 <tr> 145 <td width="100"> </td> 146 <th> 147<a href="../../../../nn/cec/CTR/MessageBox/GetMessageBoxData.html"><CODE>GetMessageBoxData</CODE></a> 148 </th> 149<td>Gets the data associated with a <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>.</td> 150 </tr> 151 <tr> 152 <td width="100"> </td> 153 <th> 154<a href="../../../../nn/cec/CTR/MessageBox/GetMessageBoxDataSize.html"><CODE>GetMessageBoxDataSize</CODE></a> 155 </th> 156<td>Gets the data size associated with a <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>.</td> 157 </tr> 158 <tr> 159 <td width="100"> </td> 160 <th> 161<a href="../../../../nn/cec/CTR/MessageBox/SetMessageBoxData.html"><CODE>SetMessageBoxData</CODE></a> 162 </th> 163<td>Sets the data associated with a <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>.</td> 164 </tr> 165 <tr> 166 <td width="100"> </td> 167 <th> 168<a href="../../../../nn/cec/CTR/MessageBox/SetMessageBoxName.html"><CODE>SetMessageBoxName</CODE></a> 169 </th> 170<td>Sets a <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>'s name.</td> 171 </tr> 172 <tr> 173 <td width="100"> </td> 174 <th> 175<a href="../../../../nn/cec/CTR/MessageBox/SetMessageBoxIcon.html"><CODE>SetMessageBoxIcon</CODE></a> 176 </th> 177<td>Sets a <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>'s icon.</td> 178 </tr> 179 <tr> 180 <td width="100"> </td> 181 <th> 182<a href="../../../../nn/cec/CTR/MessageBox/GetMessageBoxName.html"><CODE>GetMessageBoxName</CODE></a> 183 </th> 184<td>Gets a <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>'s name.</td> 185 </tr> 186 <tr> 187 <td width="100"> </td> 188 <th> 189<a href="../../../../nn/cec/CTR/MessageBox/GetMessageBoxIcon.html"><CODE>GetMessageBoxIcon</CODE></a> 190 </th> 191<td>Gets a <CODE><a href="../../../../nn/cec/CTR/MessageBox/Overview.html">MessageBox</a></CODE>'s icon.</td> 192 </tr> 193 <tr> 194<th class="category" colspan="3">Getting Message Box Information</th> 195 </tr> 196 <tr> 197 <td width="100"> </td> 198 <th> 199<a href="../../../../nn/cec/CTR/MessageBox/GetBoxSizeMax.html"><CODE>GetBoxSizeMax</CODE></a> 200 </th> 201<td>Gets the capacity of the inbox or outbox.</td> 202 </tr> 203 <tr> 204 <td width="100"> </td> 205 <th> 206<a href="../../../../nn/cec/CTR/MessageBox/GetBoxSize.html"><CODE>GetBoxSize</CODE></a> 207 </th> 208<td>Gets the used capacity of the inbox or outbox.</td> 209 </tr> 210 <tr> 211 <td width="100"> </td> 212 <th> 213<a href="../../../../nn/cec/CTR/MessageBox/GetBoxMessageNumMax.html"><CODE>GetBoxMessageNumMax</CODE></a> 214 </th> 215<td>Gets the maximum number of messages in the inbox or outbox.</td> 216 </tr> 217 <tr> 218 <td width="100"> </td> 219 <th> 220<a href="../../../../nn/cec/CTR/MessageBox/GetBoxMessageNum.html"><CODE>GetBoxMessageNum</CODE></a> 221 </th> 222<td>Gets the number of messages in the inbox or outbox.</td> 223 </tr> 224 <tr> 225 <td width="100"> </td> 226 <th> 227<a href="../../../../nn/cec/CTR/MessageBox/GetBoxGroupNumMax.html"><CODE>GetBoxGroupNumMax</CODE></a> 228 </th> 229<td>Gets the maximum number of message groups in the inbox or outbox.</td> 230 </tr> 231 <tr> 232 <td width="100"> </td> 233 <th> 234<a href="../../../../nn/cec/CTR/MessageBox/GetBoxGroupNum.html"><CODE>GetBoxGroupNum</CODE></a> 235 </th> 236<td>Gets the number of message groups in the inbox or outbox.</td> 237 </tr> 238 <tr> 239 <td width="100"> </td> 240 <th> 241<a href="../../../../nn/cec/CTR/MessageBox/SetBoxGroupNumMax.html"><CODE>SetBoxGroupNumMax</CODE></a> 242 </th> 243<td>Specifies the maximum number of message groups in the inbox or outbox.</td> 244 </tr> 245 <tr> 246 <td width="100"> </td> 247 <th> 248<a href="../../../../nn/cec/CTR/MessageBox/GetBoxSessionNum.html"><CODE>GetBoxSessionNum</CODE></a> 249 </th> 250<td>Gets the Session ID count for (the number of items received in) the inbox.</td> 251 </tr> 252 <tr> 253<th class="category" colspan="3">Getting Message Information (old API)</th> 254 </tr> 255 <tr> 256 <td width="100"> </td> 257 <th> 258<a href="../../../../nn/cec/CTR/MessageBox/GetInBoxMessIdByIndex.html"><CODE>GetInBoxMessIdByIndex</CODE></a> 259 </th> 260<td>Gets the message ID of the <CODE>n</CODE><SUP>th</SUP> message in the inbox.</td> 261 </tr> 262 <tr> 263 <td width="100"> </td> 264 <th> 265<a href="../../../../nn/cec/CTR/MessageBox/GetOutBoxMessIdByIndex.html"><CODE>GetOutBoxMessIdByIndex</CODE></a> 266 </th> 267<td>Gets the message ID of the <CODE>n</CODE><SUP>th</SUP> message in the outbox.</td> 268 </tr> 269 <tr> 270 <td width="100"> </td> 271 <th> 272<a href="../../../../nn/cec/CTR/MessageBox/GetMessSizeByMessId.html"><CODE>GetMessSizeByMessId</CODE></a> 273 </th> 274<td>Gets the size of the message with the specified message ID.</td> 275 </tr> 276 <tr> 277<th class="category" colspan="3">Getting Message Information</th> 278 </tr> 279 <tr> 280 <td width="100"> </td> 281 <th> 282<a href="../../../../nn/cec/CTR/MessageBox/GetMessageSize.html"><CODE>GetMessageSize</CODE></a> 283 </th> 284<td>Gets the size of a message.</td> 285 </tr> 286 <tr> 287 <td width="100"> </td> 288 <th> 289<a href="../../../../nn/cec/CTR/MessageBox/GetMessageBodySize.html"><CODE>GetMessageBodySize</CODE></a> 290 </th> 291<td>Gets the size of a message's body.</td> 292 </tr> 293 <tr> 294 <td width="100"> </td> 295 <th> 296<a href="../../../../nn/cec/CTR/MessageBox/GetMessageGroupId.html"><CODE>GetMessageGroupId</CODE></a> 297 </th> 298<td>Gets the group ID of a message.</td> 299 </tr> 300 <tr> 301 <td width="100"> </td> 302 <th> 303<a href="../../../../nn/cec/CTR/MessageBox/GetMessageSessionId.html"><CODE>GetMessageSessionId</CODE></a> 304 </th> 305<td>Gets an inbox message's session ID. (The ID assigned when received.)</td> 306 </tr> 307 <tr> 308 <td width="100"> </td> 309 <th> 310<a href="../../../../nn/cec/CTR/MessageBox/GetMessageTypeFlag.html"><CODE>GetMessageTypeFlag</CODE></a> 311 </th> 312<td>Gets the <CODE><a href="../../../../nn/cec/CTR/MessageTypeFlag.html">MessageTypeFlag</a></CODE> of a box message.</td> 313 </tr> 314 <tr> 315 <td width="100"> </td> 316 <th> 317<a href="../../../../nn/cec/CTR/MessageBox/GetMessageSendMode.html"><CODE>GetMessageSendMode</CODE></a> 318 </th> 319<td>Gets the <CODE><a href="../../../../nn/cec/CTR/SendMode.html">SendMode</a></CODE> of a message.</td> 320 </tr> 321 <tr> 322 <td width="100"> </td> 323 <th> 324<a href="../../../../nn/cec/CTR/MessageBox/GetMessageSendCount.html"><CODE>GetMessageSendCount</CODE></a> 325 </th> 326<td>Gets the send count of a message.</td> 327 </tr> 328 <tr> 329 <td width="100"> </td> 330 <th> 331<a href="../../../../nn/cec/CTR/MessageBox/GetMessagePropagationCount.html"><CODE>GetMessagePropagationCount</CODE></a> 332 </th> 333<td>Gets the propagation count of a message.</td> 334 </tr> 335 <tr> 336 <td width="100"> </td> 337 <th> 338<a href="../../../../nn/cec/CTR/MessageBox/GetMessageTag.html"><CODE>GetMessageTag</CODE></a> 339 </th> 340<td>Gets the message tag of a message.</td> 341 </tr> 342 <tr> 343 <td width="100"> </td> 344 <th> 345<a href="../../../../nn/cec/CTR/MessageBox/GetMessageSendDate.html"><CODE>GetMessageSendDate</CODE></a> 346 </th> 347<td>Gets the timestamp of when a received message was sent.</td> 348 </tr> 349 <tr> 350 <td width="100"> </td> 351 <th> 352<a href="../../../../nn/cec/CTR/MessageBox/GetMessageRecvDate.html"><CODE>GetMessageRecvDate</CODE></a> 353 </th> 354<td>Gets the timestamp of when a message was received.</td> 355 </tr> 356 <tr> 357 <td width="100"> </td> 358 <th> 359<a href="../../../../nn/cec/CTR/MessageBox/GetMessageCreateDate.html"><CODE>GetMessageCreateDate</CODE></a> 360 </th> 361<td>Gets the timestamp of when a message was created.</td> 362 </tr> 363 <tr> 364 <td width="100"> </td> 365 <th> 366<a href="../../../../nn/cec/CTR/MessageBox/GetMessageIdPair.html"><CODE>GetMessageIdPair</CODE></a> 367 </th> 368<td>Gets the ID of the exchanged message forming a pair with this one.</td> 369 </tr> 370 <tr> 371 <td width="100"> </td> 372 <th> 373<a href="../../../../nn/cec/CTR/MessageBox/GetMessageId.html"><CODE>GetMessageId</CODE></a> 374 </th> 375<td>Gets the <CODE>MessageID</CODE> of a message.</td> 376 </tr> 377 <tr> 378 <td width="100"> </td> 379 <th> 380<a href="../../../../nn/cec/CTR/MessageBox/GetMessageIndex.html"><CODE>GetMessageIndex</CODE></a> 381 </th> 382<td>Gets a message's index (<CODE>messIndex</CODE>) based on its <CODE>MessageID</CODE>.</td> 383 </tr> 384 <tr> 385<th class="category" colspan="3">Other</th> 386 </tr> 387 <tr> 388 <td width="100"> </td> 389 <th> 390<a href="../../../../nn/cec/CTR/MessageBox/SetBoxActivate.html"><CODE>SetBoxActivate</CODE></a> 391 </th> 392<td>Specifies whether a <CODE>MessageBox</CODE> is enabled or disabled. A disabled message box will not have any data sent or received.</td> 393 </tr> 394 <tr> 395 <td width="100"> </td> 396 <th> 397<a href="../../../../nn/cec/CTR/MessageBox/GetBoxActivate.html"><CODE>GetBoxActivate</CODE></a> 398 </th> 399<td>Gets whether a <CODE>MessageBox</CODE> is enabled or disabled. A disabled message box will not have any data sent or received.</td> 400 </tr> 401 <tr> 402 <td width="100"> </td> 403 <th> 404<a href="../../../../nn/cec/CTR/MessageBox/GetMessHeader.html">GetMessHeader</a> 405 </th> 406<td>Gets the message header.</td> 407 </tr> 408 <tr> 409 <td width="100"> </td> 410 <th> 411<a href="../../../../nn/cec/CTR/MessageBox/RoundOutBoxIndex.html"><CODE>RoundOutBoxIndex</CODE></a> 412 </th> 413<td>Moves the message with the specified message ID to the end of the outbox's outgoing message queue. (The message ID order is automatically changed when a message is sent, so there is normally no need to call this function.)</td> 414 </tr> </table> 415 </div> 416 </a> 417<h2>Revision History</h2> 418 <div class="section"> 419 <dl class="history"> 420 <dt>2011/03/18</dt> 421<dd>Renamed functions as follows: <CODE>GetBoxMessNumMax</CODE> to <CODE>GetBoxMessageNumMax</CODE>; <CODE>GetBoxMessNum </CODE>to <CODE>GetBoxMessageNum</CODE>; <CODE>GetMessageMessSize </CODE>to <CODE>GetMessageSize</CODE>; <CODE>GetMessageMessTypeFlag </CODE>to <CODE>GetMessageTypeFlag</CODE>; <CODE>GetMessageMessIdPairto </CODE><CODE>GetMessageIdPair</CODE>; <CODE>GetMessageMessId </CODE>to <CODE>GetMessageId</CODE>; <CODE>GetMessIndex </CODE>to <CODE>GetMessageIndex</CODE><br /> 422 </dd> 423 <dt>2011/01/24</dt> 424<dd>Added description of errors in <CODE>OpenMessageBox</CODE>, <CODE>ReadMessage</CODE>, and <CODE>WriteMessage</CODE>.<br /> 425 </dd> 426 <dt>2010/08/16</dt> 427<dd>Initial version.<br /> 428 </dd> 429 </dl> 430 </div> 431 <hr><p>CONFIDENTIAL</p></body> 432</html> 433