Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: MythTV: Dev

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

 

 

MythTV dev RSS feed   Index | Next | Previous | View Threaded


MythTv at TheBlains

Mar 9, 2011, 8:26 AM

Post #1 of 13 (2849 views)
Permalink
API Framework has been committed (May break existing users of mythXML).

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

_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


gnassas at mac

Mar 9, 2011, 8:54 AM

Post #2 of 13 (2755 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

On 2011-03-09, at 11:26 AM, David Blain wrote:

> 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.

I hope I didn't miss an announcement somewhere but is this intended to replace the myth protocol in the fullness of time? The archives have a few mentions of mythXML but they don't say one way or the other.

- George

_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


stuart at tase

Mar 9, 2011, 9:16 AM

Post #3 of 13 (2761 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

On Wednesday 09 Mar 2011 16:54:31 George Nassas wrote:
> On 2011-03-09, at 11:26 AM, David Blain wrote:
> > 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.
>
> I hope I didn't miss an announcement somewhere but is this intended to
> replace the myth protocol in the fullness of time? The archives have a few
> mentions of mythXML but they don't say one way or the other.

No. MythXML was there as a user-friendly API, xml is too heavy for a high
performance protocol which what the fe<>be protocol needs to be.

--
Stuart Morgan
MythTV
_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


MythTv at TheBlains

Mar 9, 2011, 9:33 AM

Post #4 of 13 (2757 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

>
> No. MythXML was there as a user-friendly API, xml is too heavy for a high
> performance protocol which what the fe<>be protocol needs to be.
>

Although I agree with Stuart, there is nothing stopping us from implementing
a serializer that is more light-weight (even rendering a version of the
current protocol, or even a binary one - so we can stop converting to/from
strings everywhere).

Also, it wouldn't take much effort to have a ServiceHost implementation that
doesn't use http (maybe raw sockets).
...

Either way, I wasn't planning on working on any of this unless the majority
of the core developers think it's a good idea. What I would like to see
however, is that even the myth protocol use the underlying api classes
(since they are just standard c++ classes), so that any current/future
functions can be exposed to other non-myth clients with little/no effort.

David.




_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


simon at koala

Mar 10, 2011, 12:40 AM

Post #5 of 13 (2738 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

On 09/03/2011 16:26, David Blain wrote:
> 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 )

had you considered making the protocol RESTful?
--
simon
_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


MythTv at TheBlains

Mar 10, 2011, 5:28 AM

Post #6 of 13 (2740 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

> had you considered making the protocol RESTful?
> --
> simon

I would already consider this protocol RESTful.

The only thing that I haven't added is the ability to use directory
structure like URIs. Currently it still depends on query strings for any
parameters.

This is something I was going to look into adding, since some clients (i.e.
some upnp clients) have a problem with '?' '&' being in the url.

Is there something that I've overlooked that makes these services not
callable as RESTful for you?

David.

_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


thewbman at gmail

Mar 10, 2011, 10:02 AM

Post #7 of 13 (2731 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

