DVBLink Client API

Version 0.1

Introduction

DVBLink Client API is a set of function calls that allows building a custom DVBLink client. The API uses http transactions with xml-structured parameters.

As a prerequisite DVBLink Clinet API requires installation of DVBLink Connect! Server on the server system.

 

Supported stream types

The following stream types are supported:

-       Raw transport stream via UDP

-       HLS (IPhone-type stream)

-       ASF (windows media stream)

-       Transport stream with mpeg-4 video and AAC audio over RTSP (android)

-       Raw transport stream via HTTP

Direct vs Indirect http streaming

Raw transport stream via HTTP can be request either directly or indirectly.

Indirect stream request works via play_channel API function and will be discussed later in this document.

Direct HTTP stream can be requested via url of the following format:

 

http://<server ip>:<server port>/dvblink/direct?client=<client_id>&channel=<channel_id>

 

where

-       <server ip> - IP address of DVBLink server

-       <server port> - base streaming port of DVBLink server (default – 8080)

-       <client_id> - a unique id of the client that requests a stream. Can be any string of alphanumeric characters without spaces as long as it is unique – a guid for example

-       <channel_id> - DVBLink channel id. You can find it under <frequency> tag in dvblink_channel_storage.xml for each channel. It is a long number – something like 10010000

 

For example:

http://192.168.0.100:8080/dvblink/direct?client=AAABBBCCC&channel=10460000

Authentication

DVBLink Connect! Server requires basic HTTP authentication with user name and password.

Generic request format

Request has to be sent using POST command to the following http address:

http://<server ip>:<server port>/cs/

 

Where

-       <server ip> - IP address of DVBLink server

-       <server port> - base port of DVBLink server

 

 

The following parameter string has to be POSTed:

command=<dvblink command>&xml_param=<xml data>

 

Where

-       <dvblink command> - function to perform (see below for the list of functions)

-       <xml data> - function dependent set of parameters in xml format

Generic response format

Response is sent in xml format with the following generic structure:

 

<response xmlns="http://www.dvblogic.com">

            <status_code/>

             <xml_result/>

</response>

 

Where

-       <status_code/> - mandatory field of integer type. Can have the following values:

o   STATUS_OK = 0

o   STATUS_ERROR = 1000

o   STATUS_INVALID_DATA = 1001

o   STATUS_INVALID_PARAM = 1002

o   STATUS_NOT_IMPLEMENTED = 1003

o   STATUS_MC_NOT_RUNNING = 1005

o   STATUS_MC_NOT_RUNNING = 1005

o   STATUS_NO_DEFAULT_RECORDER = 1006

o   STATUS_MCE_CONNECTION_ERROR = 1008

-       <xml_result/> - contains function specific result information (optional)

Content-Type and encoding

POST requests should pass parameters in the body in a URL-encoded form, and use Content-Type application/x-www-form-urlencoded

 

Response is sent back using UTF-8 encoding.

Date/time type

All date/time parameters, used in xml structures, have long type. They are number of seconds, counted from UNIX epoc: 00:00:00 UTC on 1 January 1970.

All duration parameters have long type and are expressed in seconds.

Schedules and recordings

DVBLink recording functionality operates in terms of schedules and recordings.

Schedule defines a rule what has to be recorded. The following examples can be considered: “Record all series of a particular EPG program” or “Record a program on a channel 12 every day from 14:00 until 15:00”.

Each schedule produces a number (zero or more) of recordings – these are actual tasks to do the recording. The second example above will produce a recording for each day on channel 12 starting at 14:00 until 15:00.

 

DVBLink commands

DVBLink Connect! Server implements the following commands:

  1. get_channels
  2. play_channel
  3. stop_channel
  4. search_epg
  5. get_recordings
  6. add_schedule
  7. remove_schedule
  8. remove_recording
  9. set_parental_lock
  10. get_parental_status

 

Function get_channels

 

DVBLink command

get_channels

 

Request xml data

<?xml version="1.0" encoding="utf-8" ?>

<channels xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.dvblogic.com" />

 

Response xml_result

<?xml version="1.0" encoding="utf-8" ?>

<channels xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

                  xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.dvblogic.com">

   <channel>

            <channel_id/> - string mandatory

            <channel_dvblink_id/> - long mandatory

            <channel_name/> - string mandatory

            <channel_number/> - int optional

            <channel_subnumber/> - int optional

   </channel>

   …

</channels>

 

Notes:

-       <channel_id> is a generic channel identifier used in all other commands that perform operations on the channel(s). The exception is play_channel command that uses <channel_dvblink_id> to play channel.

Function play_channel

 

DVBLink command

play_channel

 

Request xml data

<?xml version="1.0" encoding="utf-8" ?>

