AwareNet Client Software

This document describes a clientside application we hope to use in school computer labs to complement awareNet. awareNet is a suite of social networking software aimed primarily at high schools in the developed and developing world. The purpose of this client side application (app) is to simplify user management of files - particularly images - to be uploaded to and stored on awareNet servers.

The first version of this software is concerned only with uploading images from removable media on the client machine, such as USB cameras and flash sticks. When USB media are attached to a student's workstation the app runs automatically - as Microsoft's Photo Import wizard would - showing the user the contents of the USB drive and a list of their items on awareNet to which the images can be uploaded and attached.

At present images can be added to open projects where the user is a member, to users photo galleries and blog posts and may be used to set a users profile picture.

All uploaded images should be sent as jpegs no more than 1024x768px in size. The awareNet images module can use larger images and other formats, but since these files may be synced to awareNet servers in bandwidth-poor areas it is best to scale images down.

1 Image Records

Images (and files in general) stored on awareNet are represented by a database record which contains their metadata.

The user should be able to change the following fields from the app:

• title
• caption
• licence and attribution (on hold for now)
• weight (integer)

How copyright is to be handled is currently an open issue. Copyright belongs to the person who created a file or image and they can then copyleft their content using CC, GDFL, etc or resign copyright to the public domain. How awareNet should handle this is as yet unknown - content licensing isn't the first thing schoolkids think about when they snap a picture. For now these fields can be left blank.

Note: A person who uploads a picture from a camera isn't necessarily the person who took it, but that will be in control of the image record.

2 Interface

The suggested user interface is composed of two panels, each with a treeview control and a grid of thumbnails, the panel on the left is used to explore the contents of the attached USB device, the panel on the right shows awareNet objects and images associated with them. Below the left (USB) thumbnail grid is a button to upload selected items. Below the right hand panel should be buttons for deleting items on the server, and optionally for updating title/caption/licence.

3 Configuration

It is suggested that configuration data for the app be stored in the [http://en.wikipedia.org/wiki/Windows_Registry registry] to simplify administration of the app in a school computer lab. The app will need to know:

• URL of local awareNet server
• local firefox/ie cookie path (may be discovered at runtime)

Future versions will likely need information about video codecs and 3rd party binaries. When video hosting is supported on awareNet it will likely take the form of streaming flash video; video loaded from cameras is transcoded on the client before upload to the local awarenet server. This is to save server resources, and reduce bandwidth use between servers.

4 Authentication

It is hoped that the app will be able to reuse a current browser session cookie so that it will not be necessary to re-enter a username and password to upload files. The user logs into awareNet and a session cookie is stored by the browser. This cookie contains (among other things) a PHP session ID. This is then used by the app when making requests of awareNet APIs.

Before each action the app should query an API on the users module to discover the UID, username, etc of the current user. This is to ensure that:

• a user is logged in to awareNet from the lab machine
• the user remains logged in throughout the process
• the same user is logged in throughout the process

If the user logged in on the browser session changes, so will the objects (eg, profile) to which images can be attached.

GET /users/api/current/ HTTP/1.1 (try it: [http://mothsorchid.com/users/api/current/])

Will return something like:

If the UID or group is 'public' then the user is not logged in.

5 MyRecords APIs

The app will need to use several APIs on various awareNet modules to discover which objects the current user can attach images to. All will follow the same conventions. Please advise if particular API formats are preferred (eg, [http://en.wikipedia.org/wiki/JSON JSON], [http://en.wikipedia.org/wiki/XML-RPC XML-RPC], etc). These APIs are queried with a GET request which includes the current browser cookie.

In each case the API will respond with a list of records in XML format

<?xml version="1.0"?>

<recordset>

<record>

<uid>87654321</uid>

<module>gallery</module>

<title>My Example Gallery</title>

<recordalias>My-Example-Gallery</recordalias>

<files>none</files>

<images>uploadmultiple</images>

<videos>none</videos>

</record>

... more records ...

</recordset>

UID, title and recordAlias refer to a record on which the current user has some permissions. files, images and videos refer to permissions the current user has on a record. For images, a user may be permitted the following actions

• uploadsingle: eg, on a profile; a new image replaces the old one
• uploadmultiple: eg, on a project or gallery; new images are added alongside existing images
• none: don't upload images to attach to this

It is suggested that objects discovered in this way are used to populate a treeview control.

6 Images API

An API on the images module may be used to discover images which an object already owns.

Might return:

This set of images owned by a given object can be used to populate a thumbnail grid and to fill the form for updating metadata. To retrieve a transform (eg, a thumbnail) from awareNet

GET /images/size/recordAlias HTTP/1.1 (include cookie in request)

Size of the transform may be: [http://mothsorchid.com/images/thumb/Teacher-Training-in-the-Eastern-Cape.jpg thumb],[http://mothsorchid.com/images/thumbsm/Teacher-Training-in-the-Eastern-Cape.jpg thumbsm],[http://mothsorchid.com/images/width300/Teacher-Training-in-the-Eastern-Cape.jpg width300],[http://mothsorchid.com/images/full/Teacher-Training-in-the-Eastern-Cape.jpg full], etc

7 Uploading images

The upload action on the images module accepts an HTTP POST with the following fields:

• action: uploadSingleImage or uploadMultipleImages
• refUID: UID of the object which owns this image
• refModule: module to which owning record belongs
• category: not used, set to empty string
• return: set to 'xml'
• userfile: file to upload, encoded as multipart form data.

It is suggested one captures an upload on a test awareNet profile for reference if there are any questions as to how this should be done.

To set user profile picture:

• refUID = the current user's UID (from /users/api/current/)
• refModule = 'users'
• action = 'uploadSingleImage'

The server should then reply with an xml copy of the new image record, or an xml error message. This new record with contain new UID and recordAlias of the newly added image as created by the server, and the app can then update the right-hand thumbnail grid.

Important: the action uploadSingleImage will cause the server to delete any existing images owned by something. It is only for situations where an object should own one image at a time, such as user profile picture.

8 Deleting images

Images may be deleted by sending an HTTP POST to /images/delete/ with the following fields:

• UID: UID of the image to delete
• return: set to 'xml'

This should then return XML indicating the success or failure of the deletion.