109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
# servicepoint_binding_c
|
|
|
|
[](https://crates.io/crates/servicepoint)
|
|
[](https://crates.io/crates/servicepoint)
|
|
[](https://docs.rs/servicepoint/latest/servicepoint/)
|
|
[](./LICENSE)
|
|
|
|
In [CCCB](https://berlin.ccc.de/), 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](https://git.berlin.ccc.de/servicepoint/servicepoint) library, enabling users to parse, encode and send packets to this display via UDP.
|
|
|
|
## Examples
|
|
|
|
```c++
|
|
#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:
|
|
|
|
```bash
|
|
git submodule add https://git.berlin.ccc.de/servicepoint/servicepoint-binding-c.git
|
|
git commit -m "add servicepoint-binding-c submodule"
|
|
```
|
|
|
|
Update your Makefile:
|
|
|
|
```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<T> 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](https://docs.rs/servicepoint_binding_c/latest/servicepoint_binding_c/)
|
|
|
|
## 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](https://git.berlin.ccc.de/servicepoint/servicepoint/src/branch/main/README.md) for
|
|
further information.
|