HOT! Download Java Plugin For Netscape Navigator 9

You cannot automatically uninstall Autodesk MapGuide Viewer, Java Edition (Unless you the are using Autodesk MapGuide Viewer, Java Edition with Java Plugin. Click here to view uninstall procedure for Autodesk MapGuide Java Edition with Java Plugin.)

Use one of the following manual procedures, depending on your platform: Microsoft Internet Explorer on Windows 2000 Professional/XP Professional: In the \Windows or \WinNT folder, depending on your operating system, open the subfolder \Downloaded Program Files. Right-click Autodesk MapGuide Viewer Java Edition, and then choose Remove from the shortcut menu. Netscape Communicator for Solaris: Remove $home/.netscape/java/download/mgjava.jar. If you installed the Autodesk MapGuide Viewer Java Edition that is to be used with Java Plug-in use one of the following procedures, depending on your platform: Windows 2000 Professional/XP Professional: Go to Control Panel\ Add/Remove Programs.

Select Autodesk MapGuide Viewer Java Edition and click on its remove button.

Safari for MacOS X version 10.4.x: Click on the link "Safari with Java Plug-In for Mac OS X" in this web page. Choose "Uninstall" from the applet installer.

OR Open the folder: [Your User Home directory] > Library > Java > Extensions. Drag the mgjava.jar file to the trash. You might also want to remove the files that contain your bookmarks and preferences. These files are contained in a folder called autodesk\mapguide\old_version (where old_version is the version number of the old release, such as 6.3). To remove these files, search for the autodesk\mapguide\old_version folder (for example, use the Find command in Windows Explorer), and then remove the entire \old_version folder.

