and last but not least: document the new InLength<> feature. :-)
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.