This document contains guidelines for writing a file server plugin for Symbian platform.
This document is split into three sections:
A file server plug-in is made up of at least two classes:
a factory class derived from the CFspluginFactory base class,
a plug-in class derived from the CFsplugin base class.
Each plug-in must register to intercept messages. To make internal requests call the functions RFilePlugin, RDirPlugin or RFsPlugin.
Each plug-in DLL must export a plug-in entry point function with the prototype:
CFsPluginFactory* CreateFileSystem();
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:
extern "C" { EXPORT_C CFsPluginFactory* CreateFileSystem() { return(new CMyPluginFactory()); } }
The CFsPluginFactory base class follows the standard factory pattern as used in other file server DLLs. CFsPluginFactory creates CFsPlugin derived objects.
plug-in authors must provide implementations of the pure virtual functions:
Install()
This function is called by the file server in response to a call to RFs::AddPlugin() and installs the plug-in factory.
This function must set the name of the plug-in factory with a call to CObject::SetName(). The plug-in name is used when mounting, dismounting and unloading plug-ins. Optionally, RFs::AddPlugin() can perform other plugin specific initialization, for example setting iSupportedDrives to indicate which drives the plugin will operate on, as required by the plugin factory. See drive selection.
NewPluginL()
This is called by the file server in response to a call to RFs::MountPlugin(), this function creates a new CFsPlugin derived object and returns a pointer to it.
UniquePosition()
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 unique position.
Remove() (overriding this virtual function is optional as it is not a pure virtual function)
This is called just before the plugin factory object is destroyed and allows any clean up to be carried out.
The default implementation just returns KErrNone. Implementations should return an error code on error detection.
The CFsPluginfactory base class also has the following member variables:
iSupportedDrives
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.
Plugin authors should use the the SetSupportedDrives() API in order to correctly set up which drives their plugin should be mounted on. Set the drive number to KPluginSupportAllDrives to indicate that the plugin needs to be mounted on all drives.
If you are using Symbian platform prior to version 9.5, iSupportedDrives is assigned to by plugin writers directly. However, this is now discouraged in favour of using SetSupportedDrives.
iUniquePos
This member stores the unique position identifier. If this member is used then plugin authors should implement the UniquePosition() function to return the variable.
An example skeleton implementation of a CFsPluginFactory derived class is as follows:
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; }
This is the base class for the file server plugin and is defined in f32plugin.h.
Plugins must register to intercept particular types of file server requests. See Registering a plugin to intercept messages.
Plugin authors need to provide an implementation of the pure virtual method DoRequestL() and can optionally override the virtual functions:
SessionDisconnect() - virtual,
InitialiseL() - virtual,
Deliver() - virtual,
NewPluginConnL() - virtual,
DoRequestL() - pure virtual,
SessionDisconnect() is called by the file server when a file server session is disconnected.
The default implementation just returns KErrNone. Overriding this function allows plugins to free up any resources prior to the outstanding operations being cancelled.
The default implementation of InitialiseL() does nothing. Override this implementation to perform a plugin specific initialisation, for example registering intercepts. If the plugin cannot be initialised this function must leave with a suitable error code.
Deliver() 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.
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 RPlugin session) are delivered to the front of the queue. See Communicating with plugins.
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.
Deliver() 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.
If KErrNone 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 DoRequestL().
KPluginMessageForward 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 DoRequestL() function). This is used for pre-intercepts.
KPluginMessageComplete 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 DoRequestL() function). This is used for post-intercepts.
The function NewPluginConnL() is the default implementation and it returns KErrNotSupported. Override this implementation to create a CFsPluginConn derived object to enable direct communication between a client application and a plugin using RPlugin. See Communicating with plugins.
DoRequestL() 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. DoRequestL() is called in the context of the plugin’s main thread and must be implemented to intercept file server requests in this context.
The current request must have finished all processing before DoRequestL() has completed. If a plugin has multiple threads and the request is handled in a thread other than the main thread then the DoRequestL() function must be blocked until the request has been processed. This is because when DoRequestL() 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.
Errors returned by this function are propagated back to the client. If this function leaves then the client thread panics. Note: 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.
KErrCompletion 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.
When a plugin intercepts a file read or file write request and does an early completion (i.e. returns KErrCompletion in pre-intercept) then the plugin author should call TFsPluginRequest::SetSharePos() to allow share position to be updated after early read/write completion.
The TFsPluginRequest class encapsulates the intercepted file server request and is passed as a reference to the plugin's DoRequestL() function. TFsPluginRequest provides APIs that extract request specific information such as:
DriveNumber() - returns the target drive number. The drive number is in the range of zero to 25, which corresponds to drive letters A to Z,
Function() - the type of request as defined in TFsMessage,
IsPostOperation() - returns ETrue or EFalse to indicate if the request being intercepted is in post-intercept mode (ETrue) or pre-intercept.
TFsPluginRequest acts as a utility class for plugins. This class has two main functions TFsPluginRequest::Read() and TFsPluginRequest::Write(), which allow a plugin to read from and write to the message arguments of a request.
TFsPluginRequest::Read() has various overloads for TInt, TUint, Tint64 and descriptor data types, all of which take as their first argument a TF32ArgType object.
The TF32ArgType is an enumeration which defines the type of data that is requested. For example, EPosition, ELength, EData for getting the position, length and data arguments from the request. TF32ArgType is defined as follows:
enum TF32ArgType { EPosition, ELength, EData, ESize, EName, ENewName, EEntry, ETime, ESetAtt, EClearAtt, EMode, EAtt, EAttMask, EUid, EEntryArray, ENewPosition, };
TFsPluginRequest::Write() only has two overloads, both of these take descriptor types and the argument TF32ArgType. Many functions do not use descriptor types, it will be necessary to package data for these inside a descriptor.
The following provides an example of how to do this for Entry:
TPckgC<TEntry> entryPckg(entry); err = aRequest.Write(EEntry, entryPckg);
Sending internal requests to the file server
The classes RFilePlugin, RDirPlugin and RFsPlugin, defined in F32Plugin.h, 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 (RFile, RDir and RFs) counter-parts.
Before a plugin can perform any requests on a file it must first either perform an Open() or AdoptFromClient(). When an AdoptFromClient() is performed the RFilePlugin instance opens the file associated with the client request. Open() 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.
RFilePlugin has the following public functions:
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); ...
Registering a plugin to intercept messages
The base class CFsPlugin, has functions that allow a plugin to register to intercept specific types of file server request. This is explained in more detail under Interception of file server requests.
RegisterIntercept()
The function RegisterIntercept() registers a plugin to intercept a specified TFsMessage. The second parameter of RegisterIntercept() 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 TInterceptAtts.
UnregisterIntercept()
Un-register an intercept with UnregisterIntercept(). UnregisterIntercept() takes TFsMessage, which is the ID of the message and TInterceptAtts, which is the type of intercept that you no longer wish to intercept.
A plugin must be loaded and mounted before it can intercept requests.
Loading and unloading a plugin
Before a plugin can be used by the file server the library (.PXT) that contains the plugin needs to be loaded into the file server process by the loader. Do this using the RFs::AddPlugin() function defined in f32file.h.
AddPlugin() can be called by any user side application with the relevant platform security capabilities.
Unload a plugin using the RFs::RemovePlugin() function also defined in f32file.h.
Note: Refer to the device manufacturer if you want to load plugins automatically at system startup time.
Mounting and unmounting a plugin
File Server plugins are mounted using the RFs::MountPlugin() function defined in f32file.h. The plug in must have already been loaded using RFs::AddPlugin().
There are various overloads of the MountPlugin() function. Those functions which do not take a drive parameter are mounted using KPluginAutoAttach.
Call RFs::DismountPlugin() to dismount the file server plugin. Dismount the plugin when you no longer need it to intercept file server requests.
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.
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. Note: DiskAdmin capabilities are required in order to load a plugin. See platform security capabilities.
Data transfer
The class CFsPluginConnRequest is an information container for asynchronous requests that the client application wants performed. CFsPluginConnRequest also provides functions that enable data to be transferred between the plugin and the application. The following examples show how to use CFsPluginConnRequest.
A user-side application uses a class derived from RPlugin to access the plugin. See plugin side. The RPlugin class (defined in f32file.h) provides various functions that must be overridden. The functions DoControl(), DoRequest() and DoCancel() 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.
An RPlugin session is opened by passing in the unique position 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 NewPluginConnL() function. The plugin must certify that it is expecting the client application before creating the server side connection object.
Below is a basic example of an RPlugin derived class:
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);
}
This is used in the following way:
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();
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..
}
This is used in the following way:
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();
This is the plugin side of the communication. This must be implemented in order to communicate with the application side class RPlugin above. The plugin side is a class derived from the CFsPluginConn class. The plugin’s NewPluginConnL() function is called from the file server when RPlugin::Open() is called by the client.
Synchronous (DoControl()) and asynchronous (DoRequest()) requests sent from the RPlugin class are routed directly to the associated plugin's CFsPluginConn derived class. The following code shows a basic implementation:
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 }