Week 28 contribution of SDK documentation content. See release notes for details. Fixes bugs Bug 1897 and Bug 1522.
<?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 id="GUID-00764271-AD6B-5F41-AF72-843107EBF95F" xml:lang="en"><title> File
Server Plugin implementation tutorial</title><shortdesc>This document contains guidelines for writing a file server plugin
for Symbian platform. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This document is split into three sections: </p>
<ul>
<li id="GUID-56E1538B-5EA5-542B-873B-A620D26DC183"><p> <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-CE12FAD4-531B-5AAB-B37B-9C61AF61205E">Writing a plug-in</xref>, </p> </li>
<li id="GUID-1CBFE144-BF63-5184-9677-5730A1CFBC1C"><p> <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-7AFFCF4E-B247-59FB-BA0C-4A548DF6D7CB">Loading and mounting a plug-in</xref>, </p> </li>
<li id="GUID-77348F5C-D42E-572F-A878-19153729C8E4"><p> <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-5E29C798-17A7-568F-B35C-1D8D10A03B80">Communicating with plug-ins</xref>. </p> </li>
</ul>
<section id="GUID-CE12FAD4-531B-5AAB-B37B-9C61AF61205E"><title>Writing a plug-in</title> <p>A
file server plug-in is made up of at least two classes: </p> <ul>
<li id="GUID-C6DF4F62-C13B-5CDC-972D-C46A88C0D612"><p>a factory class derived
from the <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-89CF85BE-784F-5237-9F78-69D603B650C4">CFspluginFactory</xref> base
class, </p> </li>
<li id="GUID-B9E3CC8E-B7E1-5964-976D-ADD67BCBDD6C"><p>a plug-in class derived
from the <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-0994B2F1-23FE-524B-939E-1F83C766924B">CFsplugin</xref> base
class. </p> </li>
</ul> <p>Each plug-in must <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-06B294FF-4F84-5181-AB30-71C3292B9107">register
to intercept messages</xref>. To <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-248CA470-6939-55C3-8D93-B41ECD7D5D28">make
internal requests</xref> call the functions RFilePlugin, RDirPlugin or RFsPlugin. </p> <p>Each
plug-in DLL must export a plug-in entry point function with the prototype: </p> <codeblock id="GUID-73D95801-F3C7-5EB2-9767-25F0634DFE63" xml:space="preserve">CFsPluginFactory* CreateFileSystem();</codeblock> <p>The
loader calls this function when a client wishes to install a file server plug-in
and creates an instance of the factory class. For example: </p> <codeblock id="GUID-99E3309A-52CA-58AF-B46C-D4DCA43B865E" xml:space="preserve">extern "C" {
EXPORT_C CFsPluginFactory* CreateFileSystem()
{
return(new CMyPluginFactory());
}
} </codeblock> <p id="GUID-89CF85BE-784F-5237-9F78-69D603B650C4"><b>CFsPluginFactory</b> </p> <p>The <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPluginFactory</apiname></xref> base class follows
the standard factory pattern as used in other file server DLLs. <codeph>CFsPluginFactory</codeph> creates <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPlugin</apiname></xref> derived objects. </p> <p>plug-in
authors must provide implementations of the pure virtual functions: </p> <ul>
<li id="GUID-A1BC45F3-96F1-5261-B4AE-9D7D9AC7871E"><p> <codeph>Install()</codeph> </p> <p>This
function is called by the file server in response to a call to <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFs::AddPlugin()</apiname></xref> and
installs the plug-in factory. </p> <p>This function must set the name of the
plug-in factory with a call to <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CObject::SetName()</apiname></xref>.
The plug-in name is used when mounting, dismounting and unloading plug-ins.
Optionally, <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFs::AddPlugin()</apiname></xref> can
perform other plugin specific initialization, for example setting <codeph>iSupportedDrives</codeph> to
indicate which drives the plugin will operate on, as required by the plugin
factory. See <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-DB21C0FD-46F8-5E4F-9288-69AE8609482B">drive
selection</xref>. </p> </li>
<li id="GUID-75D6526F-30EA-51DC-89D3-C4A30B431751"><p> <codeph>NewPluginL()</codeph> </p> <p>This
is called by the file server in response to a call to <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFs::MountPlugin()</apiname></xref>,
this function creates a new <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPlugin</apiname></xref> derived
object and returns a pointer to it. </p> </li>
<li id="GUID-961B38B5-C459-539F-9918-DB4F83F40424"><p> <codeph>UniquePosition()</codeph> </p> <p>This
function returns the unique ID of the plugin. This is used to identify the
plugin and to specify the location of the plugin in the chain. See <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-90FC1AD9-D709-5105-A445-0AA3D7BA85B7">unique position</xref>. </p> </li>
<li id="GUID-D7457283-699D-54BA-B375-F16443792D2D"><p> <codeph>Remove()</codeph> (overriding
this virtual function is optional as it is not a pure virtual function) </p> <p>This
is called just before the plugin factory object is destroyed and allows any
clean up to be carried out. </p> <p>The default implementation just returns <codeph>KErrNone</codeph>.
Implementations should return an error code on error detection. </p> </li>
</ul> <p>The <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPluginfactory</apiname></xref> base
class also has the following member variables: </p> <ul>
<li id="GUID-388D1206-5AE5-52FF-A1CF-3CB66D5ADB4A"><p>iSupportedDrives </p> <p>This
member holds a bit mask that indicates which drives the plugin created by
this factory supports being mounted on. Bits 0 to 25 correspond to 26 drive
letters lettered from A to Z. </p> <p>Plugin authors should use the the <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>SetSupportedDrives()</apiname></xref> API in order
to correctly set up which drives their plugin should be mounted on. Set the
drive number to <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>KPluginSupportAllDrives</apiname></xref> to
indicate that the plugin needs to be mounted on all drives. </p> <p>If you
are using Symbian platform prior to version 9.5, <codeph>iSupportedDrives</codeph> is
assigned to by plugin writers directly. However, this is now discouraged in
favour of using SetSupportedDrives. </p> </li>
<li id="GUID-72C4595A-9E95-5082-935D-40D2818A9055"><p>iUniquePos </p> <p>This
member stores the unique position identifier. If this member is used then
plugin authors should implement the <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>UniquePosition()</apiname></xref> function
to return the variable. </p> </li>
</ul> <p>An example skeleton implementation of a <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPluginFactory</apiname></xref> derived
class is as follows: </p> <codeblock id="GUID-06314778-EB27-573E-A1B5-E10C64CBF1D1" xml:space="preserve">class CMyPluginFactory : public CFsPluginFactory
{
public:
CMyPluginFactory();
virtual TInt Install();
virtual CFsPlugin* NewPluginL();
virtual TInt UniquePosition();
virtual TInt Remove();
};
CMyPluginFactory::CMyPluginFactory()
{
// Constructor for the plugin factory
}
TInt CMyPluginFactory::Install()
{
// Install function for the plugin factory
iUniquePos = 0x2000001;
// Mount on all drives
SetSupportedDrives(KPluginSupportAllDrives);
return SetName(_L("MyPluginName"));
}
CFsPlugin* CMyPluginFactory::NewPluginL()
{
// plugin factory function, creates the plugin
return CMyPlugin::NewL();
}
TInt CMyPluginFactory::UniquePosition()
{
// Return’s the unique position identifier for plugins created by this factory class.
return iUniquePos;
}
TInt CMyPluginFactory::Remove()
{
// Clean up function for the plugin factory
return KErrNone;
}</codeblock> <p id="GUID-0994B2F1-23FE-524B-939E-1F83C766924B"><b>CFsPlugin</b> </p> <p>This
is the base class for the file server plugin and is defined in <filepath>f32plugin.h</filepath>. </p> <p>Plugins
must register to intercept particular types of file server requests. See <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-06B294FF-4F84-5181-AB30-71C3292B9107">Registering
a plugin to intercept messages</xref>. </p> <p>Plugin authors need to provide
an implementation of the pure virtual method <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>DoRequestL()</apiname></xref> and
can optionally override the virtual functions: </p> <ul>
<li id="GUID-C9814092-F5CB-5FE6-A233-5ED43269CE8F"><p> <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-64373962-7AB0-597B-BF2E-0D336AFBB545">SessionDisconnect()</xref> - virtual, </p> </li>
<li id="GUID-8DDC108F-A379-58D6-98E8-20983B0B64FB"><p> <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-5371EF5C-F02E-556D-8BC4-6E0D8D9B35D2">InitialiseL()</xref> - virtual, </p> </li>
<li id="GUID-1B536E1D-974A-584F-B2C6-36DEDFA6B55B"><p> <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-97427151-C6E4-5FE4-8197-0D7C58EDB29F">Deliver()</xref> - virtual, </p> </li>
<li id="GUID-49E41C16-6653-5719-93B9-43C639D0444F"><p> <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-CE67C69C-1E85-59FC-8E2B-1802F65D94F3">NewPluginConnL()</xref> - virtual, </p> </li>
<li id="GUID-DB7354C0-9587-5D6E-BF6C-6C0DBF3C7582"><p> <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-8E1D4416-DE65-516F-92CD-D18C2166B279">DoRequestL()</xref> - pure virtual, </p> </li>
</ul> <p id="GUID-64373962-7AB0-597B-BF2E-0D336AFBB545"><b>SessionDisconnect()</b> </p> <p> <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>SessionDisconnect()</apiname></xref> is called
by the file server when a file server session is disconnected. </p> <p>The
default implementation just returns <codeph>KErrNone</codeph>. Overriding
this function allows plugins to free up any resources prior to the outstanding
operations being cancelled. </p> <p id="GUID-5371EF5C-F02E-556D-8BC4-6E0D8D9B35D2"><b>InitialiseL()</b> </p> <p>The
default implementation of <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>InitialiseL()</apiname></xref> does
nothing. Override this implementation to perform a plugin specific initialisation,
for example <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-06B294FF-4F84-5181-AB30-71C3292B9107">registering
intercepts</xref>. If the plugin cannot be initialised this function must
leave with a suitable error code. </p> <p id="GUID-97427151-C6E4-5FE4-8197-0D7C58EDB29F"><b>Deliver()</b> </p> <p> <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>Deliver()</apiname></xref> is called in the context
of the previous thread that originated or processed the request (either the
file server main thread or another plugin thread) before the request is dispatched
to the plugin’s thread. </p> <p>The default implementation delivers the request
to the end of the plugin thread's request queue. Requests that require priority
handling (usually those sent using an <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RPlugin</apiname></xref> session)
are delivered to the front of the queue. See <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-5E29C798-17A7-568F-B35C-1D8D10A03B80">Communicating
with plugins</xref>. </p> <p>Overriding this function allows plugins to perform
operations within the context of the original thread (like validation of request
parameters or filtering requests) before the request is sent to the plugin’s
main thread or passed to the next plugin or drive thread. </p> <p> <codeph>Deliver()</codeph> is
called from outside the context of the plugin’s main thread so care must be
taken as the plugin main thread may still be processing the previous request. </p> <ul>
<li id="GUID-DAA3DBC2-4C31-51B9-B071-E36F44A7BFDE"><p>If <codeph>KErrNone</codeph> is
returned then the base class implementation of this function must be called
to ensure that the request is dispatched to the plugin’s thread for further
processing in <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>DoRequestL()</apiname></xref>. </p> </li>
<li id="GUID-9A2229A2-D17D-5BE4-A8C1-66FCBD4447F6"><p> <codeph>KPluginMessageForward</codeph> indicates
that the request has been processed synchronously and should be passed down
to the next plugin in the stack (bypassing the current plugin’s <codeph>DoRequestL()</codeph> function).
This is used for pre-intercepts. </p> </li>
<li id="GUID-D10FB123-B30D-5CE0-B3EB-CDBA78CF2A8D"><p> <codeph>KPluginMessageComplete</codeph> indicates
that the request has been processed synchronously and should be passed up
to the previous plugin in the stack (bypassing the current plugin’s <codeph>DoRequestL()</codeph> function).
This is used for post-intercepts. </p> </li>
</ul> <p id="GUID-CE67C69C-1E85-59FC-8E2B-1802F65D94F3"><b>NewPluginConnL()</b> </p> <p>The
function <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>NewPluginConnL()</apiname></xref> is
the default implementation and it returns <codeph>KErrNotSupported</codeph>.
Override this implementation to create a <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPluginConn</apiname></xref> derived
object to enable direct communication between a client application and a plugin
using <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RPlugin</apiname></xref>. See <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-5E29C798-17A7-568F-B35C-1D8D10A03B80">Communicating
with plugins</xref>. </p> <p id="GUID-8E1D4416-DE65-516F-92CD-D18C2166B279"><b>DoRequestL()</b> </p> <p> <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>DoRequestL()</apiname></xref> is the main entry
point for messages intercepted by a plugin. Individual plugins are usually
single-threaded and must process requests in the order that they arrive. However,
the plugin framework is not single-threaded. While a plugin is handling a
request all other plugins are also able to handle requests. The drive thread
is also able to handle requests forwarded to it by plugins. <codeph>DoRequestL()</codeph> is
called in the context of the plugin’s main thread and must be implemented
to intercept file server requests in this context. </p> <p>The current request
must have finished all processing before <codeph>DoRequestL()</codeph> has
completed. If a plugin has multiple threads and the request is handled in
a thread other than the main thread then the <codeph>DoRequestL()</codeph> function
must be blocked until the request has been processed. This is because when <codeph>DoRequestL()</codeph> exits,
the plugin framework forwards the message to the next plugin in the chain.
Unpredictable behaviour may occur if the plugin has not finished processing
a request before it is passed to the next plugin/file system. </p> <p>Errors
returned by this function are propagated back to the client. If this function
leaves then the client thread panics. <b>Note</b>: Do not return from this
function until the request has been fully processed. This is because after
returning from this function the request is passed onto the next plugin in
the chain. This means that you cannot pass the request to a separate thread
and return immediately in order to implement a multi-threaded plugin. </p> <p> <codeph>KErrCompletion</codeph> indicates
that all processing for this request has been completed by this plugin. Post-intercept
is then enabled and the flow of execution is up the plugin stack towards the
client, starting at the previous plugin. </p> <p>When a plugin intercepts
a file read or file write request and does an early completion (i.e. returns <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>KErrCompletion</apiname></xref> in pre-intercept)
then the plugin author should call <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsPluginRequest::SetSharePos()</apiname></xref> to
allow share position to be updated after early read/write completion. </p> <p id="GUID-14773530-7C15-52E2-A542-72A0B2163461"><b>TFsPluginRequest</b> </p> <p>The <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsPluginRequest</apiname></xref> class encapsulates
the intercepted file server request and is passed as a reference to the plugin's <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>DoRequestL()</apiname></xref> function. <codeph>TFsPluginRequest</codeph> provides
APIs that extract request specific information such as: </p> <ul>
<li id="GUID-D5FE21A2-F05A-5509-8A4B-21D95B79B4AE"><p> <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>DriveNumber()</apiname></xref> -
returns the target drive number. The drive number is in the range of zero
to 25, which corresponds to drive letters A to Z, </p> </li>
<li id="GUID-9EDB9144-38EC-5117-A029-268658BE6877"><p> <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>Function()</apiname></xref> -
the type of request as defined in <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsMessage</apiname></xref>, </p> </li>
<li id="GUID-96068F44-2CC3-5361-8814-2CDBD13C30C7"><p> <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>IsPostOperation()</apiname></xref> -
returns <codeph>ETrue</codeph> or <codeph>EFalse</codeph> to indicate if the
request being intercepted is in post-intercept mode (<codeph>ETrue</codeph>)
or pre-intercept. </p> </li>
</ul> <p> <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsPluginRequest</apiname></xref> acts
as a utility class for plugins. This class has two main functions <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsPluginRequest::Read()</apiname></xref> and <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsPluginRequest::Write()</apiname></xref>, which
allow a plugin to read from and write to the message arguments of a request. </p> <p> <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsPluginRequest::Read()</apiname></xref> has
various overloads for <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TInt</apiname></xref>, <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TUint</apiname></xref>, <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>Tint64</apiname></xref> and
descriptor data types, all of which take as their first argument a <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TF32ArgType</apiname></xref> object. </p> <p>The <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TF32ArgType</apiname></xref> is an enumeration
which defines the type of data that is requested. For example, <codeph>EPosition</codeph>, <codeph>ELength</codeph>, <codeph>EData</codeph> for
getting the position, length and data arguments from the request. <codeph>TF32ArgType</codeph> is
defined as follows: </p> <codeblock id="GUID-E8DCEB67-BFA0-52AD-A554-C8C76645E3CC" xml:space="preserve">enum TF32ArgType
{
EPosition,
ELength,
EData,
ESize,
EName,
ENewName,
EEntry,
ETime,
ESetAtt,
EClearAtt,
EMode,
EAtt,
EAttMask,
EUid,
EEntryArray,
ENewPosition,
};</codeblock> <p> <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsPluginRequest::Write()</apiname></xref> only
has two overloads, both of these take descriptor types and the argument <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TF32ArgType</apiname></xref>. Many functions do
not use descriptor types, it will be necessary to package data for these inside
a descriptor. </p> <p>The following provides an example of how to do this
for <codeph>Entry</codeph>: </p> <codeblock id="GUID-ECF1B967-6588-5D4C-95A1-FA108E3D0417" xml:space="preserve"> TPckgC<TEntry> entryPckg(entry);
err = aRequest.Write(EEntry, entryPckg);</codeblock> <p id="GUID-248CA470-6939-55C3-8D93-B41ECD7D5D28"><b>Sending internal requests
to the file server</b> </p> <p>The classes <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFilePlugin</apiname></xref>, <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RDirPlugin</apiname></xref> and <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFsPlugin</apiname></xref>,
defined in <filepath>F32Plugin.h</filepath>, are the classes that plugin authors
should use to send internal requests to the file server. The APIs for these
classes are mostly identical from their client side (<xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFile</apiname></xref>, <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RDir</apiname></xref> and <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFs</apiname></xref>)
counter-parts. </p> <p>Before a plugin can perform any requests on a file
it must first either perform an <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>Open()</apiname></xref> or <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>AdoptFromClient()</apiname></xref>. When an <codeph>AdoptFromClient()</codeph> is
performed the <codeph>RFilePlugin</codeph> instance opens the file associated
with the client request. <codeph>Open()</codeph> can be used to open the same
file (potentially with different parameters than those supplied by the client)
and it can be used to open an entirely different file. </p> <p> <codeph>RFilePlugin</codeph> has
the following public functions: </p> <codeblock id="GUID-FC3DCDA2-964C-50F9-A0C9-97A3F00E3DDC" xml:space="preserve">class RFilePlugin : private RFile
{
public:
IMPORT_C RFilePlugin(TFsPluginRequest& aRequest, TBool aDirectToDrive = EFalse);
// open a NEW file using same session as passed request
IMPORT_C TInt Open(const TDesC& aName,TUint aMode);
IMPORT_C TInt Create(const TDesC& aName,TUint aFileMode);
IMPORT_C TInt Replace(const TDesC& aName,TUint aFileMode);
IMPORT_C TInt Temp(const TDesC& aPath,TFileName& aName,TUint aFileMode);
// re-open SAME file as client's request
IMPORT_C TInt AdoptFromClient();
// Transfer the plugin's open file to the client
IMPORT_C TInt TransferToClient();
IMPORT_C void Close();
// RFile overloads
IMPORT_C TInt Read(TInt64 aPos,TDes8& aDes) const;
IMPORT_C TInt Read(TInt64 aPos,TDes8& aDes,TInt aLength) const;
IMPORT_C TInt Write(TInt64 aPos,const TDesC8& aDes);
IMPORT_C TInt Write(TInt64 aPos,const TDesC8& aDes,TInt aLength);
IMPORT_C TInt Lock(TInt64 aPos,TInt64 aLength) const;
IMPORT_C TInt UnLock(TInt64 aPos,TInt64 aLength) const;
IMPORT_C TInt Seek(TSeek aMode,TInt64& aPos) const;
IMPORT_C TInt Flush();
IMPORT_C TInt Size(TInt64& aSize) const;
IMPORT_C TInt SetSize(TInt64 aSize);
IMPORT_C TInt Att(TUint& aAttValue) const;
IMPORT_C TInt SetAtt(TUint aSetAttMask,TUint aClearAttMask);
IMPORT_C TInt Modified(TTime& aTime) const;
IMPORT_C TInt SetModified(const TTime& aTime);
IMPORT_C TInt Set(const TTime& aTime,TUint aSetAttMask,TUint aClearAttMask);
IMPORT_C TInt ChangeMode(TFileMode aNewMode);
IMPORT_C TInt Rename(const TDesC& aNewName);
...</codeblock> <p id="GUID-06B294FF-4F84-5181-AB30-71C3292B9107"><b>Registering a plugin to
intercept messages</b> </p> <p>The base class <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPlugin</apiname></xref>,
has functions that allow a plugin to register to intercept specific types
of file server request. This is explained in more detail under <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-50F7CD3A-A051-5498-8886-B4501523FD1D">Interception of file server requests</xref>. </p> <p><b>RegisterIntercept()</b> </p> <p>The function <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RegisterIntercept()</apiname></xref> registers
a plugin to intercept a specified <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsMessage</apiname></xref>.
The second parameter of <codeph>RegisterIntercept()</codeph> allows plugin
authors to specify whether the intercept is processed before, after or both
before and after the request is processed by the drive thread. See <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TInterceptAtts</apiname></xref>. </p> <p><b>UnregisterIntercept()</b> </p> <p>Un-register an intercept with <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>UnregisterIntercept()</apiname></xref>. <codeph>UnregisterIntercept()</codeph> takes <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TFsMessage</apiname></xref>, which is the ID of
the message and <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>TInterceptAtts</apiname></xref>,
which is the type of intercept that you no longer wish to intercept. </p> </section>
<section id="GUID-7AFFCF4E-B247-59FB-BA0C-4A548DF6D7CB"><title>Loading and
mounting a plugin</title> <p>A plugin must be loaded and mounted before it
can intercept requests. </p> <p id="GUID-84812368-5915-5E30-A29C-FBC05C51E8F0"><b>Loading and unloading a
plugin</b> </p> <p>Before a plugin can be used by the file server the library
(<filepath>.PXT</filepath>) that contains the plugin needs to be loaded into
the file server process by the loader. Do this using the <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFs::AddPlugin()</apiname></xref> function
defined in <filepath>f32file.h</filepath>. </p> <p> <codeph>AddPlugin()</codeph> can
be called by any user side application with the relevant <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-0B7B373D-41ED-5C91-ACC4-393A8669815A">platform security capabilities</xref>. </p> <p>Unload a plugin using the <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFs::RemovePlugin()</apiname></xref> function
also defined in <filepath>f32file.h</filepath>. </p> <p> <b>Note</b>: Refer
to the device manufacturer if you want to load plugins automatically at system
startup time. </p> <p id="GUID-BED54BD9-2F3F-588E-854B-C28745C8F30A"><b>Mounting and unmounting
a plugin</b> </p> <p>File Server plugins are mounted using the <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFs::MountPlugin()</apiname></xref> function
defined in <filepath>f32file.h</filepath>. The plug in must have already been
loaded using <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFs::AddPlugin()</apiname></xref>. </p> <p>There
are various overloads of the <codeph>MountPlugin()</codeph> function. Those
functions which do not take a drive parameter are mounted using <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>KPluginAutoAttach</apiname></xref>. </p> <p>Call <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RFs::DismountPlugin()</apiname></xref> to dismount
the file server plugin. Dismount the plugin when you no longer need it to
intercept file server requests. </p> <p>Before a plugin can be dismounted
all resources owned by the plugin must be closed. A plugin can intercept the
request to dismount it and use this to free resources and close down cleanly.
If the plugin owns resources on behalf of a client (for example, a client
has a file open that is using the decompression plugin) then the plugin can
reject the request to dismount by returning one of the system wide error codes. </p> </section>
<section id="GUID-5E29C798-17A7-568F-B35C-1D8D10A03B80"><title>Communicating
with plugins</title> <p>The file server provides a standard logical channel
based mechanism that enables a trusted application to communicate with a file
server plugin. For example, a virus scanning plugin can present a user interface
for the device user. <b>Note</b>: <codeph>DiskAdmin</codeph> capabilities
are required in order to load a plugin. See <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-0B7B373D-41ED-5C91-ACC4-393A8669815A">platform
security capabilities</xref>. </p> <p><b>Data transfer </b> </p> <p>The class <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPluginConnRequest</apiname></xref> is
an information container for asynchronous requests that the client application
wants performed. <codeph>CFsPluginConnRequest</codeph> also provides functions
that enable data to be transferred between the plugin and the application.
The following examples show how to use <codeph>CFsPluginConnRequest</codeph>. </p> <p id="GUID-D0B1C6A0-4952-51C3-9DCF-7B8344D60333"><b>User-side application</b></p><p>A
user-side application uses a class derived from <xref href="GUID-118CCC9E-C58B-3AA0-86A8-219914E7E7BC.dita"><apiname>RPlugin</apiname></xref> to
access the plugin. See <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-285326AB-9D14-5DE2-BDD5-C418B755F57B">plugin
side</xref>. The <xref href="GUID-118CCC9E-C58B-3AA0-86A8-219914E7E7BC.dita"><apiname>RPlugin</apiname></xref> class (defined in <filepath>f32file.h</filepath>)
provides various functions that must be overridden. The functions <xref href="GUID-06C73075-6095-3D8F-AFC9-FD832958A49C.dita"><apiname>DoControl()</apiname></xref>,<xref href="GUID-9D910016-5611-30DD-A139-EE46705A4912.dita"><apiname> DoRequest()</apiname></xref> and <xref href="GUID-675860FB-AA37-3467-AF52-7D1B17FEE0A6.dita"><apiname>DoCancel()</apiname></xref> are protected. Plugin authors must provide a public interface of their own
design in the derived class that communicates with the plugin using these
protected functions. </p><p> An <codeph>RPlugin</codeph> session is opened
by passing in the <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-90FC1AD9-D709-5105-A445-0AA3D7BA85B7">unique
position</xref> identifier of the plugin it wishes to communicate with. When
the file server receives the request it validates the capabilities of the
application before calling the plugin's <xref href="GUID-3A78342A-1CA1-372F-B003-B0B3461BA836.dita"><apiname>NewPluginConnL()</apiname></xref> function.
The plugin must certify that it is expecting the client application before
creating the server side connection object.</p><p> Below is a basic example
of an <codeph>RPlugin</codeph> derived class: </p><codeblock xml:space="preserve">class RMyPlugin : public RPlugin
{
public:
inline TInt Enable();
inline TInt Disable();
};
inline TInt RMyPlugin::Enable()
{
return DoControl(EEnable);
}
inline TInt RMyPlugin::Disable()
{
return DoControl(EDisable);
}
void MyRPlugin::DoRequest(TInt aReqNo,TRequestStatus& aStatus) const
{
RPlugin::DoRequest(aReqNo,aStatus);
}
void MyRPlugin::DoRequest(TInt aReqNo,TRequestStatus& aStatus,TDes8& a1) const
{
RPlugin::DoRequest(aReqNo,aStatus,a1);
}
void MyRPlugin::DoRequest(TInt aReqNo,TRequestStatus& aStatus,TDes8& a1,TDes8& a2) const
{
RPlugin::DoRequest(aReqNo,aStatus,a1,a2);
}
TInt MyRPlugin::DoControl(TInt aFunction) const
{
return RPlugin::DoControl(aFunction);
}
</codeblock><p>This is used in the following way:</p><codeblock xml:space="preserve">Tint r = KErrNone
r = TheFs.AddPlugin(_L("MyPlugin"));
r = TheFs.MountPlugin(_L("MyPlugin"),KPluginSupportAllDrives);
User::LeaveIfError(r);
RMyPlugin thePlugin;
r = thePlugin.Open(TheFs, KMyPluginUniquePos);
User::LeaveIfError(r);
r = thePlugin.Enable();
User::LeaveIfError(r);
...
//Perform communication with plugin here
...
r = thePlugin.Disable();
User::LeaveIfError(r);
thePlugin.Close();</codeblock> <codeblock xml:space="preserve">class RMyPlugin : public RPlugin
{
public:
inline TInt Enable();
inline TInt Disable();
};
inline TInt RMyPlugin::Enable()
{
return DoControl(EEnable);
}
inline TInt RMyPlugin::Disable()
{
return DoControl(EDisable);
}
void MyRPlugin::DoRequest(TInt aReqNo,TRequestStatus& aStatus) const
{
RPlugin::DoRequest(aReqNo,aStatus);
}
void MyRPlugin::DoRequest(TInt aReqNo,TRequestStatus& aStatus,TDes8& a1) const
{
RPlugin::DoRequest(aReqNo,aStatus,a1);
}
void MyRPlugin::DoRequest(TInt aReqNo,TRequestStatus& aStatus,TDes8& a1,TDes8& a2) const
{
RPlugin::DoRequest(aReqNo,aStatus,a1,a2);
}
TInt MyRPlugin::DoControl(TInt aFunction) const
{
return RPlugin::DoControl(aFunction);
}
etc..
}
</codeblock><p>This is used in the following way:</p><codeblock xml:space="preserve">Tint r = KErrNone
r = TheFs.AddPlugin(_L("MyPlugin"));
r = TheFs.MountPlugin(_L("MyPlugin"),KPluginSupportAllDrives);
User::LeaveIfError(r);
RMyPlugin thePlugin;
r = thePlugin.Open(TheFs, KMyPluginUniquePos);
User::LeaveIfError(r);
r = thePlugin.Enable();
User::LeaveIfError(r);
...
//Perform communication with plugin here
...
r = thePlugin.Disable();
User::LeaveIfError(r);
thePlugin.Close();</codeblock> <p id="GUID-285326AB-9D14-5DE2-BDD5-C418B755F57B"><b>Plugin side</b> </p> <p>This
is the plugin side of the communication. This must be implemented in order
to communicate with the application side class <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RPlugin</apiname></xref> above.
The plugin side is a class derived from the <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPluginConn</apiname></xref> class.
The plugin’s <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>NewPluginConnL()</apiname></xref> function
is called from the file server when <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RPlugin::Open()</apiname></xref> is
called by the client. </p> <p>Synchronous (<xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>DoControl()</apiname></xref>)
and asynchronous (<xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>DoRequest()</apiname></xref>)
requests sent from the <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>RPlugin</apiname></xref> class
are routed directly to the associated plugin's <xref href="GUID-DA6C5564-96A4-3A06-A1A0-59A29F797570.dita"><apiname>CFsPluginConn</apiname></xref> derived
class. The following code shows a basic implementation: </p> <codeblock id="GUID-4B07F646-AEC0-5923-9647-E827D111E587" xml:space="preserve">class CMyPluginConn : public CFsPluginConn
{
virtual TInt DoControl(CFsPluginConnRequest& aRequest);
virtual void DoRequest(CFsPluginConnRequest& aRequest);
virtual void DoCancel(TInt aReqMask);
};
// From the CFsPlugin derived class
CFsPluginConn* CMyPlugin::NewPluginConnL()
{
CMyPluginConn* thePluginConn = new(ELeave) CMyPluginConn();
return thePluginConn;
}
TInt CMyPluginConn::DoControl(CFsPluginConnRequest& aRequest)
{
TInt r = KErrNotSupported;
CMyPlugin& myPlugin = *(CMyPlugin*)Plugin();
switch(aRequest.Function())
{
case RMyPlugin::EEnable:
r = myPlugin.Enable();
break;
case RLoggerConn::EDisable:
r = myPlugin.Disable();
break;
default:
break;
}
return r;
}
void CMyPluginConn::DoRequest(CFsPluginConnRequest& aRequest)
{
return KErrNotSupported;
}
void DoCancel(TInt aReqMask)
{
// Not required as no asynchronous request support
}</codeblock> </section>
</conbody></concept>