Voynex Media Guard: Control Protocol Specification

Version: 3.2.1

Preface

This document specifies data exchange between WMS plug-in and gateway (web server).

Voynex Media Guard assumes that user has two servers:

First server is a windows media server, which streams requested media content to its users. Windows media services and its plug-ins perform streaming, authorization and other server functions. Voynex Media Guard software includes media servises plug-in for users authorization and billing.
Second server is a gateway. It is targeted to perform clients authorization, statistics gathering or other operations needed .

These servers can be located at the same computer.

Gateway interconnects with Voynex Media Guard via application layer protocol based on HTTP. Thus gateway server has to incorporate functionality of the HTTP server. The most common implementation of the gateway looks like this: business logics is coded in CGI scripts, HTTP communication carried out by Web server and accounts related operations are performed by DBMS.

This documents describes communication protocol so this specification does not put any requirements on OS, DBMS and web server installed. So it can be either Linux-Apache-MySQL-PHP or Windows-IIS-MSSQL-ASP. This specification defines authorization steps, requests and responses to perform authorization of the WMS clients and statistics gathering.

Specification

Client's media player send connection request to the media server:

          mms:\\mediaserver\media.asf[?tail], where
            mediaserver - media server, where media services are installed,
            media.asf - requested resource name (title - video/audio),
            [tail - request parameters which may contain unique user identificator.]

Tail is transmitted to the gateway server unaltered (see the item 2), Voynex Media Guard plug-in does not modify it.

When Media Server receives client's request it notifies Voynex Media Guard plug-in on connect event. Plug-in sends request to the payment server. Plug-in requests user info and access rights:
```
          http:\\paymentserver\contoller.html?key=Password&[authorize=Method&]client=Id&ip=IpAddr&referer=URL&title=URL[&tail], where
            paymentserver - Payment Server,
            contoller.html - authorization page,
            key - password to access the page (string),
            authorize - authorization method (string) [optional],
            client - WMS user ID (number),
            ip - client IP address (dotted format),
            referer - HTTP referrer (URL),
            title - requested media resource name (URL),
            tail - tail (string) [optional]
       
```
Authorization method (authorize) is an optional parameter. It can be used to define the authorization method for the gateway to apply to all the clients coming from the particular mediaserver. This parameter makes sence when several media servers are used and various authorization methods have be applied to each server. Also it can be used for debug purposes or to switch authorization methods for the gateway without the need to modify the scripts.

WMS user ID (client) is the identificator of the user connected to WMS. This ID is assigned to client by WMS and is not guaranted to be unique.
Payment server sends response to the plug-in. Response contents information on new client.
```
          http:\\mediaserver
        
```
Gateway's response contains the following data:
```
         service={0|1|...}
         time={0,...,n}, where
           service - service type:
             0 - Default service (not used),
             1 - Reserved for Pay-per-minute,
           Service numbers > 1 are not used by the plug-in and can be defined by the gateway for its own needs.
           For example, the following service types can be defined in addition to Pay-per-minute:
           time - purchased (paid) time (T_paid).
        
```
Time measured in SECONDS. If time = 0, then access media content will be denied.

The name of the parameter is case insensitive. Thus 'service', 'SERVICE', 'Service' means the same parameter. Parameters can be located anywhere in the body of the HTTP response and delimited by any non-digital characters. Parameters' order is significant. Parameters have to appear in the response in the same order as listed above.
If pay-per-minute service type is used, plug-in decrements time value. When time value reaches zero, plug-in sends authorization request to payment gateway. Authorization request is sent each time when the number of the time units for the user reaches zero. In respose to the authorization request getaway returns information on the existing client. Possibly this information was updated during playback. For example client can purchase additional time. So steps 2 and 3 are repeated.
When user closes media title in the player, plug-in sends statistical data to the payment server:
```
          http:\\paymentserver\statistics.html?key=Password&ip=IpAddr&played=Num&streamed=Num&sent=Num[&tail], where
            paymentserver - Payment server,
            statistics.html - HTML page where statistical data sent,
            key - password to access the page (string),
            client - WMS user ID (number),
            ip - client IP address (dotted format),
            played - time of the media playback T_played (number),
            streamed - time equivalent of data amount streamed to the client T_streamed (number),
            sent - amount of data sent to client (number)
            tail - tail (string) [optional],
       
```
Time measured in SECONDS, data in BYTES.

It is always true that T_played ≤ media title's duration. Usually T_streamed > T_played. It happens because T_streamed includes time needed for buffering. But for example Windows Media Player downloads media data and playbacks it simultaneously. Thus if the bandwidth of the client's connection exceeds the bandwidth needed for non-buffered media playback, media is downloaded faster then it played. In this case T_streamed ≤ T_played
Example: Windows Media Player plays the 1st minute of a clip, but 3 minutes of this clip was downloaded to the client.

The developer of the business logics of the gateway can chose which time parameter will be used for billing.

Voynex Media Guard Plug-in increments T_played during playback and disconnects client if T_played > T_paid.