I have a webOS app called WebMyth that uses the old XML calls (
http://code.google.com/p/webmyth/) that will probably break some
functionality with this change. I do want to support both the old and new
versions in the app. Is there some easy way I could check to see if a
backend is using the old or new so my app could request the data
appropriately?

- wes

On Wed, Mar 9, 2011 at 9:26 AM, David Blain <MythTv [at] theblains> wrote:

> 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
>
> _______________________________________________
> mythtv-dev mailing list
> mythtv-dev [at] mythtv
> http://www.mythtv.org/mailman/listinfo/mythtv-dev
>


robert.mcnamara at gmail

Mar 10, 2011, 10:09 AM

Post #8 of 13 (2738 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

On Thu, Mar 10, 2011 at 10:02 AM, Wes Brown <thewbman [at] gmail> wrote:
> I have a webOS app called WebMyth that uses the old XML calls
> (http://code.google.com/p/webmyth/) that will probably break some
> functionality with this change.  I do want to support both the old and new
> versions in the app.  Is there some easy way I could check to see if a
> backend is using the old or new so my app could request the data
> appropriately?
>  - wes

BackendIP:6544/Status/GetStatus

If that returns XML, it's the new API framework.

Robert
_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


thewbman at gmail

Mar 10, 2011, 10:21 AM

Post #9 of 13 (2730 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

Sounds good - thanks.

- wes

On Thu, Mar 10, 2011 at 11:09 AM, Robert McNamara <robert.mcnamara [at] gmail
> wrote:

> On Thu, Mar 10, 2011 at 10:02 AM, Wes Brown <thewbman [at] gmail> wrote:
> > I have a webOS app called WebMyth that uses the old XML calls
> > (http://code.google.com/p/webmyth/) that will probably break some
> > functionality with this change. I do want to support both the old and
> new
> > versions in the app. Is there some easy way I could check to see if a
> > backend is using the old or new so my app could request the data
> > appropriately?
> > - wes
>
> BackendIP:6544/Status/GetStatus
>
> If that returns XML, it's the new API framework.
>
> Robert
> _______________________________________________
> mythtv-dev mailing list
> mythtv-dev [at] mythtv
> http://www.mythtv.org/mailman/listinfo/mythtv-dev
>


MythTv at TheBlains

Mar 10, 2011, 11:09 AM

Post #10 of 13 (2721 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

> I have a webOS app called WebMyth that uses the old XML calls
> (http://code.google.com/p/webmyth/) that will probably break
> some functionality with this change. I do want to support both
> the old and new versions in the app. Is there some easy way I could
> check to see if a backend is using the old or new so my app could
> request the data appropriately?
>
> - wes

I just added a built-in method that all current and future services will
have...

http://mythbackend:6544/<service_name>/version

example:
http://mythbackend:6544/Myth/version

If will return...

With header of: "Accept: application/json"

{"value": "1.0"}

With header of: "Accept: application/xml" or non-existing or non-json
accept header

<?xml version="1.0" encoding="UTF-8"?><value>1.0</value>

Note: you want the 1.0 within the <value> element.

-----
If it's the old version, these calls will fail.

Hope this helps.
David.

_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


simon at koala

Mar 10, 2011, 11:46 AM

Post #11 of 13 (2729 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

On 03/10/11 13:28, David Blain wrote:
>> had you considered making the protocol RESTful?
>> --
>> simon
>
> I would already consider this protocol RESTful.
>
> The only thing that I haven't added is the ability to use directory
> structure like URIs. Currently it still depends on query strings for any
> parameters.
>
> This is something I was going to look into adding, since some clients (i.e.
> some upnp clients) have a problem with '?' '&' being in the url.
>
> Is there something that I've overlooked that makes these services not
> callable as RESTful for you?
>
> David.
>
> _______________________________________________
> mythtv-dev mailing list
> mythtv-dev [at] mythtv
> http://www.mythtv.org/mailman/listinfo/mythtv-dev
>

now that i reread what you said:
> 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.
i see that they are
the "any method that modifies files/data should be limited to POST
request" did not ring the right bell in my head. if you had said "is"
instead of "should be" i would have got it.

but my question about the names of the methods still stands. i.e.

GetSetting/PutSetting vs settings with GET and POST
_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


david.whyte at gmail

Mar 21, 2011, 8:44 PM

Post #12 of 13 (2575 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

On Thu, Mar 10, 2011 at 2:26 AM, David Blain <MythTv [at] theblains> wrote:
> For those not following IRC, I committed the API Framework last night.
>
>

Hi David,

Congrats on the great work. I have been working a little on the
ability to expose MythXML to the external world via a MythWeb module.
My goal was to be able to write an app for my android phone, that
could access mythTV data via my mythweb server and not have to forward
more ports etc on my router or have to interpret the mythTV protocol
within the app. A stretch goal was to produce something that could
eventually be included in mythTV so that others could use the same
app, but against their mythTV installation or develop their own app
maybe on different platforms too.

A write up and downloadable version of the module is at
https://sites.google.com/a/thewhytehouse.org/mythtv/modification/mythxmlmoduleformythweb

Obviously, the module I have developed will have to change a little,
but I just wanted some feedback on whether what I was doing was
redundant/unwanted. I am also unsure of how to get it before the
developers eyes. Should I just raise a ticket as it is, with the
couple of minor problems it has (i.e. no mythweb translation etc) or
does it need to be fully finished and polished before it gets there?

Any feedback is welcome...

Regards,
Whytey
_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://www.mythtv.org/mailman/listinfo/mythtv-dev


thewbman at gmail

Mar 22, 2011, 3:46 PM

Post #13 of 13 (2559 views)
Permalink
Re: API Framework has been committed (May break existing users of mythXML). [In reply to]

Whytey,

I think this is a great idea. Works great on my machine. I am not
an actual MythTV developer so I don't have any say on this becoming
official, but I do want to show my support. Writing my app for Palm webOS (
http://code.google.com/p/webmyth/) I ended up writing a small python script
to get access to a lot of MythTV features. I have since added native
support for the app to communicate the actual mythprotocol on the device
(and do more complicated MySQL and remote operations). So to use the full
app remotely the user has to forward ports 80, 3306, 6543, 6544 and 6546.
Cutting out 6544 for XML would be nice both to reduce the number of ports
and to allow usage through a proxy that blocks all ports besides 80. (My
app would still require the other ports for full functionality, but the
majority of things could be done through XML).

[.Somewhat off-topic, but adding the list of upcoming recordings to MythXML
would be great. I am not sure if it is deliberately not part of MythXML or
just nobody has decided to do it themselves. Being able to show upcoming
recordings I think is key to a good MythTV app and having an XML interface
for it would simplify that for any apps on any platform.]

- wes

On Mon, Mar 21, 2011 at 9:44 PM, David Whyte <david.whyte [at] gmail> wrote:

> On Thu, Mar 10, 2011 at 2:26 AM, David Blain <MythTv [at] theblains> wrote:
> > For those not following IRC, I committed the API Framework last night.
> >
> >
>
> Hi David,
>
> Congrats on the great work. I have been working a little on the
> ability to expose MythXML to the external world via a MythWeb module.
> My goal was to be able to write an app for my android phone, that
> could access mythTV data via my mythweb server and not have to forward
> more ports etc on my router or have to interpret the mythTV protocol
> within the app. A stretch goal was to produce something that could
> eventually be included in mythTV so that others could use the same
> app, but against their mythTV installation or develop their own app
> maybe on different platforms too.
>
> A write up and downloadable version of the module is at
>
> https://sites.google.com/a/thewhytehouse.org/mythtv/modification/mythxmlmoduleformythweb
>
> Obviously, the module I have developed will have to change a little,
> but I just wanted some feedback on whether what I was doing was
> redundant/unwanted. I am also unsure of how to get it before the
> developers eyes. Should I just raise a ticket as it is, with the
> couple of minor problems it has (i.e. no mythweb translation etc) or
> does it need to be fully finished and polished before it gets there?
>
> Any feedback is welcome...
>
> Regards,
> Whytey
> _______________________________________________
> mythtv-dev mailing list
> mythtv-dev [at] mythtv
> http://www.mythtv.org/mailman/listinfo/mythtv-dev
>

MythTV dev RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.