Browser Plug-in API: API Description

A plug-in is an add-on program that extends the capabilities of a Browser. For example, plug-ins can enable users to view pdf files and flash files, or to play audiotapes or movies on a Browser.

The Browser Plug-in API enables developers to create plug-ins that can do the following:

HTML tags determine the way a plug-in is displayed on a Web page. The following HTML tags invoke the plug-in and determine its display mode:

The object tag specifies the attributes of an object, such as a plug-in, to be embedded in a Web page to be viewed with the Browser. An example of an object tag is as follows:

<object

    data="dataLocation"

    type="MIMEType"

    align="alignment" 

    height="pixHeight" 

    width="pixWidth"

    id="name"

>

		<param name="name1" value="value1"  />

		<param name="name2" value="value2" />

  </object>

The embed tag specifies the attributes of a plug-in to be embedded in a Web page to be viewed with the Browser. An example of an embed tag is as follows:

<embed

		src="location"

    type="MIMEtype"

    align="left"|"right"|"top"|"bottom"

    border="borderWidth" 

    frameborder="no"  

    height="height"

    width="width"

    units="units"

    hspace="horizMargin" 

    vspace="vertMargin" 

    id="name"

    name1="value1"

	  name2="value2"

>

</embed>

An embed tag must contain either the src attribute or the type attribute in order for the plug-in to load. The Browser uses either the value of the type attribute or the suffix of the file name of the source to determine which plug-in to use. For example:

<embed src="doh.wav" width="100" height="40" type="audio/wav">

</embed>

The Utilities class of the Browser Plug-in API provides developers with the capability to program and compile their plug-ins once for the S60 platform.

Plug-in developers must link their plug-ins with the PluginAdapterUtil.dll dynamic-link Library (DLL). Call the ExtractParentControlAndApiL function to get the parent window.

The EPOC Component Object Model (ECOM) provides a means to improve S60 platform security and reduce Browser startup time. When the Browser starts up, it queries the ECOM framework to get a list of all plug-ins that are registered with Symbian and whose UIDs match the KBrowserPluginInterfaceUid. Unlike earlier versions of the Browser, the Browser for S60 3rd Edition does not have to search all directories to find dynamic link library (DLL) files for the appropriate plug-in to render a particular MIME type. Instead, the new Browser gets a list of Symbian-approved plug-in applications that contains the following information:

When the Browser needs to display data of a particular MIME type, it finds a plug-in registered to that type and load that plug-in application.

S60 uses ECOM to decouple a reusable module interface from its implementation(s). Therefore, in order to implement an ECOM object, an interface and one or more implementations must exist or be created. ECOM has all of the runtime advantages of polymorphic DLLs for implementing a specified interface. Unlike polymorphic DLLs, ECOM contains a generic framework that provides a single mechanism for all clients to discover and instantiate the appropriate implementation.

An ECOM implementation is associated with its interface by means of a resource file that contains information such as the following:

/*  Description : Resource file for the test Interface

     Implementation plug-in */

// INCLUDES

#include "RegistryInfo.rh"

// RESOURCE DEFINITIONS



// Registry info

// The UIDs for the filters implemented in this DLL

RESOURCE_REGISTRY_INFO  theInfo

{

 dll_uid = 0x101F8756;

  // Should match the name of the file. 

  // 3-d UID of the associated plug-in DLL (declared in the 

  // mmp file of the plug-in’s DLL)      

 interfaces=

   {

    INTERFACE_INFO

      {

       interface_uid =  0x101F8810; 

        // identifies plug-in type (used by ECom)

        // interface_uid =  KBrowserPluginInterfaceUid;



       implementations =

         {

          IMPLEMENTATION_INFO

            {

             implementation_uid = 0x101F8757;

              // Specify specific implementation

              //(must match an implementation entry in the DLL

	           version_no = 1;

             display_name = "np.dll;S60 Test Plugin"; 

              // file name and name of the plug-in

	           default_data = "application/pdf;pdf;|app/pdf;abc;|application/x-shockwave-flash;plg,xplg,swf;My plugin;|txt/plg;txt|";

              // Supported MIME types (application/pdf,

              //  application/x-shockwave-flash ..), 

              // MIME Extensions (pdf, plg, xplg ..),

              // and MIME descriptions (My plugin)

             opaque_data = "Plugin to test Browser support"; 

              // Description of the plug-in

             }

          };

       }

    };

}

// End of File

The Browser Plug-in API is classified as a Library API. It provides classes and functions that are used in the context of the client's thread. The classes and functions can be used independently of each other.

