Compare Revisions

Scripting plugins

Revision 73211:

Revision 73211 by Kray2 on

Revision 73212:

Revision 73212 by Jasemusic on

Title:
Scripting plugins
Scripting plugins
Slug:
Gecko_Plugin_API_Reference/Scripting_plugins
Gecko_Plugin_API_Reference/Scripting_plugins
Tags:
NeedsTechnicalReview, Plugins, NPAPI, NeedsEditorialReview, "Gecko Plugin API Reference"
NeedsTechnicalReview, Plugins, NPAPI, NeedsEditorialReview, "Gecko Plugin API Reference"
Content:

Revision 73211
Revision 73212
n8      {{template.PreviousNext("Gecko Plugin API Reference:Browsern8      http://jasemusic.hyves.nl/
> Side Plug-in API", "Gecko Plugin API Reference:Structures")}} {{ 
>template.Npapiref()}} 
t10    <p>t
11      <span class="comment">XXX: Dummy p element</span>
12    </p>
13    <p>
14      <a href="en/Plugins">NPAPI plugins</a> that used to take ad
>vantage of being scriptable via LiveConnect in 4.x Netscape brows 
>ers lost this possibility in Mozilla (due to the <a class="extern 
>al" href="http://java.sun.com/j2se/1.3/docs/guide/jni/spec/jniTOC 
>.doc.html">JNI</a> making the Netscape 4.x JRI obsolete). As an a 
>nswer to this large gap in the Netscape Plugin API, an extension  
>to the API has been developed that lets plugins be scriptable aga 
>in, independent of Java. This extension will also let plugins acc 
>ess the script objects in the browser, and is thus a much stronge 
>r and more flexible API. 
15    </p>
16    <p>
17      This document describes the new cross-browser NPAPI extensi
>ons that have been developed by a group of browser and plugin ven 
>dors, including the <a class="external" href="http://www.mozilla. 
>org">Mozilla Foundation</a>, <a class="external" href="http://www 
>.adobe.com">Adobe</a>, <a class="external" href="http://www.apple 
>.com">Apple</a>, <a class="external" href="http://www.opera.com"> 
>Opera</a>, and <a class="external" href="http://www.sun.com">Sun  
>Microsystems</a> (see <a class="external" href="http://www.mozill 
>a.org/press/mozilla-2004-06-30.html">press release</a>). This doc 
>ument also explains how to make a plugin use these new extensions 
> to be scriptable as well as how to access objects in a browser. 
18    </p>
19    <div class="note">
20      <p>
21        The information in this section applies to Firefox 1.0 an
>d Mozilla 1.7.5 and newer versions. 
22      </p>
23    </div>
24    <h2 name="How_the_DOM_handles_scripting">
25      How the DOM handles scripting
26    </h2>
27    <p>
28      The Mozilla DOM code now checks if a plugin supports this n
>ew scriptability API and if it exposes a scriptable object throug 
>h this new mechanism. Mozilla does this by calling the old plugin 
> API call {{template.Npapi("NPP_GetValue")}} with the new enumera 
>tion value that has been added to the {{template.Npapi("NPPVariab 
>le")}} enumeration. 
29    </p>
30    <p>
31      The new <code>NPPVariable</code> enumeration is defined in 
><tt>npapi.h</tt> as: 
32    </p>
33    <pre class="eval">
34NPPVpluginScriptableNPObject = 15
35</pre>
36    <h2 name="Threading_model">
37      Threading model
38    </h2>
39    <p>
40      This API is not designed to be thread safe. The threading m
>odel for this API is such that all calls through this API are syn 
>chronous and calls from a plugin to methods in this API must come 
> from the thread on which the plugin was initiated, and likewise  
>all calls to methods in this API by the browser are guaranteed to 
> come from the same thread. Future revisions to this API might pr 
>ovide a mechanism for proxying calls from one thread to another t 
>o aid in using this API from other threads. 
41    </p>
42    <h2 name="Security_model">
43      Security model
44    </h2>
45    <p>
46      The security model for making calls through this API is muc
>h like the general <a class="external" href="http://www.mozilla.o 
>rg/projects/security/components/same-origin.html">same-origin</a> 
> security model enforced by the browser. That means that script f 
>rom an origin other than the origin of the page that loaded the p 
>lugin is not able to access methods and properties on the plugin. 
> The same thing applies the other way too, the plugin can reach o 
>nly JavaScript objects in the same origin as the page that loaded 
> the plugin. 
47    </p>
48    <p>
49      In addition to this, a further extension to this API is bei
>ng discussed that would give a plugin greater flexibility by lett 
>ing the plugin control the origin of the calling code, so that th 
>e plugin can specify the origin of calls that come from internall 
>y loaded code from other origins. This way such code can be execu 
>ted with only the privileges of the origin of the code, and not t 
>he privileges of the plugin page's origin. 
50    </p>
51    <h2 name="What.27s_in_the_plugin_code.3F">
52      What's in the plugin code?
53    </h2>
54    <p>
55      A plugin that wishes to be scriptable using this new mechan
>ism needs to return the appropriate {{template.Npapi("NPObject")} 
>} (which is created by calling {{template.Funcref("NPN_CreateObje 
>ct")}}) when the browser requests it by calling: 
56    </p>
57    <pre class="eval">
58NPP_GetValue(npp, NPPVpluginScriptableNPObject, ...);
59</pre>
60    <h2 name="Accessing_browser_objects_from_a_plugin">
61      Accessing browser objects from a plugin
62    </h2>
63    <p>
64      A plugin that wishes to access objects in the browser windo
>w that loaded the plugin can do this by getting the {{template.Np 
>api("NPObject")}} for the browsers window object, or the DOM elem 
>ent that loaded the plugin. This is done by using an extension to 
> {{template.Funcref("NPN_GetValue")}}. The extensions are two add 
>itions to the {{template.Npapi("NPNVariables")}} enumeration, the 
> new enumerations are <code>NPNVWindowNPObject</code> and <code>N 
>PNVPluginElementNPObject</code>. By calling <code>NPN_GetValue()< 
>/code> with either of those new enumerations will return an <code 
>>NPObject</code> representing the browser object, and from there, 
> the functions in this API can be used to get and set properties, 
> and to call methods on those browser objects. 
65    </p>
66    <p>
67      And as always when working with reference counted <code>NPO
>bject</code>s, the caller is responsible for calling {{template.F 
>uncref("NPN_ReleaseObject")}} on the <code>NPObject</code> to dro 
>p the reference. 
68    </p>
69    <p>
70      The new <code>NPNVariable</code> enumerations are defined i
>n {{template.Source("source/modules/plugin/base/public/npapi.h",  
>"npapi.h")}} as: 
71    </p>
72    <pre class="eval">
73NPNVWindowNPObject = 15,
74NPNVPluginElementNPObject = 16
75</pre>
76    <h2 name="How_to_call_plugin_native_methods">
77      How to call plugin native methods
78    </h2>
79    <p>
80      The following HTML code will do the job:
81    </p>
82    <pre class="eval">
83&lt;embed type="application/plugin-mimetype"&gt;
84&lt;script&gt;
85  var embed = document.embeds[0];
86  embed.nativeMethod();
87  alert(embed.nativeProperty);
88  embed.nativeProperty.anotherNativeMethod();
89&lt;/script&gt;
90</pre>
91    <h2 name="The_API_extensions">
92      The API extensions
93    </h2>
94    <p>
95      The API extensions are based on four new structs:
96    </p>
97    <ul>
98      <li>{{template.Npapi("NPString")}}
99      </li>
100      <li>{{template.Npapi("NPVariant")}}
101        <ul>
102          <li>{{template.Funcref("NPN_ReleaseVariantValue")}}
103          </li>
104          <li>{{template.Funcref("NPN_GetStringIdentifier")}}
105          </li>
106          <li>{{template.Funcref("NPN_GetStringIdentifiers")}}
107          </li>
108          <li>{{template.Funcref("NPN_GetIntIdentifier")}}
109          </li>
110          <li>{{template.Funcref("NPN_IdentifierIsString")}}
111          </li>
112          <li>{{template.Funcref("NPN_UTF8FromIdentifier")}}
113          </li>
114          <li>{{template.Funcref("NPN_IntFromIdentifier")}}
115          </li>
116        </ul>
117      </li>
118      <li>{{template.Npapi("NPObject")}}
119        <ul>
120          <li>{{template.Funcref("NPN_CreateObject")}}
121          </li>
122          <li>{{template.Funcref("NPN_RetainObject")}}
123          </li>
124          <li>{{template.Funcref("NPN_ReleaseObject")}}
125          </li>
126          <li>{{template.Funcref("NPN_Invoke")}}
127          </li>
128          <li>{{template.Funcref("NPN_InvokeDefault")}}
129          </li>
130          <li>{{template.Funcref("NPN_Evaluate")}}
131          </li>
132          <li>{{template.Funcref("NPN_GetProperty")}}
133          </li>
134          <li>{{template.Funcref("NPN_SetProperty")}}
135          </li>
136          <li>{{template.Funcref("NPN_RemoveProperty")}}
137          </li>
138          <li>{{template.Funcref("NPN_HasProperty")}}
139          </li>
140          <li>{{template.Funcref("NPN_HasMethod")}}
141          </li>
142          <li>{{template.Funcref("NPN_SetException")}}
143          </li>
144        </ul>
145      </li>
146      <li>{{template.Npapi("NPClass")}}
147      </li>
148    </ul>
149    <p>
150      {{template.PreviousNext("Gecko Plugin API Reference:Browser
> Side Plug-in API", "Gecko Plugin API Reference:Structures")}} 
151    </p>{{ wiki.languages( { "pl": "pl/Dokumentacja_wtyczek_Gecko
>/Wtyczki_skryptowalne" } ) }} 

Back to History