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.
Images (and files in general) stored on awareNet are represented by a database record which contains their metadata.
|| Data Type
|| a number uniquely representing the record
|| the UID of the record which owns this image (eg, a blog post)
|| the awareNet module to thich the owner record belongs (eg, the blog module)
|| name of the image
|| text describing this image
|| content licence: Copyright, GFDL, AFL, Creative Commons, etc...
|| attribution name for this image (eg, the copyright holder's name)
|| attribution URL (eg, a link to a flickr profile or government archive)
|| local filename relative to awareNet install
|| jpg,png or gif
|| files generated from this one, eg thumbnails
|| currently unused in awareNet
|| used to order images belonging to the same record, eg slides in a slideshow
|| date and time this record was created
|| UID of the user who created this record
|| number of times this image has been displayed
|| string used to refer to this image in URLs
The user should be able to change the following fields from the app:
- 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.
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.
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.
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.
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.
GET /gallery/api/myrecords/ HTTP/1.1 (try it: [http://mothsorchid.com/gallery/api/myrecords/])
GET /projects/api/myrecords/ HTTP/1.1 (try it: [http://mothsorchid.com/projects/api/myrecords/])
GET /moblog/api/myrecords/ HTTP/1.1 (try it: [http://mothsorchid.com/moblog/api/myrecords/])
In each case the API will respond with a list of records in XML format
<title>My Example Gallery</title>
... more records ...
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.
An API on the images module may be used to discover images which an object already owns.
GET /images/api/list/refModule_gallery/refUID_87654321 HTTP/1.1 (try it: [http://mothsorchid.com/images/api/list/refModule_gallery/refUID_153644194392804984])
<caption>his name is Spasm</caption>
<transforms>(not explained here)</transforms>
... more images ...
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
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.
POST /images/upload/ HTTP/1.1 (include browser cookie in header)
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.
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.