Browse Source

add more informations about parameter mapping etc.

JSON-57
Roker 5 years ago
parent
commit
b3995ed3bc
2 changed files with 94 additions and 40 deletions
  1. +92
    -38
      README.md
  2. +2
    -2
      server/pep-types.cc

+ 92
- 38
README.md View File

@ -2,16 +2,19 @@
## Introduction
The p≡p JSON Server Adapter provides a REST-like jQuery-compatible API to connect with
the p≡p engine. It is language-independent and can be used by any client.
The p≡p JSON Server Adapter provides a REST-like jQuery-compatible API to
connect with the p≡p engine. It is language-independent and can be used by
any client.
## Getting started - build and run
In order to use the p≡p JSON Server Adapter, you need to build and run it. Currently, Linux and OSX/macOS are supported, Windows is about to follow.
In order to use the p≡p JSON Server Adapter, you need to build and run it.
Currently, Linux and OSX/macOS are supported, Windows is about to follow.
### Building on Linux
The p≡p JSON Server Adapter can be build on Debian and Ubuntu. Other flavors may work, but are not officially supported.
The p≡p JSON Server Adapter can be build on Debian and Ubuntu. Other
distributions should work, but are not officially supported.
#### System requirements
@ -46,7 +49,8 @@ The p≡p JSON Server Adapter can be build on OS X or macOS with MacPorts.
#### Preconditions
For compiling the p≡p JSON Server Adapter and its dependencies, make sure you have the LANG variable set.
For compiling the p≡p JSON Server Adapter and its dependencies, make sure
you have the LANG variable set.
```
export LANG=en_US.UTF-8
@ -54,12 +58,15 @@ export LANG=en_US.UTF-8
#### Dependencies
The following dependencies need to be installed in order to be able to build the p≡p JSON Server Adapter.
The following dependencies need to be installed in order to be able to build
the p≡p JSON Server Adapter.
##### MacPorts
[Install MacPorts](https://www.macports.org/install.php) for your version of OS X/macOS.
If MacPorts is already installed on your machine, but was installed by a different user, make sure your `PATH` variable is set as follows in `~/.profile`:
If MacPorts is already installed on your machine, but was installed by a
different user, make sure your `PATH` variable is set as follows in
`~/.profile`:
```
export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
@ -88,7 +95,7 @@ make install
#### Build steps
1. Install dependencies
1. Install dependencies
2. Run "make" in the server/ path
```
@ -102,11 +109,11 @@ make
current user (/tmp/pEp-json-token-${USER}) and contains the address and
port the JSON adapter is listening on, normally 127.0.0.1:4223 and a
"security-token" that must be given in each function call to authenticate
you as the valid user.
you as the valid user.
```
./pep-json-server
```
```
2. Visit that address (normally http://127.0.0.1:4223/) in your
javascript-enabled web browser to see the test JavaScript client.
@ -118,62 +125,109 @@ make
In the following section, you'll find background information on how to use
the adapter and its functions.
### Preliminary notes
### Session handling
* When using the p≡p engine, a session is needed to which any adapter can connect.
In case of the p≡p JSON Server Adapter, it creates this session automatically and
attaches to / detaches from it automatically. Therefore, the client does not need
to take care of the session management. However, it might be necessary to set up a
[HTTP persistent connection](https://en.wikipedia.org/wiki/HTTP_persistent_connection).
When using the p≡p engine, a session is needed to which any adapter can
connect. The p≡p JSON Server Adapter automatically creates one session per
HTTP client connection (and also closes that session automatically when the
client connections is closed). Therefore, the client does not need to take
care of the session management. However, the client has to set up a [HTTP
persistent
connection](https://en.wikipedia.org/wiki/HTTP_persistent_connection).
### API Principles
All C data types are mapped the same way, so some day the JSON wrapper can be generated from the p≡p Engine header files (or the JSON wrapper and the p≡p engine header are both generated from a common interface description file)
All C data types are mapped the same way, so some day the JSON wrapper can
be generated from the p≡p Engine header files (or the JSON wrapper and the
p≡p engine header are both generated from a common interface description
file)
| C type | JSON mapping |
|--|--|
| `bool` | JSON boolean |
| `int` | JSON decimal number |
| `int` | JSON decimal number |
| `size_t` | JSON decimal number |
| `char*` (representing a UTF-8-encoded NULL-terminated string | JSON string |
| `char*` (representing a binary string | base64-encoded JSON string |
| `enum` | string with the enumerator constant (e.g. `PEP_KEY_NOT_FOUND` ) |
| `enum` | either JSON decimal number or JSON object containing one decimal number as member |
| `struct` | JSON object |
| linked lists (e.g. `bloblist_t`, `stringlist_t`, `identity_list` etc.) | JSON array of their member data type (without the `next` pointer) |
The parameter type PEP_SESSION is handled automatically by the JSON Server
Adapter and the PEP_SESSION parameter is omitted from the JSON API.
#### enum types
Enum types are represented as JSON objects with one member, whose name is
derived from the enum type name, holding the numeric value of the enum.
Some enum types are still represented directly as JSON decimal number. It
shall be changed in a future version of the JSON Adapter.
#### String types
The JSON Server Adapter does automatic memory management for string
parameters. The current p≡p Engine's API distinguish between `const char*`
parameters and `char*` parameters. `const char*` normally means: the
"ownership" of the string remains at the caller, so the JSON Adapter frees
the string automatically after the call. `char*` normally means: the
"ownership" of the string goes to the Engine, so the JSON Adapter does _not_
free string.
If there are functions that have a different semantics the behavior of the
JSON wrapper has to be changed.
#### Supported return types
The current implementation only supports functions with a non-void return
type. (It would be possible to extend the `FunctionMap` implementation to
support also void-returning functions if desired, but it would require more
template specializations in `function_map.hh` etc. that's why it is not
implemented, yet.) So void-returning functions must currently be wrapped in
a helper function that calls the void function and just returns a dummy
value.
#### Parameter (value) restrictions
Some API functions have restrictions on their parameter values. The JSON
Adapter does not know these restrictions (because it does not know the
semantics of the wrapped functions at all). So it is the client's
responsibility to fulfill these parameter restrictions! Especially when
there are restrictions that are checked with assert() within the p≡p Engine,
it is impossible for the JSON Adapter to catch failed assertions - the
Engine and the Adapter process will be terminated immediatetely when the
Engine is compiled in debug mode (= with enabled assert() checking).
Currently there are no range checks for numerical parameter types (e.g. a
JSON decimal number can hold a bigger value than the `int` parameter type of
a certain C function).
### API Reference
An complete overview with all functions that are callable from the client can be found in the [API Reference](pEp JSON Server Adapter/API Reference).
An complete overview with all functions that are callable from the client
can be found in the [API Reference](pEp JSON Server Adapter/API Reference).
## Extending / customizing
Most of the callable functions are functions from the C API of the p≡p
Engine. They are described in detail, incl. pre- and post-conditions in
the appropriate C header files of the Engine.
If you want to extend or customize the p≡p JSON Adapter, there are several
rules and defitions to take into account.
### General
## Extending / customizing
* At the moment only functions with a non-void return type are supported.
It is possible to extend the FunctionMap to support also void-returning
functions if desired, but it would require more template specializations
in function_map.hh etc. The alternative is a helper function that calls
the void function and just returns a dummy value.
If you want to extend or customize the p≡p JSON Adapter, there are several
rules and definitions to take into account.
### Definitions
* The 'FunctionMap function' in mt-server.cc defines which functions are
callable via the JSON-RPC interface. The existing entries show the syntax
of that map.
* The current implementation supports input and output parameters, no
"inout".
* The `FunctionMap function` in `json-adapter.cc` defines which functions
are callable via the JSON-RPC interface. The existing entries show the
syntax of that map.
* For each type there must exist specializations of the template classes
"In" (for input parameters) and "Out" (for output parameters).
The linker will tell you, which specializations are needed.
* The specializations for "generic types" are in function_map.cc
* The specializations for "p≡p-specific types" are in pep-types.cc
* The specializations for "generic types" are in `function_map.cc`.
* The specializations for "p≡p-specific types" are in `pep-types.cc`.
## TODOs


+ 2
- 2
server/pep-types.cc View File

@ -217,9 +217,9 @@ message* from_json<message*>(const js::Value& v)
msg->sent = from_json_object<timestamp*, js::int_type>(o, "sent");
msg->recv = from_json_object<timestamp*, js::int_type>(o, "recv");
msg->from = from_json_object<pEp_identity*, js::obj_type>(o, "from");
msg->from = from_json_object<pEp_identity* , js::obj_type> (o, "from");
msg->to = from_json_object<identity_list*, js::array_type>(o, "to");
msg->recv_by = from_json_object<pEp_identity*, js::obj_type>(o, "recv_by");
msg->recv_by = from_json_object<pEp_identity* , js::obj_type> (o, "recv_by");
msg->cc = from_json_object<identity_list*, js::array_type>(o, "cc");
msg->bcc = from_json_object<identity_list*, js::array_type>(o, "bcc");
msg->reply_to = from_json_object<identity_list*, js::array_type>(o, "reply_to");


Loading…
Cancel
Save