Webservices
===========
Sebastien RAILLARD and Brice DUBOST

To activate the webservices, just enable the unicast mode with something like that:
----------------
unicast=1         : Activate the internal webserver
ip_http=127.0.0.1 : IP address for accepting the HTTP requests
port_http=8005    : Listening port
----------------

[NOTE]
When you use several card on one server you can use the template `%card` for the listening port. Ex: `port_http=4000+%card`. Ports higher than 1024 can be used by unprivileged users.

The webservices responses are not SOAP compliant, but formatted in simple XML documents (UTF-8) or in JSON.
The output can be easily parsed in PHP for example.

Status monitoring :
-------------------

There is no input parameters.
URL : http://ip_http:port_http/monitor/state.xml

Example of response with comments:

----------------
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mumudvb card="5" frontend="0">                                          => adapter and frontend devices
	<card_path>/dev/dvb/adapter5</card_path>                             => card device path
	<global_version><![CDATA[1.6.1b_20101101]]></global_version>         => MuMuDVB version
	<global_pid>19574</global_pid>                                       => process PID
	<global_uptime>45</global_uptime>                                    => process uptime in seconds
	<frontend_name><![CDATA[ST STV0299 DVB-S]]></frontend_name>          => frontend name
	<frontend_tuned>1</frontend_tuned>                                   => 0 if adapter not tuned, 1 if adapter is tuned
	<frontend_frequency>11856000</frontend_frequency>                    => tuning frequency (always in kHz)
	<frontend_polarization><![CDATA[V]]></frontend_polarization>         => "-" if polarization isn't applicable, or "V" (Vertical), "H" (Horizontal", "L" (Left), "R" (Right)
	<frontend_symbolrate>27500000</frontend_symbolrate>                  => Satellite symbole rate in symbols per second (or 0 if not applicable)
	<frontend_system><![CDATA[DVB-S]]></frontend_system>                 => System used : "DVB-C", "DVB-T", "DVB-S", "DVB-S2", "ATSC"
	<frontend_status><![CDATA[SCVYL]]></frontend_status>                 => Tuner lock status: "S"/"-" (Signal), "C"/"-" (Carrier), "V"/"-" (Viterbi), "Y"/"-" (Synchro), "L"/"-" (Locked)
	<frontend_ber>0</frontend_ber>                                       => RAW BER value from driver (unsigned 16-bits integer)
	<frontend_signal>56955</frontend_signal>                             => RAW Signal level value from driver (unsigned 16-bits integer)
	<frontend_snr>54759</frontend_snr>                                   => RAW Signal to noise ratio from driver (unsigned 16-bits integer)
	<autoconfiguration>2</autoconfiguration>                             => Autoconfiguration status 0: none, 2: full
	<autoconfiguration_detected_parameters>                              => Part displayed only when autoconfiguration is enabled
		<transport_stream_id>2</transport_stream_id>                     => Transport stream id
		<network_id>8442</network_id>                                    => network id (see ts_10261102v010201p.pdf p14 and ts_101162v010701p.pdf p18 p19)
		<original_network_id>8442</original_network_id>                  => original network id (see ts_10261102v010201p.pdf p14 and ts_101162v010701p.pdf p18 p19)
		<pat_version>19</pat_version>                                    => Version of the PAT PID
		<sdt_version>2</sdt_version>                                     => Version of the SDT PID
		<nit_version>28</nit_version>                                    => Version of the NIT PID
		<psip_version>0</psip_version>                                   => Version of the PSIP PID (ATSC only)
	</autoconfiguration_detected_parameters>                             =>
	<autoconfiguration_finished>1</autoconfiguration_finished>			 => 0 if not autoconfiguration or autoconfiguration in progress, 1 if autoconfiguration is finished
	<cam_support>1</cam_support>                                         => 0 if no CAM support asked, 1 if CAM support was asked
	<cam_number>0</cam_number>                                           => CAM slot number
	<cam_menustring><![CDATA[Not retrieved]]></cam_menustring>           => When CAM is initialized, CAM model
	<cam_initialized>0</cam_initialized>                                 => 0 if CAM isn't initialized, 1 if CAM is initialized

	<channel number="1">                                                 => Loop over channels, one node per channel, with MuMuDVB internal id (starting at 1)
		<lcn>0</lcn>                                                     => If present, Channel Logical Number (Channel number)
		<name><![CDATA[CANAL+]]></name>                                  => Channel name
		<service_type type="1"><![CDATA[Television]]></service_type>     => See function "service_type_to_str" in "log.c" file for complete description
		<ip_multicast><![CDATA[0.0.0.0]]></ip_multicast>                 => Multicast IP address (0.0.0.0 if multicast is disabled)
		<port_multicast>0</port_multicast>                               => Multicast UDP port (0 if multicast is disabled)
		<is_up>0</is_up>                                                 => 0 if channel is not streamed, 1 if channel is streamed
		<traffic>7</traffic>                                             => Channel streamed IP bandwidth in kB (kilo-Bytes) per second
		<ratio_scrambled>99</ratio_scrambled>                            => Percentage of scrambled packets received
		<service_id>8201</service_id>                                    => Service ID of channel
		<pmt_pid>1280</pmt_pid>                                          => PMT PID of channel
		<pmt_version>1</pmt_version>                                     => The version of the PMT PID in the TS stream
		<pcr_pid>160</pcr_pid>                                           => PCR PID of channel
		<unicast_port>0</unicast_port>                                   => Unicast port associated with the channle if unicast is setup by port
		<ca_sys>                                                         => Loop over all the CA systems listed in the PMT for the channel
			<ca num="256"><![CDATA[Canal Plus]]></ca>                    => CA identifier and description if avaliable
		</ca_sys>                                                        => End of CA systems loop
		<pids>                                                           => Loop over all PID related to the channel and declared in the PMT
			<pid number="1280" language="---"><![CDATA[PMT]]></pid>      => PID number, Language associated (or "---" if no language associated), PID description if avaliable
			<pid number="160" language="---"><![CDATA[Video (MPEG2)]]></pid>
			<pid number="80" language="fra"><![CDATA[Audio (MPEG2)]]></pid>
			<pid number="81" language="eng"><![CDATA[Audio (MPEG2)]]></pid>
			<pid number="32" language="---"><![CDATA[Teletext]]></pid>
			<pid number="82" language="fra"><![CDATA[Audio (AC3)]]></pid>
			<pid number="83" language="eng"><![CDATA[Audio (AC3)]]></pid>
		</pids>                                                          => End of PID loop
		<clients count="1">                                              => Loop over unicast clients
		    <client number="0">                                          => Client Information
			  <socket>80</socket>                                        => Local socket FD
			  <remote_address><![CDATA[192.168.0.54]]></remote_address>  => Remote IP address of the client
			  <remote_port>438754</remote_port>                          => Remote port
			  <buffersize>0</buffersize>                                 => Client Buffer
			  <consecutive_errors>0</consecutive_errors>                 => Count of consecutive errors when writing to this client
			  <first_error_time>1411392479</first_error_time>            =>
			  <last_error_time>0</last_error_time>                       =>
			</client>                                                    => End of Client.
		</clients>                                                       => End of clients loop
	</channel>                                                           => End of channels loop
