Commit 60cd06ff authored by Google Code Exporter's avatar Google Code Exporter
Browse files

Migrating wiki contents from Google Code

parents
The MaharaDroid sync API is made up of an HTTP(s) POST (multi-part mime) with a JSON response object.
The HTTP(s) POST contains the user, token and last-sync details. The POST is multi-part mime encoded as per a standard HTTP(s) form submit. On receiving the POST request the API (in order):
1. checks to see if site configuration 'allowmobileuploads' is enabled
1. validates the user with their token
1. retrieves user details such as:
1. blogs (Journals)
1. blogposts (Journal posts)
1. folders
1. tags
1. activity
1. version (Mahara version)
1. generates a new token and response with success and the server time (as lastsync as EPOCH)
For more in depth detail you are encouraged to view the API in it's complete form (it's not that complex) ..it can be found on the Mahara gitorious site here https://www.gitorious.org/mahara/mahara/blobs/master/htdocs/api/mobile/sync.php
There is also a test utility (web form) that cane be found here
https://www.gitorious.org/mahara/mahara/blobs/master/htdocs/api/mobile/test.php
## Parameters POSTed ##
1. token
1. username
1. lastsync
1. notifications
### Example raw HTTP Post ###
```
POST /~alanm/mahara/htdocs/api/mobile/sync.php HTTP/1.1
Content-Length: 760
Content-Type: multipart/form-data; boundary=K1X-SOmSHUE9niJ4MnTMlRluCgYej2YCKMb
Host: 10.0.0.103
Connection: Keep-Alive
--K1X-SOmSHUE9niJ4MnTMlRluCgYej2YCKMb
Content-Disposition: form-data; name="lastsync"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
0
--K1X-SOmSHUE9niJ4MnTMlRluCgYej2YCKMb
Content-Disposition: form-data; name="notifications"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
maharamessage,feedback,newpost,usermessage
--K1X-SOmSHUE9niJ4MnTMlRluCgYej2YCKMb
Content-Disposition: form-data; name="token"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
foobar
--K1X-SOmSHUE9niJ4MnTMlRluCgYej2YCKMb
Content-Disposition: form-data; name="username"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
alan
--K1X-SOmSHUE9niJ4MnTMlRluCgYej2YCKMb--
```
## Example Output ##
```
Content-Type: application/json
{
"success":"909632858af6da5c73eb290dac63e02f",
"lastsync":"1343241003",
"version":"20120712",
"sync":{
"activity":[
{
"id":"1",
"subject":"New friend request",
"message":"Admin User has requested that you add them as a friend. You can either do this from the link below or from your friends list page. Their reason was:\n Hey do you want to be my friend"
},
{
"id":"2",
"subject":"New message from Admin User (admin)",
"message":"Test message"
}
],
"tags":[
{
"id":"Android",
"tag":"Android"
},
{
"id":"second",
"tag":"second"
},
{
"id":"third",
"tag":"third"
}
],
"blogs":[
{
"id":"8",
"blog":"Alan McNatty's Blog"
}
],
"blogposts":[
{
"id":"1",
"blog":"2012-07-26: COMP trip to Auckland"
}
],
"folders":[
{
"id":189,
"folder":"MobileUploads"
}
]
}
}
```
\ No newline at end of file
The MaharaDroid API is made up of an HTTP(s) POST (multi-part mime) with a JSON response object.
The HTTP(s) POST contains all the user, token and artefact details as well as the file. The POST is multi-part mime encoded as per a standard HTTP form submit. On receiving the POST request the API (in order):
1. checks to see if site configuration 'allowmobileuploads' is enabled
1. validates the user with their token
1. checks to see if the upload directory exists (if not it is created)
1. if a blog id is provided creates a blog post with the title and description
1. if a blog post id is provided load the blog post
1. if a file has been uploaded creates the artefact (with the details, user and folder provided)
1. checks to see if users file quota has been exceeded (or responds with failure)
1. checks to see if file has been saved (or responds with failure)
1. if a blog post has been loaded/created attach the file to the blog post
1. generates a new token and response with success
For more in depth detail you are encouraged to view the API in it's complete form (it's not that complex) ..it can be found on the Mahara gitorious site here /htdocs/api/mobile/upload.php
## Parameters POSTed ##
1. token
1. username
1. foldername
1. blog / journal id
1. blog post / journal entry id
1. title
1. description
1. userfile (uploaded file)
1. tags
## Example Output ##
```
Content-Type: application/json
{"fail":"Auth token cannot be blank"}
```
### A note on HTTPS certificates ###
Testing with untrusted certificates (e.g. default apache2 ssl set-up) gives a "No peer certificate" error. This is because Android by default expects certificates to be trusted.
```
...
04-20 12:06:49.517: W/System.err(31973): javax.net.ssl.SSLPeerUnverifiedException: No peer certificate
04-20 12:06:49.527: W/System.err(31973): at org.apache.harmony.xnet.provider.jsse.SSLSessionImpl.getPeerCertificates(SSLSessionImpl.java:258)
```
Based on discussions on StackOverflow I have created a debug SSL treatment which overrides this default behavior and ignores SSL cert errors allowing developers to test with untrusted certificates.
Testing has not yet confirmed whether or not a trusted certificate does work. If you have HTTPS we a working it would be good to hear from you.
# Problems #
## Web-server / Php configuration ##
If you have problems uploading files check your web-server error log but also your php.ini file for max upload filesize. If this is too small your upload will quietly fail (on the server side).
For example - my default for Php of 2M is too small for modern smart-phones with 4+ mega-pixel cameras:
```
;;;;;;;;;;;;;;;;
; File Uploads ;
;;;;;;;;;;;;;;;;
; Whether to allow HTTP file uploads.
; http://php.net/file-uploads
file_uploads = On
; Temporary directory for HTTP uploaded files (will use system default if not
; specified).
; http://php.net/upload-tmp-dir
;upload_tmp_dir =
; Maximum allowed size for uploaded files.
; http://php.net/upload-max-filesize
upload_max_filesize = 20M
; Maximum number of files that can be uploaded via a single request
max_file_uploads = 20
```
\ No newline at end of file
## Introduction ##
<wiki:gadget url="http://www.ohloh.net/p/486236/widgets/project\_users\_logo.xml" height="43" border="0"/>
MaharaDroid enables Android phones to _share_ or upload content to a [Mahara](http://www.mahara.org) instance. Note: requires Mahara >= 1.4.
* Configure the Mahara site you want to post to (must have mobileuploads enabled)
* Select a image and 'Share' to MaharaDroid
* MaharaDroid enable by users using (auto renewing) token based authentication
* Log-on to Mahara web-site and further manage your uploaded artefact
* QR code configurable
| ![https://lh5.googleusercontent.com/_ZQm5YtCKEqM/TdH6PW3GW-I/AAAAAAAAALE/91R4FIew17E/s400/n1.png](https://lh5.googleusercontent.com/_ZQm5YtCKEqM/TdH6PW3GW-I/AAAAAAAAALE/91R4FIew17E/s400/n1.png) | ![https://lh4.googleusercontent.com/_ZQm5YtCKEqM/TdH6PTaZ-4I/AAAAAAAAALA/5kOHaRG2KbU/s400/n2.png](https://lh4.googleusercontent.com/_ZQm5YtCKEqM/TdH6PTaZ-4I/AAAAAAAAALA/5kOHaRG2KbU/s400/n2.png) |
|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
## Source Code ##
Since Mahara 1.4 MaharaDroid has become a recognized Mahara contribution. Consequently the source has moved to gitorious
Browse the repository http://www.gitorious.org/mahara-contrib/mahara-droid or check out the code:
` git co http://git.gitorious.org/mahara-contrib/mahara-droid.git `
## Changelog ##
1.8
* French language support (thanks Pascale Hyboud-Peron).
* Japanese language support (thanks Mitsuhiro Yoshida).
* Fixes for issues 16, 17 and 18.
1.7
* Ability to 'save' artefacts for later upload. Including ability to delete all / upload all and view a saved artefact on the device
* adjusted supported for additional content-types (removed text/plain as text v file is not easily distinguished)
* improved language support (see credits below for details)
* also includes some bug fixes ([issue 15](https://code.google.com/p/maharadroid/issues/detail?id=15))
* QR configuration added
1.6 Note: compatibility breaker - now requires Android 1.6 (API level 4).
* multiple file upload support
* changed the back-end response handling to JSON as opposed to HTTP header responses to improve error handling. Requires matching Mahara functionality (see commit http://www.gitorious.org/mahara/mahara/commit/3023307c951628e8f2b9ecbf3c5ff48f0b53d646)
* improved language support (see credits below for details)
* added specific supported for additional content-types (beyond images, having reduced the scope after some reports of problems)
* also includes some bug fixes ([issue 8](https://code.google.com/p/maharadroid/issues/detail?id=8), [issue 12](https://code.google.com/p/maharadroid/issues/detail?id=12), [issue 13](https://code.google.com/p/maharadroid/issues/detail?id=13) and [issue 14](https://code.google.com/p/maharadroid/issues/detail?id=14))
1.5 Fixed bug crashing the app when no preferences were set. Reduced upload capability to images only as Mahara doesn't support mobile video formats as yet. More forum discussion required to scope this further.
1.4 Enabled upload of 'any' file
1.3 Added support of global and per item artefact tags and content description - disabled stripping of file extension on upload
1.2 First release including title name and image support
1.1 Proof of concept - basic token authentication and content upload
## Howto ##
See <a href='http://www.youtube.com/watch?feature=player_embedded&v=D2lPwH4HWYA' target='_blank'><img src='http://img.youtube.com/vi/D2lPwH4HWYA/0.jpg' width='425' height=344 /></a>
Currently the 'token' based authentication is performed by a user setting a token in their settings on Mahara. This same token is then entered into the MaharaDroid preferences. Note that the token is re-keyed automatically for each upload. If you have any issues / problems .. simple reset the token both on Mahara and in MaharaDroid.
If there is no option to set your 'mobile upload' token then mobile uploads have not been enabled for your Mahara instance. Mobile uploads are enabled by a Mahara site administrator under system setting in versions >= 1.4. For demonstration purposes see http://master.dev.mahara.org.
### Wishlist ###
1. Support for journals
1. Support for auto-creating a public view perhaps (a-la http://master.dev.mahara.org/view/view.php?id=428).
1. Support for OAuth and future Mahara web API
See 'issues' tab for more.
## Screenshots ##
| ![http://lh4.ggpht.com/_ZQm5YtCKEqM/TMZCX1DeRSI/AAAAAAAAAEY/uLWsCMT0Lks/s400/m2.png](http://lh4.ggpht.com/_ZQm5YtCKEqM/TMZCX1DeRSI/AAAAAAAAAEY/uLWsCMT0Lks/s400/m2.png) | ![http://lh3.ggpht.com/_ZQm5YtCKEqM/TK5_6_StmFI/AAAAAAAAADE/6T48sdfidFU/s400/m3.png](http://lh3.ggpht.com/_ZQm5YtCKEqM/TK5_6_StmFI/AAAAAAAAADE/6T48sdfidFU/s400/m3.png) |
|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
![http://lh5.ggpht.com/_ZQm5YtCKEqM/TK5_7WfpLjI/AAAAAAAAADM/NSPNi2z58rA/s800/m7.png](http://lh5.ggpht.com/_ZQm5YtCKEqM/TK5_7WfpLjI/AAAAAAAAADM/NSPNi2z58rA/s800/m7.png)
## Credits ##
The base concept of MaharaDroid, as an artefact uploader came from [Flickr Free](http://code.google.com/p/flickrfree/) written by [Russel Stewart](mailto://rnstewart@gmail.com). Thanks to Russel for giving us the nod to start by using his FlickrFree upload code.
### Translations ###
| **Translator** | **Language** | **Version** |
|:---------------|:-------------|:------------|
| Kristina Hoeppner | German | 1.6 |
| Gregor Anželj | Slovenian | 1.6 |
| Inaki Arenaza | Spanish | 1.6 |
| Joan Queralt | Catalan | 1.7 |
| Mitsuhiro Yoshida | Japanese | 1.8 |
| Pascale Hyboud-Peron | French | 1.8 |
\ No newline at end of file
# QR Code Configuration #
It is possible to make a QR code for your Mahara site so that users can automatically configure MaharaDroid. This can be done in one of two ways.
1. create a QR code of the XML configuration file
1. create a QR code of the URL to the XML configuration file
https://mahara.org/artefact/file/download.php?file=164805&view=36871
# XML configuration file #
Common to both these method is the XML configuration file. MaharaDroid can read an XML configuration file and overwrite some it's default settings with those provided in the file. The configuration variables that can be overridden are upload variables such as:
* upload.uri
* upload.folder
* upload.tags
So a XML configuration file may look like:
```
<config>
<upload.uri>http://master.dev.mahara.org/artefact/file/mobileupload.php</upload.uri>
<upload.folder>MobileUploads</upload.folder>
<upload.tags>Android</upload.tags>
</config>
```
## Advanced ##
In fact it allows setting of any upload preferences based on key name. For example check the pref\_uload**key fields in the strings.xml file such as: ` <string name="pref_upload_url_key">upload.uri</string> ` https://www.gitorious.org/mahara-contrib/mahara-droid/blobs/master/res/values/strings.xml**
# Create a QR code of the XML configuration file #
To create a QR code of the XML configuration file use a tool to create a QR code from the contents of the XML configuration file.
`qrencode -O config.png < config.xml`
Or use an online tool such as http://qrcode.kaywa.com/
# Create a QR code of the URL to the XML configuration file #
By creating a QR code of the URL to the XML configuration file the QR code has a reference to the configuration and not the configuration itself. This enables you to dynamically change the configuration without changing the QR code (saved, cached and physical copies remain valid). That said, a data connection would be required for the user to download the XML configuration file.
To make a QR code containing a URL to the XML configuration file
> use a tool to create a QR code from the contents of the XML configuration file.
`qrencode -O config.png http://my.mahara.instance.com/config.xml`
Or use an online tool such as http://qrcode.kaywa.com/
\ No newline at end of file
# MaharaDroid Supported File Types #
The currently supported file types are content that has the following mime-type:
1. `image/*`
1. `video/*`
1. `audio/*`
1. `text/csv`
1. `text/rtf`
1. `text/html`
1. `text/xml`
This could be extended by request - please ask in the Mahara forums or raise an issue on this site. The reason for restricting the file types is simple related to whether or not support has been tested.
## Advanced ##
Interested in testing some new mime-type? Grab the MaharaDroid source and build in the change. The file types supported by MaharaDroid are controlled by the Intent filter in the Android Manaifest XML file.
```
<intent-filter>
<action android:name="android.intent.action.SEND" />
<action android:name="android.intent.action.SEND_MULTIPLE" />
<category android:name="android.intent.category.DEFAULT" />
<data android:mimeType="image/*" />
<data android:mimeType="video/*" />
<data android:mimeType="audio/*" />
<data android:mimeType="application/*" />
<data android:mimeType="text/csv" />
<data android:mimeType="text/rtf" />
<data android:mimeType="text/html" />
<data android:mimeType="text/xml" />
</intent-filter>
```
\ No newline at end of file
config.png

756 Bytes

Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment