Overview

The OCMP directory API lets developers create OCMP applications in any language without having to write Java plugins for them or to recompile OCMP. These applications all take advantage of a common user account system and status report system, including a graphical status manager. The unit of transport is a file, which may contain any type of information. Applications simply put files they want to send into one directory and are notified when they receive files in a second directory. Thus, developers don't have to worry at all about maintaining a connection, breaking up data into packets, keeping the application running to receive data, etc.

As in the rest of OCMP, communication occurs between a client on a mobile device or kiosk and a proxy connected to the wired Internet and the application's back-end. In the directory API, a transfer on the forward path, from a client to the proxy, is called an upload, and a transfer on the reverse path, from the proxy to a client, is called a download. Each transfer is associated with both a user, which could be a unique user on a device such as a cellphone or one of several users on a shared kiosk, and an application. A simple configuration file tells OCMP how to invoke each application when a file for it arrives, and can be used to give the application the name of the data file as well as the name of the user for which it came. Each file transferred may optionally have an associated description file containing a "title" to display for it in the GUI as well as a short description (e.g. one paragraph), to show the user some information about the file while it is transferring.

For example, a transfer from the client to the proxy occurs in the following manner:

1. An application on the client creates a file in its upload directory. For example, a graphical Blogger interface might allow the user to write a blog post, then drop it in the upload directory when the user presses Submit. The application could also create a description file here, to provide a title and short description for the file to show in the OCMP status GUI.
2. OCMP transfers first the file to the proxy when a connection becomes available.
3. The proxy reconstructs the file in its upload directory for that application/user combination.
4. The proxy looks in the configuration file to find a command to run when it receives a file for this application, and invokes it. For example, for a blog application, this could be a shell script which submits the post to the blog site using a web service.

Applications on the proxy can send a message to a client in a similar manner, by dropping a file in that user's download directory. For example, a mail daemon might send a new email message to a given user in this manner. Once the client receives the file, it also invokes a command from a config file (e.g. to copy the message to the user's inbox or pop up an alert).

The users used by the directory API also correspond to OCMP user ID's, and routing rules can be used to support mobility in a kiosk environment (even though only one OCMP client is running on a kiosk, it can send and receive bundles for multiple users).

Running the Directory API

In addition to the OCMP proxy and client, a Directory Watcher daemon must be started to monitor the directories for the directory API. This is started automatically by OCMP if you provide the parameter autoStartDirWatcher = true in the OCMP config file.

You may also start the daemon manually by invoking

java OcmpApplicationPlugins.DirectoryApi.DirectoryWatcher client

on the client (to watch the client directory), or

java OcmpApplicationPlugins.DirectoryApi.DirectoryWatcher proxy

to run on the proxy. You can also give each daemon a port as an optional second argument, to tell it where the OCMP client daemon (on the client side) or the ReverseProxyListener (on the proxy side) is listening, if this is not the default port (8080 on client, 8083 for proxy listener).

Naming Rules

Both the user and application names should be arbitrary strings of alphanumeric characters and the characters '-', '_', '.' and '@'. They must be valid directory names on any operating system and they should not contain spaces.

Files may have any names other than "status.xml", which is used for a special files. Filenames are also not allowed to end in ".desc", which is used for description files. A file's description file must have the same name, with .desc at the end (for example, for the file "image.jpg", the description file would be "image.jpg.desc").

Note that files will not keep their names on the destination side after they are transferred - each file received is given a unique, random name - so the filename should not be used for information that does not also occur in the file itself. This is done to prevent confusion when a user sends two files with the same name. The title of the file displayed on the status manager GUI will be read from the description file, however, so the user doesn't need to ever see the random filenames.

Directory Structure

The directory API stores its files in C:\ocmp on Windows or /var/ocmp on Linux. We'll use the Linux paths as an example from now on, but similar paths are used on Windows. The client and proxy use different subdirectories in /var/ocmp: the client send and receives files using /var/ocmp/client, and the proxy sends and receives files using /var/ocmp/proxy. This is done so you can run both a client and a proxy on the same machine, for testing. Within each of these directories, there is a bookkeeping file (filesSent) and a directory for each user. Within each user's directory, there is a directory for each application, and each of these contains two directories, upload and download, for the forward and reverse paths respectively. On the client, files to send to the proxy should be put in upload, and files received are put in download. On the proxy, files received come into upload and files to send should be put in download. Each upload/download directory also contains a status file, status.xml, detailing the status of each file that is being sent or received.

For example, the directory structure on a client, which has a single user, "user1", and two applications, "blogger" and "email", could be:

/var/ocmp/client
            /user1
                 /blogger
                     /upload
                            /post1.txt       (arbitrary filename, chosen by app)
                            /post1.txt.desc  (description file)
                            /post2.txt
                            /post2.txt.desc
                            /status.xml      (status file)
                 /email
                    /upload
                            /message1.txt            (note: having no .desc file is OK)
                            /status.xml
                    /download
                            /RO0RU304WWK03CRH        (random filename for received file)
                            /RO0RU304WWK03CRH.desc   (description file)
                            /SVK35PDO0FSG4MU5
                            /F90AYSUV411DVM61
                            /status.xml              (status file)
            /filesSent    (bookkeeping: list of files OCMP has seen and sent)

Secure Directory Structure

Inside each user's home directory is a list of folders, one for each KioskNet application. Inside each application folder is an 'supload' and an 'sdownload' directory. Files dropped in the supload directories are encrypted by the secure directory watcher and dropped into /var/ocmp/client/APPNAME/upload. This is then sent securely to the proxy. Along with each file should be a description file, which determines the destination of the file, the file is always dropped in the sender's uplaod directory on the proxy.

