previous next

Chapter 7: File System Plug-In

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.

File Handling Overview

The following actions occur when RealServer receives a request for a file:

  1. RealServer parses the request URL for the mount point, which is the directory or directory alias preceding the file name.

  2. Based on its 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.

  3. RealServer initializes the selected file system plug-in, creates a file object, and checks that the file exists on that file system.

  4. RealServer uses the file object to determine the file's MIME type. If it cannot determine the MIME type through the interfaces, it uses information it received from its file format plug-ins at start-up to cross-reference the file extension with the MIME type.

  5. Based on the file MIME type, RealServer loads the appropriate file format plug-in and passes it the file object for the requested file.

  6. The file format plug-in then initializes and uses the file object to retrieve file data. If file authentication is used, the file object verifies user access for the file during its initialization stage.

Interfaces

A file system plug-in implements the following interfaces:

File objects created by file system plug-ins typically implement the following interfaces:

Coding the Plug-In

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.

Note
The order of function calls listed in the following sections provides a generalized explanation and is for illustrative purposes only. Because RealSystem is asynchronous, your plug-in must be able to handle any call made to it while it is processing data or waiting for a response from another object. Do not code your plug-in so that it expects a specific sequence of events to occur as it interacts with RealSystem.

Starting Up

When RealSystem starts up, it loads each file system plug-in:

  1. RealServer calls 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.

  2. RealServer calls 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.

  3. RealServer calls IRMAFileSystemObject::GetFileSystemInfo, which returns functional information about the plug-in:

Initializing

When RealServer receives a request for a file, it initializes the file system plug-in as follows (see "File Handling Overview"):

  1. RealServer calls the file system plug-in's 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.

  2. RealServer calls 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.

Creating a File Object

The file system plug-in creates and initializes a file object:

  1. RealServer calls the plug-in's IRMAFileSystemObject::CreateFile method.

  2. The plug-in implements 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.

  3. RealServer calls 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.

  4. If 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).

  5. The file object calls 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".

  6. Based on the requested file's MIME type, RealServer loads the appropriate file format plug-in and passes it a ponter to the file object.

  7. The file format plug-in calls 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".

  8. The file object passes the file format plug-in a status code through 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".

Supporting Relative File Access

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:

  1. A file system manager object created by the file format plug-in calls IRMAGetFileFromSamePool on the file object to indicate that it needs a new file object and to identify itself as the response object.

  2. The file object creates a new, uninitialized file object. It can do this by calling IRMAFileSystemObject::CreateFile on the file system plug-in.

  3. Using 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".

  4. The file format plug-in and file system manager object then initialize and use the new file object as needed.

Closing

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.

Modifying the File System Plug-in Sample Code

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:

Carry out the following steps to modify the sample files:

  1. Copy the source code from the samples directory to a working directory.

  2. Change the file names and class names to match your file system name.

  3. In filesys1.cpp, change the plug-in description, copyright, more information URL, file system short name, and protocol stored in zm_pDescription, zm_pCopyright, zm_pMoreInfoURL, zm_pShortName, and zm_pProtocol.

  4. By following the comments, modify the sample methods to handle file access as necessary for your platform and data source.

  5. Compile, debug, and test your plug-in.

    Additional Information
    See "Compiling a Plug-In".


Copyright © 2000 RealNetworks
For technical support, please contact supportsdk@real.com.
This file last updated on 05/17/00 at 13:11:26.
previous next