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>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 83 // Prompt the user when creating a MessageBox 84 85 // Create MessageBox 86 result = CreateMessageBox(); 87 if(result.IsFailure()) 88 { 89 if(result == nn::cec::ResultBoxAlreadyExists()) 90 { 91 // If a box seems to exist, but it won't open -> a box exists whose lower 8 bits of its ID are different 92 93 // If the <CODE>CecTitleId</CODE> is specified correctly, this state will never occur. 94 // This state occurs when the <SPAN class="argument">variation</SPAN> value was set unintentionally in <CODE>MakeCecTitleId</CODE>. 95 96 // If you need to delete and recreate it -> <CODE>DeleteMessageBox(titleId);</CODE> 97 98 } 99 else if(result == nn::cec::ResultBoxNumFull()) 100 { 101 // Number of boxes has reached maximum 102 103 // Prompt the user to delete the box of some other application 104 } 105 else if(result == nn::cec::ResultStateBusy()) 106 { 107 // Daemon is running 108 // This state will never normally occur, but it might be possible to succeed by retrying 109 } 110 else if(result == nn::cec::ResultInvalidArgument() 111 || result == nn::cec::ResultTooLarge() 112 || result == nn::cec::ResultInvalidData() ) 113 { 114 // Mistake in an argument, box icon, or similar 115 } 116 117 return result; // Failure 118 } 119 120 // If <CODE>CreateMessageBox</CODE> succeeds, the box is opened. 121 122 } 123 else if(result == nn::cec::ResultNotAuthorized()) 124 { 125 // Private ID does not match 126 return result; // Failure 127 128 // If you need to delete and recreate it -> <CODE>DeleteMessageBox(titleId);</CODE> 129 } 130 else if(result.GetDescription() == Result::DESCRIPTION_BUSY) 131 { 132 // Daemon is running 133 // This state will never normally occur, but it might be possible to succeed by retrying 134 return result; // Failure 135 } 136 else 137 { 138 // Err 139 return result; // Failure 140 } 141 } 142 return result; // Success 143 144 </pre></code></div> 145<h2>Revision History</h2> 146 <div class="section"> 147 <dl class="history"> 148 <dt>2011/01/19</dt> 149<dd>Added description of error handling.<br /> 150 </dd> 151 <dt>2010/06/14</dt> 152<dd>Initial version.<br /> 153 </dd> 154 </dl> 155 </div> 156 <hr><p>CONFIDENTIAL</p></body> 157</html>