Re: [mythtv] [mythtv-commits] mythtv/master commit: 45a3bfcd4 by Robert McNamara (rmcnamara)

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