</mumudvb>                                                               => End of response
----------------

JSON files:
~~~~~~~~~~~

You can get similar information in the JSON files

* `http://ip_http:port_http/channels_list.json`
* `http://ip_http:port_http/monitor/signal_power.json`
* `http://ip_http:port_http/channels_traffic.json`
* `http://ip_http:port_http/monitor/state.json`


Access to the CAM menu:
-----------------------

These two webservices allow for accessing the CAM menu during streaming.
This is usefull for checking rights or download status for example.


The file `cam_menu.php` is a simple demonstration on how to use these webservices in order to make a web interface with AJAX compatible with the most important browsers (Firefox, Chrome, Internet Explorer).

For using it, you just need a webserver (lighttpd, apache, etc.) with PHP activated.
The web page accept one GET parameter: `port_server`. This is the unicast port setup for accessing MuMuDVB webservices.

The CAM menu is refresded every 2 seconds and buttons can be used to navigate in the menus.
MENU, LIST and ENQUIRY MMI objects are supported.

 * First webservice return the latest menu returned by the CAM.
There is no input parameters.
URL : http://ip_http:port_http/cam/menu.xml
Below, some examples of response with comments.

Case when the CAM isn't initialized:
----------------
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

	<datetime><![CDATA[Mon Nov  1 22:08:17 2010]]></datetime>  => Last update time/date
	<![CDATA[NONE]]>                          => No object to show
	<![CDATA[CAM not initialized!]]>            => Message about CAM not initialized

