and last but not least: document the new InLength<> feature. :-) JSON-93
authorRoker <roker@pep-project.org>
Thu, 07 Jun 2018 13:53:16 +0200
branchJSON-93
changeset 541030b53a59cab
parent 540 1edfe161fea7
child 542 42ff394ca203
and last but not least: document the new InLength<> feature. :-)
README.md
     1.1 --- a/README.md	Thu Jun 07 13:52:50 2018 +0200
     1.2 +++ b/README.md	Thu Jun 07 13:53:16 2018 +0200
     1.3 @@ -363,6 +363,60 @@
     1.4  More flags will be added when different semantics will be needed.
     1.5  
     1.6  
     1.7 +### Automatic parameter value generation
     1.8 +
     1.9 +For some parameters or parameter combinations the JSON Server Adapter is
    1.10 +able to generate the values automatically either from the environment or
    1.11 +from other parameters.
    1.12 +
    1.13 +These automatic parameter value generators are supported at the moment:
    1.14 +
    1.15 +#### InLength
    1.16 +
    1.17 +For functions that have a string parameter of type `const char*` followed by
    1.18 +a `size_t` that specifies the length of the string, the JSON Adapter can
    1.19 +calculate the value of that length parameter automatically because in the
    1.20 +JSON API the lengths of strings are always known.
    1.21 +
    1.22 +Moreover, the "length" that has to be given here means the length of the
    1.23 +string seen by the C API side, after processing of all JSON escaping
    1.24 +mechanisms, so it might be difficult to calculate that value at client side.
    1.25 +
    1.26 +Example:
    1.27 +```
    1.28 +// C function declaration:
    1.29 +char* tohex(const char* input, size_t length);
    1.30 +
    1.31 +// API definition:
    1.32 +// with implicit length parameter, with dummy JSON parameter
    1.33 +FP( "tohex", new Func<char*, In<c_string>, InLength<>>( &tohex ))
    1.34 +```
    1.35 +
    1.36 +To be compatible with previous API versions the `InLength` parameter still
    1.37 +needs a dummy placeholder in the JSON interface, but its value is no longer
    1.38 +relevant:
    1.39 +
    1.40 +```
    1.41 +{"jsonrpc":"2.0", "id":28,
    1.42 + "method":"tohex", "params":["some string","dummy_parameter"]
    1.43 +}
    1.44 +```
    1.45 +
    1.46 +It is possible to specifiy `InLength<ParamFlag::NoInput>` so no
    1.47 +parameter is exposed to the JSON API anymore:
    1.48 +
    1.49 +```
    1.50 +FP( "tohex", new Func<char*, In<c_string>, InLength<ParamFlag::NoInput>>( &tohex ))
    1.51 +```
    1.52 +
    1.53 +Now the 2nd parameter is omitted:
    1.54 +```
    1.55 +{"jsonrpc":"2.0", "id":28,
    1.56 + "method":"tohex", "params":["some string"]
    1.57 +}
    1.58 +```
    1.59 +
    1.60 +
    1.61  ## TODOs
    1.62  
    1.63  The following issues are planned but not yet implemented.