[mythtv] [mythtv-commits] mythtv/master commit: 45a3bfcd4 by Robert McNamara (rmcnamara)
mythtv at theblains.net
Wed Feb 8 02:39:44 UTC 2012
> OK, now that we're going to the general, let me put it more succinctly
> my first post, "An API should hide implementation details, allowing for
> necessary flexibility in implementation."
> I agree that the specific value we use makes no difference--I just think
> should be at least one step removed from internal implementation.
> Using internal values externally, such that if we change the internal
> implementation we have to change external APIs or such that we can never
> change internal implementation, just seems to be needlessly shortsighted
> /because/ the specific value we use makes no difference.
> Besides, it's not like a web client can read /usr/include/recordingtypes.h
> programtypes.h or ...) to see what values are available and "what they
> mean", and it doesn't make sense to make developers duplicate the
> definitions of RecordingTypes, RecordingDupInTypes,
> RecordingDupMethodType, RecSearchTypes, MarkTypes,
> CommFlagStatuses, SkipTypes, TranscodingStatuses,
> ProgramFlag,ProgramInfoType, AudioProps, VideoProps, SubtitleTypes,
> RecStatusTypes, AvailableStatusTypes, WatchListStatus, AutoExpireTypes,
> ... (and there are /many/ more) in every single 3rd-party application
> (written in Perl, Python, Ruby, Vala, Java, Objective C,
> or whatever other language they choose)
> My current recommendation (as described in my previous e-mail) is to send
> a list of values and their meanings. This would actually make it easier
> create a client that works with any version of MythTV--as the client would
> be given a list of all appropriate choices for RecordingDupMethodType and
> would then just be able to display them in its UI (or use them to
> information about existing recording rules or ...). Because the client
> always get the current list of available types, it would never send us bad
> data--it would use the value associated with the option we provide. And,
> since we have teams of users all around the world translating
> names/descriptions of these things, 3rd-party client developers wouldn't
> need to do redundant translations of these names/descriptions for their
> own apps--they could use those provided by MythTV (or, if they really
> wanted to, they could ignore them). I really think this is much more
> to a 3rd-party developer than a page on a wiki or something that documents
> that 2=kDupsInOldRecorded in API version 1.0 or whatever.
> You're right that fundamental changes to the API (some of which may be
> caused by fundamental changes to the way MythTV works internally) will
> require some other solution. My proposal, though, was only related to
> providing an approach that ensures the client and the server are speaking
> the same language (by using the same list of values and their
> meanings) while still allowing us the flexibility to change our internal
> implementation as appropriate.
My intentions with the Services API were to make a framework that is
self-describing and tolerant to change (having sane defaults for missing
parameters, ability to overload methods, versioning ... ). If we use enum
types that are exposed using Qt macros, the service host can provide
real-time type information to the client (no need to write an api to return
it). Currently we expose WSDL (granted I still have some work to fix it,
but it's mostly there). Alternatively, we can implement any additional
schema the team feels would be useful.
My design goal has always been that the implementer of a service doesn't
need to do anything special to expose or leverage all the different
supported protocols/transports. They just need to write a class with
well-defined methods and data contracts.
I feel I've met this goal within reason, if I do say so myself. I don't
want to compromise or lose sight of these goals.
More information about the mythtv-dev