diff options
| -rw-r--r-- | README.md | 96 | ||||
| -rw-r--r-- | book.json | 11 | ||||
| -rw-r--r-- | docs/README.md | 19 | ||||
| -rw-r--r-- | docs/SUMMARY.md | 10 | ||||
| -rw-r--r-- | docs/afb-timer.md | 48 | ||||
| -rw-r--r-- | docs/curl-wrap.md | 111 | ||||
| -rw-r--r-- | docs/escape.md | 37 | ||||
| -rw-r--r-- | docs/filescan-utils.md | 47 | ||||
| -rw-r--r-- | docs/json.md (renamed from json.md) | 83 | ||||
| -rw-r--r-- | docs/qafbwebsocketclient.md | 39 | ||||
| -rw-r--r-- | docs/usage.md | 88 | ||||
| -rw-r--r-- | docs/wrap-json.md (renamed from wrap-json.md) | 156 |
12 files changed, 605 insertions, 140 deletions
@@ -1,11 +1,95 @@ -AFB Utilities -============= +# AFB Helpers library -You should find useful utilities to integrates as submodule in your bindings -development. +You should find useful utilities to integrate in your bindings development. -From your AFB apps repository do the following to integrates this repo: +This library is the successor of the old git [afb-helpers-submodule](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps%2Fapp-afb-helpers-submodule.git;a=summary) +now available as a separated library. + +Please refer to the documentation in the `docs` folder for further informations. + +## Installation + +The afb-helpers library is integrated by default in the AGL SDK since the Guppy +version (>=7) and is also available as a package for the AGL supported linux +distributions. + +You could find the SDK build from Yocto which embed the afb-helpers library +here: + +* For the [releases](https://download.automotivelinux.org/AGL/release/) >= Guppy + in the latest machine's deploy directory. (e.g for Guppy in + `latest/<yourmachine>/deploy/sdk` directory) +* For the [master](https://download.automotivelinux.org/AGL/snapshots/master/) + development branch, in the latest machine's deploy directory. (e.g in + `latest/<yourmachine>/deploy/sdk` directory) + +To install the native package please refer to [this chapter](../host-configuration/docs/1_Prerequisites.md) +in the AGL documentation to install the AGL repository for your distribution. + +Then use your package manager to install the library. + +### OpenSuse + +```bash +sudo zypper ref +sudo zypper install agl-libafb-helpers-devel +``` + +### Fedora ```bash -git submodule add git@github.com:iotbzh/afb-utilities +sudo dnf ref +sudo dnf install agl-libafb-helpers-devel ``` + +### Ubuntu/Debian + +```bash +sudo apt-get update +sudo apt-get install agl-libafb-helpers-dev +``` + +## (Optionnal) Remove the git submodule version + +If you already use the afb-helpers component but using the submodule version +then you have to get rid of it to be sure to link and use the library version. +To do so, you have to do the following: + +* Deinitialize the submodule using `git` + +```bash +# This example assumes that the git submodule is named app-afb-helpers-submodule +# and is located at your root project repository. +git submodule deinit app-afb-helpers-submodule +``` + +* Remove the submodule relatives lines from the `.gitmodules` file + +```bash +vim .gitmodules +``` + +* Remove the `afb-helpers` target link from any CMake target you specified. + Those lines look like: + +```bash +TARGET_LINK_LIBRARIES(${TARGET_NAME} + afb-helpers # REMOVE THIS LINE + ${link_libraries} + ) +``` + +## Add the libafb-helpers as a static library to your binding + +In your `config.cmake` file, add a dependency to the afb-helpers library, i.e: + +```cmake +set(PKG_REQUIRED_LIST + json-c + afb-daemon + afb-helpers --> this is the afb-helpers library dependency name. +) +``` + +Or you can also use the [FIND_PACKAGE](https://cmake.org/cmake/help/v3.6/command/find_package.html?highlight=find_package) +CMake command to add it if you don't use the [cmake-apps-module](../cmakeafbtemplates/0_Abstract.html) diff --git a/book.json b/book.json new file mode 100644 index 0000000..e0ae0b5 --- /dev/null +++ b/book.json @@ -0,0 +1,11 @@ +{ + "title": "AFB Helpers Reference", + "subtitle": "Developer Documentation", + "description": "This is the utilisation guide for the AFB helpers functions", + "keywords": "AGL, Development, Iotbzh, afb-helpers, helpers, afb", + "author": "IoT.Bzh Team", + "website": "http://iot.bzh", + "published": "January 2019", + "version": "1.0", + "pdf_filename": "AFB_Helpers_reference" +} diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..69822c8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,19 @@ +# Introduction + +<br> +<br> +<br> +<br> +<br> + +| *Meta* | *Data* | +| -- | -- | +| **Title** | {{ config.title }} | +| **Author** | {{ config.author }} | +| **Description** | {{ config.description }} | +| **Keywords** | {{ config.keywords }} | +| **Language** | English | +| **Published** | Published {{ config.published }} as an electronic book | +| **Updated** | {{ gitbook.time }} | +| **Collection** | Open-source | +| **Website** | [{{ config.website }}]({{ config.website }}) | diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..26fca90 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,10 @@ +# Summary + +* [Usage Guide](usage.md) +* [AFB Timer](afb-timer.md) +* [Curl Wrap](curl-wrap.md) +* [Escape](escape.md) +* [Filescan Utils](filescan-utils.md) +* [Qt AFB Websockets client](qafbwebsocketclient.md) +* [JSON for modern C++](json.md) +* [Wrap-JSON](wrap-json.md) diff --git a/docs/afb-timer.md b/docs/afb-timer.md new file mode 100644 index 0000000..d02ab69 --- /dev/null +++ b/docs/afb-timer.md @@ -0,0 +1,48 @@ +# AFB Timer functions reference + +## TimerHandleT + +Members are: + +* `count`: integer representing the number of times the timers should run. +* `delay`: millisecond integer representing the delay to wait before and between + the callback run. +* `uid`: a string identifying the timer. +* `context`: an opaq pointer that could be used in the callback function. +* `evtSource`: a systemd event source struct. Should be NULL. +* `api`: the AFB api pointer. +* `callback`: a function pointer for the callback to call at timer expiration +* `freeCB`: a function pointer called after expiration of the timer. Mainly meant + to release the context pointer by example. + +## void TimerEvtStart(afb_api_t api, TimerHandleT *timerHandle, timerCallbackT callback, void *context) + +Start a timer which invokes the callback when the delay expires for `count` +times. + +* `api`: AFB api pointer. +* `timerHandle`: pointer to struct representing a timer. +* `callback`: a function pointer for the callback to call at timer expiration +* `context`: an opaq pointer that could be used in the callback function. + +## void TimerEvtStop(TimerHandleT *timerHandle) + +Manually stop the timer's run. If the `count` isn't finished then it will end +the timer and no other runs will occur. + +* `timerHandle`: pointer to struct representing a timer. + +## uint64_t LockWait(afb_api_t api, uint64_t utimeout) + +It is function acting like a non-blocking sleep for an API. It lets the main API +event loop runs while you are waiting and will unlock at the first received +event and returns the remaining time to wait if an event occurs or 0 if no events +occured and timeout hits. Then you have to manually ensure that once an event +has been received that it was the one you are waiting for and if not launch again +the wait with the remaining time returned. + +* `api`: AFB api pointer. +* `timeout`: timeout in microsecond. + +Returns the remaining time in microsecond to wait if an event occurs or 0 if no +events occured and timeout hits diff --git a/docs/curl-wrap.md b/docs/curl-wrap.md new file mode 100644 index 0000000..0103317 --- /dev/null +++ b/docs/curl-wrap.md @@ -0,0 +1,111 @@ +# CURL wrapping functions reference. + +## int curl_wrap_perform (CURL * curl, char **result, size_t * size) + +Perform the CURL operation for 'curl' and put the result in memory. If 'result' +isn't NULL it receives the returned content that then must be freed. If 'size' +isn't NULL, it receives the size of the returned content. Note that if not NULL, +the real content is one byte greater than the read size and the last byte +zero. This facility allows to handle the returned content as a null terminated +C-string. + +## void curl_wrap_do(CURL *curl, void (*callback)(void *closure, int status, CURL *curl, const char *result, size_t size), void *closure) + +Will perform the CURL operation and on success invokes the callback with the +result and size of the operation or error on a failure. + +## int curl_wrap_content_type_is (CURL * curl, const char *value) + +Request `Content-Type` information from the curl session with this function + +Returns non-zero value if the CURL content type match the `value` and 0 otherwize + +## long curl_wrap_response_code_get(CURL *curl) + +Request the response code to a CURL operation. + +Returns the response code received on success or 0 on failure. + +## CURL *curl_wrap_prepare_get_url(const char *url) + +Prepare a GET CURL operation on the url given as parameter and Returns the CURL +pointer. + +## CURL *curl_wrap_prepare_get(const char *base, const char *path, const char * const *args) + +Prepare a GET CURL operation on the decomposed url and escape it. The `url` has been +decomposed in 3 parts: + +* `base`: representing the FQDN of the url. +* `path`: the path to the requested page. +* `args`: optionnal array of arguments provided for the GET request. + +Returns the prepared CURL request. + +## int curl_wrap_add_header(CURL *curl, const char *header) + +Add a header to a CURL operation. + +Returns the prepared CURL request. + +## int curl_wrap_add_header_value(CURL *curl, const char *name, const char *value) + +Add a tuple `name`, `value` to the header of a CURL operation. + +Returns the prepared CURL request. + +## CURL *curl_wrap_prepare_post_url_data(const char *url, const char *datatype, const char *data, size_t szdata) + +Prepare a POST CURL operation on the provided `url`. + +* `url`: a HTTP url. +* `datatype`: HTTP `Content-Type` to use for the operation. +* `data`: data to send. +* `szdata`: size of the data to send. + +Returns the prepared CURL request. + +## CURL *curl_wrap_prepare_post_simple_unescaped(const char *base, const char *path, const char *args) + +Prepare a POST CURL operation on an unescaped `url` with arguments provided as +a simple string. + +* `base`: representing the FQDN of the url. +* `path`: the path to the requested page. +* `args`: optionnals argument for the POST http request. + +Returns the prepared CURL request. + +## CURL *curl_wrap_prepare_post_simple_escaped(const char *base, const char *path, char *args) + +Prepare a POST CURL operation on an escaped `url` with arguments provided as +a simple string. + +* `base`: representing the FQDN of the url. +* `path`: the path to the requested page. +* `args`: optionnals argument for the POST http request. + +Returns the prepared CURL request. + +## CURL *curl_wrap_prepare_post_unescaped(const char *base, const char *path, const char *separator, const char * const *args) + +Prepare a POST CURL operation on an unescaped `url` with arguments provided as +an array of string concatened with a provided separator string. + +* `base`: representing the FQDN of the url. +* `path`: the path to the requested page. +* `separator`: string used as a separator when concatening the arguments. +* `args`: optionnal array of arguments for the POST http request. + +Returns the prepared CURL request. + +## CURL *curl_wrap_prepare_post_escaped(const char *base, const char *path, const char * const *args) + +Prepare a POST CURL operation on an unescaped `url` with arguments provided as +an array of string concatened without any separator. + +* `base`: representing the FQDN of the url. +* `path`: the path to the requested page. +* `args`: optionnal array of arguments for the POST http request. + +Returns the prepared CURL request. diff --git a/docs/escape.md b/docs/escape.md new file mode 100644 index 0000000..200e6b6 --- /dev/null +++ b/docs/escape.md @@ -0,0 +1,37 @@ +# Escaping helpers functions reference + +## char *escape_url(const char *base, const char *path, const char * const *args, size_t *length) + +Escape an `url` and `arguments` and returned it as a string. + +* `base`: representing the FQDN of the url. +* `path`: the path to the requested page. +* `args`: optionnal array of arguments provided for the GET request. +* `length`: length of the returned `url`. + +Returns the escaped `url`. + +## const char *escape_args(const char * const *args, size_t *length) + +Escape an array of arguments and returned the lenght of the escaped arguments +string. + +* `args`: array of arguments provided for the GET request. +* `length`: length of the returned `arguments`. + +Returns the escaped `arguments`. + +## const char *escape_str(const char *str, size_t *length) + +Escape a string and returns it. + +* `str`: the string to escape. +* `length`: length of the returned string. + +Returns the escaped string. + +## const char **unescape_args(const char *args) + +Unescape an argument and returns it. + +* `args`: the argument to unescape. diff --git a/docs/filescan-utils.md b/docs/filescan-utils.md new file mode 100644 index 0000000..4a4c2d2 --- /dev/null +++ b/docs/filescan-utils.md @@ -0,0 +1,47 @@ +# Filescan utils functions reference + +## const char *GetMiddleName(const char *name) + +Get rid of the binder name prefix 'afbd-' + +* name will be typically the full binder name + +Returns the process middle name of the running binder. + +## const char *GetBinderName() + +Get the Binder Name without the prefix set by the AGL appfw 'afbd-' + +Returns the Binder name without the prefix. + +## json_object* ScanForConfig (const char* searchPath, CtlScanDirModeT mode, const char *prefix, const char *extension) + +Scan a directory searching all files matching pattern: 'prefix*extention'. + +* `searchPath`: directory where to begin the searching. +* `mode`: either or not the search will be recursive. +* `prefix`: file prefix that will be looking for. +* `extention`: file extention that will be looking for. + +Returns a json_object array of object with 2 parts a 'fullpath' describing the +fullpath to reach the file and 'filename' containing the matched files. + +## char *GetBindingDirPath_(afb_api_t api) + +For binding with a version >= 3, get the root directory path. + +* `api` : pointer to the AFB API. + +Returns a string representing the path to binding root directory. + +## const char *getEnvDirList(const char *prefix, const char *suffix) + +Get the environment directory colon separated path list. This take the prefix +add the binder's name then the suffix as environment variable name and also +search for another variable without the binder's name (so only prefix+suffix). + +* `prefix`: Environment variable prefix +* `suffix`: Environment variable suffix + +Returns a string representing a colon separated path list or NULL is case of +error or none environment variables found. @@ -1,17 +1,4 @@ -[](https://github.com/nlohmann/json/releases) - -[](https://travis-ci.org/nlohmann/json) -[](https://ci.appveyor.com/project/nlohmann/json) -[](https://coveralls.io/r/nlohmann/json) -[](https://scan.coverity.com/projects/nlohmann-json) -[](https://www.codacy.com/app/nlohmann/json?utm_source=github.com&utm_medium=referral&utm_content=nlohmann/json&utm_campaign=Badge_Grade) -[](http://melpon.org/wandbox/permlink/nv9fOg0XVVhWmFFy) -[](http://nlohmann.github.io/json) -[](https://raw.githubusercontent.com/nlohmann/json/master/LICENSE.MIT) -[](https://github.com/nlohmann/json/releases) -[](http://github.com/nlohmann/json/issues) -[](http://isitmaintained.com/project/nlohmann/json "Average time to resolve an issue") -[](https://bestpractices.coreinfrastructure.org/projects/289) +# JSON for Modern C++ - [Design goals](#design-goals) - [Integration](#integration) @@ -50,7 +37,6 @@ Other aspects were not so important to us: See the [contribution guidelines](https://github.com/nlohmann/json/blob/master/.github/CONTRIBUTING.md#please-dont) for more information. - ## Integration The single required source, file `json.hpp` is in the `src` directory or [released here](https://github.com/nlohmann/json/releases). All you need to do is add @@ -74,7 +60,6 @@ If you are using [hunter](https://github.com/ruslo/hunter/) on your project for :warning: [Version 3.0.0](https://github.com/nlohmann/json/wiki/Road-toward-3.0.0) is currently under development. Branch `develop` is used for the ongoing work and is probably **unstable**. Please use the `master` branch for the last stable version 2.1.1. - ## Examples Beside the examples below, you may want to check the [documentation](https://nlohmann.github.io/json/) where each function contains a separate code example (e.g., check out [`emplace()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a602f275f0359ab181221384989810604.html#a602f275f0359ab181221384989810604)). All [example files](https://github.com/nlohmann/json/tree/develop/doc/examples) can be compiled and executed on their own (e.g., file [emplace.cpp](https://github.com/nlohmann/json/blob/develop/doc/examples/emplace.cpp)). @@ -160,7 +145,6 @@ json empty_object_explicit = json::object(); json array_not_object = { json::array({"currency", "USD"}), json::array({"value", 42.99}) }; ``` - ### Serialization / Deserialization #### To/from strings @@ -251,7 +235,6 @@ std::vector<std::uint8_t> v = {'t', 'r', 'u', 'e'}; json j = json::parse(v); ``` - ### STL-like access We designed the JSON class to behave just like an STL container. In fact, it satisfies the [**ReversibleContainer**](http://en.cppreference.com/w/cpp/concept/ReversibleContainer) requirement. @@ -325,7 +308,6 @@ int fob_present = o.count("fob"); // 0 o.erase("foo"); ``` - ### Conversion from STL containers Any sequence container (`std::array`, `std::vector`, `std::deque`, `std::forward_list`, `std::list`) whose values can be used to construct JSON types (e.g., integers, floating point numbers, Booleans, string types, or again STL containers described in this section) can be used to create a JSON array. The same holds for similar associative containers (`std::set`, `std::multiset`, `std::unordered_set`, `std::unordered_multiset`), but in these cases the order of the elements of the array depends how the elements are ordered in the respective STL container. @@ -426,7 +408,6 @@ json::diff(j_result, j_original); // ] ``` - ### Implicit conversions The type of the JSON object is determined automatically by the expression to store. Likewise, the stored value is implicitly converted. @@ -520,7 +501,7 @@ using nlohmann::json; namespace ns { void to_json(json& j, const person& p) { - j = json{{"name", p.name}, {"address", p.address}, {"age", p.age}}; + j = json{ {"name", p.name}, {"address", p.address}, {"age", p.age} }; } void from_json(const json& j, person& p) { @@ -536,12 +517,11 @@ Likewise, when calling `get<your_type>()`, the `from_json` method will be called Some important things: -* Those methods **MUST** be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace `ns`, where `person` is defined). -* When using `get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible). (There is a way to bypass this requirement described later.) -* In function `from_json`, use function [`at()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a93403e803947b86f4da2d1fb3345cf2c.html#a93403e803947b86f4da2d1fb3345cf2c) to access the object values rather than `operator[]`. In case a key does not exists, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior. -* In case your type contains several `operator=` definitions, code like `your_variable = your_json;` [may not compile](https://github.com/nlohmann/json/issues/667). You need to write `your_variable = your_json.get<decltype your_variable>();` instead. -* You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these. - +- Those methods **MUST** be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace `ns`, where `person` is defined). +- When using `get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible). (There is a way to bypass this requirement described later.) +- In function `from_json`, use function [`at()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a93403e803947b86f4da2d1fb3345cf2c.html#a93403e803947b86f4da2d1fb3345cf2c) to access the object values rather than `operator[]`. In case a key does not exists, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior. +- In case your type contains several `operator=` definitions, code like `your_variable = your_json;` [may not compile](https://github.com/nlohmann/json/issues/667). You need to write `your_variable = your_json.get<decltype your_variable>();` instead. +- You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these. #### How do I convert third-party types? @@ -587,7 +567,7 @@ namespace nlohmann { if (j.is_null()) { opt = boost::none; } else { - opt = j.get<T>(); // same as above, but with + opt = j.get<T>(); // same as above, but with // adl_serializer<T>::from_json } } @@ -605,7 +585,7 @@ struct move_only_type { move_only_type(int ii): i(ii) {} move_only_type(const move_only_type&) = delete; move_only_type(move_only_type&&) = default; - + int i; }; @@ -617,7 +597,7 @@ namespace nlohmann { static move_only_type from_json(const json& j) { return {j.get<int>()}; } - + // Here's the catch! You must provide a to_json method! Otherwise you // will not be able to convert move_only_type to json, since you fully // specialized adl_serializer on that type @@ -634,9 +614,9 @@ Yes. You might want to take a look at [`unit-udt.cpp`](https://github.com/nlohma If you write your own serializer, you'll need to do a few things: -* use a different `basic_json` alias than `nlohmann::json` (the last template parameter of `basic_json` is the `JSONSerializer`) -* use your `basic_json` alias (or a template parameter) in all your `to_json`/`from_json` methods -* use `nlohmann::to_json` and `nlohmann::from_json` when you need ADL +- use a different `basic_json` alias than `nlohmann::json` (the last template parameter of `basic_json` is the `JSONSerializer`) +- use your `basic_json` alias (or a template parameter) in all your `to_json`/`from_json` methods +- use `nlohmann::to_json` and `nlohmann::from_json` when you need ADL Here is an example, without simplifications, that only accepts types with a size <= 32, and uses ADL. @@ -652,7 +632,7 @@ struct less_than_32_serializer { // this is where the magic happens to_json(j, value); } - + template <typename BasicJsonType> static void from_json(const BasicJsonType& j, T& value) { // same thing here @@ -674,7 +654,7 @@ struct bad_serializer // if BasicJsonType::json_serializer == bad_serializer ... oops! j = value; } - + template <typename BasicJsonType> static void to_json(const BasicJsonType& j, T& value) { // this calls BasicJsonType::json_serializer<T>::from_json(j, value); @@ -709,7 +689,6 @@ std::vector<std::uint8_t> v_msgpack = json::to_msgpack(j); json j_from_msgpack = json::from_msgpack(v_msgpack); ``` - ## Supported compilers Though it's 2016 already, the support for C++11 is still a bit sparse. Currently, the following compilers are known to work: @@ -725,14 +704,14 @@ Please note: - GCC 4.8 does not work because of two bugs ([55817](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=55817) and [57824](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=57824)) in the C++11 support. Note there is a [pull request](https://github.com/nlohmann/json/pull/212) to fix some of the issues. - Android defaults to using very old compilers and C++ libraries. To fix this, add the following to your `Application.mk`. This will switch to the LLVM C++ library, the Clang compiler, and enable C++11 and other features disabled by default. - - ``` + +```bb APP_STL := c++_shared NDK_TOOLCHAIN_VERSION := clang3.6 APP_CPPFLAGS += -frtti -fexceptions - ``` - - The code compiles successfully with [Android NDK](https://developer.android.com/ndk/index.html?hl=ml), Revision 9 - 11 (and possibly later) and [CrystaX's Android NDK](https://www.crystax.net/en/android/ndk) version 10. +``` + +The code compiles successfully with [Android NDK](https://developer.android.com/ndk/index.html?hl=ml), Revision 9 - 11 (and possibly later) and [CrystaX's Android NDK](https://www.crystax.net/en/android/ndk) version 10. - For GCC running on MinGW or Android SDK, the error `'to_string' is not a member of 'std'` (or similarly, for `strtod`) may occur. Note this is not an issue with the code, but rather with the compiler itself. On Android, see above to build with a newer environment. For MinGW, please refer to [this site](http://tehsausage.com/mingw-to-string) and [this discussion](https://github.com/nlohmann/json/issues/136) for information on how to fix this bug. For Android NDK using `APP_STL := gnustl_static`, please refer to [this discussion](https://github.com/nlohmann/json/issues/219). @@ -758,13 +737,11 @@ The following compilers are currently used in continuous integration at [Travis] | Clang Xcode 8.2 | Darwin Kernel Version 16.1.0 (macOS 10.12.1) | Apple LLVM version 8.0.0 (clang-800.0.42.1) | | Clang Xcode 8.3 | Darwin Kernel Version 16.5.0 (macOS 10.12.4) | Apple LLVM version 8.1.0 (clang-802.0.38) | | Clang Xcode 9 beta | Darwin Kernel Version 16.6.0 (macOS 10.12.5) | Apple LLVM version 9.0.0 (clang-900.0.26) | -| Visual Studio 14 2015 | Windows Server 2012 R2 (x64) | Microsoft (R) Build Engine version 14.0.25420.1 | +| Visual Studio 14 2015 | Windows Server 2012 R2 (x64) | Microsoft (R) Build Engine version 14.0.25420.1 | | Visual Studio 2017 | Windows Server 2016 | Microsoft (R) Build Engine version 15.1.1012.6693 | ## License -<img align="right" src="http://opensource.org/trademarks/opensource/OSI-Approved-License-100x137.png"> - The class is licensed under the [MIT License](http://opensource.org/licenses/MIT): Copyright © 2013-2017 [Niels Lohmann](http://nlohmann.me) @@ -775,7 +752,6 @@ The above copyright notice and this permission notice shall be included in all c THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - ## Thanks I deeply appreciate the help of the following people. @@ -807,7 +783,7 @@ I deeply appreciate the help of the following people. - [Corbin Hughes](https://github.com/nibroc) fixed some typos in the contribution guidelines. - [twelsby](https://github.com/twelsby) fixed the array subscript operator, an issue that failed the MSVC build, and floating-point parsing/dumping. He further added support for unsigned integer numbers and implemented better roundtrip support for parsed numbers. - [Volker Diels-Grabsch](https://github.com/vog) fixed a link in the README file. -- [msm-](https://github.com/msm-) added support for american fuzzy lop. +- [msm-](https://github.com/msm-) added support for american fuzzy lop. - [Annihil](https://github.com/Annihil) fixed an example in the README file. - [Themercee](https://github.com/Themercee) noted a wrong URL in the README file. - [Lv Zheng](https://github.com/lv-zheng) fixed a namespace issue with `int64_t` and `uint64_t`. @@ -863,10 +839,8 @@ I deeply appreciate the help of the following people. - [Markus Werle](https://github.com/daixtrose) fixed a typo. - [WebProdPP](https://github.com/WebProdPP) fixed a subtle error in a precondition check. - Thanks a lot for helping out! Please [let me know](mailto:mail@nlohmann.me) if I forgot someone. - ## Used third-party tools The library itself contains of a single header file licensed under the MIT license. However, it is built, tested, documented, and whatnot using a lot of third-party tools and services. Thanks a lot! @@ -894,12 +868,10 @@ The library itself contains of a single header file licensed under the MIT licen - [**Valgrind**](http://valgrind.org) to check for correct memory management - [**Wandbox**](http://melpon.org/wandbox) for [online examples](http://melpon.org/wandbox/permlink/4NEU6ZZMoM9lpIex) - ## Projects using JSON for Modern C++ The library is currently used in Apple macOS Sierra and iOS 10. I am not sure what they are using the library for, but I am happy that it runs on so many devices. - ## Notes - The code contains numerous debug **assertions** which can be switched off by defining the preprocessor macro `NDEBUG`, see the [documentation of `assert`](http://en.cppreference.com/w/cpp/error/assert). In particular, note [`operator[]`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a2e26bd0b0168abb61f67ad5bcd5b9fa1.html#a2e26bd0b0168abb61f67ad5bcd5b9fa1) implements **unchecked access** for const objects: If the given key is not present, the behavior is undefined (think of a dereferenced null pointer) and yields an [assertion failure](https://github.com/nlohmann/json/issues/289) if assertions are switched on. If you are not sure whether an element in an object exists, use checked access with the [`at()` function](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a674de1ee73e6bf4843fc5dc1351fb726.html#a674de1ee73e6bf4843fc5dc1351fb726). @@ -914,7 +886,6 @@ The library is currently used in Apple macOS Sierra and iOS 10. I am not sure wh - **Exceptions** are used widely within the library. They can, however, be switched off with either using the compiler flag `-fno-exceptions` or by defining the symbol `JSON_NOEXCEPTION`. In this case, exceptions are replaced by an `abort()` call. - By default, the library does not preserve the **insertion order of object elements**. This is standards-compliant, as the [JSON standard](https://tools.ietf.org/html/rfc7159.html) defines objects as "an unordered collection of zero or more name/value pairs". If you do want to preserve the insertion order, you can specialize the object type with containers like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map). - ## Execute unit tests To compile and run the tests, you need to execute @@ -930,11 +901,11 @@ All tests passed (14504461 assertions in 48 test cases) Alternatively, you can use [CMake](https://cmake.org) and run ```sh -$ mkdir build -$ cd build -$ cmake .. -$ make -$ ctest +mkdir build +cd build +cmake .. +make +ctest ``` For more information, have a look at the file [.travis.yml](https://github.com/nlohmann/json/blob/master/.travis.yml). diff --git a/docs/qafbwebsocketclient.md b/docs/qafbwebsocketclient.md new file mode 100644 index 0000000..5a6a3da --- /dev/null +++ b/docs/qafbwebsocketclient.md @@ -0,0 +1,39 @@ +# A WebSocket client to an Application Framework Binder + +## QAfbWebsocketClient(QObject* parent = nullptr) + +Default constructor. + +* `parent`: Parent object. + +## QAbstractSocket::SocketError error() + +Get and return the last error code. + +## QString errorString() + +Get and return the last error as a string. + +## bool isValid() + +Check if connection is ready or not. + +Returns `true` if the connected is ready to read and write, `false` otherwise. + +## void call(const QString& api, const QString& verb, const QJsonValue& arg = QJsonValue(), closure_t closure = nullptr) + +Call an api's verb with an argument. + +* `api`: Api to call. +* `verb`: Verb to call. +* `arg`: Argument to pass. +* `closure`: callback function to call at the verb reply + +## void QAfbWebsocketClient::sendTextMessage(QString msg) + +Send a text message over the websocket. + +This is use for test only, you should not use this method because it sent text +**as-is**, so you have to follow the binder's protocol by your self. + +* `msg`: Message to send. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..a746599 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,88 @@ +# Usage + +## Installation + +The afb-helpers library is integrated by default in the AGL SDK since the Guppy +version (>=7) and is also available as a package for the AGL supported linux +distributions. + +You could find the SDK build from Yocto which embed the afb-helpers library +here: + +* For the [releases](https://download.automotivelinux.org/AGL/release/) >= Guppy + in the latest machine's deploy directory. (e.g for Guppy in + `latest/<yourmachine>/deploy/sdk` directory) +* For the [master](https://download.automotivelinux.org/AGL/snapshots/master/) + development branch, in the latest machine's deploy directory. (e.g in + `latest/<yourmachine>/deploy/sdk` directory) + +To install the native package please refer to [this chapter](../host-configuration/docs/1_Prerequisites.md) +in the AGL documentation to install the AGL repository for your distribution. + +Then use your package manager to install the library. + +### OpenSuse + +```bash +sudo zypper ref +sudo zypper install agl-libafb-helpers-devel +``` + +### Fedora + +```bash +sudo dnf ref +sudo dnf install agl-libafb-helpers-devel +``` + +### Ubuntu/Debian + +```bash +sudo apt-get update +sudo apt-get install agl-libafb-helpers-dev +``` + +## (Optionnal) Remove the git submodule version + +If you already use the afb-helpers component but using the submodule version +then you have to get rid of it to be sure to link and use the library version. +To do so, you have to do the following: + +* Deinitialize the submodule using `git` + +```bash +# This example assumes that the git submodule is named app-afb-helpers-submodule +# and is located at your root project repository. +git submodule deinit app-afb-helpers-submodule +``` + +* Remove the submodule relatives lines from the `.gitmodules` file + +```bash +vim .gitmodules +``` + +* Remove the `afb-helpers` target link from any CMake target you specified. + Those lines look like: + +```bash +TARGET_LINK_LIBRARIES(${TARGET_NAME} + afb-helpers # REMOVE THIS LINE + ${link_libraries} + ) +``` + +## Add the libafb-helpers as a static library to your binding + +In your `config.cmake` file, add a dependency to the controller library, i.e: + +```cmake +set(PKG_REQUIRED_LIST + json-c + afb-daemon + afb-helpers --> this is the afb-helpers library dependency name. +) +``` + +Or you can also use the [FIND_PACKAGE](https://cmake.org/cmake/help/v3.6/command/find_package.html?highlight=find_package) +CMake command to add it if you don't use the [cmake-apps-module](../cmakeafbtemplates/0_Abstract.html) diff --git a/wrap-json.md b/docs/wrap-json.md index 8f7693c..9db96d2 100644 --- a/wrap-json.md +++ b/docs/wrap-json.md @@ -31,122 +31,122 @@ arguments. `s` (string) \[const char \*\] -: Convert a null terminated UTF-8 string to a JSON string. +: Convert a null terminated UTF-8 string to a JSON string. `s?` (string) \[const char \*\] -: Like `s`, but if the argument is *NULL*, output a JSON null value. +: Like `s`, but if the argument is *NULL*, output a JSON null value. `s*` (string) \[const char \*\] -: Like `s`, but if the argument is *NULL*, do not output any value. +: Like `s`, but if the argument is *NULL*, do not output any value. This format can only be used inside an object or an array. If used inside an object, the corresponding key is additionally suppressed when the value is omitted. See below for an example. `s#` (string) \[const char \*, int\] -: Convert a UTF-8 buffer of a given length to a JSON string. +: Convert a UTF-8 buffer of a given length to a JSON string. `s%` (string) \[const char \*, size\_t\] -: Like `s#` but the length argument is of type size\_t. +: Like `s#` but the length argument is of type size\_t. `+` \[const char \*\] -: Like `s`, but concatenate to the previous string. Only valid after +: Like `s`, but concatenate to the previous string. Only valid after `s`, `s#`, `+` or `+#`. `+#` \[const char \*, int\] -: Like `s#`, but concatenate to the previous string. Only valid after +: Like `s#`, but concatenate to the previous string. Only valid after `s`, `s#`, `+` or `+#`. `+%` (string) \[const char \*, size\_t\] -: Like `+#` but the length argument is of type size\_t. +: Like `+#` but the length argument is of type size\_t. `y` (byte array) \[const uint8_t \*, size\_t\] -: Convert the byte array whose length is given to +: Convert the byte array whose length is given to its base64url string representation. `Y` (byte array) \[const uint8_t \*, size\_t\] -: Like 'y' but output is base64. +: Like 'y' but output is base64. `y?`, `Y?` (byte array or null) \[const uint8_t \*, size\_t\] -: Like 'y' or 'Y' but allows to output a JSON null value +: Like 'y' or 'Y' but allows to output a JSON null value either when the buffer is *NULL* or when the size is *0*. `y*`, `y*` (optional byte array) \[const uint8_t \*, size\_t\] -: Like 'y' or 'Y' but do not put JSON value - either when the buffer is *NULL* or when the size is *0*. - This format can only be used inside an object or an array. If used - inside an object, the corresponding key is additionally suppressed - when the value is omitted. See below for an example. +: Like 'y' or 'Y' but do not put JSON value + either when the buffer is *NULL* or when the size is *0*. + This format can only be used inside an object or an array. If used + inside an object, the corresponding key is additionally suppressed + when the value is omitted. See below for an example. `n` (null) -: Output a JSON null value. No argument is consumed. +: Output a JSON null value. No argument is consumed. `b` (boolean) \[int\] -: Convert a C int to JSON boolean value. Zero is converted to `false` +: Convert a C int to JSON boolean value. Zero is converted to `false` and non-zero to `true`. `i` (integer) \[int\] -: Convert a C int to JSON integer. +: Convert a C int to JSON integer. `I` (integer) \[json\_int\_t\] -: Convert a C json\_int\_t to JSON integer. +: Convert a C json\_int\_t to JSON integer. `f` (real) \[double\] -: Convert a C double to JSON real. +: Convert a C double to JSON real. `o` (any value) \[json\_t \*\] -: Output any given JSON value as-is. If the value is added to an array - or object, the reference to the value passed to `o` is stolen by the - container. +: Output any given JSON value as-is. If the value is added to an array + or object, the reference to the value passed to `o` is stolen by the + container. `O` (any value) \[json\_t \*\] -: Like `o`, but the argument's reference count is incremented. This is - useful if you pack into an array or object and want to keep the - reference for the JSON value consumed by `O` to yourself. +: Like `o`, but the argument's reference count is incremented. This is + useful if you pack into an array or object and want to keep the + reference for the JSON value consumed by `O` to yourself. `o?`, `O?` (any value) \[json\_t \*\] -: Like `o` and `O`, respectively, but if the argument is *NULL*, - output a JSON null value. +: Like `o` and `O`, respectively, but if the argument is *NULL*, + output a JSON null value. `o*`, `O*` (any value) \[json\_t \*\] -: Like `o` and `O`, respectively, but if the argument is *NULL*, do - not output any value. This format can only be used inside an object - or an array. If used inside an object, the corresponding key is - additionally suppressed. See below for an example. +: Like `o` and `O`, respectively, but if the argument is *NULL*, do + not output any value. This format can only be used inside an object + or an array. If used inside an object, the corresponding key is + additionally suppressed. See below for an example. `[fmt]` (array) -: Build an array with contents from the inner format string. `fmt` may - contain objects and arrays, i.e. recursive value building is - supported. +: Build an array with contents from the inner format string. `fmt` may + contain objects and arrays, i.e. recursive value building is + supported. `{fmt}` (object) -: Build an object with contents from the inner format string `fmt`. - The first, third, etc. format specifier represent a key, and must be - a string (see `s`, `s#`, `+` and `+#` above), as object keys are - always strings. The second, fourth, etc. format specifier represent - a value. Any value may be an object or array, i.e. recursive value - building is supported. +: Build an object with contents from the inner format string `fmt`. + The first, third, etc. format specifier represent a key, and must be + a string (see `s`, `s#`, `+` and `+#` above), as object keys are + always strings. The second, fourth, etc. format specifier represent + a value. Any value may be an object or array, i.e. recursive value + building is supported. Whitespace, `:` and `,` are ignored. @@ -195,90 +195,90 @@ type whose address should be passed. `s` (string) \[const char \*\] -: Convert a JSON string to a pointer to a null terminated UTF-8 - string. The resulting string is extracted by using - json\_string\_value() internally, so it exists as long as there are - still references to the corresponding JSON string. +: Convert a JSON string to a pointer to a null terminated UTF-8 + string. The resulting string is extracted by using + json\_string\_value() internally, so it exists as long as there are + still references to the corresponding JSON string. `s%` (string) \[const char \*, size\_t \*\] -: Convert a JSON string to a pointer to a null terminated UTF-8 string - and its length. +: Convert a JSON string to a pointer to a null terminated UTF-8 string + and its length. `y` (byte array) \[uint8_t \*\*, size\_t \*\] -: Convert an input string base64url encoded to its - byte array representation. The result and its length - are stored. The returned buffer must be freed by the caller. +: Convert an input string base64url encoded to its + byte array representation. The result and its length + are stored. The returned buffer must be freed by the caller. `Y` (byte array) \[uint8_t \*\*, size\_t \*\] -: Like 'y' but input is base64. +: Like 'y' but input is base64. `n` (null) -: Expect a JSON null value. Nothing is extracted. +: Expect a JSON null value. Nothing is extracted. `b` (boolean) \[int\] -: Convert a JSON boolean value to a C int, so that `true` is converted - to 1 and `false` to 0. +: Convert a JSON boolean value to a C int, so that `true` is converted + to 1 and `false` to 0. `i` (integer) \[int\] -: Convert a JSON integer to C int. +: Convert a JSON integer to C int. `I` (integer) \[json\_int\_t\] -: Convert a JSON integer to C json\_int\_t. +: Convert a JSON integer to C json\_int\_t. `f` (real) \[double\] -: Convert a JSON real to C double. +: Convert a JSON real to C double. `F` (integer or real) \[double\] -: Convert a JSON number (integer or real) to C double. +: Convert a JSON number (integer or real) to C double. `o` (any value) \[json\_t \*\] -: Store a JSON value with no conversion to a json\_t pointer. +: Store a JSON value with no conversion to a json\_t pointer. `O` (any value) \[json\_t \*\] -: Like `O`, but the JSON value's reference count is incremented. +: Like `O`, but the JSON value's reference count is incremented. `[fmt]` (array) -: Convert each item in the JSON array according to the inner format - string. `fmt` may contain objects and arrays, i.e. recursive value - extraction is supported. +: Convert each item in the JSON array according to the inner format + string. `fmt` may contain objects and arrays, i.e. recursive value + extraction is supported. `{fmt}` (object) -: Convert each item in the JSON object according to the inner format - string `fmt`. The first, third, etc. format specifier represent a - key, and must be `s`. The corresponding argument to unpack functions - is read as the object key. The second fourth, etc. format specifier - represent a value and is written to the address given as the - corresponding argument. **Note** that every other argument is read - from and every other is written to. +: Convert each item in the JSON object according to the inner format + string `fmt`. The first, third, etc. format specifier represent a + key, and must be `s`. The corresponding argument to unpack functions + is read as the object key. The second fourth, etc. format specifier + represent a value and is written to the address given as the + corresponding argument. **Note** that every other argument is read + from and every other is written to. `fmt` may contain objects and arrays as values, i.e. recursive value extraction is supported. `!` -: This special format specifier is used to enable the check that all - object and array items are accessed, on a per-value basis. It must - appear inside an array or object as the last format specifier before - the closing bracket or brace. +: This special format specifier is used to enable the check that all + object and array items are accessed, on a per-value basis. It must + appear inside an array or object as the last format specifier before + the closing bracket or brace. `*` -: This special format specifier is the opposite of `!`. This is the default. - It must appear inside an array or object as the last format specifier - before the closing bracket or brace. +: This special format specifier is the opposite of `!`. This is the default. + It must appear inside an array or object as the last format specifier + before the closing bracket or brace. Whitespace, `:` and `,` are ignored. |