History

kdeme 8a3decd977 Add dynlib pragma to be useful as dynamic library on Windows		2019-11-29 11:08:45 +01:00
..
README.md	Remove -linkshared & update Nix file to be consistent	2019-11-27 11:06:58 +01:00
cfuncs.go	Allow to provide user data for the filter subscribe callback	2019-11-19 11:02:00 +00:00
libnimbus.h	Move output parameters to end and add defines for buffer sizes	2019-11-19 11:02:00 +00:00
libnimbus.nim	Add dynlib pragma to be useful as dynamic library on Windows	2019-11-29 11:08:45 +01:00
wrapper_example.c	Add switching between Status beta and staging fleet	2019-11-19 11:02:00 +00:00
wrapper_example.go	Improve some freeing in the examples	2019-11-19 11:02:00 +00:00
wrapper_whisper_example.go	Improve some freeing in the examples	2019-11-19 11:02:00 +00:00

README.md

This folder contains an experimental C wrapper for using parts of the Nimbus code from C/Go in the Status console client:

https://github.com/status-im/status-console-client/

It serves mainly as a proof-of-concept for now - there are several unresolved issues surrounding threading, inter-language communication, callbacks etc.

To build the wrappers and the example programs, run from the top level directory:

make wrappers

Now you can run the example programs:

build/C_wrapper_example
build/go_wrapper_example
build/go_wrapper_whisper_example

To build statically linked versions:

make wrappers-static

You can also build the wrappers with the Nix build file (Need to install Nix first):

nix-build -A wrappers

Notes on usage

Before any of the API calls are done, NimMain() needs to be run.

After this any of the asymmetric or symmetric keys API calls can be done.

Before any actual Whisper calls are done, nimbus_start() needs to be called. This will setup the Whisper node, start discovery and connect to the Status fleet.

After this call you can use the Whisper related calls such as nimbus_subscribe_filter and nimbus_post.

nimbus_subscribe_filter allows you to pass a pointer to user data. This will just pass the pointer to the, by you provided, callback. You can use this to have a certain context in the callback.

Be aware that when using this with cgo, you will have a problem when passing a Go pointer that contains other Go pointers, as this is no longer allowed. See also: https://golang.org/cmd/cgo/#hdr-Passing_pointers

This can be resolved by refering to it indirectly, e.g. using a map in Go containing the pointers. See here for an example solution: https://github.com/mattn/go-pointer/blob/master/pointer.go

Caveat

Two items to take into consideration:

All API calls must be called from the same thread where the initial NimMain() was called from. While there are ways of thread coordination, this will not work for calls involving async work with Chronos. Thus to be extra clear & consistent, the above mentioned ways are not used at all.
For most of the API calls it is assumed that when passing a pointer as parameter, that the data that this pointer refers to remains valid during the duration of the call. If this is not the case, issues might occur as copying might happen to late.