RealServer uses file system plug-ins to access the files it serves. Each file system plug-in provides access to a different type of data storage mechanism, such as the machine's local disks or a database. On each file request, a file system plug-in creates a file object that components such as file format plug-ins use to access the requested file's data. These system-standard file objects thereby create a virtual file system for accessing file data without regard to data location or storage format.
RealServer ships with a plug-in for accessing files on its local disks. It also includes an HTTP plug-in for accessing files on a Web server and a broadcast plug-in for streaming files from a live source. If you need to access data from a source not accessible through these plug-ins, you need to build a file system plug-in or a broadcast plug-in that handles standard file operations for that data source. You need to write a file system plug-in, for example, to stream files stored in a database.
![]() |
Additional Information |
---|
See "Chapter 2: SDK Organization" for a list of plug-ins included with the system. Before you begin building, read the design considerations described in "Designing a Plug-In". |
RealSystem clients also use file system plug-ins to access files locally through their Open File... commands. Clients ship with plug-ins for accessing data on their local disks as well as on HTTP servers. They typically do not need to have other file system plug-ins installed. Because RealSystem makes file handling identical for server and clients, however, any file system plug-in developed for RealServer will also work on clients.
The following actions occur when RealServer receives a request for a file:
FSMount
parameter, which pairs mount points to file system plug-ins, RealServer determines which file system plug-in to use.
![]() |
Additional Information |
---|
See "FSMount Parameter" for information on how RealServer handles multiple plug-ins for the same mount point. |
A file system plug-in implements the following interfaces:
IRMAPlugin
. Header file: rmaplugn.h
. Every plug-in implements this interface, which RealSystem uses to determine the plug-in's characteristics.
IRMAFileSystemObject.
Header file: rmafiles.h
. A file system plug-in must implement this interface, which provides the basic methods that RealServer uses to instruct it to create file objects.
IRMAPendingStatus.
Header file: rmapends.h
. The file system plug-in can implement this interface to provide the RealSystem client with the status of its pending operations.
File objects created by file system plug-ins typically implement the following interfaces:
IRMAFileObject
. Header file: rmafiles.h
. All file objects implement this interface, which gives the system read and write access to a single file or resource. The response interface implemented by file format plug-ins is IRMAFileResponse
.
IRMAFileExists
. Header file: rmafiles.h
. The file object must implement this interface, which RealServer uses to check if the requested file exists on the file system. The response interface is IRMAFileExistsResponse
.
IRMAFileMimeMapper
. Header file: rmafiles.h
. RealServer uses this optional interface to request the MIME type of a file. The response interface is IRMAFileMimeMapperResponse
.
IRMAFileStat
. Header file: rmafiles.h
. This optional interface provides information about a specific file, such as file length and creation time. The response interface is IRMAFileStatResponse
.
IRMAGetFileFromSamePool
. Header file: rmafiles.h
. This interface instructs the file object to create a relative file object. The response interface is IRMAGetFileFromSamePoolResponse
.
IRMARequestHandler
. Header file: rmafiles.h
. If the file object implements this interface, it can access the request object and modify the request response headers.
IRMAFileAuthenticator
. Header file: rmafiles.h
. The file object implements this interface to become associated with an authenticator object.
IRMAAuthenticatorResponse
. Header file: rmaauth.h
. The file object implements this interface to receive notice that an authentication request succeeded or failed.
The following sections explain how RealServer, a file system plug-in, and a file format plug-in use the RealSystem interfaces to create and use file objects. The sample files included with this SDK illustrate many of these features. Refer to the RealSystem SDK header files for more information on function variables and return values.
When RealSystem starts up, it loads each file system plug-in:
RMACreateInstance
to create a new instance of a plug-in. RealServer calls this method at start-up and each time it receives a request for a file handled by the plug-in.
![]() |
Additional Information |
---|
See "Creating a Plug-In Instance" for more on this method. |
IRMAPlugin::GetPluginInfo
, which returns descriptive information about the plug-in, including its copyright and "more information" URL. Set the bLoadMultiple
attribute to TRUE
to open multiple instances of the plug-in in separate processes. Set it to FALSE
to open all instances in the same process.
IRMAFileSystemObject::GetFileSystemInfo
, which returns functional information about the plug-in:
pShortName
provides the plug-in short name, which is listed in RealServer's FSMount
configuration parameter. RealServer uses this short name to identify which file system plug-in to use for an URL request.
pProtocol
lists the local file access protocol supported by the plug-in. It is used only by the RealSystem client to select a plug-in to use for local files. In the URL file://myfile.txt, for example, the protocol is file
. RealServer plug-ins do not need to include this parameter.
When RealServer receives a request for a file, it initializes the file system plug-in as follows (see "File Handling Overview"):
IRMAPlugin::InitPlugin
method, passing it a pointer to the system context. The plug-in should use this context pointer to store a reference to IRMACommonClassFactory
so that it can later create RealSystem objects.
IRMAFileSystemObject::InitFileSystem
, in which the plug-in should perform any initialization procedures. This method passes the plug-in a pointer to an IRMAValues
interface that contains the plug-in's FSMount
parameters (except for the short name). For example, the values interface pairs the name MountPoint
with a pointer to an IRMABuffer
interface containing the plug-in's mount point value, and BasePath
with a pointer to a buffer containing its base path value.
![]() |
Note |
---|
The file system plug-in does not have a response interface through which it indicates that its initialization is complete. Only the file object uses a response interface. |
The file system plug-in creates and initializes a file object:
IRMAFileSystemObject::CreateFile
method.
IRMAFileSystemObject::CreateFile
so as to create a new IRMAFileObject
. The create method then passes RealServer a pointer to the object. The system then "owns" the object and is responsible for releasing it.
IRMAFileExists::DoesExist
, passing the file object the path from the URL request and a pointer to the response object (RealServer). The file object converts the path as necessary to find the file on its file system. It returns a Boolean with IRMAFileExistsResponse::DoesExistDone
.
IRMAFileExistsResponse::DoesExistDone
returns FALSE
, RealServer releases the file object and closes the plug-in. On TRUE
, RealServer calls IRMAFileMimeMapper::FindMimeType
to determine the file's MIME type. The method passes the file object a pointer to the response object (RealServer).
IRMAFileMimeMapperResponse::MimeTypeFound
method, returning a status code and the file's MIME type. If the file object does not implement this interface or cannot determine the MIME type, RealServer uses information it received from its file format plug-ins at start-up to cross-reference the file extension with the MIME type.
![]() |
Additional Information |
---|
See "Status Codes". |
IRMAFileObject::Init
to pass the file object a pointer to the file response object and flags to indicate that it is opening the file as read/write/binary (see rmafiles.h
for the flag definitions).
![]() |
Note |
---|
Within this method, the file object should check the file validity by opening the file. If file authentication is implemented, the file object performs authentication during initialization. See "Chapter 19: Authentication". |
IRMAFileResponse::InitDone
.
![]() |
Additional Information |
---|
See "Interacting with a File Object" for information on how that plug-in uses the file object to get file data. The section "Modifying the Response Headers" explains how to modify the request response headers to send data to the client. See also "Status Codes". |
As described in "Getting Relative File Objects", file format plug-ins can use relative file objects to access files related to a requested file, or open multiple file objects for a single file. To support this feature, file objects must implement IRMAGetFileFromSamePool
:
IRMAGetFileFromSamePool
on the file object to indicate that it needs a new file object and to identify itself as the response object.
IRMAFileSystemObject::CreateFile
on the file system plug-in.
IRMAGetFileFromSamePoolResponse::FileObjectReady
, the original file object passes the file system manager object a status code and a pointer to the new file object.
![]() |
Additional Information |
---|
See "Status Codes". |
Before destroying a file object, the component using the file object calls IRMAFileObject::Close
. This routine should release all resources associated with the file object. RealServer calls IUnknown::Release
when it finishes with a file system plug-in.
The RealSystem SDK includes source code for a file system plug-in based on the standard file system plug-in that ships with RealServer. Use these sample files to learn basic concepts about RealSystem file handling. You can also use the samples as templates for building your own file system plug-in:
/samples/intro/filesys1/filesys1.cpp
This sample file provides the basics for creating the file system plug-in.
/samples/intro/filesys1/fileobj1.cpp
This sample file creates the basic file objects that give system components access to file data.
Carry out the following steps to modify the sample files:
zm_pDescription
, zm_pCopyright
, zm_pMoreInfoURL
, zm_pShortName
, and zm_pProtocol
.
![]() |
Additional Information |
---|
See "Compiling a Plug-In". |