This document describes the SMASH Home Storage APIs. It takes into account the requirements of the three applications currently foreseen for the SMASH storage device: DVB-VCR, Web-VCR, and Remote Education Application (REA).
There is no such thing as a single API. As a matter of fact, there are a number of high-level interfaces: a table of contents (TOC) a VCR-like interface with streams, and a more traditional file system interface based on Samba. These interfaces are built on low level interfaces dealing with the storage media directly.
To provide an efficient implementation of the (high-level) APIs, information about the data to be stored is needed. More specifically, one needs to know how the data is to be used in each application. As an example, consider the DVB-VCR. Playing a MPEG-2 video with a certain bit rate requires that the video file is stored contiguously on the storage medium. As another example, suppose that we are dealing with a lot of relatively small files on a slow storage medium. If we know which files are related, e.g., the files are always accessed in a certain order, we can utilize this by caching related files on the faster storage medium.
The SMASH COMBO can be seen as a file server for a client application. Basically the SMASH server should handle the following types of files: text, graphics, animation, audio and digital video. Also, certain operations on files need to be supported: create, delete, open, close, read, write, etc. Finally, we need to be able to retrieve the files using some Table Of Contents (TOC) of the stored data.
Each of the applications currently defined has different requirements with respect to files and TOC. For example, DVB-VCR deals mainly with very large files with certain real-time requirements. Meta-data, information about the DVB programs provided by the content provider, as well as the storage location of the programs is stored in a multimedia database (MMDB). The REA has many small (HTML) files and a simple TOC. Web-VCR deals both with small and larger files, the TOC can be similar to the one for the REA.
For simplicity reasons, we assume that the SMASH server will be used for one particular application at a time. The interaction with the server is called a session.
The following figure shows how the application PC and the SMASH COMBO are connected via some network (currently Ethernet, in the future IEEE 1394).
Figure 8 Residental Network
Typically an application on a client makes use of the functionality as provided by the API. The underlying hardware is hidden for the application programmer. On the SMASH server, a controller deals explicitly with the peculiarities of the current hardware architecture.
Figure 9 Client Server Relation
If we zoom in on a Web-based application (like the Web-VCR, or the REA), we see the
following interactions: 
Figure 10 Model of WEB based Applications
The functionality needed to implement the interactions between controller and the tape drive and hard disk drive is typically described by the low level API.
The low level API is aware of the storage media. In the current implementation we need to deal with tapes, tape partitions, and a disk for caching tape partitions. This disk can be accessed using the native file system of the client using the Samba protocol, which supports open, close, read, write of files. Information on files stored on tape can be found in the TOC, which is copied upon session initialization to disk. The implementation of the TOC is application dependent. We only describe the commands from the low-level API that are relevant for the end user application.
In principle, files are retrieved partition-wise. Thus, we need to be able to find out in which partition(s) a particular file resides.
Lookup(Filename)
Returns the partition in which Filename resides or the first partition if the file
occupies more than one partition.
Once we know in which partition a particular file resides, we can copy that partition to
disk:
Restore(TapePartition)
Copy the files in TapePartition to disk.
Vice versa, files can be written to tape:
Archive()
Copy all the files on disk to tape. Update TOC.
Archive(FileList)
Copy the list of files identified by FileList to tape. Update TOC.
The interface available for files is provided by the classes in the java.io package. At the moment storage space is limited by the size of the exported server disk. The commands in the low level API can be used to enlarge that by copying tape partitions back and forth to the exported disk at the appropriate time.
Streams are a combination of a file and a port, where the file must either send or receive a stream of bits from the specified port in the communication network at a specified sustained bit rate. Streaming functionality can be handled using the file system interface. It is the responsibility of the application to read (write) the data from (to) a file at the appropriate rate. In the current configuration we can handle two of such streams at the same time.
If needed play, pause/resume, stop, and record can be implemented on top of general file system commands. Obviously, these commands are file type dependent, since playing MPEG-1 is different from playing AVI, QuickTime, or MPEG-2 single program transport stream. (At the moment we have an implementation of the commands for the DVB-VCR application). The signature of these commands is as follows:
Play(Port, Filename)
Allocates the resources and starts playback of a stream from the file identified by Filename
to the Port. A reference to the
stream object for further stream commands is returned.
Pause(Handle)
Interrupt a stream identified by Handle. During the interrupt all the resources
(bandwidth, ports, etc.) will remain reserved.
Resume(Handle)
Resumes a previously interrupted stream.
Stop(Handle)
Stops recording of playback of a stream and releases all resources.
Record(Port, Filename)
Allocates the resources and starts the recording of a stream coming from Port to
the file identified by Filename. A reference to
the stream object for further stream commands is returned.
Status(Handle)
Returns current values of stream attributes.
Recall that we introduced sessions to deal with application-specific implementations of generic commands. Each session bracketed by OpenSession - CloseSession pairs:
OpenSession(SessionType)
Start a session of type SessionType. Returns a reference to the session for further
commands. Initializes on-disk TOC, if needed.
Perform other initializations depending on SessionType.
CloseSession(SessionId)
Update TOC, if needed. Release resources.
Further we have some commands dealing explicitly with tapes:
List()
Returns the files that reside on the current tape.
List(TapePartition)
Returns the files that reside on TapePartition of the current tape.
Free()
Returns the amount of free space of the current tape.
Eject()
This function ejects the tape from the tape drive.
Insert()
This function inserts a tape into the system. If the tape was not used before, it can be
initialized, otherwise the TOC should be read.
Only the REA needs to deal with several tapes explicitly. Namely, a course resides on a particular tape. We assume that such a tape is only temporary in the system. The tapes, which are permanent in the system, as is the case for the DVB-VCR and the Web-VCR applications, are handled by a tape autoloader. Here the application programmer need not worry about individual tapes. However, manually changing a tape can be done using Eject and Restore commands.