1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
|
<HTML>
<HEAD><TITLE>Netscape Navigator Plug-ins</TITLE></HEAD>
<BODY>
<CENTER>
<A HREF="/index.html"><IMG SRC="/comprod/images/netscape_navigator.gif" BORDER=0></A>
<H2>
<FONT SIZE = +3>P</FONT>LUG-IN
<FONT SIZE = +3>D</FONT>ESIGN
<FONT SIZE = +3>S</FONT>PECIFICATIONS
</H2>
</CENTER>
<P>
<FONT SIZE=-1>Last updated 11/15/95</FONT>
<HR SIZE=4>
<P>
<CENTER>
<H3>
<FONT SIZE=+2>T</FONT>ABLE OF
<FONT SIZE=+2>C</FONT>ONTENTS
</H3>
</CENTER>
<UL>
<LI><A HREF="#Introduction">Introduction</A>
<LI><A HREF="#Architectural Overview">Architectural Overview</A>
<UL>
<LI><A HREF="#Appearance">Appearance</A>
<LI><A HREF="#Network">Network</A>
</UL>
<LI><A HREF="#Design Details">Design Details</A>
<UL>
<LI><A HREF="#Runtime model">Run-Time Model</A>
<LI><A HREF="#Windows and Events">Windows and Events</A>
<LI><A HREF="#Streams">Streams</A>
</UL>
<LI><A HREF="#Programming Interface">Programming Interface</A>
<UL>
<LI><A HREF="#Plug-in Methods">Plug-in Methods</A>
<LI><A HREF="#Netscape Methods">Netscape Methods</A>
<LI><A HREF="#Macintosh-specific APIs">Macintosh-Specific APIs</A>
<LI><A HREF="#Windows-specific APIs">Windows-Specific APIs</A>
<LI><A HREF="#Unix-specific APIs">Unix-Specific APIs</A>
</UL>
</UL>
<HR SIZE=4>
<P>
<A NAME="Introduction">
<CENTER>
<H3>
<FONT SIZE=+2>I</FONT>NTRODUCTION
</H3>
</CENTER>
</A>
<P>
The Netscape Client Plug-in API allows third parties to extend the Netscape client with native support for new data types and additional features. Plug-ins appear as additional capabilities of the Netscape client, indistinguishable to the user from the baseline features.
<P>
<HR SIZE=3>
<P>
<A NAME="Architectural Overview">
<CENTER>
<H3>
<FONT SIZE=+2>A</FONT>RCHITECTURAL <FONT SIZE=+2>O</FONT>VERVIEW
</H3>
</CENTER>
</A>
<P>
Plug-ins are dynamic code modules, native to a specific platform on which the Netscape client runs. Plug-ins are intended to be complementary to platform-native inter-application architectures such as OLE 2 and platform-independent programming languages such as Java. The primary goals of the plug-in API are to:
<UL>
<LI>Provide seamless new data-type support for Netscape users
<LI>Provide the maximum degree of flexibility for plug-in writers
<LI>Be functionally equivalent across all platforms
</UL>
<P>
The current version of the plug-in API supports four broad areas of functionality. Plug-ins can:
<UL>
<LI>Draw into, and receive events from, a native window element that is a part of the Netscape window hierarchy
<LI>Obtain data from the network via URLs
<LI>Generate data for consumption by other plug-ins or Netscape
<LI>Override and implement protocol handlers
</UL>
<A NAME="Appearance">
<B>
A<FONT SIZE=-1>PPEARANCE</FONT>
</B>
</A>
<P>
Plug-ins can have one of three modes of operation: embedded, full-screen, or hidden.
<P>
An embedded plug-in is a part of a larger HTML document, where the plug-in is visible as a rectangular subpart of an HTML page. This is similar to an embedded GIF or JPEG image today, except that the image can be live and may respond to user events such as mouse motion. An example of such a plug-in might be an MPEG player. Embedded plug-ins are specified in HTML with the <CODE>EMBED</CODE> tag (see an <A HREF="/assist/net_sites/embed_tag.html">example</A> of <CODE>EMBED</CODE> tag syntax).
<P>
A full-screen plug-in would be the viewer for a particular data type that was not a part of an HTML document. In this mode a plug-in will completely fill the inner frame of a Netscape window with its representation of some data type. An example of this kind of plug-in is an Adobe Acrobat viewer.
<P>
A hidden plug-in is one that runs in the background. An example of this might be a MIDI player.
<P>
The Netscape user interface is intended to remain relatively constant regardless of which plug-ins are in use. The part of the application frame that is not displaying plug-in data should remain familiar to a Netscape user. In particular, the basic operations of the client, such as navigation, history, opening files and the like, are intended to apply to all pages, regardless of which plug-ins are required to view them.
<P>
<A NAME="Network">
<B>
N<FONT SIZE=-1>ETWORK</FONT>
</B>
</A>
<P>
One of the fundamental things that a plug-in can do is fetch a URL with all the network functionality of the standard Netscape client. The data from such a URL is provided as a stream as it arrives from the network. This allows a plug-in to implement a progressive viewer or to make a particular decision without seeing an entire stream. Individual plug-ins can request multiple simultaneous streams, to the extent that this is supported by the host client. The Netscape client caches plug-in data in its existing persistent cache mechanism.
<P>
Plug-ins are also provided a random access model of network data, via the proposed <A HREF=byterang.html>byte range extension to HTTP</A>.
<P>
Plug-ins can themselves generate data that Netscape or other plug-ins will display. So they can be both producers and consumers of data. In this way plug-ins can be data translators or filters.
<P>
<HR SIZE=3>
<P>
<A NAME="Design Details">
<CENTER>
<H3>
<FONT SIZE=+2>D</FONT>ESIGN <FONT SIZE=+2>D</FONT>ETAILS
</B>
</A>
</CENTER>
<P>
<A NAME="Runtime model">
<B>
R<FONT SIZE=-1>UN-</FONT>T<FONT SIZE=-1>IME</FONT>
M<FONT SIZE=-1>ODEL</FONT>
</H4>
</A>
<P>
Plug-ins are dynamic code modules. They are associated with a MIME data type that the Netscape client has no native support for. When Netscape encounters an unknown data type from a server it will look for a plug-in that is associated with that MIME type and load it. Plug-ins consume no resources (other than disk space) when they have not been referenced. When the Netscape client starts, it enumerates the available plug-ins in a platform-specific manner and registers them according to their MIME type. A single plug-in may register for multiple MIME types.
<P>
The plug-in API is structured as two co-operating objects. One object represents an instance of the plug-in application and its current state. Each of these objects has a peer Netscape object that represents the associated Netscape window (or context) from which the plug-in was created. API calls are modeled as methods on the two objects.
<P>
A new instance is created whenever Netscape encounters data to be handled by a particular plug-in. There may be multiple instances of the same plug-in if there are multiple embedded objects on a single page or if several Netscape windows are open, each displaying the same data type. Plug-in instances are deleted when a user leaves the page.
<P>
<A NAME="Windows and Events">
<B>
W<FONT SIZE=-1>INDOWS AND</FONT>
E<FONT SIZE=-1>VENTS</FONT>
</B>
</A>
<P>
All imaging and user interface events for an instance are handled in a platform-native way. The plug-in API provides a native window handle within which a plug-in should restrict its drawing. On some platforms all user event processing is relative to the window hierarchy, and the window handle is sufficient for event processing. On other platforms (notably the Macintosh) the native window is shared between the plug-in and the Netscape client, and events are explicitly provided to the plug-in by Netscape.
<P>
It is important that plug-ins do not block in any API call from the Netscape client. There is no yield function from the plug-in to Netscape since many plug-ins may be active at once. If a plug-in needs to do substantial asynchronous work, then it should use a separate thread or a timer if appropriate. In some cases a plug-in may achieve this goal by communicating with an entirely separate application thread. If a plug-in makes calls on the Netscape client object, it should be prepared to handle re-entrant API calls.
<P>
<A NAME="Streams">
<B>
S<FONT SIZE=-1>TREAMS</FONT>
</B>
</A>
<P>
Streams are objects representing URLs and the data in them. Streams are associated with a specific instance of a plug-in, and there can be more than one stream object per instance. Streams can be created by Netscape in response to a document or user event, or streams may be explicitly requested by a plug-in. Typically an initial stream is generated by Netscape for each plug-in instance.
<P>
Initially streams are in <I>push</I> mode, where the stream data is provided as it is available. Plug-ins can request that streams be put in <I>pull</I> mode, where data is provided in response to specific read requests from the plug-in. In general this mode is more expensive, unless the stream is a local file. If the network protocol used for a particular stream is unable to support byte ranges, then pull mode may require that the entire file be downloaded before use.
<P>
Plug-ins have a facility to turn a network stream into a temporary local file and obtain a handle to that file. The use of this feature is strongly discouraged. Plug-ins should implement a stream-based interface wherever possible.
<P>
<HR SIZE=3>
<P>
<A NAME="Programming Interface">
<CENTER>
<H3>
<FONT SIZE=+2>P</FONT>ROGRAMMING
<FONT SIZE=+2>I</FONT>NTERFACE
</H3>
</A>
</CENTER>
<P>
<A NAME="Plug-in Methods">
<B>
P<FONT SIZE=-1>LUG-IN</FONT>
M<FONT SIZE=-1>ETHODS</FONT>
</B>
</A>
<P>
A plug-in may implement several methods. All methods except <CODE>NP_New</CODE> are optional. Unless otherwise stated, ownership for all arguments in the API remains with the caller, and values are valid only for the duration of each call.
<P>
<BR>
<CODE>void NP_Initialize(void)</CODE>
<P>
<BR>
Global initialization for a plug-in. Called once when a plug-in is loaded and before any instances are created.
<P>
<BR>
<CODE>void NP_Shutdown(void)</CODE>
<P>
<BR>
Called when a plug-in is unloaded, typically at program termination time.
<P>
<BR>
<CODE>void NP_Version(int *plugin_major, int *plugin_minor, int *netscape_major,
<P>
int *netscape_minor)</CODE>
<P>
<BR>
Version information.
<P>
<BR>
<CODE>NPError NP_New(void *pluginType, NPP instance, uint16 mode,
<P>
int16 argc, char *argn[], char *argv[], NPSavedData *saved)</CODE>
<P>
<BR>
Creates a new instance of a plug-in. <code>NPP</code> is an instance handle that uniquely describes this instance. <code>Mode</code> indicates whether this instance is embedded or not. A list of name-value pairs may be passed in <code>argc</code>, <code>argn</code>, and <code>argv</code>. These correspond to any HTML attributes associated with this instance. The final argument is any data saved for this instance as a result of a previous <code>NP_Destroy</code> (see below). <code>NP_New</code> returns <code>0L</code> or an error result if an instance cannot be created.
<P>
<BR>
<CODE>NPError NP_Destroy(NPP instance, NPSavedData **save)</CODE>
<P>
<BR>
Deletes a specific instance of a plug-in. All resources allocated to this instance should be relinquished. No further graphics operations should take place on any window objects associated with this instance.
<P>
The plug-in may specify in <code>save</code> some specific piece of data, relative to this instance, that it would like preserved between instances. This is useful if the plug-in wishes to save some state so that, if the user were to return to exactly the same document at some time in the future, a new instance could be created that remembered the state. For example, a video player might choose to save the frame number that was last displayed so that, upon returning to this document, a new instance could initially display the same frame. This data is not persistent and may never be returned to the plug-in. The allocation space for the data passes ownership from the plug-in to Netscape when <code>NP_Destroy</code> returns. Netscape can and will discard this data based on arbitrary criteria such as its size, the user's page history, and other factors. Plug-ins should treat it as a hint and not rely on it being provided in a future call to <code>NP_New</code>.
<P>
<BR>
<CODE>NPError NP_SetWindow(NPP instance, NPWindow *window)</CODE>
<P>
<BR>
Provides a window for the plug-in to draw into. Typically this will be a subwindow of the Netscape window hierarchy. This method will only be called if the instance <code>NPP</code> is of the types <code>NPEmbed</code> or <code>NPFull</code>. Subsequent calls to <code>NP_SetWindow</code> for a single instance indicate that the window has been resized. A <code>0L</code> value for <code>window</code> indicates that the plug-in should no longer use the window and must free any resources associated with it.
<P>
<BR>
<CODE>NPError NP_NewStream(NPP instance, NPMIMEType type, NPStream *stream,
<P>
NPBool seekable, uint16 *stype)</CODE>
<P>
<BR>
Notifies an instance of a new data stream. The stream may have been started by a user action or by a specific <code>NP_GetUrl</code> request by the plug-in. The MIME-type of the stream is provided in <code>type</code>. If the stream is known to be capable of byte-range requests, then the Boolean <code>seekable</code> will be <code>1</code>. An instance can request stream modes other than the default (<code>NPNormal</code>) by setting the value of <code>stype</code>. The semantics of <code>NPSeek</code> and <code>NPAsFile</code> streams are described elsewhere.
<P>
<BR>
<CODE>int32 NP_WriteReady(NPP instance, NPStream *stream)</CODE>
<P>
<BR>
Returns the maximum number of bytes that an instance is prepared to accept in a subsequent <code>NP_Write</code> call.
<P>
<BR>
<CODE>int32 NP_Write(NPP instance, NPStream *stream, int32 offset, int32 len,
<P>
void *buf)</CODE>
<P>
<BR>
Writes <code>len</code> bytes of data in <code>buf</code> to the <code>stream</code>. <code>Offset</code> is the logical position of <code>buf</code> in an idealized file URL. A plug-in must consume at least as many bytes as it indicated in the preceding <code>NP_WriteReady</code> call. A negative return value will cause an error on the stream which will subsequently be destroyed.
<P>
<BR>
<CODE>NPError NP_DestroyStream(NPP instance, NPStream *stream, NPError reason)</CODE>
<P>
<BR>
Closes and deletes the <code>stream</code>. <code>Reason</code> indicates why the stream was closed. Possible reasons are that it was complete, because there was some error, or because the user interrupted it.
<P>
<BR>
<CODE>void NP_StreamAsFile(NPP instance, NPStream *stream, const char* fname)</CODE>
<P>
<BR>
Provides a valid filename if a stream was opened in <code>NPAsFile</code> mode and it completed without error. If the file was created from a network stream, it will be locked in the disk cache until the stream or its owning instance is destroyed.
<P>
<BR>
<CODE>int16 NP_HandleEvent(NPP instance, void *event)</CODE>
<P>
<BR>
Delivers a platform-specific <code>event</code> to the <code>instance</code>. Currently this function is only used on the Macintosh platform.
<P>
<BR>
<CODE>void NP_Print(NPP instance, void *platformPrint)</CODE>
<P>
<BR>
Requests a native print action for the current <code>instance</code>. Platform-specific print machinery is provided in <code>platformPrint</code>.
<P>
<BR>
<A NAME="Netscape Methods">
<B>
N<FONT SIZE=-1>ETSCAPE</FONT>
M<FONT SIZE=-1>ETHODS</FONT>
</B>
</A>
<P>
The following are the methods a plug-in can call on the Netscape client.
<P>
<BR>
<CODE>NPError NP_GetURL(NPP instance, const char *url, const char *window)</CODE>
<P>
<BR>
Requests that a new stream be created with the contents of <code>url</code>. This operation is asynchronous and will happen at some time in the future. If <code>window</code> is <code>0L</code>, then a new stream will be created for this instance, regardless of the type of the data. If <code>window</code> is <code>"_current"</code>, then the URL will be interpreted as though a user had requested it; this may result in the current plug-in being unloaded and the current view being replaced with the new MIME type.
<P>
<BR>
<CODE>NPError NP_PostURL(NPP instance, const char *url, uint32 len, const char
<P>
*buf, NPBool file)</CODE>
<P>
<BR>
Posts data to a URL.
<P>
<BR>
<CODE>NPError NP_RequestRead((NPStream *stream, NPByteRange *rangeList)</CODE>
<P>
<BR>
Requests a number of bytes for <code>stream</code>. One or more <code>NP_Writes</code> will result from this call. This operation is an error unless the stream is of type <code>NPSeek</code>. <code>Rangelist</code> is a <code>0L</code> terminated linked list of offsets and lengths to get from this stream. It is likely to be substantially more efficient to request a number of segments in one call than to make a number of separate calls to this routine.
<P>
<BR>
<CODE>NPError NP_NewStream(NPP instance, NPMIMEType type, NPStream *stream)</CODE>
<P>
<BR>
Creates a new stream of data from the plug-in to be interpreted by Netscape in the current window. This operation is currently only useful for instances of type <code>NPBackground</code>.
<P>
<BR>
<CODE>int32 NP_Write(NPP instance, NPStream *stream, int32 len, void *buffer)</CODE>
<P>
<BR>
Writes <code>len</code> bytes of data in <code>buf</code> to the Netscape <code>stream</code>.
<P>
<BR>
<CODE>NPError NP_DestroyStream(NPP instance, NPStream *stream, NPError reason)</CODE>
<P>
<BR>
Closes a stream object. <code>Reason</code> indicates why the stream was closed.
<P>
<BR>
<CODE>void NP_Status((NPP instance, const char *message)</CODE>
<P>
<BR>
Provides a text status message that appears in the Netscape client user interface.
<P>
<BR>
<A NAME="Macintosh-specific APIs">
<B>
M<FONT SIZE=-1>ACINTOSH</FONT>-S<FONT SIZE=-1>PECIFIC</FONT>
API<FONT SIZE=-1>S</FONT>
</B>
</A>
<P>
<BR>
<CODE>void *NP_MemAlloc (uint32 size)</CODE>
<P>
<BR>
Macintosh-specific.
<P>
<BR>
<CODE>void NP_MemFree (void *ptr)</CODE>
<P>
<BR>
Macintosh-specific.
<P>
<BR>
<CODE>uint32 NP_MemFlush(uint32 size)</CODE>
<P>
<BR>
Macintosh-specific.
<P>
<BR>
<A NAME="Windows-specific APIs">
<B>
W<FONT SIZE=-1>INDOWS</FONT>-S<FONT SIZE=-1>PECIFIC</FONT>
API<FONT SIZE=-1>S</FONT>
</B>
</A>
<P>
Coming soon.
<P>
<BR>
<A NAME="Unix-specific APIs">
<B>
U<FONT SIZE=-1>NIX</FONT>-S<FONT SIZE=-1>PECIFIC</FONT>
API<FONT SIZE=-1>S</FONT>
</B>
</A>
<P>
Coming soon.
<P>
<HR SIZE=4>
<P>
<CENTER>
<A HREF="/misc/bottom.map">
<IMG SRC="/images/navigation_bar.gif" ISMAP BORDER=0 WIDTH=468 HEIGHT=32></a>
<P>
<FONT SIZE=-1>
Corporate Sales: 415/528-2555; Personal Sales: 415/528-3777<BR>
If you have any questions, please visit <A HREF="/assist/customer_service/index.html">Customer Service</A>.<P>
Copyright © 1996 <A HREF="/misc/contact_info.html">Netscape Communications Corporation</A></FONT>
</CENTER>
</BODY>
</HTML>
|
