Proposal to API design

Hi. All.

I tried to think how could we do simplify and optimize the operation of the current API in yesterday meeting.

And then I just made the proposal as below. Let’s have a discussion in today meeting.

 

We defined below methods for getting the some field’s information from metadata sources and knowing the available field taken real value in metadata sources.

Issues:

In case of getMediaProperty(), when application would like to get more than one field’s value, this has to call the number of times depending on the fields you want.

And this method has many parameters. It could be inconvenient to application developers.

In addition, if possible we should cover below two method’s role in only getMediaProperty() in the perspectives of simplification of API.

 

           getMediaProperty (in DOMString propertyName,

                                  in PropertyCallback successCallback, 

                                  in ErrorCallback errorCallback, 

                                  in optional DOMString fragment, 

                                  in optional DOMString sourceFormat, 

                                  in optional DOMString subtype, 

                                  in optional DOMString language);

                                                       

    getPropertyNamesHavingValues (in PropertyNamesCallback successCallback, 

                                             in ErrorCallback errorCallback,

                                             in optional DOMString sourceFormat,

                                             in optional DOMString language,

                                             in optional DOMString fragment); 

 

 

My Proposal is as below. It’s inspired via the specifications(e.g. contacts API, gallery API, etc) in DAP WG. AFAW browser vendors closely involved in this WG.

 

Goal of this design: (for better understanding, please refer some samples in the end of this email)

1)     Minimize the number of method call:  we can indicate the which properties information we want from metadata source using the first parameter( properties ). We can specify from 1 to 28)

2)     Simply the number of parameter: I make the MediaSourceOptions interface. And then I moved existing four parameters to here. So finally getMediaProperty() just have four parameters as you see.

3)     The role of getPropertyNamesHavingValues() could to be merged to getMediaProperty() by to defining new parameter( onlyHavingValue ) within MediaSourceOptions interface.

 

           getMediaProperty (in DOMString[] properties,

                                  in PropertyCallback successCallback, 

                                  in ErrorCallback errorCallback,

                                  in optional MediaSourceOptions? options

                                  );

                                                      

           interface MediaSourceOptions {

                     const unsigned short FALSE = 0;

                     const unsigned short TURE = 1;

                     attribute optional short onlyHavingValue;

                     attribute optional DOMString fragment;

                     attribute optional DOMString sourceFormat;

                     attribute optional DOMString subtype;

                     attribute optional DOMString language;

           };

 

----------

 

           // Example 1) This shows how application can get the title and copyright information by just one call of getMediaProperty()

           function MAgetPropertySuccessCallback(MediaAnnotationObject)

           {

                     alert("Title is " + MediaAnnotationObject.title " and Copyright is " + MediaAnnotationObject.copyright);

           }

 

           MAErrorCB(error)

           {

                     console.log("whoops, something went wrong!, error code is " + error.code);

           }

           

           mediaResource = new MediaResource("http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG");

           getMediaProperty(['title', 'copyright'],

                     MAgetPropertySuccessCallback, 

                     MAErrorCB,

                     {sourceForamt:'mrss', language:'kr'}

                     );

 

-----------------                                               

// Example 2) This show how getMediaProperty() could be used instead of getPropertyNamesHavingValues() using new parameter, onlyHavingValue.

           mediaResource = new MediaResource("http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG");

           getMediaProperty([‘all’],

                     MAgetPropertySuccessCallback, 

                     MAErrorCB,

                     {onlyHavingValue:TURE, sourceForamt:'mrss', language:'kr'}

                     );

 

Any comment is more than welcome~ ;)

 

Best regards,

Wonsuk.