Similarly, on the proxy is a directory at /var/ocmp/proxy which has folders for each KioskNet application, and corresponding upload, download directories for each application folder. Again, files dropped in upload on the proxy should be accompanied by a description file which determines to which kiosk they are routed. There is also a special user on the proxy called the operator which has in its home directory the supload an download directories which function in a similar fashion to the corresponding directories on the kiosk with one key difference, the functionality is reversed. i.e. Download is for sending and upload is for receiving.

The security daemon will copy the files to the operators upload and download directories from where it is sent to the user at the kiosk.

Note that user's do not have supload and sdownload directories on the proxy since the proxy has no knowledge about user's private keys and hence cannot decrypt or sign packets securely.

- Rowena Feb 2008 - Usman March 2008

Configuration File Format

The directory API uses a configuration file separate from the OCMP config file to find applications to invoke upon receipt of a file. In the OCMP config file, this file can be be given as the parameter dirApiConfig; for example:

dirApiConfig = /home/test/dirapi.conf

If no dirApiConfig parameter is specified, OCMP looks for C:\ocmp\dirapi.conf.

The directory API config file can contain a number of applications, each of which may specify a proxy command (to be called by the proxy when it receives an upload for the application) or a client command (to be called by the client when it receives a download). Each command can contain the following "variables", which will be substituted for their values by OCMP:

• $FILE: Full path to the file received.
• $USER: Name of the user for which the file is received. (So apps don't have to parse the full path to figure this out).
• $APP: Name of the application (so apps don't have to parse this).

The file format is simply a number of name-value pairs with ":" inbetween, as follows:

# A simple test application which copies all files to c:\test
Application: test
ProxyCommand: cp $FILE c:\test
ClientCommand: cp $FILE c:\test

# The Blogger app, which invokes a PHP script that posts the file to a blog
Application: blogger
ProxyCommand: php blogger.php $FILE
# No ClientCommand (since Blogger doesn't send any files back)

The proxy really only needs ProxyCommands and the client really only needs ClientCommands, but you can specify both to support testing on a single machine.

Extra space in the config file is ignored, and lines starting with "#" are treated as comments.

Description File Format

Each file can have an optional description file, with the same filename with .desc added at the end (for example, image.jpg.desc for a file named image.jpg). This file is used by the graphical status manager, to which it gives a title to display for the file as well as a description paragraph. This way, applications can display application-specific data for each of their files. The format is very simple:

At the sender side

• The first line of the file is the destination.
• The second line contains the keyword "secured" if this is an encrypted bundle otherwise can contain anything
• The rest of the file is the description. This should be short, so it has space to display in the GUI.

At the receiver side

• The first line contains the original file name
• Then there will be one line which contains the keyword 'secured' if the bundle is encrypted and the keyword 'command' followed by a shell command to be executed after decryption (if it is a secured bundle)
• Otherwise it contains the user supplied description file.

Description files will be transferred before the data files themselves, to give the status manager something to show in the GUI as soon as a download begins.

The description file for the Secure Dir API is different. First of all the destination is prefixed by "Dest: " (note capitalization). If the bundle requires the certificate of sender to be attached in the bundle then the "attach_cert" keyword is added on a line by itself.

Writing a Directory API Application

To send a file, drop it into /var/ocmp/<client or proxy>/<username>/<app name>/<upload or download>. Please ensure that the file is written quickly - OCMP starts sending it as soon as it hasn't been modified for 2 seconds, so if you pause for a long time, a partial file will be sent. If you need to compose a message over time, it's best to keep it in memory and then drop it as a file when it's complete. It's OK to overwrite an old upload file to send another - OCMP will check each old file for modifications and send it anew if it changes. Thus, you might not need to worry about upload files having unique names. However, if you do this too quickly (within 10 seconds of the first file being created), OCMP might "miss" the original. It's recommended to use current time in the filename to prevent this. If you wish to create a description file, create it before the original file, to ensure that OCMP "sees" it when it sees the original file.

To receive files, either check the upload/download directory for each user, or specify a command in the config file that should be invoked on each file. For example, even if you have a daemon running all the time, you can have a simple command that sends it a message through some socket to tell it to deal with the new file. Using the command mechanism is preferable to polling because it's much more efficient. Note that received files will have random filenames (consisting of 20 alphanumeric characters). Do not store any information in the filename that is not also stored in the file. Please also note that your script should return 0 on success. If your script returns a non-zero value, the incoming file will not be deleted, to help with debugging.

When using the DTN CO, transfer of the file to OCMP happens when the ferry arrives. So, you should not delete a file until that time. In any case, OCMP will delete the file when an ack is received.

Sample Applications

Blogger

The Blogger application allows sending posts to blogger.com opportunistically over OCMP. It provides a graphical front end where the user can specify a blogger.com ID password, and blog ID (the 8 or 9 digit number in the blog's URL), then type in a post. A back end which posts the file to the specified blog using blogger.com's XMLRPC API. The application's directory is "blogger", and the graphical front-end can be run as java BlogApp from the OCMP codebase. The proxy must have PHP installed and on the PATH for the back-end to work.

Wget Application

The Wget application allows the user to download files from the web over HTTP or FTP. The front end asks for an HTTP or FTP URL, and sends a request file to the proxy. The back end downloads the file using wget, then streams it back to the user, where it is placed in a "downloads" directory. To run the front end, use java DownloadApp from the OCMP codebase. The proxy must have PHP and Wget (http://www.gnu.org/software/wget/) installed and on the path. This application's directory name within the OCMP directory structure is "wget".