LLSD for Parameters (was re: [sldev] Plugin API)

[Tim Shephard]

I was thinking on the email proposed by Ryan regarding LLSD and it has
some interesting implications.

If we were to use LLSD for parameter passing, one useful area might be
(I stress the word, might, as I have significant concerns about this
approach) for registering services.

For example, we might have UIServices, RenderingServices, and MessageServices.

Here is what a C api might roughly look like (so far, only 6 top level
functions):

//Get a list of the services (Ie: UI Services, Message Services,
//Rendering Servers) this plugin wishes to subscribe to
// Included in the LLSD object will be function pointers to
// callbacks that the client will call into the plugin.
LLSD *SLP_GetServiceSubscriptions();

//Tell the client it's trying to subscribe to a no longer supported
// service and version tuple.  This would be at a coarse grain level.
void SLP_InvalidateServiceSubscription(const char *ServiceLabel);

//Initialization / Shutdown callbacks
//called when the client loads /unloads the plugin.
//XML Manifest file would be more suited
SLPError SLP_Load();
SLPError SLP_Unload();

// called when the client starts up /shuts down
SLPError SLP_ClientStartup();
SLPError SLP_ClientShutDown();


Given that services from the client themselves (on the assumption that
it's a rapidly evolving client) will need to be versioned, I was
thinking we may want to use the LLSD object to register services with
the client.

For example (this is just to give you an idea.  This would be highly
evolvable, which is the whole point of using LLSD objects):

There would be a part of the plugin api:

LLSD *SLP_GetServiceSubscriptions();

SLP_GetServiceSubscriptions could return an

Services Low    Trusted  Zerocoded
{
UIService Variable
       {
              ServiceData  Single
               { Version         S32}
               { ServiceLabel Variable 2}
               {  XMLSpec     Variable 2}   //UI Xml Spec
               {  MenuName  Variable 2}   //There could be a 'plugin' menu
               {  Show           LLFUNC}    //call back when show is
called, has a signature not documented here
               {  .. etc .. }

               Events Variable
               {       EventType                       S8
}  //eg, setAction,
               {       EventFunc                       LLFUNC        }
//callback function
                    .. etc
       }

MessageService Variable
// Dynamic structure for MessageService
// Probably something that specifies message types and
// associated callbacks

RenderingService Variable
// etc
 ..

}

This has four aspects, two I think is relatively straightforward, the
other two are concerns.

The first aspect is versioning.  Right now the versioning in the LLSD
objects are done in different parts with different nomenclature.
Ideally, we could develop a more  consistent approach not just in
verbiage but also handling revision tracking of the message protocol
itself so that future tools for dealing with versioning on a finer
grained scale will be more successful.

The second issue is how flexible the LLSD protocol is.   Looking
through message_template, I couldn't find examples of realtively
complex hierarchical types.   It would be useful to urge LL to XMLify
this.

The third aspect are function pointers as a LLFUNC type which is a
pointer.  This will have a different size on different platforms, and
isn't entirely in the spirit of the LLSD object which is mostly used
for RPC / serialization .. though there is some interesting discussion
there to be had for using the message spec for services in other
plugins which work over the wire.

The fourth aspect is related to the second in that we do not really
need to encode and we're using this message spec for communicating the
structure of the Service specifications, on the theory that they
change rapidly and we'll need dynamic typing.  Perhaps we're over
building if we do this.

The alternative approach is to use LLSD like type C structs.

I still think we need some kind of specification for what the structs
will look like
(we could use the message protocol) and we still need to allow for
dynamic typing because of changing features (adding and deprecating
data fields, LLFUNCS, etc), however, instead of returning LLSD class
objects, we'd return a C version which is similar but without the C++
features of the full on LLSD object.

The advantage of that approach is that we'd be able to deal with C++
ABI issues and we'd be able to share concept, code, and grammar
between the two types, LLSD and CLLSD.   The Plugin SDK would have
helper funcs for creating these CLLSD objects.

Anyhow, let me know your thoughts.

For those who don't like the idea, alternative header files are your
best answer!  This idea should inspire better ideas only, not empty
critique :)

For those who like the idea, suggestions on alternative nomenclature
and function grammar that clearly evokes purpose.  Ideas for parameter
signatures would be useful.   Expanding the API is fine, however,
keeping it as simple as possible .. ((especially the bits that are
likely to be stable) is critical for Plugin API success.

Cheers,

Tim.