[mythtv] API Framework has been committed (May break existing users of mythXML).

[David Blain]

For those not following IRC, I committed the API Framework last night.

 
https://github.com/MythTV/mythtv/commit/856b61b5378c4b6d8bd60638f86606e76036
54ef

A few things to note:

*** THIS CHANGE MAY BREAK ANYONE USING OLD MYTHXML CALLS. ***

In order to have a standard way to serialize objects, some of the data
returned has been rearranged.  Also, I took this opportunity to re-organize
the methods and have separated them into these categories (each being its
own API Class):

    Myth 	- Contains utility functions
    Guide	- Program Guide Methods
    Dvr		- Recording/tv related methods
    Content	- Content Retrieval
    Myth 	- Yes, there are two services that use this...  MythXml
still has the GetInternetXXXX functions unchanged.

 ( the status page / status xml has not been changed at this time )

How to access -
--------------------------
Call each method using a URL formatted as:
    http://<backend>:6544/<API Class Name>/<Method>

Methods default to responding to GET requests, however some have been
configured to respond only to POST. 
 (i.e. PutSetting will only work if called with a POST)  Any method that
modifies files/data should be limited to POST requests.  This is done in the
service class definition.

Parameters can be supplied on the query string, or as  form post data
(Content-Type: application/x-www-form-urlencoded).

The code currently supports 3 data formats: XML, SOAP & json.

XML 	- The default. 
SOAP 	- Returned if the request contains a SOAP envelope and required
headers. 
Json 	- Returned if the request header has an Accept value of
"application/json" or "text/javascript".

Other formats can be implemented without changes to the API or Data Classes.

Details -
--------------------------
A new library has been added (libmythservicecontracts), which contains all
the data classes and the abstract (pure virtual/interface) class definitions
for each of the API classes .

Services - 
--------------------------
Each service class is defined as a pure virtual class.  It must be derived
from "Service", and declare the Q_OBJECT macro.  It shouldn't have any
implementation in it and should be treated solely as an Interface.  Although
this is not a requirement of the Framework, I chose this design  to allow
the creation of client proxy classes, (none have been created at this point)
and can inherit from these base classes to provide a way to isolate the
definition from the implementation.

Each method can take any number/type of parameters.  The parameter names
used in the method prototype is what ultimately will be used when making
service calls.  Currently, only simple types are supported as parameters,
but there are hooks in place to hopefully support complex parameters in the
future.

It is a requirement of each method to return a QObject* derived object, a
pointer to a QFileInfo*, or a QVariant.  If it's a QObject*, only properties
declared using Q_PROPERTY will be serialized to the calling client.

DataContracts -
--------------------------
DataContracts are data classes designed specifically to be used to return
complex data from service methods.  They are currently contained in a DTC
namespace to help with naming conflicts.

There are numerous macros to help with the implementation.  It's important
that these classes only store data and do not offer any functionality.   If
one data class contains pointers to other data classes (an object
hierarchy), each child object must be created with the current object as
it's parent so that when the parent gets deleted, all it's children will as
well.

Implementation - 
--------------------------
The actual implement of all the service/api classes is currently in
mythbackend (this may change in the future).

The classes/methods can be freely used directly by any part of the
application, so as the number of methods increase, duplicate functionality
can be removed from other parts of the system.

Here is an inventory of current methods:
--------------------------

Base URL - http://mythbackend:6544/Myth/

  Methods -

     GetConnectionInfo
     GetHosts
     GetKeys
     GetSetting
     PutSetting

    *GetInternetSearch
    *GetInternetSources
    *GetInternetContent

  * These methods are still implemented in MythXml using legacy approach.

Base URL - http://mythbackend:6544/Guide/

  Methods -

     GetProgramGuide
     GetProgramDetails
     GetChannelIcon

Base URL - http://mythbackend:6544/Dvr/

  Methods -

     GetExpiring
     GetRecorded
     Encoders

Base URL - http://mythbackend:6544/Content/

  Methods -

     GetFile
     GetFileList
     GetVideoArt
     GetAlbumArt
     GetPreviewImage
     GetRecording
     GetMusic
     GetVideo
	
I think this e-mail is long enough... let me know if you have any questions
or find any issues.
	
David Blain