API Reference Netscape Gecko Plug-ins Version 2.0 August 2002 Table of Contents Preface........................................................................ 3 AboutThisGuide .......................................................................3 WhoShouldReadThisGuide.............................................................3 ThePlug-inSoftwareDevelopmentKit.....................................................4 Plug-inBasics ..................................................................3 HowPlug-insAreUsed..................................................................3 Plug-insandHelperApplications.......................................................4 HowPlug-insWork......................................................................4 UnderstandingtheRuntimeModel ........................................................5 Plug-inDetection........................................................................6 HowNetscapeGeckoFindsPlug-ins....................................................6 CheckingPlug-insbyMIMEType ......................................................7 OverviewofPlug-inStructure.............................................................7 UnderstandingthePlug-inAPI.........................................................8 Plug-insandPlatformIndependence....................................................8 WindowedandWindowlessPlug-ins ......................................................9 TheDefaultPlug-in......................................................................9 UsingHTMLtoDisplayPlug-ins.........................................................10 Plug-inDisplayModes ...............................................................11 UsingtheOBJECTTagforPlug-inDisplay..............................................13 NestingRulesforHTMLElements.....................................................15 UsingtheAppropriateAttributes......................................................16 UsingtheEMBEDTagforPlug-inDisplay ..............................................16 UsingCustomEMBEDAttributes......................................................19 Plug-inReferences......................................................................20 Plug-in Development Overview ...................................................21 WritingPlug-ins........................................................................21 RegisteringPlug-ins ....................................................................22 MacOS.............................................................................23 MSWindows........................................................................23 Unix ...............................................................................24 DrawingaPlug-inInstance..............................................................24 HandlingMemory......................................................................25 i SendingandReceivingStreams.......................................................... 25 WorkingwithURLs.................................................................... 26 GettingVersionandUIInformation ...................................................... 26 DisplayingMessagesontheStatusLine................................................... 27 MakingPlug-insScriptable.............................................................. 27 HowtocallJavaScriptfromtheplug-in................................................. 29 ScriptablePlug-inLifetime............................................................ 30 Scriptableplug-inbuildingandinstallationoverview .................................... 30 BuildingPlug-ins ...................................................................... 35 Building,Platforms,andCompilers.................................................... 35 BuildingCarbonizedPlug-insforMacOSX ............................................. 35 GettingandUsingthexpidlCompiler.................................................. 39 TypeLibraries ...................................................................... 39 Installing Plug-ins . ..................................................................... 40 NativeInstallers..................................................................... 40 XPIPlug-insInstallations............................................................. 42 Plug-inInstallationandtheWindowsRegistry.......................................... 44 InitializationandDestruction.....................................................47 Initialization........................................................................... 47 InstanceCreation ...................................................................... 48 InstanceDestruction.................................................................... 49 Shutdown............................................................................. 51 InitializeandShutdownExample ........................................................ 52 DrawingandEventHandling .....................................................53 TheNPWindowStructure............................................................... 53 TheNPWindowStructure ............................................................ 54 DrawingPlug-ins ...................................................................... 55 PrintingthePlug-in.................................................................. 56 SettingtheWindow.................................................................. 56 GettingInformation.................................................................. 57 WindowedPlug-ins .................................................................... 58 MacOS ............................................................................ 59 Windows........................................................................... 60 Unix............................................................................... 60 EventHandlingforWindowedPlug-ins................................................ 60 WindowlessPlug-ins ................................................................... 60 SpecifyingThataPlug-inIsWindowless ............................................... 61 InvalidatingtheDrawingArea........................................................ 62 ForcingaPaintMessage.............................................................. 63 MakingaPlug-inOpaque ............................................................ 64 ii Gecko Plug-in API Reference MakingaPlug-inTransparent.........................................................64 CreatingPop-upMenusandDialogBoxes ..............................................65 EventHandlingforWindowlessPlug-ins...............................................65 Streams ......................................................................67 ReceivingaStream .....................................................................68 TellingthePlug-inWhenaStreamIsCreated............................................68 TellingthePlug-inWhenaStreamIsDeleted............................................69 FindingOutHowMuchDatathePlug-inCanAccept ....................................70 WritingtheStreamtothePlug-in ......................................................71 SendingtheStreaminRandom-AccessMode............................................72 SendingtheStreaminFileMode.......................................................73 SendingaStream.......................................................................74 CreatingaStream....................................................................74 PushingDataintotheStream..........................................................75 DeletingtheStream..................................................................76 ExampleofSendingaStream..........................................................77 URLs.........................................................................79 GettingURLs ..........................................................................80 GettingtheURLandDisplayingthePage...............................................82 PostingURLs ..........................................................................83 PostingDatatoanHTTPServer .......................................................85 UploadingFilestoanFTPServer ......................................................85 SendingMail........................................................................86 Memory.......................................................................87 AllocatingandFreeingMemory..........................................................87 MacOS.............................................................................88 FlushingMemory(MacOSonly) .........................................................88 Version,UI,andStatusInformation................................................91 DisplayingaStatusLineMessage.........................................................91 GettingAgentInformation...............................................................92 GettingtheCurrentVersion..............................................................92 FindingOutifaFeatureExists ...........................................................93 ReloadingaPlug-in.....................................................................94 Plug-inSidePlug-inAPI.........................................................95 PluginMethodSummary................................................................95 NPP_Destroy........................................................................96 iii NPP_DestroyStream................................................................