[mythtv] [mythtv-commits] mythtv/master commit: 45a3bfcd4 by Robert McNamara (rmcnamara)
Michael T. Dean
mtdean at thirdcontact.com
Tue Feb 7 23:09:32 UTC 2012
On 02/07/2012 05:40 PM, Jean-Yves Avenard wrote:
> On 8 February 2012 04:44, Michael T. Dean wrote:
>> My preference for external API use is to present the data such that
>> clients don't need to know that (currently) 0 means HDTV, 1 means
>> WIDESCREEN, and 2 means AVC for program's videoprop, and for
>> recordedprogram's videoprop, there are additional values, 3 = 720 and 4
>> = 1080 and (as of only very recently) 5 = DAMAGED. It would also be
>> nice if clients didn't need to know that, for dupin values,
>> 1=kDupsInRecorded, 2=kDupsInOldRecorded, 15=kDupsInAll, and
>> 16=kDupsNewEpi (and other values are invalid--though in 0.24, we also
>> had meanings for 32, 64, and 128). Since we're constantly changing our
>> internal values, I don't want clients trying to interpret those values.
> Every public APIs used over a networked protocol use numbers or code.
> And so should we.
OK, now that we're going to the general, let me put it more succinctly
than 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
it 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 (or 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,
HTML/JavaScript/CSS, 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 to 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 determine information about existing recording
rules or ...). Because the client would 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 useful 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.
Mike
More information about the mythtv-dev
mailing list