<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C"><title>Miscellaneous Plug-in Interfaces</title><shortdesc>This topic provides information about the use of miscellaneous plug-ins in the non-ScreenPlay variant. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p> <b>Variant</b>: <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">Non-ScreenPlay</xref>. <b>Target audience</b>: Device creators. </p> <section><title>Purpose</title> <p>This document details a number of use cases that a developer may wish to use in order to use plug-ins with other interfaces. For example <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsWindow</apiname></xref>, <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsMemoryRelease</apiname></xref>, <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsPluginManager</apiname></xref> and <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsIniFile</apiname></xref>. In addition, there is a use case on a plug-in installing a new animation/redraw scheduler. </p> </section> <example><title>Introduction</title> <p>The Window Server now provides some minor extensions to existing object provider interfaces, together with the some new object provider extension interfaces. The interfaces covered by the use cases in this document are: </p> <ul><li id="GUID-9B9DC1F2-39CF-5BB8-82CD-FB676F268461"><p> <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsWindow</apiname></xref> – an interface through which windows can be examined </p> </li> <li id="GUID-AAE3AC32-5E0A-5E1C-AE73-F4D14F22774A"><p> <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsMemoryRelease</apiname></xref> – an interface which enables plug-ins to cooperate with WSERV by releasing memory when requested (for example, caches) </p> </li> <li id="GUID-1307F79B-9E3C-5D4F-B3F7-2A21A190A5D7"><p> <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsPluginManager</apiname></xref> – enables plug-ins to request services from other plug-ins </p> </li> <li id="GUID-F19C10A5-EC45-5980-8942-880EC9942011"><p> <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsIniFile</apiname></xref> – enables plug-ins to read the <codeph>WSINI.INI</codeph> file </p> </li> </ul> <p>Each of these new interfaces inherits from the existing <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsObjectProvider</apiname></xref> interface, and they are made available through the object provider mechanism. In other words, each interface has an associated “type id”, and the interface is obtained by calling <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsObjectProvider::ResolveObjectInterface(&lt;type id&gt;)</apiname></xref> on an appropriate object provider. In the case where a plug-in wants to request the interface, the object provider will be WSERV’s <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsGraphicDrawerEnvironment</apiname></xref>, which is passed to plug-ins during their construction. </p> <p>In addition there is also a use case detailing how a plug-in can install a new animation/redraw scheduler. </p> </example> <section><title>Setup and configuration requirements</title> <p><b>Loading plug-ins </b> </p> <p>All specified plug-ins are loaded by WSERV, or the default plug-ins are loaded if none are specified. </p> <p>The plug-ins to be loaded are specified in the <codeph>WSINI.INI</codeph> file using a line such as the following: </p> <p> <codeph>PLUGINS FLICKERBUFFER STD DEFAULTFADER </codeph>  </p> <p>Each plug-in can then have its own section in the <codeph>WSINI.INI</codeph> file in which <codeph>ID</codeph>, <codeph>TYPE</codeph>, and <codeph>DATA</codeph> parameters can be specified. These are as follows: </p> <ul><li id="GUID-3D4BA5DB-7939-5034-8EEC-C0D66DD6D5E6"><p> <codeph>ID</codeph> is a UID, used to search for <codeph>&lt;uid&gt;.dll</codeph>. </p> </li> <li id="GUID-BD857EDB-BFAA-55C4-8E3D-753278F4C415"><p> <codeph>TYPE</codeph> is a type, used to search for DLLs of that type. This can be used if no UID is specified. </p> </li> <li id="GUID-2D56DF72-69B5-5C5F-8956-A67AF8EDA30A"><p> <codeph>DATA</codeph> can be used to pass arbitrary data to a plug-in. </p> </li> </ul> <p>A typical section might look like this: </p> <codeblock id="GUID-3036BD17-50DB-5D09-8A85-AE3203A3F5C7" xml:space="preserve">[FLICKERBUFFER]

