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>CreateMessageBox</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>::CreateMessageBox</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> CreateMessageBox( 15 const <a href="../../../../nn/cec/CTR/TitleId.html">TitleId</a> cecTitleId, 16 const <a href="../../../../nn_types/u32.html">u32</a> privateId, 17 const char * hmacKey, 18 const void * icon, 19 size_t iconSize, 20 const wchar_t * name, 21 size_t nameSize, 22 size_t inboxSizeMax = CEC_INBOX_SIZE_DEFAULT, 23 size_t outboxSizeMax = CEC_OUTBOX_SIZE_DEFAULT, 24 size_t inboxMessNumMax = CEC_INBOX_MESSNUM_DEFAULT, 25 size_t outboxMessNumMax = CEC_OUTBOX_MESSNUM_DEFAULT, 26 size_t size = CEC_MESSSIZEMAX_DEFAULT 27); 28</pre> 29 </div> 30<h2>Parameters</h2> 31 <div class="section"> 32 <table class="arguments"> 33 <thead> 34 <tr> 35 <td width="15" /> 36<th>Name</th> 37<td>Description</td> 38 </tr> 39 </thead> 40 <tr> 41<td>in</td> 42<th>cecTitleId</th> 43<td>A 32-bit StreetPass ID. Can be generated with <a href="../../../../nn/cec/CTR/MakeCecTitleId.html"><CODE>MakeCecTitleId</CODE></a>.</td> 44 </tr> 45 <tr> 46<td>in</td> 47<th>privateId</th> 48<td>The key needed to open a message box.→ <a href="../../../../nn/cec/CTR/MessageBox/OpenMessageBox.html"><CODE>OpenMessageBox</CODE></a><br />The value used must be stored by the application accessing the message box.</td> 49 </tr> 50 <tr> 51<td>in</td> 52<th>hmacKey</th> 53<td>Specifies the key needed to read a <a href="../../../../nn/cec/CTR/Message/Overview.html">Message</a>. Specifies a 32-byte value. This must be a secret key shared with the communication partner.<br />This value is used to check if the transmitted data has been tampered with. Transmitted data is signed with a signature generated using this key. Use a value stored by the application.<br />If it is a 32-byte value, you can also use characters other than (<CODE>0x20</CODE> – <CODE>0x7e</CODE>).</td> 54 </tr> 55 <tr> 56<td>in</td> 57<th>icon</th> 58<td>Specifies an icon.<br />Format: RGB565 (little-endian).<br /> Size: 48x48 (4.5 KB). <br /></td> 59 </tr> 60 <tr> 61<td>in</td> 62<th>iconSize</th> 63<td>Specifies the size of the icon data.</td> 64 </tr> 65 <tr> 66<td>in</td> 67<th>name</th> 68<td>Specifies an application name.<br />Encoding: UTF16-LE.<br /> Display size: Equivalent of the width of 17 full-width characters.<br /> Maximum buffer size: 64 x 2 bytes (including the <CODE>NULL</CODE> terminator).<br /></td> 69 </tr> 70 <tr> 71<td>in</td> 72<th>nameSize</th> 73<td>Specifies the size of the application name.</td> 74 </tr> 75 <tr> 76<td>in</td> 77<th>inboxSizeMax</th> 78<td>Specifies the maximum amount of data that can be saved in the inbox. The combined size of the inbox and outbox must be no more than 1 MB. The default size is 512 * 1024 bytes.</td> 79 </tr> 80 <tr> 81<td>in</td> 82<th>outboxSizeMax</th> 83<td>Specifies the maximum amount of data that can be saved in the outbox. The combined size of the inbox and outbox must be no more than 1 MB. The default size is 512 * 1024 bytes.</td> 84 </tr> 85 <tr> 86<td>in</td> 87<th>inboxMessNumMax</th> 88<td>Specifies the maximum number of messages that can be saved in the inbox. The default is 99, which is the maximum specifiable value.</td> 89 </tr> 90 <tr> 91<td>in</td> 92<th>outboxMessNumMax</th> 93<td>Specifies the maximum number of messages that can be saved in the outbox. The default is 99, which is the maximum specifiable value.</td> 94 </tr> 95 <tr> 96<td>in</td> 97<th>size</th> 98<td>This value is not used.</td> 99 </tr> </table> 100 </div> 101<h2>Return Values</h2> 102<div class="section"><a href="../../../../nn/Result/Overview.html"><CODE>nn::Result</CODE></a><br /> <br /> 103 <table class="arguments"> 104 <thead> 105 <tr> 106<th>Value</th> 107<td>Description</td> 108 </tr> 109 </thead> 110 <tr> 111<th><CODE>Result::IsSuccess</CODE></th> 112<td>Process succeeded.</td> 113 </tr> 114 <tr> 115<th><CODE>ResultBoxAlreadyExists</CODE></th> 116<td>Could not create box, because box already exists.<br />If this error is returned when the current status is <CODE>OpenMessageBox == nn::cec::ResultNoData()</CODE>, it might have been caused by an already-existing box with a different lower 8 bits of its <CODE>CecTitleId</CODE>.→ <a href="../../../../nn/cec/CTR/MakeCecTitleId.html"><CODE>MakeCecTitleId</CODE></a>, <a href="../../../../nn/cec/CTR/MessageBox/OpenMessageBox.html"><CODE>OpenMessageBox</CODE></a></td> 117 </tr> 118 <tr> 119<th><CODE>ResultBoxNumFull</CODE></th> 120<td>The maximum number of boxes have been created. To create a new box, you must delete a box for another game title.</td> 121 </tr> 122 <tr> 123<th><CODE>ResultInvalidArgument</CODE></th> 124<td>An argument was specified incorrectly.</td> 125 </tr> 126 <tr> 127<th><CODE>ResultInvalidData</CODE></th> 128<td>There is a problem with the data, icon, or name being set.</td> 129 </tr> 130 <tr> 131<th><CODE>ResultTooLarge</CODE></th> 132<td>There is a problem with the size of data being set.</td> 133 </tr> 134 <tr> 135<th><CODE>ResultStateBusy</CODE></th> 136<td>Unable to access because the daemon is busy (BUSY state). This may succeed if you wait some time before accessing again.</td> 137 </tr> 138 <tr> 139<th>A value other than the above.</th> 140<td>Process failed.</td> 141 </tr> 142 </table> </div> 143<h2>Description</h2> 144 <div class="section"> 145<p>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.</p><p><CODE>MessageBox</CODE> objects are created in NAND memory. Only one box may be created for each application. Only 12 boxes may be created in total. Attempting to create a new message box when 12 already exist will not create a new box.<br /> When a box is created, it immediately enters the "opened" state (<a href="../../../../nn/cec/CTR/MessageBox/OpenMessageBox.html"><CODE>OpenMessageBox</CODE></a>).<br /> The <SPAN class="argument">privateId</SPAN> and <SPAN class="argument">hmacKey</SPAN> values are used to restrict access. Decide and set these values on the application side.<br />The <SPAN class="argument">privateId</SPAN> value is the key needed to open a message box and is intended to be limited to one system. The <SPAN class="argument">hmacKey</SPAN> value is a secret key common to all instances of an application and is used to prevent data tampering and application spoofing. Set a value that cannot be guessed by analogy. These keys are stored in the message box. Create and set shared keys in an appropriate configuration if you need to access the same message box from multiple save-data files or applications.<br /><br />You can restrict the number and size of messages placed in the INBOX and OUTBOX. If not specified, these number of messages is limited to 99 and their size is limited to 512KB. You can get the limit on the number of messages using <a href="../../../../nn/cec/CTR/MessageBox/GetBoxMessageNum.html"><CODE>GetBoxMessageNum</CODE></a> and the size limitation using <a href="../../../../nn/cec/CTR/MessageBox/GetBoxSize.html"><CODE>GetBoxSize</CODE></a> (the total of message sizes given by <a href="../../../../nn/cec/CTR/MessageBox/GetMessageSize.html"><CODE>GetMessageSize</CODE></a> for each message). Messages will not be saved if either the number of messages or the message size exceeds the specified limit. To limit the box size in terms of number of messages, be sure to set values so that box size is not limited by message size first.<BR>When specifying a propagation count, note that there must be available space in the OUTBOX as well.<BR><B>Note:</B> When this function is called, the CEC (StreetPass) daemon operating in the background stops. Be aware that background communication might be interrupted.→ See <a href="../../../../nn/cec/CTR/CecControl/StopScanning.html"><CODE>CecControl::StopScanning</CODE></a>.<br /><br />There are two types of StreetPass icons used on System Settings screens and other screens.<br />There is a box icon and an icon for individual messages. You must specify both. This function sets the box icon.<br /><br /> Please note that if there is no data in the outbox or if send counts for all messages are zero, then communications with that title will not be performed, even if it has an exclusive box.<br /> If the inbox becomes full, communication with the partner that was discovered will be recorded as complete, but messages will not be received in the application's box. After communication with a partner is recorded as complete, no communication will be conducted with that partner for a set period of time.</p><!-- write here --></div> 146<h2>Revision History</h2> 147 <div class="section"> 148 <dl class="history"> 149 <dt>2010/08/16</dt> 150<dd>Initial version.<br /> 151 </dd> 152 </dl> 153 </div> 154 <hr><p>CONFIDENTIAL</p></body> 155</html>