<stream xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.dvblogic.com">

            <channel_dvblink_id/> - long mandatory

            <client_id/> - string mandatory

            <stream_type/> - string mandatory (rtp, hls, asf, raw_http, raw_udp)

            <server_address/> - string mandatory

            <client_address/> - string optopnal (used for raw_udp)

            <streaming_port/> - ushort optinal (used for raw_udp)

            <transcoder> - optional

                        <height/> - uint mandatory

                        <width/> - uint mandatory

                        <bitrate/> - uint optional

                        <audio_track/> - string optional

            </transcoder>

            <duration/> - long optional

</stream>

 

Notes:

-       <channel_dvblink_id> is a DVBLink specific channel identifier

-       <client_id> is the unique identification string of the client. Should be the same across all DVBLink Client API calls from a given client. Can be a uuid for example or id/mac of the client device

-       <stream_type> is the type of requested stream. The following values are supported: “rtp”, “hls”, “asf”, “raw_http”, “raw_udp”

-       <server_address> - ip address/server network name of the DVBLink server

-       <transcoder> is optional element, defining the parameters of transcoded stream. It is used for certain stream types, namely rtp, hls and asf.

o   <height> is height in pixels of the transcoded video stream

o   <width> is width in pixels of the transcoded video stream

o   <bitrate> is bitrate in kilobits/sec of the transcoded video stream

o   <audio_track> is ISO-639 language code that is used to choose a particular audio track for transcoding

-       <duration> is the timeout until channel playback is stopped by a server (indefinite if not specified)

-       If <stream_type> is “rtp”, “hls” or “asf” then <transcoder> element must be present

 

 

Response xml_result

<?xml version="1.0" encoding="utf-8" ?>

<stream xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.dvblogic.com">

            <channel_handle/> - long mandatory

            <url/> - string mandatory

</stream>

 

Notes

-       <channel_handle> is the channel handle of a playing channel. It should be used in stop_channel command to stop stream. Attention, if stream is not stopped server will play it indefinitely (unless it has a client disconnect detection mechanism for a particular protocol).

-       <url> is the uri that client can use to read the stream.

-       There can be more than one stream started for the same <client_id>. Each stream will have its own handle and should be stopped separately. Alternatively client can stop all its streams at once using <client_id> parameter for stop_channel command.

-       Server has client disconnect detection functionality implemented for a number of protocols, namely: “rtp”, “hls”, “asf” and “raw_http”

 

 

Function stop_channel

 

DVBLink command

stop_channel

 

Request xml data

<?xml version="1.0" encoding="utf-8" ?>

<stop_stream xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.dvblogic.com">

            <channel_handle/> - long mandatory

               or

            <client_id/> - string mandatory

</stop_stream>

 

Notes

-       Function stop channel playback for a particular channel handle (if <channel_handle> is supplied as a parameter) or for all client’s streams (if <client_id> is supplied as a parameter)

 

Response xml_result

Response contains only <status_code>

 

Function search_epg

 

DVBLink command

search_epg

 

Request xml data

<?xml version="1.0" encoding="utf-8" ?>

<epg_searcher xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.dvblogic.com">

            <channels_ids> - mandatory

                        <channel_id/>   - string mandatory

                        ...

            </channels_ids>

            <program_id/> – string optional

            <keywords/>   - string mandatory

            <start_time/> – mandatory long

            <end_time/> – mandatory long

      

            <epg_short/> – optional bool (ïî óìîë÷àíèþ false)

</epg_searcher>

 

Notes

