Developing a File plug-in

Last updated on Apr 27, 2021

File plug-in overview

The File plug‑in gives you control over where and how the server reads content from the file system. The plug‑in provides an interface between the operating system’s file I/O mechanism and the server. You can configure or modify the sample file to create an alternative to the default operating-system-based file system I/O.

Previous versions of the server supported synchronous access to the file system. Each request for a read operation on a file had to wait for the previous requests in the queue to be completed. The File plug‑in supports asynchronous access, making it easier to implement network-based file I/O.

You can code the File plug‑in to do the following:

Grab files from a remote location over HTTP and serve them to clients through the core server process to off-load content management duties.
Remap files to a different physical location.
Retrieve external SWF files for verification.

Note:

The File plug‑in works with stream files and SWF files.

If a custom File plug‑in is not present or is inactive, the server uses the standard operating system file system for backwards compatibility. You can only use one File plug‑in.

Responding to server calls

The File plug‑in is asynchronous—when the server calls the plug‑in, the plug‑in doesn’t respond immediately. The server calls the plug‑in, and the plug‑in calls the server back on the response interface.

When the server calls a function on the plug‑in, the plug‑in interface can return an error code (-1) indicating that the operation failed. If the function returns an error, the plug‑in should not call the server back.

If a call to the plug‑in returns successfully (returns 0), the plug‑in should call the server back and pass the context received from the server.

The close() and remove() calls are an exception to this rule. When the server calls the close() and remove() functions on the plug‑in, the server is not interested in the response. To free resources associated with the request before the callback occurs, the server sometimes passes NULL as the pCtx pointer. If the context is NULL, then it is not necessary to call the server back. If the plug‑in calls the server back with the NULL context, the server ignores it.

Retrieving external SWF files for verification

Verifying SWF files ensures that only legitimate applications can access this instance of Adobe Media Server. This feature prevents third parties from creating their own applications that attempt to stream your resources.

In Content Distribution Networks, the SWF files that you want to verify reside in an external content repository or on another server in a cluster. You can use the File plug‑in to retrieve SWF files that are stored in external locations so that the server can verify them. By using the File plug‑in, SWF files do not have to reside locally on Adobe Media Server. Developers can update SWF files frequently without impacting the server. Using the File plug‑in facilitates and simplifies content management by developers.

When using the File plug‑in, the server verifies SWF files at the file level, regardless of the application. You cannot enable SWF verification through the File plug‑in on a per-application basis.

Note:

The ability to retrieve SWF files using the File plug‑in is only available in version 1.0 of the plug‑in (Adobe Media Server 3.5 or later).

To verify SWF files through the File plug‑in, follow this workflow:

Enable SWF verification in Application.xml.
Enable SWF verification in Server.xml.
Implement the File plug‑in.

Enable SWF verification in Application.xml

In an XML editor, open Application.xml.
Set the enabled attribute in the SWFVerification tag to true.
```
<SWFVerification enabled="true">
```
This tag enables verification for all applications, regardless of whether this file is the vhost-level or application-level XML file.
Leave the SWFFolder tag empty. By doing so, the server passes the default SWFFolder value to the plug‑in. The default value is the application’s folder appended with SWFs. For example, applications/application_name/SWFs.

Your File plug‑in must redirect this value to your external content repository.
(optional) Configure additional verification tags.

Enable SWF verification in Server.xml

In an XML editor, open Server.xml.

In the Plugins tag, set the enabled attribute in the FilePlugin tag to true:

<Plugins> 
    <FilePlugin enabled="true"> 
        <Content type="Streams">true</Content> 
        <Content type="SWF">false</Content> 
    </FilePlugin> 
</Plugins>

To enable verification of SWF files, set the <Content type="SWF"> attribute to true.
(optional) To configure global verification, leave the SWFFolder tag empty. By doing so, the server passes the default SWFFolder value to the plug‑in. Your File plug‑in must redirect this value to your external content repository.

With global verification, you can configure verification for a group of SWF files that are common to all applications.
(optional) Configure additional verification settings: DirLevelSWFScan, MaxNumberofRequests, and any desired user-defined keys in the UserDefined element. See the XML reference in the Configuration and Administration Guide.

Implement the File plug-in

The File plug‑in can open directories or files in external locations and pass a list of directories and files to the server. The File plug‑in does not contain a specific attribute to distinguish stream files from SWF files. The server performs verification like it does when SWF files are stored on the server.

See the File plug‑in sample included with the server. Some highlights of the code are presented here.

The File plug‑in sample file includes a function that calls IFmsFileAdaptor::open. The open() function includes a parameter, sFileName. The value of sFileName is passed to the File plug‑in by the server; it is the default value of the SWFFolder tag in either Application.xml or Server.xml.

The plug‑in redirects the SWFFolder value to the external content repository. The sample creates a handle to that repository and passes it back to the server. The getAttributes() function also takes sFileName as a parameter.

After calling the open() function, the sample includes code that determines if the value of sFileName is a file or a directory. Files are opened. Directories are opened and written to a temporary file. The sample uses the new attribute FMSFileAttribute::kMode to determine if sFileName is a file or directory (1 for a stream, 0 for a directory.)

The File plug‑in returns a handle to this temporary file to the server. If the directory contains any subdirectories or SWF files, the server opens the directory or file, and continues the process until all the subdirectories and files are read. Through the plug‑in's read() method, the server reads the file and performs verification. Through the plug‑in's close() method, the server closes the file when fully read.

Use the File plug-in to manage content for live HTTP streaming

Adobe Media Server 4.5

[adoberuntime]Adobe Media Server 4.5[/adoberuntime]

Use the File plug-in to manage content for live HTTP streaming, including asynchronous file IO operations. The live packager application (livepkgr) ingests a live stream and packages it into fragments (F4F files) and additional helper files. The server operations that record these files are routed through the File plug-in. Use the File plug-in to manage the location of the following files:

.f4f
.f4x
.bootstrap
.control
.drmmeta
.meta

Adobe Media Server 4.5 adds the following APIs:

rename()
Moves a file. Pass the absolute path of the source file and the destination file. This call overwrites a file of the same name in the destination path.
The server calls this method on the File plug-in synchronously or asynchronously. If the server calls this method asynchronously, call onRename() to resume operations to the server.
truncate()
Truncates a file to a specified file size. The server calls this method on the File plug-in synchronously or asynchronously. If the server calls this method asynchronously, call onTruncate() to resume operations on the server.
onRename()
Calls the resume operation on the server after the server has called rename() on the File plug-in asynchronously.
onTruncate()
Calls the resume operation on the server after the server has called truncate() on the File plug-in asynchronously.

For detailed information about each API, see Flash Media Server Plug-in API Reference. In addition, these APIs are used in the sample File plug-in installed to rootinstall/samples/plugins/file/SimpleFileAdaptor.h.

Get help faster and easier

New user?