native_client_sdk/doc_generated/pepper_dev/c/struct_p_p_p___instance__1__1.html

{{+bindTo:partials.standard_nacl_api}}
<h1>PPP_Instance Struct Reference</h1>
<div id="doxygen-ref">
{{- dummy div to appease doxygen -}}
  <div>
<!-- Generated by Doxygen 1.7.6.1 -->


</div>
<!--header-->
<div class="contents">
<!-- doxytag: class="PPP_Instance" --><h2>
Data Fields</h2><table class="memberdecls">

<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group___enums.html#ga4f272d99be14aacafe08dfd4ef830918">PP_Bool</a>(*&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_p_p_p___instance__1__1.html#aff2dd72f7aab6335cacf8bc3a66ccbba">DidCreate</a> )(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, uint32_t argc, const char *argn[], const char *argv[])</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void(*&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_p_p_p___instance__1__1.html#a99edbb91abde255fec3bc3e1f9c8ba82">DidDestroy</a> )(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void(*&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_p_p_p___instance__1__1.html#aa028a7b17d62242ac56b6ab4b55dc047">DidChangeView</a> )(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, <a class="el" href="group___typedefs.html#gafdc3895ee80f4750d0d95ae1b677e9b7">PP_Resource</a> view)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void(*&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_p_p_p___instance__1__1.html#abf4a481156b605938416bf873bd2c782">DidChangeFocus</a> )(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, <a class="el" href="group___enums.html#ga4f272d99be14aacafe08dfd4ef830918">PP_Bool</a> has_focus)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group___enums.html#ga4f272d99be14aacafe08dfd4ef830918">PP_Bool</a>(*&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct_p_p_p___instance__1__1.html#a2fba2c9d06044a48e73a649b04398e1d">HandleDocumentLoad</a> )(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, <a class="el" href="group___typedefs.html#gafdc3895ee80f4750d0d95ae1b677e9b7">PP_Resource</a> url_loader)</td></tr>
</table>
<hr /><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>The <code>PPP_Instance</code> interface contains pointers to a series of functions that you must implement in your module. </p>
<p>These functions can be trivial (simply return the default return value) unless you want your module to handle events such as change of focus or input events (keyboard/mouse) events. </p>
</div><hr /><h2>Field Documentation</h2>
<a class="anchor" id="abf4a481156b605938416bf873bd2c782"></a><!-- doxytag: member="PPP_Instance::DidChangeFocus" ref="abf4a481156b605938416bf873bd2c782" args=")(PP_Instance instance, PP_Bool has_focus)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void(* <a class="el" href="struct_p_p_p___instance__1__1.html#abf4a481156b605938416bf873bd2c782">PPP_Instance::DidChangeFocus</a>)(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, <a class="el" href="group___enums.html#ga4f272d99be14aacafe08dfd4ef830918">PP_Bool</a> has_focus)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="struct_p_p_p___instance__1__1.html#abf4a481156b605938416bf873bd2c782" title="DidChangeFocus() is called when an instance has gained or lost focus.">DidChangeFocus()</a> is called when an instance has gained or lost focus. </p>
<p>Having focus means that keyboard events will be sent to the instance. An instance's default condition is that it will not have focus.</p>
<p>The focus flag takes into account both browser tab and window focus as well as focus of the plugin element on the page. In order to be deemed to have focus, the browser window must be topmost, the tab must be selected in the window, and the instance must be the focused element on the page.</p>
<p><b>Note:</b>Clicks on instances will give focus only if you handle the click event. Return <code>true</code> from <code>HandleInputEvent</code> in <code>PPP_InputEvent</code> (or use unfiltered events) to signal that the click event was handled. Otherwise, the browser will bubble the event and give focus to the element on the page that actually did end up consuming it. If you're not getting focus, check to make sure you're either requesting them via <code>RequestInputEvents()</code><code> (which implicitly marks all input events as consumed) or via </code><code>RequestFilteringInputEvents()</code> and returning true from your event handler.</p>
<p><code></code><code> </code></p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>A <code>PP_Instance</code> identifying the instance receiving the input event.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">has_focus</td><td>Indicates the new focused state of the instance. </td></tr>
</table>
</dd>
</dl>
<p></p>
</div>
</div>
<a class="anchor" id="aa028a7b17d62242ac56b6ab4b55dc047"></a><!-- doxytag: member="PPP_Instance::DidChangeView" ref="aa028a7b17d62242ac56b6ab4b55dc047" args=")(PP_Instance instance, PP_Resource view)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void(* <a class="el" href="struct_p_p_p___instance__1__1.html#aa028a7b17d62242ac56b6ab4b55dc047">PPP_Instance::DidChangeView</a>)(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, <a class="el" href="group___typedefs.html#gafdc3895ee80f4750d0d95ae1b677e9b7">PP_Resource</a> view)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p><code><a class="el" href="struct_p_p_p___instance__1__1.html#aa028a7b17d62242ac56b6ab4b55dc047" title="DidChangeView() is called when the position, size, or other view attributes of the instance has chang...">DidChangeView()</a> is called when the position, size, or other view attributes of the instance has changed. </code></p>
</div>
</div>
<a class="anchor" id="aff2dd72f7aab6335cacf8bc3a66ccbba"></a><!-- doxytag: member="PPP_Instance::DidCreate" ref="aff2dd72f7aab6335cacf8bc3a66ccbba" args=")(PP_Instance instance, uint32_t argc, const char *argn[], const char *argv[])" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group___enums.html#ga4f272d99be14aacafe08dfd4ef830918">PP_Bool</a>(* <a class="el" href="struct_p_p_p___instance__1__1.html#aff2dd72f7aab6335cacf8bc3a66ccbba">PPP_Instance::DidCreate</a>)(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, uint32_t argc, const char *argn[], const char *argv[])</td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="struct_p_p_p___instance__1__1.html#aff2dd72f7aab6335cacf8bc3a66ccbba" title="DidCreate() is a creation handler that is called when a new instance is created.">DidCreate()</a> is a creation handler that is called when a new instance is created. </p>
<p>This function is called for each instantiation on the page, corresponding to one &lt;embed&gt; tag on the page.</p>
<p>Generally you would handle this call by initializing the information your module associates with an instance and creating a mapping from the given <code>PP_Instance</code> handle to this data. The <code>PP_Instance</code> handle will be used in subsequent calls to identify which instance the call pertains to.</p>
<p>It's possible for more than one instance to be created in a single module. This means that you may get more than one <code>OnCreate</code> without an <code>OnDestroy</code> in between, and should be prepared to maintain multiple states associated with each instance.</p>
<p>If this function reports a failure (by returning <code>PP_FALSE</code>), the instance will be deleted.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>A new <code>PP_Instance</code> identifying one instance of a module. This is an opaque handle.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">argc</td><td>The number of arguments contained in <code>argn</code> and <code>argv</code>.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">argn</td><td>An array of argument names. These argument names are supplied in the &lt;embed&gt; tag, for example: <code>&lt;embed id="nacl_module" dimensions="2"&gt;</code> will produce two argument names: "id" and "dimensions."</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">argv</td><td>An array of argument values. These are the values of the arguments listed in the &lt;embed&gt; tag, for example <code>&lt;embed id="nacl_module" dimensions="2"&gt;</code> will produce two argument values: "nacl_module" and "2". The indices of these values match the indices of the corresponding names in <code>argn</code>.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><code>PP_TRUE</code> on success or <code>PP_FALSE</code> on failure. </dd></dl>
</div>
</div>
<a class="anchor" id="a99edbb91abde255fec3bc3e1f9c8ba82"></a><!-- doxytag: member="PPP_Instance::DidDestroy" ref="a99edbb91abde255fec3bc3e1f9c8ba82" args=")(PP_Instance instance)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void(* <a class="el" href="struct_p_p_p___instance__1__1.html#a99edbb91abde255fec3bc3e1f9c8ba82">PPP_Instance::DidDestroy</a>)(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="struct_p_p_p___instance__1__1.html#a99edbb91abde255fec3bc3e1f9c8ba82" title="DidDestroy() is an instance destruction handler.">DidDestroy()</a> is an instance destruction handler. </p>
<p>This function is called in many cases (see below) when a module instance is destroyed. It will be called even if <a class="el" href="struct_p_p_p___instance__1__1.html#aff2dd72f7aab6335cacf8bc3a66ccbba" title="DidCreate() is a creation handler that is called when a new instance is created.">DidCreate()</a> returned failure.</p>
<p>Generally you will handle this call by deallocating the tracking information and the <code>PP_Instance</code> mapping you created in the <a class="el" href="struct_p_p_p___instance__1__1.html#aff2dd72f7aab6335cacf8bc3a66ccbba" title="DidCreate() is a creation handler that is called when a new instance is created.">DidCreate()</a> call. You can also free resources associated with this instance but this isn't required; all resources associated with the deleted instance will be automatically freed when this function returns.</p>
<p>The instance identifier will still be valid during this call, so the module can perform cleanup-related tasks. Once this function returns, the <code>PP_Instance</code> handle will be invalid. This means that you can't do any asynchronous operations like network requests, file writes or messaging from this function since they will be immediately canceled.</p>
<p><b>Note:</b> This function will always be skipped on untrusted (Native Client) implementations. This function may be skipped on trusted implementations in certain circumstances when Chrome does "fast shutdown" of a web page. Fast shutdown will happen in some cases when all module instances are being deleted, and no cleanup functions will be called. The module will just be unloaded and the process terminated.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>A <code>PP_Instance</code> identifying one instance of a module. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a2fba2c9d06044a48e73a649b04398e1d"></a><!-- doxytag: member="PPP_Instance::HandleDocumentLoad" ref="a2fba2c9d06044a48e73a649b04398e1d" args=")(PP_Instance instance, PP_Resource url_loader)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group___enums.html#ga4f272d99be14aacafe08dfd4ef830918">PP_Bool</a>(* <a class="el" href="struct_p_p_p___instance__1__1.html#a2fba2c9d06044a48e73a649b04398e1d">PPP_Instance::HandleDocumentLoad</a>)(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, <a class="el" href="group___typedefs.html#gafdc3895ee80f4750d0d95ae1b677e9b7">PP_Resource</a> url_loader)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="struct_p_p_p___instance__1__1.html#a2fba2c9d06044a48e73a649b04398e1d" title="HandleDocumentLoad() is called after initialize for a full-frame instance that was instantiated based...">HandleDocumentLoad()</a> is called after initialize for a full-frame instance that was instantiated based on the MIME type of a DOMWindow navigation. </p>
<p>This situation only applies to modules that are pre-registered to handle certain MIME types. If you haven't specifically registered to handle a MIME type or aren't positive this applies to you, your implementation of this function can just return <code>PP_FALSE</code>.</p>
<p>The given <code>url_loader</code> corresponds to a <code>PPB_URLLoader</code> instance that is already opened. Its response headers may be queried using <code><a class="el" href="struct_p_p_b___u_r_l_loader__1__0.html#a4901dcc43cfdc026e582555974d4d853" title="GetResponseInfo() returns the current URLResponseInfo object.">PPB_URLLoader::GetResponseInfo</a></code>. The reference count for the URL loader is not incremented automatically on behalf of the module. You need to increment the reference count yourself if you are going to keep a reference to it.</p>
<p>This method returns <code>PP_FALSE</code> if the module cannot handle the data. In response to this method, the module should call ReadResponseBody() to read the incoming data.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>A <code>PP_Instance</code> identifying the instance that should do the load.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">url_loader</td><td>An open <code>PPB_URLLoader</code> instance.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><code>PP_TRUE</code> if the data was handled, <code>PP_FALSE</code> otherwise. If you return false, the load will be canceled for you. </dd></dl>
</div>
</div>
<hr />The documentation for this struct was generated from the following file:<ul>
<li><a class="el" href="ppp__instance_8h.html">ppp_instance.h</a></li>
</ul>
</div><!-- contents -->
</div>
{{/partials.standard_nacl_api}}