Subject: [Anima-signaling] GRASP API issue 2: Passing the (CBOR) value of an objective

From: Brian E Carpenter <[email-masked]>
Date: Sun, 8 Jan 2017 14:16:32 +1300

How should the API represent the 'value' part of a GRASP Objective
in a non-OO language?

In an OO language there will be a natural way to represent the value
of an objective: for example, in Python, any valid Python object
that the CBOR library can handle.

In a traditional language such as C, it's not so clear. For example, this doesn't
quite work:

typedef struct {
    gstring name;
    bool neg;
    bool dry;
    bool synch;
    int loop_count;
    void * value;    // user has to cast this pointer appropriately and do own malloc()
    } objective;

This doesn't work because the GRASP implementation won't know how
to CBORise whatever ends up in the 'value' parameter.

Is this already a solved problem in CBORland? For example, should we expect
the ASA to pass an already CBORised byte string?

Regards
   Brian

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 19 Jan 2017 15:49:15 +1300

I have a proposal for the issue mentioned below.

We can say in the abstract description of the API something like the following:

   o  value - a specific data structure expressing the value of the
      objective.  The format is language dependent, with the constraint
      that it can be validly represented in CBOR (default integer = 0).
      In case a required format cannot be supported in a particular
      language, every implementation must provide a mechanism for passing
      the value as an already encoded CBOR bytestring, which will be
      transmitted in all resulting GRASP messages as an embedded Tag 24
      item.

For those of you who don't know every single detail of CBOR :-), Tag 24
is simply the label for CBOR encapsulated in CBOR.

So for simple things a language mapping could be defined, and for
complex things the ASA writer would use a CBOR library.

I've implemented this in Python - if the ASA passes in an objective
whose value field is a 'bytes' object, and if that bytes object is
valid CBOR, it is wrapped in Tag 24 for transmission, and unwrapped
at the far end. It seems to work fine (about 35 new lines of code).

Regards
   Brian Carpenter