wfed.me: Protocol

Download SDK:

wfed SDK 1.0
Requires web server. PHP 5.2 or later recommended.
Uploaded February 16, 2011

Protocol Overview

The protocol is very simple. On a web page, supply a link for downloading a document. The link will be of the form:

wfed:http://www.myserver.com/path/to/download/script

The browser will hand control to the Web File Editor application. The Web File Editor application will send the HTTP request to your server. The download script needs to deliver the file in the HTTP reply body, with some additional information in the headers, including an upload URL (for uploading a modified file) and a release URL (so your server knows the user is done editing).

Your download, upload, and release URLs probably need to include a user’s session and an internal file ID. So a real live wfed link might look more like:

wfed:http://www.myserver.com/download.php/ {session_id}/{file_id}

Keep This in the Back of your Mind

The Web File Editor application does not know anything about the internal workings of your server, such as what session IDs mean, where files are stored, what your read locking policies are, etc. It just knows how to make HTTP requests from your server — requests that you specify.

If your web server uses session IDs to track logged in users, either in the URLs of pages accessed or via a cookie, the session ID will not be available for the Web File Editor application to send to your server unless you make in available in the URLs it provides.

In constructing the URLs for downloading, uploading, and releasing content, you should provide the minimum information necessary out of concern for security. These URLs might be intercepted by a savvy user, or by firewalls, proxies, and other software between your user and your server. We think that most implementations can be done effectively by passing just a session ID and a file ID in the download, upload, and release URLs.

Files will not necessarily get released by users. Users might forget, lose Internet connection, experience a computer crash, etc. So your server needs to release read and write locks if they are still open after they have expired.

The SDK

To get started, you should download our SDK from the link above. If you install the included &ldqo;wfed” in the root directory of your web server you will be able to test the Web File Editor application and protocol locally before implementing the protocol on your website.

Debugging with the Web File Editor Application

If you start the Web File Editor application while holding down the “Shift” key on your keyboard, the “File” menu will contain a command to show a “Transcript” window. This window will show all communications between Web File Editor and the server along with other diagnostic information that should help you verify that things are working correctly and track down any trouble.

The Download Link

Place a wfed URL on a web page to give the user the ability to download and possibly edit a file on your server. As noted above, the download link will look like:

wfed:http://www.myserver.com/download.php/ {session_id}/{file_id}

The HTTP portion of the URL needs to point to a script on your server that validates the session id, and delivers the file associated with the file ID. Our sample PHP code shows how to parse the session ID and file ID out of such a URL.

The “wfed:” prefix tells the web browser to hand the URL off to the Web File Editor application, which will communicate with your server via HTTP using that portion of the URL.

The Download Script

Your download script is, conceptually, surprisingly simple. Here is what it needs to do:

Parse the session and file IDs from the request URL.
Validate the session ID and make sure the user has appropriate rights for the file referenced by the file ID.
Add a reply header “Filename” with the name of the file, such as “MyGreatFile.doc”.
Add a reply header “Upload-URL” with a URL for uploading the edited file. If you omit this header, changes will not be uploaded to your server.
Add a reply header “Release-URL” with a URL for releasing the edited file. This lets your server know when the user is done with the file.

Add a reply header “Lease-time-seconds” with the number of seconds the user can view or edit this file.
Add a reply header “Allow-save” with the value “true” (no quotes) to allow the user to save the file directly from Web File Editor.
Add a reply header “Spoken-name” if your file has a speech friendly filename. For example, a file named “Blow, Joe - Blood #654321” could get a spoken name like “Joe Blow’s Blood Test”.
If you would like to have the Web File Editor display a message to the user, add a reply header “Message” with the message to display.
If your script does not validate the session or file, or runs into other problems, it should return an HTTP error. The error will be displayed to the user.
Put the contents of the file in raw binary encoding in the body of the response.

The Upload Script

The upload script is even simpler than the download script. Here is what it needs to do:

Parse the session and file IDs from the request URL.
Validate the session ID and make sure the user has appropriate rights for the file referenced by the file ID.
If the user has permission to overwrite the file, then get the file data from the body of the HTTP request, and save it into the file. You may also wish to backup the previous version of the file.
If your script does not validate the session or file, or runs into other problems, it should return an HTTP error. The error will be displayed to the user.

The Release Script

The release script should also be pretty simple. Its purpose is to release any read or write locks you placed on the file, so that other users can download and edit it. Here is what this script needs to do:

Parse the session and file IDs from the request URL.
Validate the session ID and make sure the user has appropriate rights for the file referenced by the file ID.
If the user had read or write locks on the file, release them.
If your script does not validate the session or file, or runs into other problems, it should return an HTTP error. The error will be displayed to the user.

HTTPS Support

The Web File Editor application supports HTTPS. Just use HTTPS URLs instead of HTTP URLs for your download, upload, and release URLs. Note that while the Web File Editor application encrypts data over HTTPS, it does not validate the server certificate.

Failure Considerations

Keep in mind that there is a lot that go wrong between your server and the user’s computer, as well as on the user’s computer. It is possible that a file not be released correctly. If your server leases a file to user for 15 minutes, it should be prepared to automatically release the file sometime later, perhaps 20 minutes, if the file is not released by the user.