How to talk with the server over the network

- HTTP protocol, port 4962

- Get list of recorded videos:
  - URL /recorded/list/
  - returns XML
    <?xml version="1.0" encoding="UTF-8"?>
    <recordings>
      <recording done="true" recordingid="1234"> 
        <title>Stirb langsam</title>
        <subtitle></subtitle>
        <originaltitle>Die Hard</originaltitle>
        <originalsubtitle></originalsubtitle>
        <description>Classical action movie
          A cross-thinking cop shows bravery when the headquarters of his wife's company gets hijacked by terrorists during a party.
          Not much of the skyscraper nor the terrorists remain intact once Bruce is done.</description>
        <genre>Actionfilm</genre>
        <showtype name="movie" />
        <firstshown year="1950" />
        <location storename="machine1" url="http://machine1/recorded/video/1234" />
        <preview type="image" sizetype="full" storename="machine1"
                 url="http://machine1/recorded/preview/image/full/1234" />
        <management seen="true" keep="true" />
      </recording>
      ...
    </recordings>
  - supports URL query parameters:
    - sortBy=<field> (SQL ORDER BY)
    - sortDir=desc/asc
    - onlyOnePer=<field> (SQL GROUP BY),
      e.g. onlyOnePer=title returns only one record for each title 
    - filter=
      expression:
        - <expression>-and-<expression>
        - <expression>-or-<expression>
        - <tuple>
      tuple: <field>-<operator>-<literal>
      - operator:
        - eq : equals (==)
        - like : string wildcard (SQL LIKE)
        - lt : lesser than (<)
        - gt : greater than (>)
        - future : in the future (> NOW())
      - literal: integer, string or true/false
    - fields:
       id, title, subtitle, originaltitle, originalsubtitle,
       showtype, genre,
       qualityrating, firstshown,
       seen, deleted, orderrecorded
  - implemented by RecordingsListingProvider.java

- Get preview image for recording:
  - URL /recorded/preview/image/full/<recordingid>
    (URL as returned by /recorded/list )
  - returns a JPEG image of same size as video resolution
  - implemented by LocalPreviewImageProvider.java

- Get recorded video:
  - URL /recorded/video/<recordingid>
    (URL as returned by /recorded/list )
  - returns the video stream (as HTTP result body)
  - HTTP Range: is supported, to allow skipping/seeking
  - implemented by LocalRecordingsProvider.java

- Get video from a TV card:
  - URL /device/start/<deviceid>
  - URL /device/stop/<deviceid> (must be called when done)
  - HTTP header "channel-id: <channelid>" - which channel to record
  - HTTP header "target-caller: true" instructs to
    return the stream as HTTP result body
    (alternative would be to let the server open a stream to a third party
    and send the data there, e.g. to a store-only server)
  - returns the video stream (as HTTP result body, if target-caller=true)
  - implemented by TVCardProvider.java, used by RemoteTVRecorder.java

- Arbitrary video stream
  - URL /stream/<autoid>
  - implemented by RemoteTarget.java, used by RemoteSource.java
  - TODO needed?
  - TODO naming of classes is confusing

- Delete recording
  - URL /recorded/management/delete/<recordingid>
  - implemented by RecordingsManagementProvider.java, used by client
  - Deletes the file on disk, and marks the recording as deleted in DB.

- Mark recording as seen, keep etc.
  - URL /recorded/management/mark/<recordingid>?seen=true
  - URL /recorded/management/mark/<recordingid>?mark=true
  - URL /recorded/management/mark/<recordingid>?seen=true/false&keep=true/false
  - implemented by RecordingsManagementProvider.java, used by client
  - seen = user has watched the video
    Preview or watching only a short part of it does not count as "seen",
    unless user manually marks it so.
  - keep = don't touch
    Do not delete when disk space is low.
    Do not delete when it has been re-recorded with a higher quality
    (which runs the risk that the new recording failed without Zeipis noticing).
    To be used by user manually, when he really likes a recording
    and does not want to lose it under any circumstance.

-----------------------------------
  
  
Generic protocol, replacement for UPnP AV:

- TODO: server discovery. ZeroConf/Rendevous? Login?

- Get list of all videos
  - HTTP URL /content/list/all/
  - returns XML
    <?xml version="1.0" encoding="UTF-8"?>
    <contents describes="/content/list/all/">
      <content id="1234">
        <type mimetype="video/mpeg" />
        <title>Stirb langsam</title>
        <subtitle></subtitle>
        <original-title>Die Hard</original-title>
        <original-subtitle></original-subtitle>
        <description>Classical action movie
          A cross-thinking cop shows bravery when the headquarters of his wife's
          company get hijacked by terrorists during a party.
          Not much of the skyscraper nor the terrorists remain intact once Bruce
          is done.</description>
        <genre>Actionfilm</genre>
        <showtype name="movie" />
        <first-shown year="1950" />
        <location store-name="Computer 1" url="http://machine1/recorded/video/1234" />
        <preview type="image" sizetype="full"
                 url="http://machine1/recorded/preview/image/full/1234" />
        <management seen="true" keep="true" />
      </content>
      ...
    </contents>

- Get directories/groups
  - HTTP URL /content/group/root/
  - returns XML
    <?xml version="1.0" encoding="UTF-8"?>
    <contents describes="/content/group/root/">
      <content id="1234">(as above)</content>
      <group-ref title="Movies" url="/content/group/movies/" />
      <group-ref title="Series" url="/content/group/series/" />
      <group-ref title="Live TV" url="/content/group/channels/" />
      ...
    </contents>
  - root URL is fixed, other URLs as specified by <group-ref url="" />.

- Get preview image for video:
  - HTTP URL /content/preview/image/full/<id>
    (URL as returned by /content/list/ )
  - returns a JPEG image of same size as video resolution

- Get video:
  - HTTP URL /content/deliver/<id>
    (URL as returned by /content/list/ )
  - returns the video stream (as HTTP result body)
  - HTTP Range: is supported, to allow skipping/seeking

- Get video from a TV card:
  - HTTP URL /device/start/<deviceid>?channel=channelid
    (URL as returned by /content/list/ )
  - returns the video stream (as HTTP result body)
  - HTTP Range: may not be supported
    (no seek possible, unless server buffers to harddisk)