by Zan OliphantCONTENTSPlug-In Design and ArchitectureHow It All Fits TogetherLiveConnectRuntime LoadingPlug-In Instances and Instance DataWindows and EventsSeamless Web Page EmbeddingData StreamsAssisted InstallationNetscape's SDKNavigator Plug-In Design ConsiderationsChoosing a Development LanguageNavigator Version CompatibilityPlanning for Bandwidth LimitationsMultiplatform CompatibilityExpanding To Java with LiveConnectHTML EMBED Tag AttributesMultiple MIME TypesMIME ContentionFile Base Versus Streaming Plug-InsStreaming to the NavigatorClient Server DesignThe Plug-In APIWho Is Calling Whom?NP_ShutdownA Quick Look at the Plug-In API MethodsSummaryWith the release of Netscape Navigator 2.x in the firstquarter of 1996 came support for Netscape Navigator plug-in codemodules-otherwise known as plug-ins. Plug-ins are similar in functionalityto Java, an interpreted language developed by Sun Microsystems.In contrast to Java, Navigator plug-ins are binary code moduleswritten and compiled for each host operating system or hardwareplatform. Why write a plug-in instead of a Java applet? The answeris speed. Navigator plug-ins are especially well suited for handlinghigh bandwidth data transfers needed for demanding data typessuch as audio and video over the Internet.Most of the material in this chapter first appeared in ProgrammingNetscape Plug-ins, also published by Sams.net, and I referto it throughout this chapter. If you do decide to write a plug-infor Netscape's Navigator or Microsoft's Internet Explorer, youshould consider getting a copy of Programming Netscape Plug-ins; it is an authoritative, Netscape-reviewed, plug-in API referenceand contains numerous code examples.Plug-In Design and ArchitectureNetscape Navigator's plug-in architecture is based on dynamicallyloaded code modules. These modules reside in a subfolder or directorycalled PLUGINS that Navigator reads during its initialization.Each module has a resource that determines which MIME type itcan handle. When Navigator finds this MIME type embedded in aWeb page through HTML or as a single file, it loads the appropriatecode module.For embedded plug-ins, the HTML EMBED tag tells Navigatorthe size of the plug-in's window in a given Web page so that Navigatorcan create the window for the plug-in. The plug-in is given ahandle to this newly created window for drawing graphics and processingevents.When a plug-in is loaded, an instance of the plug-in is createdwith a call to the NPP_New API. The plug-in can be loadedmultiple times, creating multiple instances. Web pages frequentlyhave more than one instance of a plug-in. Therefore, if your plug-inuses a restricted resource such as an audio card, you must sharethis resource across multiple plug-in instances.Data streams are a big part of Netscape's plug-in architecture.Most plug-ins have data pushed from the server for processing,but others might choose to pull it down, perhaps in a random-accessfashion. Just as a plug-in can have multiple instances, it canalso have multiple streams per instance. The plug-in API alsoprovides for stream-instance data.With the introduction of Netscape Navigator 3.0 comes LiveConnect.LiveConnect extends the plug-in architecture by adding communicationbetween plug-ins, Java applets, and JavaScript. The Java RuntimeInterface (JRI) plays an important part in this architecture.How It All Fits TogetherAs you can see in Figure 32.1, the Navigator 3.x plug-inarchitecture consists of a plug-in code module, Navigator, JavaApplet and JRI, JavaScript, and HTML. A bare minimum plug-in couldgo without Java, JavaScript, and HTML. Figure 32.1 : Netscape's Navigator 3.x plug-in architecture.The core of the plug-in interface is the plug-in API. These APIsare prefixed by NPN for methods located within Navigatorand by NPP for methods in the plug-in. By using the APIs,the plug-in becomes part of Navigator's code. LiveConnectNetscape's LiveConnect enables you to integrate Java, JavaScript,and plug-ins. New plug-in methods for LiveConnect are NPP_GetJavaClass,NPN_GetJavaEnv, and NPN_GetJavaPeer. Chapter14 of Programming Netscape Plug-ins, "LiveConnect,"documents these Java-specific APIs for plug-ins and gives moredetails on the LiveConnect interface. Also, Chapter 23 of thatvolume includes a LiveConnect example written by Netscape.For the purposes of this chapter, you should understand what LiveConnectdoes. With LiveConnect you can perform the following tasks:Call a Java method from a plug-inCall a native method located in a plug-in from JavaCall Java methods from JavaScriptCall JavaScript methods from JavaAs you can see, LiveConnect extends not only JavaScript and Javabut also plug-ins. Notice the absence of a 33a direct connectionbetween plug-ins and JavaScript in Figure 32.1. Any plug-in toJavaScript communication must go through Java. To learn more aboutLiveConnect, make sure to get the latest Software DevelopmentKit (SDK) from Netscape and read the documentation. The NetscapeSDK has the most up-to-date LiveConnect information.Runtime LoadingWhen Navigator initializes itself, it checks for installed plug-insin the PLUGINS subdirectory or folder. Navigator doesnot load any plug-ins at this time; it just parses out the resourceinformation containing the plug-ins' supported MIME types, fileextensions, and the name for the file-open dialog. At the timeof this writing, Macintosh plug-ins enable a user to configureplug-in/MIME type association, while Windows does not. Navigatorrelease 4.0 for Windows is slated to have this feature, accordingto Netscape sources.Navigator beta 4 for Windows contains an updated version of theHelp | About Plug-ins menu item. The About Plug-ins feature tellsyou what plug-in you have installed, the full path of each plug-inand its MIME type, its description, its suffixes, and whetherit is enabled. Only after Navigator finds a MIME type to whicha plug-in is registered is the plug-in loaded into memory andexecuted. Figure 32.2 shows the Windows Navigator beta 4 AboutPlug-ins screen. Figure 32.2 : Windows Navigator beta 4 About Plug-ins screen.Plug-In Instances and Instance DataAn important feature of a plug-in is that it can be loaded multipletimes, depending on a given Web page. For example, a Web pagemight contain three audio files of the same type. Navigator thencreates three instances of the audio plug-in using the NPP_NewAPI. Each of these instances has its own instance data that isallocated by the plug-in and attached to a Navigator-maintainedinstance data pointer. Each time Navigator calls one of your plug-inmethods, you must dereference the Navigator-provided instancepointer and get access to your instance data. All of the examplesfound on the CD-ROM included with Programming Netscape Plug-insshow how to do this.In many cases, your plug-in code can be oblivious to other instances.However, in some cases, a plug-in needs to communicate among itsinstances. The RealAudio plug-in does so by enabling a Web authorto load a console instance to control other instances associatedwith audio files. You can read more about the RealAudio plug-inin Chapter 5of Programming Netscape Plug-ins, "Usinga Plug-In."Windows and EventsNavigator creates a window for your plug-in and gives you a handleto this window during a call to the NPP_SetWindow method.The HTML EMBED tag attributes WIDTH and HEIGHTdetermine the size of this window. The HTML code also determinesthe relative window position. Each operating system (UNIX, Windows,and Macintosh) handles window and event processing a little differently.In Windows and UNIX, a child window is created in the window hierarchy.This child window automatically sees all window events. In theWindows programming environment, you can subclass the Navigator-createdwindow to process any given window event.In the Macintosh environment, the plug-in and the Navigator sharea Macintosh window. Therefore, the plug-in must draw only in thespecified area of this shared window. You must save, set up, andrestore the shared drawing environment around any drawing operations.Events are sent to the Macintosh plug-in with the plug-in providedwith the NPP_HandleEvent API.Seamless Web Page EmbeddingThe big advantage of a Navigator plug-in over a Navigator helperapplication is that a plug-in can embed itself directly in theNavigator-displayed Web page. This feature is similar to the waythat a Java applet provides seamless Web page integration. A plug-indiffers from Java in that the plug-in's code is native to thelocal machine and is installed. A Java applet is downloaded beforeeach use and is platform independent.A plug-in can run in either embedded, full page, or hidden modes.Of these modes, embedded is used most often because it providesseamless Web page integration. Full page mode enables a plug-into run by itself, taking the whole Navigator display area. Hiddenmode, as the name implies, is for plug-ins that have no visibleattributes. An example of a hidden plug-in is the Background MusicalInstrument Device Interface (MIDI) Player sample code found inProgramming Netscape Plug-ins, Chapter 21.Data StreamsNetscape Navigator plug-ins are built around the concept of client/serverdata streaming. A stream is a constant flow of data. One of thefirst implementations of streams was for the UNIX I/O subsystem,which provided a full-duplex, modular connection to a given devicedriver. As multimedia becomes more prevalent on the home computer,streaming becomes very important to handle data flow for audioand video.A simple stream can be implemented with a pool of fixed-lengthbuffers. The producer of data continuously fills empty buffers,buffer order is maintained, and data is delivered to the consumer.Such problems as overruns (no more empty buffers) or underruns(no more full buffers) make the life of the stream more complicated.The Navigator plug-in API provides many methods for managing datastreams both to and from a plug-in. A stream that sends data fromNavigator to a plug-in (the most common type of stream) uses NPP_NewStreamto create it, NPP_Write to write the data, and NPP_DestroyStreamto destroy it. A stream that sends data from a plug-in to Navigator(new with the Navigator 3.0 plug-in API) uses NPN_NewStreamfor creation, NPN_Write to write data to the stream,and NPN_DestroyStream to destroy it. Additionally, yourplug-in can have multiple incoming and outgoing streams runningconcurrently.