ID 0x10285A2C</codeblock> <p><b>Additional preconditions </b> </p> <p>The following are additional preconditions for every use case in this document: </p> <ul><li id="GUID-2A8DF534-1583-503C-849A-99A7CA369B8D"><p>The plug-in object has been constructed. </p> </li> <li id="GUID-B389D464-C7FB-545D-BDFE-9057559F5C4D"><p>The plug-in has reference to <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsGraphicDrawerEnvironment</apiname></xref> which has been passed in as a parameter to <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>CWsPlugin::ConstructL()</apiname></xref>. </p> </li> </ul> </section> <section><title>Use cases </title> <p>The following use cases are covered in this topic: </p> <ol id="GUID-97B9DCFE-5AFD-5B2F-A858-EFA4FEFE2139"><li id="GUID-3653B23D-6681-597F-9D3E-849F364850D6"><p><xref href="GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C.dita#GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C/GUID-669693F6-035F-5D7A-96FE-5D1F0EF2DF81">Plug-in uses MWsWindow interface </xref>  </p> </li> <li id="GUID-A4634B13-C034-5795-B633-83568D9F15C1"><p><xref href="GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C.dita#GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C/GUID-41410434-9226-5356-AE5D-3943CDD5032A">Plug-in uses MWsMemoryRelease interface </xref>  </p> </li> <li id="GUID-95FFBE3C-069D-5FD3-A709-3CF2F8393FD7"><p><xref href="GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C.dita#GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C/GUID-C961C9DC-FD6E-5FA5-B32C-6D23BFCFFCED"> Plug-in uses MWsPluginManager interface</xref>  </p> </li> <li id="GUID-E96CEE01-8D64-5AEA-977C-662D19C339DE"><p><xref href="GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C.dita#GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C/GUID-83F7707F-F67A-5C8A-B0A3-86460F1CA4D6"> Plug-in uses MWsIniFile interface </xref>  </p> </li> <li id="GUID-F269EDAE-1F7C-5DFC-A140-CB970CA6F610"><p><xref href="GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C.dita#GUID-434F690E-738A-51DF-80CC-8A6CC067DA6C/GUID-986BD779-D902-5925-A852-D2A096856053">Plug-in installs new animation/redraw scheduler</xref>  </p> </li> </ol> </section> <section id="GUID-669693F6-035F-5D7A-96FE-5D1F0EF2DF81"><title>Plug-in uses MWsWindow interface</title> <p><b>Pre-conditions </b> </p> <p>The plug-in has registered itself as an <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsEventHandler</apiname></xref> by calling <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsGraphicDrawerEnvironment::RegisterWsEventHandler()</apiname></xref>  </p> <p><b>Process </b> </p> <p>WSERV publishes <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>EWindowClosing</apiname></xref> event. </p> <p>The Event Handler receives <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>EWindowClosing</apiname></xref> event. </p> <p>The Event Handler obtains <codeph>MWsWindow*</codeph> for window that is closing by calling <codeph>TWsCREvent::Window()</codeph> . </p> <p>The Event Handler obtains the size and position of the window that is closing using <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsWindow</apiname></xref> functions. This could then be used by a render stage to perform a window closing transition, for example. </p> </section> <section id="GUID-41410434-9226-5356-AE5D-3943CDD5032A"><title>Plug-in uses MWsMemoryRelease

          interface</title> <p><b>Preconditions </b> </p> <p>The plug-in has registered itself as a memory release by calling <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsGraphicDrawerEnvironment::RegisterMemoryRelease(MWsMemoryRelease*)</apiname></xref> </p> <p><b>Process </b> </p> <p>WSERV discovers that it is short of memory. </p> <p>WSERV notifies all registered memory release objects. It requests them to <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>ReleaseMemory(TMemoryReleaseLevel)</apiname></xref> passing in a level representing the importance - for instance tidy, unimportant or anything. </p> <p>Memory release object releases memory - for example, a cache. </p> <p>If insufficient memory is released, WSERV could try again with higher level of importance. </p> </section> <section id="GUID-C961C9DC-FD6E-5FA5-B32C-6D23BFCFFCED"><title>Plug-in uses MWsPluginManager

          interface</title> <p>The <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsPluginManager</apiname></xref> interface can be used for plug-ins to gain access to extension interfaces defined by other plug-ins – for example, a bitmap cache. </p> <p><b>Preconditions </b> </p> <p>A plug-in object implementing a custom extension interface (for example a bitmap cache) has been loaded, based on instructions in <codeph>WSINI.INI</codeph>. </p> <p><b>Process </b> </p> <p>WSERV calls into the plug-in code. For example, this could be the render stage factory. </p> <p>The plug-in calls <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsGraphicsDrawerEnvironment::ResolveObjectInterface(EMWsPluginManager)</apiname></xref> </p> <p>The Environment returns a <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsPluginManager*</apiname></xref> interface </p> <p>The plug-in calls <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsPluginManager::ResolvePluginInterface(&lt;BITMAP CACHE

          UID&gt;)</apiname></xref>  </p> <p>The plug-in manager returns <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsBitmapCache*</apiname></xref> object. </p> </section> <section id="GUID-83F7707F-F67A-5C8A-B0A3-86460F1CA4D6"><title>Plug-in uses MWsIniFile interface</title> <p><b>Process </b> </p> <p>WSERV calls into plug-in code. For example, it could call into the render stage factory to create a render stage. </p> <p>The plug-in wants to read some <codeph>WSINI.INI</codeph> file variables for configuration purposes. </p> <p>The plug-in calls <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsGraphicsDrawerEnvironment::ResolveObjectInterface(EMWsIniFile)</apiname></xref> </p> <p>The graphic drawer environment returns <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsIniFile*</apiname></xref> interface </p> <p>The plug-in calls <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsIniFile::FindVar(&lt;PARAMETERS&gt;)

          </apiname></xref> to find the value of the variable it is interested in. </p> </section> <section id="GUID-986BD779-D902-5925-A852-D2A096856053"><title>Plug-in installs new animation/redraw scheduler</title> <p><b>Process </b> </p> <p>WSERV calls into the plug-in code. For instance, it could call into a CRP or the render stage factory. </p> <p>The plug-in constructs a concrete instance of its own custom <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsAnimationScheduler</apiname></xref> subclass. </p> <p>The plug-in calls <xref href="GUID-261434A4-24A4-3592-81E4-6C580A5BB511.dita"><apiname>MWsGraphicsDrawerEnvironment::SetCustomAnimationScheduler(MWsAnimationScheduler*)</apiname></xref>, passing in the custom scheduler. </p> <p>Subsequent scheduling uses the custom scheduler created by the plug-in. </p> </section> </conbody><related-links><link href="GUID-39CFE2E2-9776-54EE-8E3B-8B85AFF1697A.dita"><linktext>Window Server Plug-in Framework in the