----------------

Case when the CAM is initialized but there is no menu to display:
----------------
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

	<datetime><![CDATA[Tue Nov  2 22:38:37 2010]]></datetime>       => Last update time/date
	<cammenustring><![CDATA[Aston Module 2.1800]]></cammenustring>  => CAM model
	<![CDATA[NONE]]>                               => No object to show
	<![CDATA[No menu to display]]>                   => Message about no menu to display

----------------
Case when a object is send by the CAM to be displayed:
----------------
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

	<datetime><![CDATA[Tue Nov  2 22:39:58 2010]]></datetime>       => When the object was received
	<cammenustring><![CDATA[Aston Module 2.1800]]></cammenustring>  => CAM model
	<![CDATA[MENU]]>                               => Object: "MENU", "LIST" or "ENQUIRY"
	<![CDATA[Module Aston]]>                         => Object title
	<subtitle><![CDATA[Carte num ro 544.193.724]]></subtitle>       => Object subtitle (when an "ENQUIRY" object is display, show the number of characters expected in the answer)
	<item num="0"><![CDATA[Return]]></item>                         => For "MENU" and "LIST" objects, contain the lines of information or the items to be choosen. The "num" attribute correspond to the key to press to choose the item.
	<item num="1"><![CDATA[Consultation des droits]]></item>
	<item num="2"><![CDATA[R glages]]></item>
	<item num="3"><![CDATA[Information]]></item>
	<bottom><![CDATA[Votre choix, svp]]></bottom>                   => Object bottom line

----------------

 *  Second webservice allows for sending response to the CAM.
There is one integer GET paramter: `key`.
Possible keys: `0` to `9` (numbers), `M` for asking the CAM menu, `C` for cancelling an `ENQUIRY` object.
URL : http://ip_http:port_http/cam/action.xml?key=X
There are 4 king of responses.

OK:
----------------
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<action>
	<datetime><![CDATA[Mon Nov  1 22:13:30 2010]]></datetime>
	<key><![CDATA[X]]></key>
	<result><![CDATA[OK]]></result>
</action>
----------------

Unknown key:
----------------
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<action>
	<datetime><![CDATA[Mon Nov  1 22:13:30 2010]]></datetime>
	<key><![CDATA[X]]></key>
	<result><![CDATA[ERROR: Unknown key!]]></result>
</action>
----------------

CAM not initialized:
----------------
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<action>
	<datetime><![CDATA[Mon Nov  1 22:13:30 2010]]></datetime>
	<key><![CDATA[X]]></key>
	<result><![CDATA[ERROR: CAM not initialized!]]></result>
</action>
----------------

MuMuDVB compiled without CAM support:
----------------
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<action>
	<datetime><![CDATA[Mon Nov  1 22:13:30 2010]]></datetime>
	<key><![CDATA[X]]></key>
	<result><![CDATA[Compiled without CAM support]]></result>
</action>
----------------


Electronic program guide
------------------------

The content of the EIT table (electronic programs guide) is now available via the Webservices.

To enable it, put `store_eit=1` in your configuration file and get the file: 

* `http://ip_http:port_http/monitor/EIT.json`


The structure follow the structure of the data descriptors of the DVB
stream, so please consult the norm `EN 300 468` if you want to get more
info see http://www.mumudvb.net/node/39[documentation].

An example result is available http://www.mumudvb.net/doc/EIT/EIT_TNT_PARIS_20141209.json[here].







