1 {{+bindTo:partials.standard_nacl_api}}
2 <h1>pp::CompletionCallback Class Reference</h1>
4 {{- dummy div to appease doxygen -}}
6 <!-- Generated by Doxygen 1.7.6.1 -->
12 <div class="contents">
13 <!-- doxytag: class="pp::CompletionCallback" --><div class="dynheader">
14 Inheritance diagram for pp::CompletionCallback:</div>
15 <div class="dyncontent">
16 <div class="center"><img src="classpp_1_1_completion_callback__inherit__graph.png" border="0" usemap="#pp_1_1_completion_callback_inherit__map" alt="Inheritance graph" /></div>
17 <map name="pp_1_1_completion_callback_inherit__map" id="pp_1_1_completion_callback_inherit__map">
18 <area shape="rect" id="node3" href="classpp_1_1internal_1_1_completion_callback_with_output_base.html" title="pp::internal::CompletionCallbackWithOutputBase\< T, internal::CallbackOutputTraits\< T \> \>" alt="" coords="237,5,835,35"></area><area shape="rect" id="node7" href="classpp_1_1internal_1_1_completion_callback_with_output_base.html" title="pp::internal::CompletionCallbackWithOutputBase\< T, internal::ExtCallbackOutputTraits\< T \> \>" alt="" coords="227,59,845,88"></area><area shape="rect" id="node11" href="classpp_1_1internal_1_1_completion_callback_with_output_base.html" title="The base class of [Ext]CompletionCallbackWithOutput." alt="" coords="332,112,740,141"></area><area shape="rect" id="node5" href="classpp_1_1_completion_callback_with_output.html" title="A CompletionCallbackWithOutput defines a completion callback that additionally stores a pointer to so..." alt="" coords="917,5,1197,35"></area><area shape="rect" id="node9" href="classpp_1_1ext_1_1_ext_completion_callback_with_output.html" title="ExtCompletionCallbackWithOutput is similar to CompletionCallbackWithOutput, but used by APIs within t..." alt="" coords="893,59,1221,88"></area></map>
19 <center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
20 <p><a href="classpp_1_1_completion_callback-members.html">List of all members.</a></p>
22 Public Member Functions</h2><table class="memberdecls">
24 <tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#a2dae27f9f015c3b9342a4a65f05bd356">CompletionCallback</a> ()</td></tr>
25 <tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#afe88416d324795a748d5112e197b0131">CompletionCallback</a> (PP_CompletionCallback_Func func, void *user_data)</td></tr>
26 <tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#a14fd9478ff007a91a3cdfa397c8e6e56">CompletionCallback</a> (PP_CompletionCallback_Func func, void *user_data, int32_t <a class="el" href="classpp_1_1_completion_callback.html#a60e466572fe7de362969dd41179c971f">flags</a>)</td></tr>
27 <tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#a89fb884e8af572e9bf38fb880e132438">set_flags</a> (int32_t <a class="el" href="classpp_1_1_completion_callback.html#a60e466572fe7de362969dd41179c971f">flags</a>)</td></tr>
28 <tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#a7795404cc15a4f96523c28db21d364c4">Run</a> (int32_t result)</td></tr>
29 <tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#a2996ca2f2b640c7da6da9016a5b0cd16">RunAndClear</a> (int32_t result)</td></tr>
30 <tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#a6ce66ec2655c9157cab494f248551b5f">IsOptional</a> () const </td></tr>
31 <tr><td class="memItemLeft" align="right" valign="top">const PP_CompletionCallback & </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#ada943a747c94eebb1e32dbd6914c2526">pp_completion_callback</a> () const </td></tr>
32 <tr><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#a60e466572fe7de362969dd41179c971f">flags</a> () const </td></tr>
33 <tr><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#a24d1648d1a92a5c36894ce081457e603">MayForce</a> (int32_t result) const </td></tr>
35 Protected Attributes</h2><table class="memberdecls">
36 <tr><td class="memItemLeft" align="right" valign="top">PP_CompletionCallback </td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_completion_callback.html#af071c756ff3eb007dfbea3f50df74111">cc_</a></td></tr>
38 <hr /><a name="details" id="details"></a><h2>Detailed Description</h2>
39 <div class="textblock"><p>This API enables you to implement and receive callbacks when Pepper operations complete asynchronously. </p>
40 <p>You can create these objects yourself, but it is most common to use the <a class="el" href="classpp_1_1_completion_callback_factory.html" title="CompletionCallbackFactory<T> may be used to create CompletionCallback objects that are bound to membe...">CompletionCallbackFactory</a> to allow the callbacks to call class member functions. </p>
41 </div><hr /><h2>Constructor & Destructor Documentation</h2>
42 <a class="anchor" id="a2dae27f9f015c3b9342a4a65f05bd356"></a><!-- doxytag: member="pp::CompletionCallback::CompletionCallback" ref="a2dae27f9f015c3b9342a4a65f05bd356" args="()" -->
44 <div class="memproto">
45 <table class="memname">
47 <td class="memname"><a class="el" href="classpp_1_1_completion_callback.html#a2dae27f9f015c3b9342a4a65f05bd356">pp::CompletionCallback::CompletionCallback</a> </td>
49 <td class="paramname"></td><td>)</td>
50 <td><code> [inline]</code></td>
55 <p>The default constructor will create a blocking <code><a class="el" href="classpp_1_1_completion_callback.html" title="This API enables you to implement and receive callbacks when Pepper operations complete asynchronousl...">CompletionCallback</a></code> that can be passed to a method to indicate that the calling thread should be blocked until the asynchronous operation corresponding to the method completes. </p>
56 <p><b>Note:</b> Blocking completion callbacks are only allowed from from background threads. </p>
59 <a class="anchor" id="afe88416d324795a748d5112e197b0131"></a><!-- doxytag: member="pp::CompletionCallback::CompletionCallback" ref="afe88416d324795a748d5112e197b0131" args="(PP_CompletionCallback_Func func, void *user_data)" -->
61 <div class="memproto">
62 <table class="memname">
64 <td class="memname"><a class="el" href="classpp_1_1_completion_callback.html#a2dae27f9f015c3b9342a4a65f05bd356">pp::CompletionCallback::CompletionCallback</a> </td>
66 <td class="paramtype">PP_CompletionCallback_Func </td>
67 <td class="paramname"><em>func</em>, </td>
70 <td class="paramkey"></td>
72 <td class="paramtype">void * </td>
73 <td class="paramname"><em>user_data</em> </td>
78 <td></td><td><code> [inline]</code></td>
83 <p>A constructor for creating a <code><a class="el" href="classpp_1_1_completion_callback.html" title="This API enables you to implement and receive callbacks when Pepper operations complete asynchronousl...">CompletionCallback</a></code>. </p>
84 <dl class="params"><dt><b>Parameters:</b></dt><dd>
85 <table class="params">
86 <tr><td class="paramdir">[in]</td><td class="paramname">func</td><td>The function to be called on completion. </td></tr>
87 <tr><td class="paramdir">[in]</td><td class="paramname">user_data</td><td>The user data to be passed to the callback function. This is optional and is typically used to help track state in case of multiple pending callbacks. </td></tr>
93 <a class="anchor" id="a14fd9478ff007a91a3cdfa397c8e6e56"></a><!-- doxytag: member="pp::CompletionCallback::CompletionCallback" ref="a14fd9478ff007a91a3cdfa397c8e6e56" args="(PP_CompletionCallback_Func func, void *user_data, int32_t flags)" -->
95 <div class="memproto">
96 <table class="memname">
98 <td class="memname"><a class="el" href="classpp_1_1_completion_callback.html#a2dae27f9f015c3b9342a4a65f05bd356">pp::CompletionCallback::CompletionCallback</a> </td>
100 <td class="paramtype">PP_CompletionCallback_Func </td>
101 <td class="paramname"><em>func</em>, </td>
104 <td class="paramkey"></td>
106 <td class="paramtype">void * </td>
107 <td class="paramname"><em>user_data</em>, </td>
110 <td class="paramkey"></td>
112 <td class="paramtype">int32_t </td>
113 <td class="paramname"><em>flags</em> </td>
118 <td></td><td><code> [inline]</code></td>
123 <p>A constructor for creating a <code><a class="el" href="classpp_1_1_completion_callback.html" title="This API enables you to implement and receive callbacks when Pepper operations complete asynchronousl...">CompletionCallback</a></code> with specified flags. </p>
124 <dl class="params"><dt><b>Parameters:</b></dt><dd>
125 <table class="params">
126 <tr><td class="paramdir">[in]</td><td class="paramname">func</td><td>The function to be called on completion. </td></tr>
127 <tr><td class="paramdir">[in]</td><td class="paramname">user_data</td><td>The user data to be passed to the callback function. This is optional and is typically used to help track state in case of multiple pending callbacks. </td></tr>
128 <tr><td class="paramdir">[in]</td><td class="paramname">flags</td><td>Bit field combination of <code>PP_CompletionCallback_Flag</code> flags used to control how non-NULL callbacks are scheduled by asynchronous methods. </td></tr>
134 <hr /><h2>Member Function Documentation</h2>
135 <a class="anchor" id="a60e466572fe7de362969dd41179c971f"></a><!-- doxytag: member="pp::CompletionCallback::flags" ref="a60e466572fe7de362969dd41179c971f" args="() const " -->
136 <div class="memitem">
137 <div class="memproto">
138 <table class="memname">
140 <td class="memname">int32_t <a class="el" href="classpp_1_1_completion_callback.html#a60e466572fe7de362969dd41179c971f">pp::CompletionCallback::flags</a> </td>
142 <td class="paramname"></td><td>)</td>
143 <td> const<code> [inline]</code></td>
148 <p>The <a class="el" href="classpp_1_1_completion_callback.html#a60e466572fe7de362969dd41179c971f" title="The flags() function returns flags used to control how non-NULL callbacks are scheduled by asynchrono...">flags()</a> function returns flags used to control how non-NULL callbacks are scheduled by asynchronous methods. </p>
149 <dl class="return"><dt><b>Returns:</b></dt><dd>An int32_t containing a bit field combination of <code>PP_CompletionCallback_Flag</code> flags. </dd></dl>
152 <a class="anchor" id="a6ce66ec2655c9157cab494f248551b5f"></a><!-- doxytag: member="pp::CompletionCallback::IsOptional" ref="a6ce66ec2655c9157cab494f248551b5f" args="() const " -->
153 <div class="memitem">
154 <div class="memproto">
155 <table class="memname">
157 <td class="memname">bool <a class="el" href="classpp_1_1_completion_callback.html#a6ce66ec2655c9157cab494f248551b5f">pp::CompletionCallback::IsOptional</a> </td>
159 <td class="paramname"></td><td>)</td>
160 <td> const<code> [inline]</code></td>
165 <p><a class="el" href="classpp_1_1_completion_callback.html#a6ce66ec2655c9157cab494f248551b5f" title="IsOptional() is used to determine the setting of the PP_COMPLETIONCALLBACK_FLAG_OPTIONAL flag...">IsOptional()</a> is used to determine the setting of the <code>PP_COMPLETIONCALLBACK_FLAG_OPTIONAL</code> flag. </p>
166 <p>This flag allows any method taking such callback to complete synchronously and not call the callback if the operation would not block. This is useful when performance is an issue, and the operation bandwidth should not be limited to the processing speed of the message loop.</p>
167 <p>On synchronous method completion, the completion result will be returned by the method itself. Otherwise, the method will return PP_OK_COMPLETIONPENDING, and the callback will be invoked asynchronously on the same thread where the PPB method was invoked.</p>
168 <dl class="return"><dt><b>Returns:</b></dt><dd>true if this callback is optional, otherwise false. </dd></dl>
171 <a class="anchor" id="a24d1648d1a92a5c36894ce081457e603"></a><!-- doxytag: member="pp::CompletionCallback::MayForce" ref="a24d1648d1a92a5c36894ce081457e603" args="(int32_t result) const " -->
172 <div class="memitem">
173 <div class="memproto">
174 <table class="memname">
176 <td class="memname">int32_t <a class="el" href="classpp_1_1_completion_callback.html#a24d1648d1a92a5c36894ce081457e603">pp::CompletionCallback::MayForce</a> </td>
178 <td class="paramtype">int32_t </td>
179 <td class="paramname"><em>result</em></td><td>)</td>
180 <td> const<code> [inline]</code></td>
185 <p><a class="el" href="classpp_1_1_completion_callback.html#a24d1648d1a92a5c36894ce081457e603" title="MayForce() is used when implementing functions taking callbacks.">MayForce()</a> is used when implementing functions taking callbacks. </p>
186 <p>If the callback is required and <code>result</code> indicates that it has not been scheduled, it will be forced on the main thread.</p>
187 <p><b>Example:</b></p>
188 <div class="fragment"><pre class="fragment"> int32_t OpenURL(<a class="code" href="classpp_1_1_u_r_l_loader.html" title="URLLoader provides an API for loading URLs.">pp::URLLoader</a>* loader,
189 <a class="code" href="classpp_1_1_u_r_l_request_info.html" title="URLRequestInfo provides an API for creating and manipulating URL requests.">pp::URLRequestInfo</a>* url_request_info,
190 <span class="keyword">const</span> <a class="code" href="classpp_1_1_completion_callback.html#a2dae27f9f015c3b9342a4a65f05bd356" title="The default constructor will create a blocking CompletionCallback that can be passed to a method to i...">CompletionCallback</a>& cc) {
191 <span class="keywordflow">if</span> (loader == NULL || url_request_info == NULL)
192 <span class="keywordflow">return</span> cc.MayForce(PP_ERROR_BADRESOURCE);
193 <span class="keywordflow">return</span> loader-><a class="code" href="classpp_1_1_u_r_l_loader.html#afb72f38f30b94a2d5494225e364395b8" title="This function begins loading the URLRequestInfo.">Open</a>(*loader, *url_request_info, cc);
195 </pre></div><dl class="params"><dt><b>Parameters:</b></dt><dd>
196 <table class="params">
197 <tr><td class="paramdir">[in]</td><td class="paramname">result</td><td>PP_OK_COMPLETIONPENDING or the result of the completed operation to be passed to the callback function. PP_OK_COMPLETIONPENDING indicates that the callback has already been scheduled. Other non-positive values correspond to error codes from <code>pp_errors.h</code>. Positive values indicate additional information such as bytes read.</td></tr>
201 <dl class="return"><dt><b>Returns:</b></dt><dd><code>PP_OK_COMPLETIONPENDING</code> if the callback has been forced, result parameter otherwise. </dd></dl>
204 <a class="anchor" id="ada943a747c94eebb1e32dbd6914c2526"></a><!-- doxytag: member="pp::CompletionCallback::pp_completion_callback" ref="ada943a747c94eebb1e32dbd6914c2526" args="() const " -->
205 <div class="memitem">
206 <div class="memproto">
207 <table class="memname">
209 <td class="memname">const PP_CompletionCallback& <a class="el" href="classpp_1_1_completion_callback.html#ada943a747c94eebb1e32dbd6914c2526">pp::CompletionCallback::pp_completion_callback</a> </td>
211 <td class="paramname"></td><td>)</td>
212 <td> const<code> [inline]</code></td>
217 <p>The <a class="el" href="classpp_1_1_completion_callback.html#ada943a747c94eebb1e32dbd6914c2526" title="The pp_completion_callback() function returns the underlying PP_CompletionCallback">pp_completion_callback()</a> function returns the underlying <code>PP_CompletionCallback</code> </p>
218 <dl class="return"><dt><b>Returns:</b></dt><dd>A <code>PP_CompletionCallback</code>. </dd></dl>
221 <a class="anchor" id="a7795404cc15a4f96523c28db21d364c4"></a><!-- doxytag: member="pp::CompletionCallback::Run" ref="a7795404cc15a4f96523c28db21d364c4" args="(int32_t result)" -->
222 <div class="memitem">
223 <div class="memproto">
224 <table class="memname">
226 <td class="memname">void <a class="el" href="classpp_1_1_completion_callback.html#a7795404cc15a4f96523c28db21d364c4">pp::CompletionCallback::Run</a> </td>
228 <td class="paramtype">int32_t </td>
229 <td class="paramname"><em>result</em></td><td>)</td>
230 <td><code> [inline]</code></td>
235 <p><a class="el" href="classpp_1_1_completion_callback.html#a7795404cc15a4f96523c28db21d364c4" title="Run() is used to run the CompletionCallback.">Run()</a> is used to run the <code><a class="el" href="classpp_1_1_completion_callback.html" title="This API enables you to implement and receive callbacks when Pepper operations complete asynchronousl...">CompletionCallback</a></code>. </p>
236 <p>Normally, the system runs a <code><a class="el" href="classpp_1_1_completion_callback.html" title="This API enables you to implement and receive callbacks when Pepper operations complete asynchronousl...">CompletionCallback</a></code> after an asynchronous operation completes, but programs may wish to run the <code><a class="el" href="classpp_1_1_completion_callback.html" title="This API enables you to implement and receive callbacks when Pepper operations complete asynchronousl...">CompletionCallback</a></code> manually in order to reuse the same code paths.</p>
237 <dl class="params"><dt><b>Parameters:</b></dt><dd>
238 <table class="params">
239 <tr><td class="paramdir">[in]</td><td class="paramname">result</td><td>The result of the operation to be passed to the callback function. Non-positive values correspond to the error codes from <code>pp_errors.h</code> (excluding <code>PP_OK_COMPLETIONPENDING</code>). Positive values indicate additional information such as bytes read. </td></tr>
245 <a class="anchor" id="a2996ca2f2b640c7da6da9016a5b0cd16"></a><!-- doxytag: member="pp::CompletionCallback::RunAndClear" ref="a2996ca2f2b640c7da6da9016a5b0cd16" args="(int32_t result)" -->
246 <div class="memitem">
247 <div class="memproto">
248 <table class="memname">
250 <td class="memname">void <a class="el" href="classpp_1_1_completion_callback.html#a2996ca2f2b640c7da6da9016a5b0cd16">pp::CompletionCallback::RunAndClear</a> </td>
252 <td class="paramtype">int32_t </td>
253 <td class="paramname"><em>result</em></td><td>)</td>
254 <td><code> [inline]</code></td>
259 <p><a class="el" href="classpp_1_1_completion_callback.html#a2996ca2f2b640c7da6da9016a5b0cd16" title="RunAndClear() is used to run the CompletionCallback and clear out the callback so that it cannot be r...">RunAndClear()</a> is used to run the <code><a class="el" href="classpp_1_1_completion_callback.html" title="This API enables you to implement and receive callbacks when Pepper operations complete asynchronousl...">CompletionCallback</a></code> and clear out the callback so that it cannot be run a second time. </p>
260 <dl class="params"><dt><b>Parameters:</b></dt><dd>
261 <table class="params">
262 <tr><td class="paramdir">[in]</td><td class="paramname">result</td><td>The result of the operation to be passed to the callback function. Non-positive values correspond to the error codes from <code>pp_errors.h</code> (excluding <code>PP_OK_COMPLETIONPENDING</code>). Positive values indicate additional information such as bytes read. </td></tr>
268 <a class="anchor" id="a89fb884e8af572e9bf38fb880e132438"></a><!-- doxytag: member="pp::CompletionCallback::set_flags" ref="a89fb884e8af572e9bf38fb880e132438" args="(int32_t flags)" -->
269 <div class="memitem">
270 <div class="memproto">
271 <table class="memname">
273 <td class="memname">void <a class="el" href="classpp_1_1_completion_callback.html#a89fb884e8af572e9bf38fb880e132438">pp::CompletionCallback::set_flags</a> </td>
275 <td class="paramtype">int32_t </td>
276 <td class="paramname"><em>flags</em></td><td>)</td>
277 <td><code> [inline]</code></td>
282 <p>The <a class="el" href="classpp_1_1_completion_callback.html#a89fb884e8af572e9bf38fb880e132438" title="The set_flags() function is used to set the flags used to control how non-NULL callbacks are schedule...">set_flags()</a> function is used to set the flags used to control how non-NULL callbacks are scheduled by asynchronous methods. </p>
283 <dl class="params"><dt><b>Parameters:</b></dt><dd>
284 <table class="params">
285 <tr><td class="paramdir">[in]</td><td class="paramname">flags</td><td>Bit field combination of <code>PP_CompletionCallback_Flag</code> flags used to control how non-NULL callbacks are scheduled by asynchronous methods. </td></tr>
291 <hr /><h2>Member Data Documentation</h2>
292 <a class="anchor" id="af071c756ff3eb007dfbea3f50df74111"></a><!-- doxytag: member="pp::CompletionCallback::cc_" ref="af071c756ff3eb007dfbea3f50df74111" args="" -->
293 <div class="memitem">
294 <div class="memproto">
295 <table class="memname">
297 <td class="memname">PP_CompletionCallback <a class="el" href="classpp_1_1_completion_callback.html#af071c756ff3eb007dfbea3f50df74111">pp::CompletionCallback::cc_</a><code> [protected]</code></td>
304 <hr />The documentation for this class was generated from the following file:<ul>
305 <li><a class="el" href="completion__callback_8h.html">completion_callback.h</a></li>
307 </div><!-- contents -->
309 {{/partials.standard_nacl_api}}