The Browser Plug-in API is a Method Call API. The interface uses only local objects.

This API is intended for developers who wish to write plug-in applications for the S60 platform. The reader should be familiar with the C++ programming language and the Symbian operating system.

For information about plug-in development, including links to a variety of plug-in sources, see Reference 2.

Use cases

This section describes the types of things you can do with the Browser Plug-in API. The main use cases are as follows:

API class structure

The following table contains descriptions of the structural classes shown in Figure 1 as well as the header files in which they are stored.

`data`	is the location of the object's data This is a mandatory attribute.
`type`	is the MIME type of the plug-in This is a mandatory attribute.
`align`	is the left, right, top, or bottom alignment of the plug-in on the HTML page This is an optional attribute.
`height`	is the vertical size, in pixels, of the plug-in on the HTML page This is an optional attribute.
`width`	is the horizontal size, in pixels, of the plug-in on the HTML page This is an optional attribute.
`id`	is the name of the plug-in This is an optional attribute.
`param name`	is the name of a parameter required by the plug-in This is an optional attribute.
`value`	is the initial value of the parameter required by the plug-in This is an optional attribute.

`src`	is the URL location of the file to run This is a mandatory attribute.
`type`	is the MIME type of the plug-in needed to run the file This is a mandatory attribute.
`align`	is the left, right, top, or bottom alignment of the plug-in on the HTML page This is an optional attribute.
`border`	is the width, in pixels, of the border surrounding the plug-in on the HTML page This creates a picture frame effect. This is an optional attribute.
`frameborder`	specifies whether or not the frames on the HTML page appear with borders separating themselves from each other Values: `yes` or `no` This is an optional attribute.
`height`	is the vertical size of the plug-in on the HTML page Default unit: pixels This is an optional attribute.
`width`	is the horizontal size of the plug-in on the HTML page Default unit: pixels This is an optional attribute.
`units`	is the unit used for the sizes of the `height` and `width` For example: inches, cm, mm, point size, or pixels This is an optional attribute.
`hspace`	is the width, in pixels, of an invisible border to the left and right of the plug-in on the HTML page This creates blank space on the left and right sides of the plug-in object. This is an optional attribute.
`vspace`	is the width, in pixels, of an invisible border above and below the plug-in on the HTML page This creates blank space above and below the plug-in object. This is an optional attribute.
`id`	is the name of the plug-in This is an optional attribute.

Header file	Class Name	Description
`EcomBrowserPluginInterface.h`	`CEcomBrowserPluginInterface`	Exposes functions that: Create a plug-in application Create an implementation Destroy an implementation
`PluginHandler.h`	`CPluginHandler`	Exposes functions that: Find a plug-in for a specified MIME type Load and unload a plug-in Get the name and description of a plug-in
`BvpPlugin.h`	`CBvpPlugin`	Interface to the Browser that handles embedded video requests. For example: Creates a new instance of the Browser Video Plug-in Sets the parent window boundaries and the size of the plug-in Notifies a plug-in instance of a new data stream Returns the URL from which the stream originates Returns the maximum size that a plug-in can accept from the stream Writes data to the plug-in Opens and plays video files Saves a data stream to a file Terminates a data stream Deletes a plug-in instance
	`CBvpPluginEcomMain`	Passes plug-in-specific initialization information to and from the Browser. Informs the plug-in of what functions the Browser makes available.
	`CBvpController`	Controls playing of the video.
`CBAPPlugin.h`	`CBAPPlugin`	Interface to the Browser that downloads and plays embedded audio files. Creates a new instance of the Browser Audio Plug-in Sets the parent window boundaries and the size of the plug-in Notifies a plug-in instance of a new data stream Returns the URL from which the stream originates Returns the maximum size that a plug-in can accept from the stream Writes data to the plug-in Opens and plays audio files Stops the audio file from playing Sets the volume level Saves a data stream to a file Terminates a data stream Deletes a plug-in instance
	`CBapPluginEcomMain`	Passes plug-in-specific initialization information to and from the Browser.
`SVGTPlugin.h`	`CSvgtPlugin`	Interface to the Browser that handles the Scalable Vector Graphics - Tiny (SVG-T) plug-in, which renders animated, interactive graphics. Creates a new instance of the SVG-T Plug-in Sets the parent window boundaries and the size of the plug-in Retrieves attributes and values from the plug-in Sets attributes and values within the plug-in Saves a data stream to a file Deletes a plug-in instance
	`CSvgtPluginEcomMain`	Passes plug-in-specific initialization information to and from the Browser.