NOTEFor further reading, see Chapter 10, "Stream Creation and Destruction," and Chapter 11, "Reading From and Writing to Streams," in Programming Netscape Plug-ins. Be sure to look at the code samples in Chapter 17, "A Streaming Audio Sample," and Chapter 18, "The Buffer Classes," to see how your plug-in can handle a real-time data stream from Navigator.Sequential and Seekable StreamsAfter a plug-in is loaded, for all intents and purposes it's partof the Navigator client. A plug-in is compiled machine code andrequires no interpretation, in contrast to platform-independentlanguages such as Java that do require interpretation. Tight couplingenables a plug-in to maintain a very high-speed bond to the Navigatorclient and, in turn, to the Web server. Data flows between theplug-in and Navigator in either sequential or seekable streams.A plug-in can change the stream type to seekable by setting *stypeto NP_SEEK. Setting this mode enables a plug-in to pulldata from a server with calls to the NPN_RequestReadmethod. This technique puts the onus on a plug-in to continuouslycall Navigator for data buffers and is not considered a true continuouslyflowing stream. A seekable stream is generally slower than a sequentialstream, which is driven by Navigator with calls to the plug-inimplemented method NPP_Write. Your plug-in should useonly seekable streams when the random access benefits outweighthe performance penalty.When Navigator creates a stream for your plug-in, it is in sequentialmode. In most cases, Navigator creates a sequential type streamfor each plug-in instance. The NPP_Write API automaticallynotifies your plug-in as chunks of data come across the net. Thisdata flow can come from the Internet via TCP/IP, a local areanetwork (LAN), a local client file, or Navigator's file cache.A sequential stream, as the name implies, is a continuous sequentialstream of data true to the streaming definition. In most cases,a sequential stream is the preferred stream type for a plug-into use.

