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 -&gt; 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 -&gt; <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 -&gt; <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>