Week 23 contribution of SDK documentation content. See release notes for details. Fixes bugs Bug 2714, Bug 462.
<?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-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6" xml:lang="en"><title>File Server
Plugin Concepts</title><shortdesc>This topic describes the file server plug-in concepts.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>File server plugins can issue direct file server requests, interpret and
modify inbound messages and change file and metadata. A compression plugin
may need to intercept file read or file write requests which are sent from
the client to provide a seamless user experience. This operation requires
the modification of the data, position and length arguments that are sent
from the client to the file server. </p>
<p>There are some limitations to the file server plugin framework: </p>
<ul>
<li id="GUID-1C02ECAE-A711-5E2A-8006-EC2D1BF5A859"><p>The file server plugin
framework only operates on one client file at any time. However, a plugin
itself can operate on any number of files during a single request from the
client. </p> </li>
<li id="GUID-F82C8E71-479B-5482-8234-C5AD2AD05A91"><p>The file server plugin
framework does not enable the compression or encryption of whole volumes.
If access to the whole media volume is needed use a <xref href="GUID-983F0ABD-470C-51C3-B6AE-1B1AA55AB4A2.dita">file
server extension</xref> rather than a plugin. </p> </li>
<li id="GUID-386C0911-30EF-56B0-BD3B-4BC97A7CEFA3"><p>File modification plugins
cannot operate on demand paged executables. Demand paging does not use the
file server, so the plugin framework cannot be used to encrypt/process the
executable. </p> </li>
</ul>
<note> The improved framework will not prevent deadlock with existing plugins.
Plugins that currently issue <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref> requests must be migrated
to the new APIs to prevent deadlock. Follow the guidelines within the <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita">plugin implementation tutorial</xref></note>
<ul>
<li id="GUID-0A5ECCEA-CD70-528D-8880-463CA77D797B"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-8B5B325D-D88C-55A7-9684-C2DCF81FCD79">Plugin type</xref>, </p> </li>
<li id="GUID-40202D9E-C136-55BB-A5A1-DF64971B99D1"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-C76B06C8-DEDC-57AC-A510-3DD1E232241A">Architecture</xref>, </p> </li>
<li id="GUID-60C8A1F1-6BE6-59A3-8F33-BD7FBFF9FB59"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-6234893D-A1C8-5870-9761-9EA2BD6909F0">Plugin order</xref>, </p> </li>
<li id="GUID-20D4D10F-5E92-5FE3-A89C-DAF45E52EB0B"><p> <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-91E1927C-3AA6-5594-8238-EA7B590278B2"><p> <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> </li>
<li id="GUID-59EB5503-3D02-5E2D-80A4-A20EA8364D81"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-0B7B373D-41ED-5C91-ACC4-393A8669815A">Security</xref>. </p> </li>
</ul>
<section id="GUID-8B5B325D-D88C-55A7-9684-C2DCF81FCD79"><title>Plugin type</title> <p>There
are two different types of file server plugins: </p> <ul>
<li id="GUID-0FBE9E75-D164-5BCC-B00A-A5A76DBD200C"><p>Observer plugins - intercept
requests but do not modify file data or associated meta data. </p> <p>Examples
of observer plugins are those for virus scanning or logging. </p> </li>
<li id="GUID-69708845-9C79-5C19-B758-AEF8F8A693E0"><p>Modifier plugins - intercept
requests and modify the data or associated meta data of the target files or
directories.. </p> <p>Examples of file modifier plugins are compression and
encryption plugins. </p> </li>
</ul> </section>
<section id="GUID-C76B06C8-DEDC-57AC-A510-3DD1E232241A"><title>Architecture</title> <p>This
section describes the structure of the plugin framework and the changes that
have been made to the framework in v9.5: </p> <ul>
<li id="GUID-399FE2E3-6576-5F98-83A8-70B9F77C65B7"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-3D91570E-8939-557B-8E1E-3A3C5BD27A26">Threads and execution context</xref>, </p> </li>
<li id="GUID-609612CB-E684-5BDA-88FC-16FFB71D70C2"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-71DC7464-0EF0-5F78-816E-24F73F5FCA12">Exclusive access</xref>, </p> </li>
<li id="GUID-665C36D1-DDD3-5DA4-86A3-574DFDC38AFF"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-9C152BE3-9113-5A0C-8EE2-81ADD09BEAD2">Intercepting requests to the ROM drive</xref>, </p> </li>
<li id="GUID-F06D0F56-40AA-5631-9686-BA955E8E263B"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-AA3990F3-52AB-5B14-8ED4-50CCA824AF84">Preventing deadlock</xref>. </p> </li>
</ul> <p>The diagram below shows how plugins fit into the File Server software
stack. </p> <fig id="GUID-EF5AECEC-9CB0-54B0-B6D2-46266B5FF49E">
<image href="GUID-9A4543B3-2A79-5604-AE11-5087507C6755_d0e262222_href.png" placement="inline"/>
</fig> <p> <b>Note</b>: more than one plugin can be loaded into the file server
at the same time. A plugin is not aware of other plugins. </p> <p id="GUID-3D91570E-8939-557B-8E1E-3A3C5BD27A26"><b> Threads and execution context</b> </p> <p>The
Symbian platform File Server has multiple threads. There is a thread for each
drive in use and a main thread that receives the requests from clients and
sends them to the drive threads. Synchronous drives, however, do not have
their own drive thread; requests for these are processed by the main thread.
There is also a separate thread for processing session disconnect requests. </p> <p>Each
plugin also has its own thread for processing requests. Requests are dispatched
to the plugin thread associated with the request's drive before they are dispatched
to the drive thread. This is discussed in more detail in <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 id="GUID-71DC7464-0EF0-5F78-816E-24F73F5FCA12"><b>Exclusive access</b> </p> <p>Previously,
when a client application opens a file for exclusive write access, no other
clients could access the file until the client closed its associated subsession.
This also applied to plugins that needed to modify file data (as they are
also clients of the file server). </p> <p>Symbian platform provides plugins
that are able to perform operations on files and directories irrespective
of the mode in which the file has been opened. </p> <p>Operations are now
able to use the same file handle as the originating request (run in the same
context as the original request) so files opened for exclusive access can
still be written to by a plugin wishing to modify the file. </p> <p id="GUID-9C152BE3-9113-5A0C-8EE2-81ADD09BEAD2"><b>Intercepting ROM drive requests</b> </p> <p>Previously,
plugins could not intercept any requests to the ROM drive (Z) however, there
is a requirement to be able to intercept requests on this drive to enable
secure-load and logging plugins. Requests to drive Z can now be intercepted
by plugins. See the tutorial for <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-89CF85BE-784F-5237-9F78-69D603B650C4">CFsPluginFactory</xref> for more details. </p> <p id="GUID-AA3990F3-52AB-5B14-8ED4-50CCA824AF84"><b>Preventing deadlock</b> </p> <p>The
new framework allows a plugin to have direct access to file data without the
need to issue new file server requests through the <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref>, <xref href="GUID-12AE154F-7741-38C0-ADFE-9784FCF5E516.dita"><apiname>RDir</apiname></xref> and <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref> client
APIs. In the pre-9.5 approach it was possible to reach deadlock if more than
one plugin was present. </p> <p>The diagram below shows two plugins in the
pre v9.5 framework. If both plugins issue new file server requests and if
the plugins are not re-entrant safe this can lead to deadlock in the file
server. </p> <fig id="GUID-01A69E82-BF01-520A-A8C5-927F1ED85E04">
<title> File server deadlock </title>
<image href="GUID-9CC5E096-74FB-59AB-BAB9-A5486B961B7D_d0e262298_href.png" placement="inline"/>
</fig> <p>The framework introduced in v9.5 prevents deadlock by allowing plugins
to issue internal file server requests after intercepting a request by using
the newly introduced <xref href="GUID-3C50CF63-9AF4-3F36-8B8F-3FBB613E1CAC.dita"><apiname>RFilePlugin</apiname></xref>, <xref href="GUID-2E871434-D08F-3275-AC55-260A9A78661A.dita"><apiname>RDirPlugin</apiname></xref> and <xref href="GUID-DE8D8017-6E9C-38CE-A023-98A53CDF7152.dita"><apiname>RFsPlugin</apiname></xref> APIs
and not by using the <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref>, <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> and <xref href="GUID-12AE154F-7741-38C0-ADFE-9784FCF5E516.dita"><apiname>RDir</apiname></xref> APIs.
Internally issued requests are only dispatched to plugins mounted below the
issuing plugin and the appropriate drive thread. </p> <p>The sequence of events
for a typical plugin intercepting a file read request is illustrated below: </p> <fig id="GUID-E366027F-3112-520F-A118-4C048102749E">
<title> Read request intercepted by a plugin
</title>
<image href="GUID-2ABCF233-7DCC-59E2-B075-81E148A1D2AB_d0e262336_href.png" placement="inline"/>
</fig> <p>The classes <xref href="GUID-3C50CF63-9AF4-3F36-8B8F-3FBB613E1CAC.dita"><apiname>RFilePlugin</apiname></xref>, <xref href="GUID-2E871434-D08F-3275-AC55-260A9A78661A.dita"><apiname>RDirPlugin</apiname></xref> and <xref href="GUID-DE8D8017-6E9C-38CE-A023-98A53CDF7152.dita"><apiname>RFsPlugin</apiname></xref> have
been introduced to facilitate plugins with direct access behaviour on file
and directory requests. These classes are analogous to the client-side <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref>, <xref href="GUID-12AE154F-7741-38C0-ADFE-9784FCF5E516.dita"><apiname>RDir</apiname></xref> and <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref> classes and have functions with similar or identical signitures. </p> <p>In
order to perform requests on a file it is necessary to open a sub-session
by calling either <xref href="GUID-EC8FDB25-3DD7-3F1C-9875-0FA9315AE9AC.dita"><apiname>AdoptFromClient()</apiname></xref> or <xref href="GUID-20D0D10F-3401-3F72-8AF6-DC35F6025DC2.dita"><apiname>Open()</apiname></xref>. <codeph>AdoptFromClient()</codeph> is
used in order to open a sub-session with the file associated with the client’s
request. Alternatively the <codeph>Open()</codeph> method can be used to open
either a different file, or the file associated with the client’s request
possibly with a different access mode. </p> <p>More than one file can be opened
at any time by creating multiple instances of <xref href="GUID-3C50CF63-9AF4-3F36-8B8F-3FBB613E1CAC.dita"><apiname>RFilePlugin</apiname></xref>. </p> <p>The
following example shows how to open many files from a plugin during a single
request: </p> <codeblock id="GUID-AFCA6392-2414-591A-98C5-A9FC2C103755" xml:space="preserve">// Define the object
RFilePlugin clientsFile(aRequest);
// Opens the file associated with the intercepted request
Tint r = clientsFile.AdoptFromClient();
User::LeaveIfError(r);
TBuf<20> data;
TInt64 pos = (Tint64)0;
Tint length = 0;
// Read the file
r = clientsFile.Read(pos, data, length);
User::LeaveIfError(r);
// Open a second file
RFilePlugin secondFile(aRequest);
_LIT(KSecondName, ”D:\\myfile.txt”);
r = secondFile.Open(KSecondName(), EFileRead);
User::LeaveIfError(r);
// Read from second file
TBuf<20> data2;
TInt64 pos2 = (Tint64)0;
Tint length2 = 0;
// Read the file
r = secondFile.Read(pos2, data2, length2);
User::LeaveIfError(r);
// Close the files
clientsFile.Close();
secondFile.Close();</codeblock> <p><b>Issuing
an internal file system request</b> </p> <p>An internal request can be marked
as ‘Direct to Drive’. This allows requests that are generated by a plugin
to be dispatched straight to the drive thread bypassing all other plugins
which may be mounted below the plugin that issued the request. After being
processed by the drive thread the request also bypasses the plugins between
the drive thread and the plugin that the Direct to Drive request originated
from. Once returned to the plugin that generated the request, the Direct to
Drive request is complete and any other requests issued from the plugin are
processed by plugins further down the plugin-stack in the normal manner. </p> <p>The
last argument of the <xref href="GUID-3C50CF63-9AF4-3F36-8B8F-3FBB613E1CAC.dita"><apiname>RFilePlugin</apiname></xref> constructor of the classes <xref href="GUID-3C50CF63-9AF4-3F36-8B8F-3FBB613E1CAC.dita"><apiname>RFilePlugin</apiname></xref>, <xref href="GUID-DE8D8017-6E9C-38CE-A023-98A53CDF7152.dita"><apiname>RFsPlugin</apiname></xref> and <xref href="GUID-2E871434-D08F-3275-AC55-260A9A78661A.dita"><apiname>RDirPlugin</apiname></xref> is named <codeph>aDirectToDrive</codeph>. <codeph>aDirectToDrive</codeph> is
a boolean value (<codeph>TBool</codeph>) to indicate that the request is Direct
to Drive. The default value is <codeph>EFalse</codeph> indicating that the
request is interceptable by plugins further down the plugin-stack. </p> </section>
<section id="GUID-6234893D-A1C8-5870-9761-9EA2BD6909F0"><title>Plugin order</title> <p>The
Plugin framework provides support for multiple plugins to be present and active.
Plugins are arranged in a stack. Plugins intercept requests in the order they
are arranged in the stack with the plugin at the top of the stack (at the
smallest numerical absolute position) getting the first intercept. The order
of plugins in the stack is therefore crucial to the correct operation of the
file server when more than one plugin is active, especially when the plugins
are modifier plugins (i.e when both modify the data or parameters of the requests). </p> <p>If
two plugins are active and one of those is a virus scanner, for the virus
scanner to operate correctly it must be the first plugin to intercept requests.
This is so that the virus scanner can have first refusal to block any requests
for files which it believes may not be safe for opening. If there is another
plugin higher in the stack then this plugin could send Direct To Drive requests,
for example, and would significantly reduce the virus scanning ability of
the virus scanning plugin. </p> <p>Two mechanisms are provided that allow
plugin authors to control the position of their plugins in the plugin stack
these are Absolute position and Unique position. </p> <p id="GUID-5C258D67-C324-5FA4-894A-88532F925EFF"><b>Absolute position </b> </p> <p>Plugins
can be inserted into the stack by specifying an absolute position at mount
time. This absolute position is the index in the internal array of plugins
in which the plugin should be mounted. The plugin at position 0 being the
first plugin to be able to intercept requests. </p> <fig id="GUID-41EB2F58-407F-52C7-A40C-0E3858CF718B">
<title> Plugin stack showing absolute positions
</title>
<image href="GUID-64BDD1DA-6B93-5F45-8CBD-7DBAF92CC4C7_d0e262462_href.png" placement="inline"/>
</fig> <p>The absolute position method is more appropriate for mounting plugins
that operate regardless of their position in the plugin stack or when all
of the plugins for a device are known and installed when manufactured. This
method does not suit plugins that are added after manufacture where the dependencies
of other available plugins is not known. If this is the case use the unique
position method described below. </p> <p id="GUID-90FC1AD9-D709-5105-A445-0AA3D7BA85B7"><b>Unique position</b> </p> <p>Plugins
can be ordered according to a unique position stored within the plugin. Unique
position identifiers are defined by the manufacturer during the software validation/signing
process. Unique positions are defined in the derived <xref href="GUID-8A3B2A79-05A6-3BD7-AEA9-02435476F45E.dita"><apiname>CFsPluginFactory</apiname></xref> class.
See the description in <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-89CF85BE-784F-5237-9F78-69D603B650C4">CFsPluginFactory</xref>. </p> <p>The position value specifies the category and position of the plugin: </p> <table id="GUID-22362455-13BE-5A26-8750-A94E79941EF3">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <b>plugin Type</b> </p> </entry>
<entry><p> <b>Unique Position Range</b> </p> </entry>
</row>
<row>
<entry><p>File Observers </p> </entry>
<entry><p> <codeph>0x20000000 - 0x2FFFFFFF</codeph> </p> </entry>
</row>
<row>
<entry><p>File Modifiers </p> </entry>
<entry><p> <codeph>0x40000000 - 0x4FFFFFFF</codeph> </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>File Observers do not modify data so they are allocated a lower
range of numbers placing them at the top of the plugin stack. File Modifiers
modify the data stream so they are allocated a higher range placing them lower
down the plugin stack. </p> <p> <b>Note</b>: a plugin has a unique position
then do not specify an <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-5C258D67-C324-5FA4-894A-88532F925EFF">absolute
position</xref> when mounting it, otherwise the error <codeph>KErrNotSupported</codeph> is
returned. </p> </section>
<section id="GUID-DB21C0FD-46F8-5E4F-9288-69AE8609482B"><title>Drive selection</title> <p>A
File Server Plugin can intercept requests for a specific drive or for all
drives. A plugin that intercepts requests for all drives must filter requests
that are not appropriate for some drives. Requests can be filtered within
an overridden <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-97427151-C6E4-5FE4-8197-0D7C58EDB29F">CFsPlugin::Deliver()</xref> function. </p> <p>There are two ways to specify a drive: </p> <ul>
<li id="GUID-296E3A2E-5985-5E4B-96A2-D247D1FAA07C"><p>When the plugin is mounted.
See <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-BED54BD9-2F3F-588E-854B-C28745C8F30A">mounting
a plugin</xref>. </p> </li>
<li id="GUID-080CD9C3-2BEA-5209-974A-910606EBF22A"><p>At run-time through
the use of <xref href="GUID-8A3B2A79-05A6-3BD7-AEA9-02435476F45E.dita#GUID-8A3B2A79-05A6-3BD7-AEA9-02435476F45E/GUID-45A67073-5EF4-3966-A2FD-555B56C89284"><apiname>CFsPluginFactory::iSupportedDrives</apiname></xref>. See the
tutorial for <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-89CF85BE-784F-5237-9F78-69D603B650C4">CFsPluginFactory</xref>. </p> </li>
</ul> <p>If the drive is not specified then <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita#GUID-E263C747-946F-35AA-9F1D-41833BD350FC/GUID-61640192-646E-33DA-B186-5EE63B07A998"><apiname>RFs::MountPlugin()</apiname></xref> attempts
to mount the plugin for all drives. If this behaviour is not supported by
the plugin <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref> is returned. </p> </section>
<section id="GUID-50F7CD3A-A051-5498-8886-B4501523FD1D"><title> Interception
of file server requests</title> <p>After a file server request has been initialised
by the main file server thread it can be intercepted by a plugin. There are
two types of intercept: </p> <ul>
<li id="GUID-288866F8-ABE5-5569-A70C-2C86B4F073B9"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-05F613B8-FF66-54B6-8D49-2BF92914E54E">pre-operation intercepts</xref>, </p> </li>
<li id="GUID-E876E576-1E94-5F06-8305-22D620A82B6F"><p> <xref href="GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita#GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6/GUID-59FD1CED-5A32-5F6E-A256-821A2783D065">post-operation intercepts</xref>. </p> </li>
</ul> <p>Plugins can register for pre-intercepts, for post-intercepts or for
both pre and post-intercepts. </p> <p id="GUID-05F613B8-FF66-54B6-8D49-2BF92914E54E"><b>Pre-operation</b> </p> <p>Pre-operation
intercepts occur before the drive associated with a request processes it.
In a file write request for example, the pre-intercept operations occur before
data has been written to the file. Requests are passed down the plugin-stack
from the file server towards the drive thread. </p> <p>When the main file
server thread has initialised a request, the request is dispatched to the
highest plugin in the stack. This plugin must have been mounted on the requested
drive and registered to pre-intercept this type of request. See <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-BED54BD9-2F3F-588E-854B-C28745C8F30A">mounting a plugin</xref>. The request is dispatched by calling the plugin's <xref href="GUID-BC0DB991-EF52-3344-8E6A-F8060B75A189.dita#GUID-BC0DB991-EF52-3344-8E6A-F8060B75A189/GUID-2EACA8A8-D569-3D6A-9383-451587A65839"><apiname>CFsPlugin::Deliver()</apiname></xref> function. </p> <p>The <codeph>Deliver()</codeph> function runs in the context of the previous calling thread,
this can be the main file server thread or a plugin thread. Override <codeph>CFsPlugin::Deliver()</codeph> to
filter the request. If the <codeph>Deliver()</codeph> function has not been
overridden then the request is dispatched for asynchronous processing by calling
the base class <codeph>Deliver()</codeph>. See the <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-97427151-C6E4-5FE4-8197-0D7C58EDB29F">CFsPlugin::Deliver()</xref> tutorial section. </p> <p id="GUID-59FD1CED-5A32-5F6E-A256-821A2783D065"><b>Post operation</b> </p> <p>Post-operation
intercepts occur after the drive associated with a request has processed it.
In a file write request for example, the post-intercept occurs after data
has been written to the file. Requests are passed from the drive thread back
up the stack towards the client. </p> <p>When the drive thread has finished
processing a request it dispatches it to the plugin lowest in the stack by
calling the plugin's <xref href="GUID-C6F20230-3D6C-3392-B040-CF627534B930.dita"><apiname>Deliver()</apiname></xref> function. </p> <p><b> Filtering requests internally</b> </p> <p>The <xref href="GUID-F1B37142-1EEF-3777-82B1-303982B888EC.dita#GUID-F1B37142-1EEF-3777-82B1-303982B888EC/GUID-8EBEAD17-B03C-3DBA-9A47-0F7DB07785F9"><apiname>CFSPlugin::Deliver()</apiname></xref> function
filters the request and decides what kind of action is neccessary in terms
of the flow of the request through the plugin stack: </p> <ul>
<li id="GUID-3E8CAD7B-BE13-531E-A387-432F4CD463C9"><p> <xref href="GUID-1E025D93-3D66-3E88-830D-CBB3A471A777.dita"><apiname>KPluginMessageForward</apiname></xref> is
returned if the intercept is pre-operation. The request is passed to the next
plugin down the stack or to the drive thread if there are no more plugins. </p> </li>
<li id="GUID-1FFEFFF4-3D5F-590F-8884-CA27B2B5B916"><p> <xref href="GUID-81C5F6A1-3FCA-33E5-99C6-7901D41BCBDE.dita"><apiname>KPluginMessageComplete</apiname></xref> is
returned if the intercept is post-operation. The request is passed to the
next plugin up the stack or if there are no more plugins to process the request
it is passed to the main file server thread. </p> </li>
</ul> <p>If the request requires processing by the plugin then the plugin's <codeph>Deliver()</codeph> function
calls the base class <codeph>Deliver()</codeph> function and the request is
dispatched to the plugin's thread for asynchronous processing. </p> <p>Asynchronous
processing is carried out in the plugin's <xref href="GUID-8EF10689-68B7-391B-AD5C-4F51780165FF.dita"><apiname>DoRequestL()</apiname></xref> function.
A plugin can only have a single <codeph>DoRequestL()</codeph> function which
must handle both pre and post-intercepts. Plugin authors can use the <xref href="GUID-06E787C2-FAC1-36D2-9C64-11BDA1B656F1.dita"><apiname>IsPostOperation()</apiname></xref> function
of the utility class, <xref href="GUID-A814151C-8AEC-3E16-8691-33174B64E36F.dita"><apiname>TFsPluginRequest</apiname></xref> to indicate whether
the <codeph>DoRequestL()</codeph> is processing a request as a pre-intercept
or post-intercept. See the description of <xref href="GUID-00764271-AD6B-5F41-AF72-843107EBF95F.dita#GUID-00764271-AD6B-5F41-AF72-843107EBF95F/GUID-14773530-7C15-52E2-A542-72A0B2163461">TFsPluginRequest</xref>. </p> <p>Once the asynchronous processing is complete the <codeph>DoRequestL()</codeph> function
returns <codeph>KErrNone</codeph> and the request is passed to the next plugin
down the stack by calling its <xref href="GUID-C6F20230-3D6C-3392-B040-CF627534B930.dita"><apiname>Deliver()</apiname></xref> function. If there
are no lower plugins then the request is passed to the appropriate drive thread
for processing. </p> <p>If the plugin intercepts a request in pre-operation
and wants to complete the request on behalf of the client then the plugin
can return <xref href="GUID-DCECEF73-9C33-3C14-951D-E75D89B21FBA.dita"><apiname>KErrCompletion</apiname></xref> to indicate that the request
has been completed and that the request is now in post operation mode. The
flow will then proceed to any previous plugins if mounted or directly back
to the client otherwise. <xref href="GUID-DCECEF73-9C33-3C14-951D-E75D89B21FBA.dita"><apiname>KErrCompletion</apiname></xref> prevents any further
plugins further down the stack from intercepting the request. </p> <p>When
a plugin intercepts file read or file write and does an early completion (i.e.
returns <xref href="GUID-DCECEF73-9C33-3C14-951D-E75D89B21FBA.dita"><apiname>KErrCompletion</apiname></xref> in pre-intercept) then the plugin
author should call <xref href="GUID-A814151C-8AEC-3E16-8691-33174B64E36F.dita#GUID-A814151C-8AEC-3E16-8691-33174B64E36F/GUID-149E1448-63AA-3F08-A3A2-606D240A8927"><apiname>TFsPluginRequest::SetSharePos()</apiname></xref> to allow
share position to be updated after early read/write completion. </p> </section>
<section id="GUID-0B7B373D-41ED-5C91-ACC4-393A8669815A"><title>Security</title> <p>File
server plugins are implemented as libraries that are loaded into the file
server process at runtime. Therefore, plugins must have the same <xref href="GUID-4BFEDD79-9502-526A-BA7B-97550A6F0601.dita">platform
security</xref> capabilities as the file server process, these are <xref href="GUID-2A022229-C333-3B0A-99A5-13CA0710025D.dita"><apiname>TCB</apiname></xref>, <xref href="GUID-E5C21B79-529B-397E-8A22-63612CA52869.dita"><apiname>ProtServ</apiname></xref>, <xref href="GUID-8DC76E7B-9EB3-3848-AD8D-3D519388A504.dita"><apiname>DiskAdmin</apiname></xref>, <xref href="GUID-ECCA7246-B2BA-3261-95C9-9E72C6EC51D4.dita"><apiname>AllFiles</apiname></xref>, <xref href="GUID-93881606-AA56-385F-A958-3957142BEFE3.dita"><apiname>PowerMgmt</apiname></xref> and <xref href="GUID-616F0C5B-D2C1-39D8-9BFC-53A2AEC7C850.dita"><apiname>CommDD</apiname></xref>. </p> <p>Any
user side process that wishes to load and mount plugins must have the <codeph>DiskAdmin</codeph> capability. </p> </section>
</conbody></concept>