NOTENavigator's cache plays an important role in your plug-in's performance. Netscape Navigator 2.0 has both a memory-based and a disk-based caching system. The caching scheme is based on whole files. If you abort a file download, it is not saved to cache. Both cache sizes are user configurable.Navigator 3.0 introduced LiveCache. LiveCache provides progressive caching, which enables you to continue where you left off if a file download is aborted. LiveCache also enables you to preload content from slow devices such as CD-ROMs for fast access and viewing.Assisted InstallationA common problem with plug-ins is that users don't know whereto find them. To view a Web page that needs a specific plug-in,the user must have that plug-in installed on his or her localmachine. Navigator's assisted installation feature helps usersinstall new plug-ins. This feature is automatically activatedwhen a user displays an HTML page that requires a plug-in thatis not currently installed.When a user hits a Web page that requires a plug-in not foundin that user's current plug-in installation, a dialog box opensand enables the user to select either Plug-in Info orCancel. If the user clicks the Plug-in Info button, Navigatorloads a new URL to get the given plug-in. This URL can be specifiedin the PLUGINSPACE attribute of the EMBED tag.If the tag does not contain the PLUGINSPACE attribute,Navigator goes to a current plug-in list.Netscape's SDKYou should download Netscape's Plug-in SDK to use in conjunctionwith this book. The SDK contains the authoritative and most up-to-dateplug-in documentation. This SDK is currently located at the followingFTP site: this address ftpXX is any one of Netscape's 20 orso FTP servers.The Plug-in SDK provides the following benefits:Documentation in HTML formatHeader and source filesSource code examplesSpecial tools for LiveConnectNavigator Plug-In Design ConsiderationsBefore you jump into the wonderful world of Netscape Navigatorplug-in development, you need to do some planning. The tools youuse, cross-platform compatibility, and the performance will affectyour plug-in's success in the quickly growing plug-in market.As you design your Netscape Navigator plug-in, consider the followingfactors:What development language should you use? Most Navigator plug-instoday are written in C++. You can use C or even assembler. Anylanguage that is capable of generating machine language for yourgiven platform will work.Will your plug-in be compatible with all versions of Netscape?Will your plug-in work with Navigator 2.x? How about 3.x?Make sure you have a good reason for not supporting these olderNavigator versions.Can your plug-in handle a 28.8Kbps Internet connection? Howabout 14.4Kbps? Bandwidth requirements for your plug-in shouldbe well-planned.Do you want a Java or JavaScript interface to your plug-in?What about MIME types? How many should you support? Is MIMEcontention an issue?Can you write your plug-in so that it processes data in areal-time streaming fashion? Or, must a user wait for a completefile to download?Does your plug-in require a CGI program?The following discussion will help you plan your plug-ins.Choosing a Development LanguageUnlike a Java applet, a plug-in is native machine code and isnot interpreted, which means that you can write a plug-in in anylanguage that compiles to native machine code. However, some issuesmake certain languages easier to use than others.For example, in Windows a plug-in must be a dynamic link library(DLL). The development language you use must be capable of generatinga DLL code module to build a stand-alone plug-in. Many languagessuch as Microsoft's Visual Basic and Borland's Delphi are quitecapable of generating Windows DLLs, but these languages mightnot be able to generate the special resources required for plug-ins.You might be better off using one of these high-level languagesto generate an OLE library for use with a third-party plug-in,such as ActiveX from NCompass or OpenScape from BusinessWeb. The best documented language for Navigator plug-in developmentis C++. Programming Netscape Plug-ins, along with Netscape'sPlug-in SDK, uses C++ exclusively. In addition, you can use assemblerinline or in separate routines. In some cases, such as softwaredecompression, an assembler routine might provide the performanceyou need. And don't hesitate to consider other possibilities,such as a hybrid solution using C++ to call routines implementedin other languages.Navigator Version CompatibilityWhich versions of Netscape's Navigator should your plug-in support?Navigator 2.x introduced plug-in support, and Navigator3.x added many new and cool features such as LiveConnectand streaming data from a plug-in to the Navigator. Can you designyour plug-in so that it works with both Navigator 2.x andNavigator 3.x? What about Navigator 4.x? Your plug-incan also "turn on" more features such as streaming datafrom the plug-in to the Navigator, depending on the Navigatorversion under which it is running.Be sure to check out the NPN_Version API for determiningthe current Navigator version. Also keep in mind that the versionnumber returned by NPN_Version corresponds to the plug-inAPI it supports, not to the Navigator version (such as 2.0, 3.0,and so on). You can read more about version support in Chapter9 of Programming Netscape Plug-ins.Planning for Bandwidth LimitationsWhat about network bandwidth? Is your plug-in geared toward Internetusage for cases in which a typical Internet Service Provider (ISP)is connecting users at 14.4Kbps or 28.8Kbps? Or, perhaps you aredeveloping a plug-in for your company's local intranet. Intranetplug-ins, used mostly on local area networks, need not worry aboutslow modem connections. Multimedia audio and video formats havehuge bandwidth requirements. Most of today's multimedia data throughputminimums were defined by CD-ROM speeds, not by comparatively slowInternet connections. Data compression for audio and video mediatypes has never been more important.Streaming AudioNow look at audio and how you can stream it in real time. A commonmodem speed today is 14,400 bits per second. Low-quality audiois generally sampled at 11,025 samples per second, using 1 byteper sample. A speed of 11,025 samples per second is 11,025 bytesper second, which means 88,200 bits per second (bps):11,025 bytes/second * 8 bits/byte = 88,200 bits/secondHow are you going to fit 88,200bps through a 14,400bps Internetconnection? The answer, of course, is data compression.Using the preceding numbers, a 7 to 1 compression ratio wouldsqueak you by.88,200bps / 14,400bps ~Some of today's plug-in vendors are claiming compression ratiosas high as 50 to 1! This more than ample compression is obtainedby using lossy compression, or removing some data,such as dead space between words. In fact, much of what you seeon the Web today uses lossy compression, such as JPEG, AVI video,and audio compression.Remember that the preceding numbers were taken from a perfectworld. You won't get 14,400bps from a 14.4Kbps modem. Other factorssuch as TCP/IP error correction, the speed of your computer, andserver load also play an important part in actual throughput.Multiplatform CompatibilityMultiplatform compatibility is a big design consideration thatdetermines your plug-in's marketability. Although this chapteris geared toward Windows plug-ins, Netscape's plug-in API wasdesigned for platform independence. You will see how Netscape'sdesign is portable later in this chapter. The Netscape developmentstaff worked hard to keep the API set consistent across the Macintosh,UNIX, and Windows platforms. Rumors that Navigator will supporteven more platforms (such as OS/2) are now coming across the Internet.If you are a Windows developer, don't be too quick to rule outa version of your plug-in for the Macintosh and UNIX platforms.Try to develop your plug-in with an eye toward other platforms.Consider using Java in conjunction with your plug-in for a userinterface. Tight integration between Java and the plug-in comeswith LiveConnect. You can read more about LiveConnect in Chapter14 of Programming Netscape Plug-ins. You should use nativeoperating system level APIs only when you have no other recourse.Expanding To Java with LiveConnectNetscape introduced LiveConnect with the release of Navigator3.0. LiveConnect enables Navigator plug-ins, Java, and JavaScriptto communicate with each other. How can this technology benefityour development efforts? Does it make sense to add a Java extensionto your plug-in, or are you doing it strictly for the hype value?Using Java in conjunction with a plug-in can certainly reduceyour development efforts. The most dramatic reduction occurs witha Java/plug-in applet that uses a plug-in for platform-specificduties and Java for an interactive user interface. In that case,your only job is to port the hardware-dependent plug-in; you don'thave to touch the user interface written in Java.Netscape's LiveConnect AVI video player is a simple example ofusing Java and JavaScript for the user interface and leaving thevideo implementation to a plug-in. The LiveConnect video playeris documented in Chapter 23 of Programming Netscape Plug-ins.HTML EMBED Tag AttributesThe EMBED tag in the Web page's HTML code starts an embeddedplug-in. When the plug-in is loaded, it is displayed as part ofthe HTML document, rather than within another window. This techniqueis very similar to how graphics are embedded in a Web page. Asyou design your plug-in, you should think about which EMBEDtag attributes your plug-in will support. Additionally, definenew attributes that are specific to your plug-in.Current AttributesThe next few sections document Netscape's current EMBEDtag attributes. The EMBED tag has the following syntax: ... HEIGHT="value"Example:HEIGHT=50The HEIGHT attribute defines the vertical size of theplug-in window in units defined by the UNITS attribute.Default UNITS are pixels.HIDDEN=true or HIDDEN=falseExample:HIDDEN=trueThe HIDDEN attribute determines whether the plug-in isvisible. A value of true indicates that the plug-in ishidden and not visible. This value overrides any HEIGHTor WIDTH parameters and makes the plug-in zero in size.An example of a hidden plug-in is a Web page background MIDI player(a sample in Programming Netscape Plug-ins). Be sure touse the HIDDEN attribute to define an invisible plug-inrather than defining HEIGHT and WIDTH to zero.If you use the HIDDEN attribute with no parameters, itdefaults to true.PALETTE=foreground or PALETTE=backgroundExample:PALETTE=backgroundThe PALETTE attribute is for the Windows platform. Thisattribute instructs the plug-in to realize its palette as eithera foreground or background palette. The attribute is useful forembedding multiple palette-aware plug-ins in a single page. Thedefault value is background.PLUGINSPAGE="URL"Example:PLUGINSPAGE= PLUGINSPAGE attribute is used by the assisted installationfeature if the plug-in registered for the MIME type of a givenEMBED tag is not found. Its argument is a standard URLthat usually contains the location of the needed plug-in.

