add more informations about parameter mapping etc.
parent
e51a7bd35b
commit
b3995ed3bc
132
README.md
132
README.md
|
|
@ -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.
|
||||
|
||||
|
||||
## Extending / customizing
|
||||
|
||||
If you want to extend or customize the p≡p JSON Adapter, there are several
|
||||
rules and defitions to take into account.
|
||||
|
||||
### General
|
||||
|
||||
* 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.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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…
Reference in New Issue