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>OpenMessageBox</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>::OpenMessageBox</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> OpenMessageBox( 15 const <a href="../../../../nn/cec/CTR/TitleId.html">TitleId</a> cecTitleId, 16 const <a href="../../../../nn_types/u32.html">u32</a> privateId 17); 18</pre> 19 </div> 20<h2>Parameters</h2> 21 <div class="section"> 22 <table class="arguments"> 23 <thead> 24 <tr> 25 <td width="15" /> 26<th>Name</th> 27<td>Description</td> 28 </tr> 29 </thead> 30 <tr> 31<td>in</td> 32<th>cecTitleId</th> 33<td>StreetPass ID</td> 34 </tr> 35 <tr> 36<td>in</td> 37<th>privateId</th> 38<td>Specify the same value that was specified when the box was created using <a href="../../../../nn/cec/CTR/MessageBox/CreateMessageBox.html"><CODE>CreateMessageBox</CODE></a>. You will not be able to access the box if you specify any other value.</td> 39 </tr> </table> 40 </div> 41<h2>Return Values</h2> 42<div class="section"><a href="../../../../nn/Result/Overview.html"><CODE>nn::Result</CODE></a><br /> <br /> 43 <table class="arguments"> 44 <thead> 45 <tr> 46<th>Value</th> 47<td>Description</td> 48 </tr> 49 </thead> 50 <tr> 51<th>Result::IsSuccess</th> 52<td>Succeeded.</td> 53 </tr> 54 <tr> 55<th>ResultNoData</th> 56<td>Box does not exist.</td> 57 </tr> 58 <tr> 59<th>ResultNotAuthorized</th> 60<td>Unable to access because the private IDs are different.</td> 61 </tr> 62 <tr> 63<th>ResultStateBusy</th> 64<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> 65 </tr> 66 <tr> 67<th>ResultBufferFull</th> 68<td>Could not allocate the memory required for the process.</td> 69 </tr> 70 <tr> 71<th>Any other value</th> 72<td>Process failed.</td> 73 </tr> 74 </table> </div> 75<h2>Description</h2> 76 <div class="section"> 77<p>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.</p><p><B>Note:</B> When this function is called, the CEC (StreetPass) daemon operating in the background stops. Note that background communication might be interrupted.→ <CODE><a href="../../../../nn/cec/CTR/CecControl/StopScanning.html">CecControl::StopScanning</a></CODE><br />Call the <CODE><a href="../../../../nn/cec/CTR/MessageBox/CloseMessageBox.html">CloseMessageBox</a></CODE> function when you have finished accessing the box. After you call this function, the CEC daemon will not start running until you call the <CODE>CloseMessageBox</CODE> function. Do not leave in an open state other than when setting a send message or getting a received message. <br />With the <CODE>Open</CODE> - Message Read/Write - <CODE>Close</CODE> interval as a single processing unit, exclude Sleep and the HOME Menu during this interval.</p><!-- write here --><h3>Error Handling</h3> 78The following simplified C++ code provides guidelines for error handling.<br /> This is the process flow for opening a message box. If no box exists, this code sample creates one with <CODE>CreateMessageBox</CODE>. <code><pre> 79 nn::Result result = OpenMessageBox(); 80 if(result.IsFailure()) 81 { 82 if(result == nn::cec::ResultNoData()) 83 { 84 // If no MessageBox exists 85 86 // Prompt the user when creating a MessageBox 87 88 // Create MessageBox 89 result = CreateMessageBox(); 90 if(result.IsFailure()) 91 { 92 if(result == nn::cec::ResultBoxAlreadyExists()) 93 { 94 // If a box seems to exist, but it won't open -> a box exists whose lower 8 bits of its ID are different 95 96 // If the <CODE>CecTitleId</CODE> is specified correctly, this state will never occur. 97 // This state occurs when the <SPAN class="argument">variation</SPAN> value was set unintentionally in <CODE>MakeCecTitleId</CODE>. 98 99 // If you need to delete and recreate it -> <CODE>DeleteMessageBox(titleId);</CODE> 100 101 } 102 else if(result == nn::cec::ResultBoxNumFull()) 103 { 104 // Number of boxes has reached maximum 105 106 // Prompt the user to delete the box of some other application 107 } 108 else if(result == nn::cec::ResultStateBusy()) 109 { 110 // Daemon is running 111 // This state normally never occurs, but it might be possible to succeed by retrying 112 } 113 else if(result == nn::cec::ResultInvalidArgument() 114 || result == nn::cec::ResultTooLarge() 115 || result == nn::cec::ResultInvalidData() ) 116 { 117 // Mistake in an argument, box icon, or similar 118 } 119 120 return result; // Failure 121 } 122 123 // If <CODE>CreateMessageBox</CODE> succeeds, the box is opened. 124 125 } 126 else if(result == nn::cec::ResultNotAuthorized()) 127 { 128 // Private ID does not match 129 return result; // Failure 130 131 // If you need to delete and recreate it -> <CODE>DeleteMessageBox(titleId);</CODE> 132 } 133 else if(result == nn::cec::ResultStateBusy()) 134 { 135 // Daemon is running 136 // This state normally never occurs, but it might be possible to succeed by retrying 137 return result; // Failure 138 } 139 else 140 { 141 // Err 142 return result; // Failure 143 } 144 } 145 return result; // Success 146 147 </pre></code></div> 148<h2>Revision History</h2> 149 <div class="section"> 150 <dl class="history"> 151 <dt>2011/01/19</dt> 152<dd>Added a description of error handling.<br /> 153 </dd> 154 <dt>2010/06/14</dt> 155<dd>Initial version.<br /> 156 </dd> 157 </dl> 158 </div> 159 <hr><p>CONFIDENTIAL</p></body> 160</html>