NOTEThe PLUGINSPACE attribute is not implemented in Navigator 2.x.SRC="URL"Example:SRC=sound.wavThe HTML argument of the SRC attribute indicates thelocation of a plug-in's data file. The MIME type of this datafile determines which plug-in is loaded to handle the file, andthe file's extension usually determines the MIME type. The EMBEDtag must use either the SRC or TYPE attribute.TYPE="type"Example:TYPE=audio/x-wavThe TYPE attribute is used instead of SRC toload a plug-in that does not require a data file for startup.The argument for this attribute is a MIME type that maps to aplug-in. The EMBED tag must use either the SRCor TYPE attribute.WIDTH="value"Example:WIDTH=200The WIDTH attribute defines the horizontal size of theplug-in window in units defined by the UNITS attribute.Default UNITS are pixels.UNITS="value"Example:UNITS=enThe UNITS attribute defines which measurement units theHEIGHT and WIDTH attributes use. The value canbe either pixels or en. Pixels arethe default. (An en is half the point size.)Adding Your Own AttributesAdding attributes for your plug-in's private use is easy. Justput them in the EMBED command line. Navigator ignoresall nonstandard attributes while parsing the HTML EMBEDtag. You can retrieve any additional name=value pairsduring your plug-in's NPP_New API.For example, many plug-ins use the AUTOSTART and LOOPattributes, which you can add to the EMBED tag such asthe following:Notice how you can put additional private attributes in the EMBEDtag command line just like standard attributes. For an exampleof extensive use of private attributes, check Chapter 5in ProgrammingNetscape Plug-ins, "Using a Plug-in," which showshow the RealAudio plug-in uses this technique.Multiple MIME TypesYour plug-in can support more than one MIME type. This featurecan be really handy for plug-ins that support more than one fileformat. Consider Netscape's LiveAudio plug-in, which is includedwith Navigator 3.x. This plug-in currently supports sevendifferent MIME types! It covers the most popular audio formatsfor UNIX, Macintosh, and Windows. Table 32.1 shows the MIME types,descriptions, and suffixes that the LiveAudio plug-in supports.

