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>nn::cec::CTR::MessageBox::OpenMessageBox</CODE> Member Function</h1> 11<h2>Syntax</h2> 12 <div class="section"> 13 <pre class="definition"> 14<a href="../../../../nn/Result/Overview.html"><CODE>nn::Result</CODE></a> OpenMessageBox( 15 const <a href="../../../../nn/cec/CTR/TitleId.html">TitleId</a> cecTitleId, 16 const u32 privateId 17); 18</pre> 19 </div> 20<h2>Arguments</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><CODE>ResultSuccess</CODE></th> 52<td>Process succeeded.</td> 53 </tr> 54 <tr> 55<th><CODE>ResultNoData</CODE></th> 56<td>Box does not exist.</td> 57 </tr> 58 <tr> 59<th><CODE>ResultNotAuthorized</CODE></th> 60<td>Unable to access because the private IDs are different.</td> 61 </tr> 62 <tr> 63<th><CODE>ResultStateBusy</CODE></th> 64<td>Unable to access because the daemon is busy (BUSY state). This may succeed if you wait some time before accessing again.</td> 65 </tr> 66 <tr> 67<th>A value other than the above.</th> 68<td>Operation failed.</td> 69 </tr> 70 </table> </div> 71<h2>Description</h2> 72 <div class="section"> 73<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>When this function is called, the CEC daemon operating in the background stops. Be aware that background communication might be interrupted.→ <a href="../../../../nn/cec/CTR/CecControl/StopScanning.html"><CODE>CecControl::StopScanning</CODE></a><br /> Call the <CODE>CloseMessageBox</CODE> function when you have finished accessing the box.<br /><br />After you call this function, the CEC daemon will not start running until you call the <CODE>CloseMessageBox</CODE> function. Open message boxes only to set a send message or get a received message; do not leave them open at any other time. One safe implementation is to treat the <CODE>Open</CODE>-to-<CODE>Close</CODE> interval as a single unit of processing and mutually exclude Sleep Mode during that time.</p><!-- write here --><h3>Error Handling</h3> 74The following simplified C++ code provides guidelines for error handling.<br /> It shows the process flow of opening a box. If no box exists, this code sample creates one with <CODE>CreateMessageBox</CODE>. 75 <code><pre> 76 nn::Result result = OpenMessageBox(); 77 if(result.IsFailure()) 78 { 79 if(result == nn::cec::ResultNoData()) 80 { 81 // If no MessageBox exists 82 // Prompt the user when creating a MessageBox 83 // Create MessageBox 84 result = CreateMessageBox(); 85 if(result.IsFailure()) 86 { 87 if(result == nn::cec::ResultBoxAlreadyExists()) 88 { 89 // If a box seems to exist, but it won't open -> a box exists whose lower 8 bits of its ID are different 90 // If the <CODE>CecTitleId</CODE> is specified correctly, this state will never occur. 91 // This state occurs when the <SPAN class="argument">variation</SPAN> value was set unintentionally in <CODE>MakeCecTitleId</CODE>. 92 // If you need to delete and recreate it -> <CODE>DeleteMessageBox(titleId);</CODE> 93 } 94 else if(result == nn::cec::ResultBoxNumFull()) 95 { 96 // Number of boxes has reached maximum 97 // Prompt the user to delete the box of some other application 98 } 99 else if(result == nn::cec::ResultStateBusy()) 100 { 101 // Daemon is running 102 // This state will never normally occur, but it might be possible to succeed by retrying 103 } 104 else if(result == nn::cec::ResultInvalidArgument() 105 || result == nn::cec::ResultTooLarge() 106 || result == nn::cec::ResultInvalidData() ) 107 { 108 // Mistake in an argument, box icon, or similar 109 } 110 return result; // Failure 111 } 112 // If <CODE>CreateMessageBox</CODE> succeeds, the box is opened. 113 } 114 else if(result == nn::cec::ResultNotAuthorized()) 115 { 116 // Private ID does not match 117 return result; // Failure 118 // If you need to delete and recreate it -> <CODE>DeleteMessageBox(titleId);</CODE> 119 } 120 else if(result.GetDescription() == Result::DESCRIPTION_BUSY) 121 { 122 // Daemon is running 123 // This state will never normally occur, but it might be possible to succeed by retrying 124 return result; // Failure 125 } 126 else 127 { 128 // Err 129 return result; // Failure 130 } 131 } 132 return result; // Success 133 </pre></code></div> 134<h2>Revision History</h2> 135 <div class="section"> 136 <dl class="history"> 137 <dt>2011/01/19</dt> 138<dd>Added description of error handling.<br /> 139 </dd> 140 <dt>2010/06/14</dt> 141<dd>Initial version.<br /> 142 </dd> 143 </dl> 144 </div> 145 <hr><p>CONFIDENTIAL</p></body> 146</html> 147