Tomas,

> for synchronization of development I send a "File Storage RFC"
> with brief explanation of storing metadata and quick API overview.
> I hope it reflects specifications sent by Akos.

thanks for the document.

first a general remark on the XML-RPC function call parameters. I think
that the way XML-RPC handles parameters, e.g. they are not named, nor
typed, but you rely on their sequence, is quite error prone. Therefore
I'd push for a pattern in which we would basically send only one
parameter, which is an XML-RPC structure. As structures are nested
associative arrays basically in XML-RPC, this would allow us to bind
parameter values to names.

The reasoning behind this would be to accomodate future channges in our
parameter lists for our XML-RPC functions. Consider the case when we
would have a functions:

xmlRpcFunction( param1, param2);

(let's use the notations params[0] = param1, params[1] = param2, etc.)

but we find out, that actually param1 is not enough for it's purpose, so
a param1.1 is also needed. With the sequencing-only method, if we do:

xmlRpcFunction( param1, param1.1, param2);

then we break the implementation that relied on params[1] = param2. If
we do:

xmlRpcFunction( param1, param2, param1.1);

then it's quite counter-intuitive, as param1 and param1.1 are closely
related, by they appear quite apart.

If we would only send a structure, we could use it's association feature:

xmlRpcFunction( {param1 = param1, param2 = param2} );

and you'd have params[0]['param1'] = param1, params[0]['param2'] =
param2. extending the parameter list would lead to:

xmlRpcFunction( {param1 = param1, param1.1 = param1.1, param2 = param2} );

and it would still hold, that params[0]['param1'] = param1,
params[0]['param2'] = param2, while the new parameter would be
params[0]['param1.1] = param1.1, also quite straightforward.


What is your opinion on the matter?


With respect to the proposed API, I see the pattern that a $sessionid is
passed to all functions requiring authentication. I think this is a good
solution.

(As a sidenote, if we used my pattern proposed above, it could always be
params[0]['sessionid'], and would make programing easier. Whereas now,
it's always a parameter at a different index.)

Some specific remarks:


> XMLRPC API for local storage
>
> * |login(/*string*/ $login, /*string*/ $pass)| returns string
> returns auth token or error
> * |logout(/*string*/ $sessid)| returns boolean
> * |authenticate(/*string*/ $login, /*string*/ $pass)| returns boolean
> basic authentication check
> * |existsAudioClip(/*string*/ $gunid)| returns boolean
> Check if an Audio clip with the specified id is stored in local storage.

this call might be missing the sessionid parameter?

> * |storeAudioClip(/*string*/ $gunid, /*string*/ $mediaFileLP, /*string*/
> $mdataFileLP, /*string*/ $sessid)| returns gunid
> Store a new audio clip or replace an existing one.

...

> * |updateAudioClipMetadata(/*string*/ $gunid, /*string*/
$newMetaData,
> /*string*/ $sessid)| returns boolean
> Update the metadata of an Audio clip stored in Local storage.


why the different parameter formats for metadata for these two
functions? (mdataFileLP vs. newMetaData?) Also, I'd make AudioClip an
XML-RPC stucture, and put that in the parameter list. That would contain
the metadata, reference to the raw audio, and all other stuff that will
be in there.

> * |deleteAudioClip(/*string*/ $gunid, /*string*/ $sessid)| returns boolean
> Delete an existing Audio clip.
> * |accessRawAudioData(/*string*/ $gunid, /*string*/ $sessid)| returns string
> Get access to raw audio data of an AudioClip.
> * |releaseRawAudioData(/*string*/ $gunid, /*string*/ $sessid)| returns boolean
> Release access for raw audio data.

here, I would not have gunid as a parameter, but the exact value
instead, that was returned bt accessRawAudioData. this way the function
could identify exaclty which accessRawAudioData call is being matched by
this releaseRawAudioData function.

> * |searchMetadata(/*string*/ $criteria, /*string*/ $sessid)| returns array
> Search through the metadata of stored AudioClips, and return all matching
> clip ids.
>
> Methods may return XMLRPC error response if fails ...
>
> Common parameters:
>
> |$sessid| - session id (token returned by login method)
> |$gunid| - global unique id of file
>
>
> XMLRPC API of interface to central archive
>
> * |downloadRawAudioData(/*string*/ $gunid, /*int*/ $offset, /*string*/
> $sessid)| returns boolean
> * |searchMetadata(/*string*/ $criteria, /*string*/ $sessid)| returns array
> Search through the metadata of stored AudioClips, and return all matching
> clip ids.

and what about the store and update functions? why I'm asking is that
the parameter type there (medaFileLP) suggests that this would be some
pointer (or what does LP stand for?). But in case of the media archive,
there is no chance the client showing pointers - it has to upload all
binary data with the XML-RPC request itself.



Akos

------------------------------------------
Posted to Phorum via PhorumMail