Table 32.1. LiveAudio MIME types.Mime typeDescriptionSuffixesaudio/basiclAUauaudio/x-aiffAIFFaiff, aifaudio/aiffAIFFaiff, aifaudio/x-wavWAVwavaudio/wavWAVwavaudio/x-midiMIDImidi, midaudio/midiMIDImidi, midMIME ContentionMIME contention occurs when more than one installed plug-in supportsthe same MIME type. The Macintosh Navigator has solved this problemby letting the user configure appropriate plug-ins for each MIMEtype. At the time of this writing, Windows and UNIX do not yethave this plug-in user configuration.When designing your plug-in, you should be aware of these MIMEcontention issues. The best defense, until Netscape resolves thisproblem, is a good installation program and user documentation.File Base Versus Streaming Plug-InsTry to design for a streaming plug-in rather than a file-basedplug-in whenever possible. A streaming plug-in processes dataon a buffer-by-buffer basis as it is downloaded from the network.The advantages of using this design are twofold. First, your plug-incan operate in real time, such as the RealAudio plug-in. And second,your plug-in can take advantage of extra processing time whilethe data file is being downloaded.Despite the popularity of the streaming plug-in design, in manycases using this design does not make sense. Consider a plug-inthat plays AVI video files. Because the AVI format was designedfor CD-ROM streaming at 150KB per second (not your everyday Internetconnection speed), you cannot possibly play this file format inreal time over the Internet. As you will see with Netscape's AVIplayer plug-in example, this type of plug-in has to be file-based.Streaming to the NavigatorNavigator 3.x enables you to stream data from your plug-into Navigator by creating a new stream with NPN_NewStream,writing to it with NPN_Write, and destroying it withNPN_DestroyStream. These APIs are fully documented inProgramming Netscape Plug-ins, Chap-ter 10.Why would you ever want to stream data from your plug-in to Navigator?Maybe you could create a plug-in that reads raw data from a Webserver, converts it to HTML, and streams that HTML data to theNavigator for display. For example, you could write a plug-inthat displays UNIX manual pages in a nice HTML format.Your plug-in can make Web pages on-the-fly using this technique.Client Server DesignWith the addition of a common gateway interface (CGI) programresiding on the Web server, your plug-in implementation can havea true client/server design. Your CGI server back end can do thingssuch as database searches while the browser client handles thedisplay.You can send data to your CGI program with NPN_GetURLor NPN_PostURL. Navigator 3.x adds NPN_GetURLNotify,NPN_PostURLNotify, and NPP_URLNotify to themix for better error checking. Be sure to check out the ServerCPU Monitor sample in Programming Netscape Plug-ins foran example of using these APIs with a CGI program.The Plug-In APIIn order to maintain similarity across multiple platforms, theWindows plug-in API is not built in the usual Windows fashion.A Netscape Navigator plug-in is implemented in a dynamically linkedcode module. In Windows, this module is the standard DLL. Microsoftdesigned the DLL with an eye toward implementations, such as aNetscape plug-in, but Netscape has taken a slightly differentapproach.This section explains the difference between a Netscape API anda plug-in API. It includes implementations for both types of APIsand how code is called. Additionally, the section briefly explainsall APIs (including platform-specific APIs). A complete referenceof these APIs, reviewed by Netscape, is available in ProgrammingNetscape Plug-ins.Who Is Calling Whom?If you scan through the plug-in documentation, you might noticetwo types of APIs. The first type begins with the convention NPP.These routines are implemented by your plug-in and are calledfrom the Navigator. The letters NPP stand for NetscapePlug-in: Plug-in Defined. The second type begins with the conventionNPN. These routines are implemented by the Navigatorand are called from your plug-in. The letters NPN standfor Netscape Plug-in: Navigator Defined. Figure 32.3 shows thecalling direction for NPN and NPP plug-in APIs. Figure 32.3 : API calling techniques.Dynamically LoadedAll plug-in types-UNIX, Macintosh, or Windows 3.1/95/NT-are dynamicallyloaded code modules. This architecture calls code on demand andover the years has proved to be an effective technique to savesystem resources. As a Windows developer, you are probably familiarwith Windows DLLs, and you might have used them in your projects.Entry points defined during compile time call routines withina DLL. An application might implicitly load a DLL by linking toa stub library during compile time or explicitly load a DLL byusing a Windows API, such as LoadLibrary, followed withcalls to GetProcAddress to retrieve function addresses.How Netscape Calls Your DLLUnfortunately, these linking methods are very specific to Windowsand do not fit Netscape's criteria for cross-platform equivalence.If you look at the header of a typical plug-in DLL, you'll noticeonly three entry points:NP_GETENTRYPOINTSNP_SHUTDOWNNP_INITIALIZEThat design certainly doesn't give Netscape much to work with-ordoes it?NPWIN.CPPNetscape provides a file called NPWIN.CPP for Windowsdevelopers in its plug-in developer's kit. This file containscode for Windows DLL entry points. You might want to review thisfile before proceeding with this chapter.Because NPWIN.CPP is intended as a layer to hide Windowsplatform-specific entry points from your plug-in, Netscape asksdevelopers not to touch this file. To ensure that no one changesthis code, Netscape has mentioned that it might convert NPWIN.CPPto a binary library in the future.NP_InitializeImmediately after the plug-in is loaded, the DLL routine NP_Initializeis called. This routine has one parameter-a pointer to the NPNetscapeFuncsstructure:NPError WINAPI NP_EXPORT NP_Initialize (NPNetscapeFuncs* pFuncs)The NPNetscapeFuncs structure, which is located in theNetscape-provided header file npupp.h, is defined inthe Navigator 3.0 Plug-in SDK as follows:typedef struct _NPNetscapeFuncs { uint16 size; uint16 version; NPN_GetURLUPP geturl; NPN_PostURLUPP posturl; NPN_RequestReadUPP requestread; NPN_NewStreamUPP newstream; NPN_WriteUPP write; NPN_DestroyStreamUPP destroystream; NPN_StatusUPP status; NPN_UserAgentUPP uagent; NPN_MemAllocUPP memalloc; NPN_MemFreeUPP memfree; NPN_MemFlushUPP memflush; NPN_ReloadPluginsUPP reloadplugins; NPN_GetJavaEnvUPP getJavaEnv; NPN_GetJavaPeerUPP getJavaPeer; NPN_GetURLNotifyUPP geturlnotify; NPN_PostURLNotifyUPP posturlnotify;#ifdef XP_UNIX NPN_GetValueUPP getvalue;#endif /* XP_UNIX */} NPNetscapeFuncs;The first things to notice are the structure members sizeand version. The size is simply a sizeofNPNetscapeFuncs. During NP_Initialize, the sizeis checked against your plug-in's internal NPNetscapeFuncsstructure to assure compatibility:if(pFuncs->size < sizeof NPNetscapeFuncs) return NPERR_INVALID_FUNCTABLE_ERROR;The version is checked in a similar fashion:if(HIBYTE(pFuncs->version) > NP_VERSION_MAJOR) return NPERR_INCOMPATIBLE_VERSION_ERROR;

