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

1. 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"
   

2. Add a build step for the servicepoint library. If you use make, this could look something like this:

   dependencies: FORCE
   	cargo build --manifest-path=servicepoint-binding-c/Cargo.toml --release
   FORCE: ; 
   

3. Link against the library. If you are on linux and linking statically:

   ${CC} main.c \
   	-I servicepoint-binding-c/include \
   	-L servicepoint-binding-c/target/release \
   	-Wl,-Bstatic -lservicepoint_binding_c \
   	-Wl,-Bdynamic -llzma \
   	-o out/example
   

You have the choice of linking statically (recommended) or dynamically.

• The C example shows how to link statically against the staticlib variant.
• When linked dynamically, you have to provide the cdylib at runtime in the same version, as there are no API/ABI guarantees yet.

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.