servicepoint_binding_c

In CCCB, there is a big pixel matrix hanging on the wall. It is called "Service Point Display" or "Airport Display".

This crate contains C bindings for the servicepoint library, enabling users to parse, encode and send packets to this display via UDP.

Examples

#include <stdio.h>
#include "servicepoint.h"

int main(void) {
    SPConnection *connection = sp_connection_open("172.23.42.29:2342");
    if (connection == NULL)
        return 1;

    SPBitmap *pixels = sp_bitmap_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT);
    sp_bitmap_fill(pixels, true);

    SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
    while (sp_connection_send_command(connection, sp_command_clone(command)));

    sp_command_free(command);
    sp_connection_free(connection);
    return 0;
}

A full example including Makefile is available as part of this crate.

Note on stability

This library is still in early development. You can absolutely use it, and it works, but expect minor breaking changes with every version bump. Please specify the full version including patch in your Cargo.toml until 1.0 is released.

Installation

This manual uses gnumake, though it should work similarly for other build systems.

Add this repo as a submodule:

git submodule add https://git.berlin.ccc.de/servicepoint/servicepoint-binding-c.git
git commit -m "add servicepoint-binding-c submodule"

Update your Makefile:

# provide header and binary to CC
CFLAGS += -I servicepoint-binding-c/include -L servicepoint-binding-c/target/release
# link statically against servicepoint, link against lzma dynamically
CFLAGS += -Wl,-Bstatic -lservicepoint_binding_c -Wl,-Bdynamic -llzma

# add target to build rust library - cargo will check for dependency changes
servicepoint-binding-c/target/release/libservicepoint.a:
	cargo build --manifest-path=servicepoint-binding-c/Cargo.toml --release

# add static lib as a dependency for your compilation
# if you build .so files separately, this should be part of your build step
my_bin: $(src) servicepoint-binding-c/target/release/libservicepoint.a
	$(CC) $(src) $(CFLAGS) -o $@

You have the choice of linking statically (recommended) or dynamically. When linked dynamically, you have to provide the cdylib at runtime in the same version, as there are no API/ABI guarantees yet. The Makefile in the example directory contains a bunch of additional compiler flags you might want to add depending on your use case.

Notes on differences to rust library

function names are: sp_ <struct_name> <rust name>.
Instances get consumed in the same way they do when writing rust code. Do not use an instance after an (implicit!) free.
Option or Result<T, E> turn into nullable return values - check for NULL!
There are no specifics for C++ here yet. You might get a nicer header when generating directly for C++, but it should be usable.
Reading and writing to instances concurrently is not safe. Only reading concurrently is safe.
documentation is included in the header and available online

Safety

Functions expect that C code honors NonNull annotations.

Any created instances have to be freed in some way. Pointers to those instances cannot be used anymore after that.

Instances cannot be shared between threads and need to be locked in the using code.

Enum values have to be used as-is. Do not pass values that are not part of the enum.

UTF-8 or UTF-32 encoding has to be used properly.

Brightness values provided as u8 parameters must be in range.

Everything else

Look at the main project README for further information.

4.3 KiB Raw Blame History