NOTEThe version numbers indicated by NP_VERSION_MAJOR and NP_VERSION_MINOR can't be directly correlated to the version of the Navigator. These values refer to the version of the API. When the major version number of the API increases, it is a breaking change. Plug-ins written for version 0 of the API (the current major version number) won't work if the API in the Navigator progresses to major version 1. Minor version changes indicate nonbreaking changes in the API. Thus, the major version number returned by Atlas (Navigator 3.x) continues to be 0, while the minor version is incremented with each change to the API. NP_VERSION_MAJOR and NP_VERSION_MINOR are predefined in the header file, so those numbers indicate the version of the API against which the plug-in was compiledFurther down in the structure, notice the 12 function pointerprototypes beginning with NPN. You remember that NPNstands for a routine within the Navigator. This structure holdsfunction pointers to all Navigator entry points that your plug-incalls. In addition, your plug-in maintains a global pointer tothis structure for future calls to the Navigator.g_pNavigatorFuncs = pFuncs; // save it for future referenceThe NP_Initialize routine ends with a call to your internalNPP_Initialize method, which is documented in Chapter9 of Programming Netscape Plug-ins.Mapping Your API Calls to NetscapeAs your plug-in is running, it makes calls to Navigator. For instance,a call to allocate memory from Navigator is NPN_MemAlloc.(See Programming Netscape Plug-ins, Chapter 12, "MemoryManagement.") NPN_MemAlloc is really a routine withinyour plug-in. Look again in the file NPWIN.CPP and findthe following routine:void* NPN_MemAlloc(uint32 size){ return g_pNavigatorFuncs->memalloc(size);}Notice that this routine simply maps your call to NPN_MemAllocto the previously mentioned structure of function pointers NPNetscapeFuncstag_hash_187and uses calls the saved pointer g_pNavigatorFuncsto call the routine memalloc.NP_GetEntryPointsAfter NP_Initialize is called and returns successfully,the DLL entry point routine NP_GetEntryPoints is called.Just as NP_Initialize gives you the means to call Navigatorroutines, NP_GetEntryPoints enables Netscape to callyour plug-in's routines without using standard DLL calling conventions.Look at the prototype for this routine:NPError WINAPI NP_EXPORT NP_GetEntryPoints (NPPluginFuncs* pFuncs)As with NP_Initialize, this routine passes a pointerto a structure. In this case, the pointer is to the structureNPPluginFuncs, which is currently defined as follows:typedef struct _NPPluginFuncs { uint16 size; uint16 version; NPP_NewUPP newp; NPP_DestroyUPP destroy; NPP_SetWindowUPP setwindow; NPP_NewStreamUPP newstream; NPP_DestroyStreamUPP destroystream; NPP_StreamAsFileUPP asfile; NPP_WriteReadyUPP writeready; NPP_WriteUPP write; NPP_PrintUPP print; NPP_HandleEventUPP event; NPP_URLNotifyUPP urlnotify; JRIGlobalRef javaClass;} NPPluginFuncs;Again, the first two members size and versionare provided for compatibility checking. In this case, your plug-inonly checks the structure size because the version refers to theplug-in:if (pFuncs->size < sizeof NPPluginFuncs) return NPERR_INVALID_FUNCTABLE_ERROR;Later in the structure, notice the function pointers and prototypesto routines such as NPP_NewUPP newp. The prototype forthese routines begins with NPP, which identifies themas calls from the Navigator to your plug-in's methods.The plug-in fills the function pointers in this structure withthe appropriate internal routines during NP_GetEntryPoints:pFuncs->version = (NP_VERSION_MAJOR newp = NPP_New;pFuncs->destroy = NPP_Destroy;pFuncs->setwindow = NPP_SetWindow;pFuncs->newstream = NPP_NewStream;pFuncs->destroystream = NPP_DestroyStream;pFuncs->asfile = NPP_StreamAsFile;pFuncs->writeready = NPP_WriteReady;pFuncs->write = NPP_Write;pFuncs->print = NPP_Print;pFuncs->event = NULL; /* reserved */Versions NP_VERSION_MAJOR and NP_VERSION_MINORare defined in NPAPI.H and indicate the plug-in API releaseand point version, respectively.Netscape Calls Your CodeAfter NP_GetEntryPoints returns, the Navigator structureNPPluginFuncs is filled with valid function pointersthat will be directly called as needed. If you are using a compilerother than Microsoft's, you should make sure that your plug-inAPIs are prototyped correctly for your compiler. See Part IV ofProgramming Netscape Plug-ins, "Plug-in ProgrammingResources for Windows," for more information.Because the plug-in is running, you no longer need to use thestandard Windows DLL interface. The Navigator doesn't use anyother DLL entry points until it unloads your plug-in from memory.At this point, NP_Shutdown is called.NP_ShutdownThe last of the Windows DLL entry points, NP_Shutdown,is called immediately before the plug-in is unloaded. It simplycalls your internal NPP_Shutdown routine (see Chapter9 in Programming Netscape Plug-ins), in addition to zeroingout the global functions pointer.NPError WINAPI NP_EXPORT NP_Shutdown(){ NPP_Shutdown(); g_pNavigatorFuncs = NULL; return NPERR_NO_ERROR;}A Quick Look at the Plug-In API MethodsFor a complete reference of Navigator's plug-in API methods, consulteither Netscape's Plug-in SDK or Programming Netscape Plug-ins.Table 32.2 shows plug-in-implemented APIs, and Table 32.3 showsNetscape-implemented APIs.

