===== Server One: Webservice for MoMult Sound Project =====

This document explains the usage of Server One and related tools.

==== Requirements ====

To run Server One, you will need the following:

  * Apache webserver with root access
  * Support for PHP 5.x
  * SOAP extension must be enabled
  * PDO extension must be enabled
  * Database backend (e.g. MySQL or PostgreSQL)
  * A (non-public) folder for media file upload

==== File description ====

Server One is based on a SOAP webservice written for PHP 5.x. It includes the following files:

  * config.php: Used for service configuration.

  * s1.wsdl: Webservice description. You find information about public
    interfaces and method arguments here.

  * s1.php: Webservice controller for request delegation.

  * MediaService.php: Webservice that handles SOAP requests.

  * MediaServer.php: Core server application for request processing
    (i.e. base64 decoding, file management, database access).

  * Database.php: Used to access database backend via PHP's PDO extension.

  * Logger.php: Advanced logging facility.

  * logfile.txt: Default file for log output.

  * download.php: Download manager for client-side sample fetching.

  * c1.php: Webservice test client.

==== Webservice methods ====

Currently the MediaService provides the following webservice interface:

  * uploadSample(Latitude, Longitude, Title, Timestamp, Description, PayloadType, Payload)

      * Description:
          Upload a sound sample to the server

      * Arguments:
        - Latitude: xsd:decimal, range +/- 90.0°
        - Longitude: xsd:decimal, range +/- 180.0°
        - Title: xsd:string, optional, max. 255 characters
        - Timestamp: xsd:string, max. 80 characters
        - Description: xsd:string, optional
        - PayloadType: xsd:string, either one of "mp3", "m4a" or "ogg"
        - Payload: xsd:string, base64 encoded binary file (sound sample)

      * Return values:
        - Statuscode: xsd:string, e.g. "OK" or "Error"
        - Message: xsd:string, human-readable message
        - SampleID: xsd:string, 32-digit hexadecimal number

---

  * reportNoiseLevel(Latitude, Longitude, Timestamp, ZipCode, NoiseLevel)

      * Description:
          Report noise level for given location

      * Arguments:
        - Latitude: xsd:decimal, range +/- 90.0°
        - Longitude: xsd:decimal, range +/- 180.0°
        - Timestamp: xsd:string, max. 80 characters
        - ZipCode: xsd:string, optional, max. 10 characters
        - NoiseLevel: xsd:int, unit is dB

      * Return values:
        - Statuscode: xsd:string, e.g. "OK" or "Error"
        - Message: xsd:string, human-readable message

---

  * getSamples(Latitude, Longitude, Range)

      * Description:
          Get a list of sound samples for the nearby area

      * Arguments:
        - Latitude: xsd:decimal, range +/- 90.0°
        - Longitude: xsd:decimal, range +/- 180.0°
        - Range: xsd:decimal, unit is km

      * Return values:
        - Statuscode: xsd:string, e.g. "OK" or "Error"
        - Message: xsd:string, human-readable message
        - SampleData: xsd:struct, a list with sample data (if any)
        - ResultCount: xsd:int, number of results returned

---

  * getNoiseLevels(Latitude, Longitude, Range)

      * Description:
          Get a list of noise levels recorded in the nearby area

      * Arguments:
        - Latitude: xsd:decimal, range +/- 90.0°
        - Longitude: xsd:decimal, range +/- 180.0°
        - Range: xsd:decimal, unit is km

      * Return values:
        - Statuscode: xsd:string, e.g. "OK" or "Error"
        - Message: xsd:string, human-readable message
        - NoiseLevels: xsd:struct, a list of noise levels (if any)
        - ResultCount: xsd:int, number of results returned

---

  * getAverageNoiseLevel(Latitude, Longitude, Range)

      * Description:
          Get the average noise level of nearby area

      * Arguments:
        - Latitude: xsd:decimal, range +/- 90.0°
        - Longitude: xsd:decimal, range +/- 180.0°
        - Range: xsd:decimal, unit is km

      * Return values:
        - Statuscode: xsd:string, e.g. "OK" or "Error"
        - Message: xsd:string, human-readable message
        - AverageNoiseLevel: xsd:int, unit is dB

---

  * getAverageNoiseLevelByZipCode(ZipCode)

      * Description:
          Get average noise level of postcode area

      * Arguments:
        - ZipCode: xsd:string, max. 10 characters

      * Return values:
        - Statuscode: xsd:string, e.g. "OK" or "Error"
        - Message: xsd:string, human-readable message
        - AverageNoiseLevel: xsd:int, unit is dB

==== General workflow ====

1. Upload a sound sample with the uploadSample() method.

2. Call getSamples() and provide your current location. You will get a list of IDs for sound samples in the nearby area.

3. Let's say one of the sample IDs was "foobar". You can now fetch the file from download.php?sid=foobar and do playback.

==== Geo coordinates ====

Geo locations are processed as decimal degrees [1], that is values from +/- 90.0° for latitude and +/- 180.0° for longitude. For example "53.834208, 10.700136" describes "latitude (north, south), longitude (west, east)" of the Audimax, UzL [2].

==== Neighbourhood discovery ====

To find nearby points of interest (POI), e.g. sound samples recorded in the neighbourhood, you can provide your current location and a range. Geo location must be given as decimal degrees, whereas the unit for range is km.

A value of 0.01 degree is equal to 1.11 km. So 1 km is on about 0.009 degrees.

==== References ====

[1] http://en.wikipedia.org/wiki/Decimal_degrees
[2] http://maps.google.com/?q=53.834208,10.700136&t=h&z=20