-       Request should include at least on channel identifier (<channel_id> to search the epg data for

-       Search can be done on the following criteria:

o   Channel ids: returns all programs for the specified channels

o   Program id: returns information about a particular program

o   Keywords (or better to say a keyphrase): returns all programs that have the provided keyphrase in their title or short description

o   Start/end time: returns all programs that fully or partially fall into a specified time span. One of the parameters (<start_time> and <end_time> may be -1, meaning that search is not bound on that side)

-       Some of the search criteria can be combined:

o   Program id search is always exclusive to keyphrase and start/end time searches

o   Search results are combined on AND principles

-       <epg_short> flag specifies the level of returned EPG information (allows for faster EPG overview build up). Short EPG information includes only program id, name, start time, duration and genre info.

 

Response xml_result

<?xml version="1.0" encoding="utf-8" ?>

<epg_searcher xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.dvblogic.com">

            <channel_epg> - optional

                        <channel_id/> - string mandatory

                        <dvblink_epg> - mandatory

                                   <program> - mandatory

                                               <program_id – string mandatory

                                               <name/> — string mandatory

                                               <start_time/> — long mandatory

                                               <duration/> — long mandatory


                                               string optional:

                                               <short_desc/>

                                               <subname/>

                                               <language/>

                                               <actors/>

                                               <directors/>

                                               <writers/>

                                               <producers/>

                                               <guests/>

                                               <categories/>

                                                <image/>

 

                                               long optional:

                                               <year/>

                                               <episode_num/>

                                               <season_num/>

                                               <stars_num/>

                                               <starsmax_num/>

 

                                               Optional.true if tag is present, false otherwise:

                                               <hdtv/>

                                               <premiere/>

                                               <repeat/>

                                               <cat_action/>

                                               <cat_comedy/>

                                               <cat_documentary/>

                                               <cat_drama/>

                                               <cat_educational/>

                                               <cat_horror/>

                                               <cat_kids/>

                                               <cat_movie/>

                                               <cat_music/>

                                               <cat_news/>

                                               <cat_reality/>

                                               <cat_romance/>

                                               <cat_scifi/>

                                               <cat_serial/>

                                               <cat_soap/>

                                               <cat_special/>

                                               <cat_sports/>

                                               <cat_thriller/>

                                               <cat_adult/>

                                               <is_record/>

                                               <is_series/>

                                               <is_repeat_record/>

                                   </program>

                                   ...

                        </dvblink_epg>

            </channel_epg>

            …

</epg_searcher>

 

Function add_schedule

DVBLink command

add_schedule

 

Request xml data

<schedule xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.dvblogic.com">

            <user_param/> - string optional

            <force_add/> - bool optional

 

            <by_epg> - mandatory

                        <channel_id/> - string mandatory

                        <program_id/> - string mandatory

                        <repeat/> - bool optional

            </by_epg>

               or

            <manual> - mandatory

                        <channel_id/> - string mandatory

                        <title/> - string optional

                        <start_time/> - long mandatory

                        <duration/> - long mandatory

                        <day_mask/> — long mandatory (DAY_MASK_SUN = 1,

                                                                           DAY_MASK_MON = 2,

                                                                           DAY_MASK_TUE = 4,

                                                                           DAY_MASK_WED = 8,

                                                                           DAY_MASK_THU = 16,

                                                                           DAY_MASK_FRI = 32,

                                                                           DAY_MASK_SAT = 64,

                                                                           DAY_MASK_DAILY = 255)

            </manual>

</schedule>

 

Notes

-       New schedules can be added either manually or based on a certain EPG program (<manual> or <by_epg>)

-       <force_add> flag indicates that new schedule should be added even if there are other conflicting schedules present

 

Response xml_result

Response contains only status_code.

Function get_recordings

DVBLink command

get_recordings

 

Request xml data

<?xml version="1.0" encoding="utf-8" ?>

<recordings xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.dvblogic.com"/>

 

Response xml_result

<recordings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.dvblogic.com">

            <recording>

                        <recording_id> - mandatory

                        <schedule_id> - mandatory

                        <channel_id> - mandatory

                        <is_active> - optional

                        <program> - mandatory

 

                        The same fields as for <program> element in <search_epg> function

 

                        </program>

            <recording>

</recordings>

 

Function remove_schedule

DVBLink command

remove_schedule

 

Request xml data

<remove_schedule xmlns:i="http://www.w3.org/2001/XMLSchema-instance"                                          xmlns="http://www.dvblogic.com">

            <schedule_id/> - string mandatory

</remove_schedule>

 

Response xml_result

Response contains only status_code.

 

Function remove_recording

DVBLink command

remove_recording

 

Request xml data

<remove_recording xmlns:i="http://www.w3.org/2001/XMLSchema-instance"                 xmlns="http://www.dvblogic.com">

            <recording_id/> - string mandatory

</remove_recording>

 

Response xml_result

Response contains only status_code.

 

Function set_parental_lock

DVBLink command

set_parental_lock

 

Request xml data

<parental_lock xmlns:i="http://www.w3.org/2001/XMLSchema-instance"             xmlns="http://www.dvblogic.com">

            <client_id/> string mandatory

            <is_enable/> bool mandatory, true – enable parental lock, false – disable parental lock

            <code/> string mandatory if is_enable = false

</parental_lock>

 

 

Response xml_result

<parental_status xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.dvblogic.com">

            <is_enabled/> - bool mandatory

</parental_status>

 

Function get_parental_status

DVBLink command

get_parental_status

 

Request xml data

<parental_lock xmlns:i="http://www.w3.org/2001/XMLSchema-instance"             xmlns="http://www.dvblogic.com">

            <client_id/> string mandatory

</parental_lock>

 

Response xml_result

<parental_status xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.dvblogic.com">

            <is_enabled/> - bool mandatory

</parental_status>