Table 32.2. The plug-in APIs, which are called fromNetscape.API NameDescriptionNPP_DestroyDeletes an instance of a plug-inNPP_DestroyStreamCalled when a data stream is completeNPP_GetJavaClassReturns the plug-in associated Java classNPP_HandleEventMacintosh-only event handlerNPP_InitializeGlobal initializationNPP_NewCreates a new instance of a plug-inNPP_NewStreamCalled when a new stream has been createdNPP_PrintPrint handlerNPP_SetWindowCalled during plug-in's window activityNPP_ShutdownGlobal terminationNPP_StreamAsFileGives the filename for the streamNPP_URLNotifyNotifies the completion of a URL requestNPP_WriteCalled to write data to a plug-inNPP_WriteReadyDetermines whether a plug-in is ready for dataTable 32.3. The Netscape APIs, which are called fromthe plug-in.API NameDescriptionNPN_DestroyStreamTerminates a data streamNPN_GetJavaEnvReturns the Java execution environmentNPN_GetJavaPeerReturns the plug-in associated Java objectNPN_GetURLRequests that a new stream be createdNPN_GetURLNotifyRequests that a new stream be created with notificationNPN_MemAllocAllocates memoryNPN_MemFlushMacintosh-only flush memoryNPN_MemFreeFrees memoryNPN_NewStreamCreates a new stream of dataNPN_PostURLPosts data to a URLNPN_PostURLNotifyPosts data to a URL and notifies of resultNPN_RequestReadRequests bytes from a streamNPN_StatusDisplays a status messageNPN_UserAgentGets Navigator's user agent fieldNPN_VersionGets Navigator's plug-in versionNPN_WriteWrites to a streamSummaryThroughout this chapter you learned about Netscape Navigator'splug-in architecture, plug-in design, and plug-in APIs. Plug-insare dynamically loaded code modules. A plug-in that is loadedmore than once is considered to have multiple instances. Navigatorcreates a child window in UNIX and Windows, but it shares themain window with a Macintosh plug-in.A Windows DLL is not called in the traditional DLL entry pointfashion, but rather through direct function pointers retrievedby Navigator. The Netscape SDK file NPUPP.H containsstructures to accomplish this calling mechanism. Calls from yourplug-in to Navigator, although more straightforward, use the sametechnique with function pointers.This chapter also suggested ways to design plug-ins. Among themany factors to consider when you design and develop plug-insare Navigator compatibility, development languages, bandwidthrequirements, LiveConnect, EMBED attributes, and MIMEtypes. Remember, streaming plug-ins are generally considered muchcooler than file-based plug-ins. Also, you can use a CGI programto provide server software as needed. For further reading, ProgrammingNetscape Plug-ins, also published by Sams.net, isan excellent resource for more in-depth information on topicscovered in this chapter.