SAMP draft document introduction

[Mark Taylor]

Hi Al,

On Wed, 30 Apr 2008, Alasdair Allan wrote:

> We just had an internet outage which conveniently let me sit down and 
> actually read the spec cover to cover. On the whole I'm pretty happy with the 
> specification...

good!

> The immediate problem I have with the document is that  I'm a little unsure 
> how the mtype mapping from what is outlined in section 5 to XML-RPC method 
> names works in practice? This isn't, at least to me, entirely clear and 
> possibly some more example documents might be in order. Sorry, it might just 
> be post-lunch time dimness on my part.

MTypes do not map to XML-RPC method names, they map to (parts of) 
XML-RPC method arguments, specifically the value of the "mtype" key
in the "message" map-type argument.  The pseudo-code excerpt from 
sec 4.4:

    # Send a message requesting file load to all other registered clients,
    # not wanting any response.
    map loadParams = ("filename" -> "/tmp/foo.bar");
    map loadMsg = ("mtype" -> "file.load",
                   "params" -> "loadParams");
    hub.xmlrpcCall("samp.hub.notifyAll", private-key, loadMsg);

shows how it works.  The explanation for why this is what you do is
in sec 3.8.  Hopefully this would become clear if you sat down to
write some code following the spec, I think it would be a good idea 
if I added an example in sec 3.8 of an encoded message, to make it 
clearer what I'm going on about there.  I resisted spelling out 
all the XML-RPC communications in sec 4.4 because it could run to
quite a lot of pages, but maybe I should do for definiteness (could
go in an appendix?)  In the mean time if you want to suggest some 
text which would have made things more obvious, please do.

> Based on the specification I'll try and put together a demonstration Perl 
> SAMP hub (and a couple of simple clients) in time for the May meeting. It'll 
> be good to have a few prototypes kicking around.

that would be great - it would certainly go a long way towards testing 
whether there are things we've forgotten to think about or to write down.
Since this is all still under discussion you might need to revise the
implementations in accordance with decisions yet to be made, but I'm
sure you can cope with that.  I'm plannning to write a Java hub reasonably
soon assuming we reach agreement, but most likely not before Trieste.

Mark

-- 
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-928-8776 http://www.star.bris.ac.uk/~mbt/