diff options
| -rw-r--r-- | src/libcoopgamma_native.pyx.gpp | 544 |
1 files changed, 543 insertions, 1 deletions
diff --git a/src/libcoopgamma_native.pyx.gpp b/src/libcoopgamma_native.pyx.gpp index c3a5a2b..bb835ec 100644 --- a/src/libcoopgamma_native.pyx.gpp +++ b/src/libcoopgamma_native.pyx.gpp @@ -1,6 +1,6 @@ # -*- python -*- ''' -pylibcoopgamma -- Python library for interfacing with cooperative gamma servers +1;2802;0cpylibcoopgamma -- Python library for interfacing with cooperative gamma servers Copyright (C) 2016 Mattias Andrée (maandree@kth.se) 1;2802;0c This library is free software: you can redistribute it and/or modify @@ -244,3 +244,545 @@ $$> int coalesce # Whether to coalesce all filters into one gamma ramp triplet + + +cdef extern int libcoopgamma_ramps_initialise_(void* this, size_t width) +''' +Initialise a `libcoopgamma_ramps_t` + +`this->red_size`, `this->green_size`, and `this->blue_size` must already be set + +@param this The record to initialise +@param width The `sizeof(*(this->red))` +@return Zero on success, -1 on error +''' + +cdef extern void libcoopgamma_ramps_destroy(void* this) +''' +Release all resources allocated to a `libcoopgamma_ramps_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_ramps_initialise +or failed call to `libcoopgamma_ramps_unmarshal + +@param this The record to destroy +''' + +cdef extern int libcoopgamma_filter_initialise(libcoopgamma_filter_t* this) +''' +Initialise a `libcoopgamma_filter_t` + +@param this The record to initialise +@return Zero on success, -1 on err +''' + +cdef extern void libcoopgamma_filter_destroy(libcoopgamma_filter_t* this) +''' +Release all resources allocated to a `libcoopgamma_filter_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_filter_initialise` +or failed call to `libcoopgamma_filter_unmarshal` + +@param this The record to destroy +''' + +cdef extern int libcoopgamma_crtc_info_initialise(libcoopgamma_crtc_info_t* this) +''' +Initialise a `libcoopgamma_crtc_info_t` + +@param this The record to initialise +@return Zero on success, -1 on error +''' + +cdef extern void libcoopgamma_crtc_info_destroy(libcoopgamma_crtc_info_t* this) +''' +Release all resources allocated to a `libcoopgamma_crtc_info_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_crtc_info_initialise` +or failed call to `libcoopgamma_crtc_info_unmarshal + +@param this The record to destroy +''' + +cdef extern int libcoopgamma_filter_query_initialise(libcoopgamma_filter_query_t* this) +''' +Initialise a `libcoopgamma_filter_query_t` + +@param this The record to initialise +@return Zero on success, -1 on error +''' + +cdef extern void libcoopgamma_filter_query_destroy(libcoopgamma_filter_query_t* this) +''' +Release all resources allocated to a `libcoopgamma_filter_query_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_filter_query_initialise` +or failed call to `libcoopgamma_filter_query_unmarshal` + +@param this The record to destroy +''' + +cdef extern int libcoopgamma_queried_filter_initialise(libcoopgamma_queried_filter_t* this) +''' +Initialise a `libcoopgamma_queried_filter_t` + +@param this The record to initialise +@return Zero on success, -1 on error +''' + +cdef extern void libcoopgamma_queried_filter_destroy(libcoopgamma_queried_filter_t* this) +''' +Release all resources allocated to a `libcoopgamma_queried_filter_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_queried_filter_initialise` +or failed call to `libcoopgamma_queried_filter_unmarshal + +@param this The record to destro +''' + +cdef extern int libcoopgamma_filter_table_initialise(libcoopgamma_filter_table_t* this) +''' +Initialise a `libcoopgamma_filter_table_t + +@param this The record to initialise +@return Zero on success, -1 on error +''' + +cdef extern void libcoopgamma_filter_table_destroy(libcoopgamma_filter_table_t* this) +''' +Release all resources allocated to a `libcoopgamma_filter_table_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_filter_table_initialise` +or failed call to `libcoopgamma_filter_table_unmarshal` + +@param this The record to destroy +''' + +cdef extern void libcoopgamma_filter_table_destroy(libcoopgamma_filter_table_t* this) +''' +Release all resources allocated to a `libcoopgamma_filter_table_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_filter_table_initialise` +or failed call to `libcoopgamma_filter_table_unmarshal` + +@param this The record to destroy +''' + +cdef extern int libcoopgamma_error_initialise(libcoopgamma_error_t* this) +''' +Initialise a `libcoopgamma_error_t` + +@param this The record to initialise +@return Zero on success, -1 on error +''' + +cdef extern void libcoopgamma_error_destroy(libcoopgamma_error_t* this) +''' +Release all resources allocated to a `libcoopgamma_error_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_error_initialise` +or failed call to `libcoopgamma_error_unmarshal` + +@param this The record to destroy +''' + +cdef extern int libcoopgamma_context_initialise(libcoopgamma_context_t* this) +''' +Initialise a `libcoopgamma_context_t` + +@param this The record to initialise +@return Zero on success, -1 on error +''' + +cdef extern void libcoopgamma_context_destroy(libcoopgamma_context_t* this, int disconnect) +''' +Release all resources allocated to a `libcoopgamma_context_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_context_initialise` +or failed call to `libcoopgamma_context_unmarshal` + +@param this The record to destroy +@param disconnect Disconnect from the server? +''' + +cdef extern size_t libcoopgamma_context_marshal(const libcoopgamma_context_t* this, void* buf) +''' +Marshal a `libcoopgamma_context_t` into a buffer + +@param this The record to marshal +@param buf The output buffer, `NULL` to only measure + how large this buffer has to be +@return The number of marshalled bytes, or if `buf == NULL`, + how many bytes would be marshalled if `buf != NULL` +''' + +cdef extern int libcoopgamma_context_unmarshal(libcoopgamma_context_t* this, const void* buf, size_t* n) +''' +Unmarshal a `libcoopgamma_context_t` from a buffer + +@param this The output parameter for unmarshalled record +@param buf The buffer with the marshalled record +@param n Output parameter for the number of unmarshalled bytes, undefined on failure +@return `LIBCOOPGAMMA_SUCCESS` (0), `LIBCOOPGAMMA_INCOMPATIBLE_DOWNGRADE`, + `LIBCOOPGAMMA_INCOMPATIBLE_UPGRADE`, or `LIBCOOPGAMMA_ERRNO_SET` +''' + +cdef extern int libcoopgamma_async_context_initialise(libcoopgamma_async_context_t* this) +''' +Initialise a `libcoopgamma_async_context_t` + +@param this The record to initialise +@return Zero on success, -1 on error +''' + +cdef extern void libcoopgamma_async_context_destroy(libcoopgamma_async_context_t* this) +''' +Release all resources allocated to a `libcoopgamma_async_context_t`, +the allocation of the record itself is not freed + +Always call this function after failed call to `libcoopgamma_async_context_initialise` +or failed call to `libcoopgamma_async_context_unmarshal` + +@param this The record to destroy +''' + +cdef extern size_t libcoopgamma_async_context_marshal(const libcoopgamma_async_context_t* this, void* buf) +''' +Marshal a `libcoopgamma_async_context_t` into a buffer + +@param this The record to marshal +@param buf The output buffer, `NULL` to only measure + how large this buffer has to be +@return The number of marshalled bytes, or if `buf == NULL`, + how many bytes would be marshalled if `buf != NULL` +''' + +cdef extern int libcoopgamma_async_context_unmarshal(libcoopgamma_async_context_t* this, + const void* buf, size_t* n) +''' +Unmarshal a `libcoopgamma_async_context_t` from a buffer + +@param this The output parameter for unmarshalled record +@param buf The buffer with the marshalled record +@param n Output parameter for the number of unmarshalled bytes, undefined on failure +@return `LIBCOOPGAMMA_SUCCESS` (0), `LIBCOOPGAMMA_INCOMPATIBLE_DOWNGRADE`, + `LIBCOOPGAMMA_INCOMPATIBLE_UPGRADE`, or `LIBCOOPGAMMA_ERRNO_SET` +''' + +cdef extern char** libcoopgamma_get_methods() +''' +List all recognised adjustment method + +SIGCHLD must not be ignored or blocked + +@return A `NULL`-terminated list of names. You should only free + the outer pointer, inner pointers are subpointers of the + outer pointer and cannot be freed. `NULL` on error. +''' + +cdef extern int libcoopgamma_get_method_and_site(const char* method, const char* site, + char** methodp, char** sitep) +''' +Get the adjustment method and site + +SIGCHLD must not be ignored or blocked + +@param method The adjustment method, `NULL` for automatic +@param site The site, `NULL` for automatic +@param methodp Output pointer for the selected adjustment method, + which cannot be `NULL`. It is safe to call + this function with this parameter set to `NULL`. +@param sitep Output pointer for the selected site, which will + be `NULL` the method only supports one site or if + `site == NULL` and no site can be selected + automatically. It is safe to call this function + with this parameter set to `NULL`. +@return Zero on success, -1 on error +''' + +cdef extern char* libcoopgamma_get_pid_file(const char* method, const char* site) +''' +Get the PID file of the coopgamma server + +SIGCHLD must not be ignored or blocked + +@param method The adjustment method, `NULL` for automatic +@param site The site, `NULL` for automatic +@return The pathname of the server's PID file, `NULL` on error + or if there server does not use PID files. The later + case is detected by checking that `errno` is set to 0. +''' + +cdef extern char* libcoopgamma_get_socket_file(const char* method, const char* site) +''' +Get the socket file of the coopgamma server + +SIGCHLD must not be ignored or blocked + +@param method The adjustment method, `NULL` for automatic +@param site The site, `NULL` for automatic +@return The pathname of the server's socket, `NULL` on error + or if there server does have its own socket. The later + case is detected by checking that `errno` is set to 0, + and is the case when communicating with a server in a + multi-server display server like mds. +''' + +cdef extern int libcoopgamma_connect(const char* method, const char* site, libcoopgamma_context_t* ctx) +''' +Connect to a coopgamma server, and start it if necessary + +Use `libcoopgamma_context_destroy` to disconnect + +SIGCHLD must not be ignored or blocked + +@param method The adjustment method, `NULL` for automatic +@param site The site, `NULL` for automatic +@param ctx The state of the library, must be initialised +@return Zero on success, -1 on error. On error, `errno` is set + to 0 if the server could not be initialised. +''' + +cdef extern int libcoopgamma_set_nonblocking(libcoopgamma_context_t* ctx, int nonblocking) +''' +By default communication is blocking, this function +can be used to switch between blocking and nonblocking + +After setting the communication to nonblocking, +`libcoopgamma_flush`, `libcoopgamma_synchronise` and +and request-sending functions can fail with EAGAIN and +EWOULDBLOCK. It is safe to continue with `libcoopgamma_flush` +(for `libcoopgamma_flush` it selfand equest-sending functions) +or `libcoopgamma_synchronise` just like EINTR failure. + +@param ctx The state of the library, must be connected +@param nonblocking Nonblocking mode? +@return Zero on success, -1 on error +''' + +cdef extern int libcoopgamma_flush(libcoopgamma_context_t* ctx) +''' +Send all pending outbound data + +If this function or another function that sends a request +to the server fails with EINTR, call this function to +complete the transfer. The `async` parameter will always +be in a properly configured state if a function fails +with EINTR. + +@param ctx The state of the library, must be connected +@return Zero on success, -1 on error +''' + +cdef extern int libcoopgamma_synchronise(libcoopgamma_context_t* ctx, libcoopgamma_async_context_t* pending, + size_t n, size_t* selected) +''' +Wait for the next message to be received + +@param ctx The state of the library, must be connected +@param pending Information for each pending request +@param n The number of elements in `pending` +@param selected The index of the element in `pending` which corresponds + to the first inbound message, note that this only means + that the message is not for any of the other request, + if the message is corrupt any of the listed requests can + be selected even if it is not for any of the requests. + Functions that parse the message will detect such corruption. +@return Zero on success, -1 on error. If the the message is ignored, + which happens if corresponding `libcoopgamma_async_context_t` + is not listed, -1 is returned and `errno` is set to 0. If -1 + is returned, `errno` is set to `ENOTRECOVERABLE` you have + received a corrupt message and the context has been tainted + beyond recover. +''' + +cdef extern void libcoopgamma_skip_message(libcoopgamma_context_t* ctx) +''' +Tell the library that you will not be parsing a receive message + +@param ctx The state of the library, must be connected +''' + +cdef extern int libcoopgamma_get_crtcs_send(libcoopgamma_context_t* ctx, libcoopgamma_async_context_t* async) +''' +List all available CRTC:s, send request part + +Cannot be used before connecting to the server + +@param ctx The state of the library, must be connected +@param async Information about the request, that is needed to + identify and parse the response, is stored here +@return Zero on success, -1 on error +''' + +cdef extern char** libcoopgamma_get_crtcs_recv(libcoopgamma_context_t* ctx, libcoopgamma_async_context_t* async) +''' +List all available CRTC:s, receive response part + +@param ctx The state of the library, must be connected +@param async Information about the request +@return A `NULL`-terminated list of names. You should only free + the outer pointer, inner pointers are subpointers of the + outer pointer and cannot be freed. `NULL` on error, in + which case `ctx->error` (rather than `errno`) is read + for information about the error. +''' + +cdef extern char** libcoopgamma_get_crtcs_sync(libcoopgamma_context_t* ctx) +''' +List all available CRTC:s, synchronous version + +This is a synchronous request function, as such, +you have to ensure that communication is blocking +(default), and that there are not asynchronous +requests waiting, it also means that EINTR:s are +silently ignored and there no wait to cancel the +operation without disconnection from the server + +@param ctx The state of the library, must be connected +@return A `NULL`-terminated list of names. You should only free + the outer pointer, inner pointers are subpointers of the + outer pointer and cannot be freed. `NULL` on error, in + which case `ctx->error` (rather than `errno`) is read + for information about the error. +''' + +cdef extern int libcoopgamma_get_gamma_info_send(const char* crtc, libcoopgamma_context_t* ctx, + libcoopgamma_async_context_t* async) +''' +Retrieve information about a CRTC:s gamma ramps, send request part + +Cannot be used before connecting to the server + +@param crtc The name of the CRTC +@param ctx The state of the library, must be connected +@param async Information about the request, that is needed to + identify and parse the response, is stored here +@return Zero on success, -1 on error +''' + +cdef extern int libcoopgamma_get_gamma_info_recv(libcoopgamma_crtc_info_t* info, libcoopgamma_context_t* ctx, + libcoopgamma_async_context_t* async) +''' +Retrieve information about a CRTC:s gamma ramps, receive response part + +@param info Output parameter for the information, must be initialised +@param ctx The state of the library, must be connected +@param async Information about the request +@return Zero on success, -1 on error, in which case `ctx->error` + (rather than `errno`) is read for information about the error +''' + +cdef extern int libcoopgamma_get_gamma_info_sync(const char* crtc, libcoopgamma_crtc_info_t* info, + libcoopgamma_context_t* ctx) +''' +Retrieve information about a CRTC:s gamma ramps, synchronous version + +This is a synchronous request function, as such, +you have to ensure that communication is blocking +(default), and that there are not asynchronous +requests waiting, it also means that EINTR:s are +silently ignored and there no wait to cancel the +operation without disconnection from the server + +@param crtc The name of the CRTC +@param info Output parameter for the information, must be initialised +@param ctx The state of the library, must be connected +@return Zero on success, -1 on error, in which case `ctx->error` + (rather than `errno`) is read for information about the error +''' + +cdef extern int libcoopgamma_get_gamma_send(const libcoopgamma_filter_query_t* query, + libcoopgamma_context_t* ctx, libcoopgamma_async_context_t* async) +''' +Retrieve the current gamma ramp adjustments, send request part + +Cannot be used before connecting to the server + +@param query The query to send +@param ctx The state of the library, must be connected +@param async Information about the request, that is needed to + identify and parse the response, is stored here +@return Zero on success, -1 on error +''' + +cdef extern int libcoopgamma_get_gamma_recv(libcoopgamma_filter_table_t* table, libcoopgamma_context_t* ctx, + libcoopgamma_async_context_t* async) +''' +Retrieve the current gamma ramp adjustments, receive response part + +@param table Output for the response, must be initialised +@param ctx The state of the library, must be connected +@param async Information about the request +@return Zero on success, -1 on error, in which case `ctx->error` + (rather than `errno`) is read for information about the error +''' + +cdef extern int libcoopgamma_get_gamma_sync(const libcoopgamma_filter_query_t* query, + libcoopgamma_filter_table_t* table, libcoopgamma_context_t* ctx) +''' +Retrieve the current gamma ramp adjustments, synchronous version + +This is a synchronous request function, as such, +you have to ensure that communication is blocking +(default), and that there are not asynchronous +requests waiting, it also means that EINTR:s are +silently ignored and there no wait to cancel the +operation without disconnection from the server + +@param query The query to send +@param table Output for the response, must be initialised +@param ctx The state of the library, must be connected +@return Zero on success, -1 on error, in which case `ctx->error` + (rather than `errno`) is read for information about the error +''' + +cdef extern int libcoopgamma_set_gamma_send(const libcoopgamma_filter_t* filter, libcoopgamma_context_t* ctx, + libcoopgamma_async_context_t* async) +''' +Apply, update, or remove a gamma ramp adjustment, send request part + +Cannot be used before connecting to the server + +@param filter The filter to apply, update, or remove, gamma ramp meta-data must match the CRTC's +@param ctx The state of the library, must be connected +@param async Information about the request, that is needed to + identify and parse the response, is stored here +@return Zero on success, -1 on error +''' + +cdef extern int libcoopgamma_set_gamma_recv(libcoopgamma_context_t* ctx, libcoopgamma_async_context_t* async) +''' +Apply, update, or remove a gamma ramp adjustment, receive response part + +@param ctx The state of the library, must be connected +@param async Information about the request +@return Zero on success, -1 on error, in which case `ctx->error` + (rather than `errno`) is read for information about the error +''' + +cdef extern int libcoopgamma_set_gamma_sync(const libcoopgamma_filter_t* filter, libcoopgamma_context_t* ctx) +''' +Apply, update, or remove a gamma ramp adjustment, synchronous version + +This is a synchronous request function, as such, +you have to ensure that communication is blocking +(default), and that there are not asynchronous +requests waiting, it also means that EINTR:s are +silently ignored and there no wait to cancel the +operation without disconnection from the server + +@param filter The filter to apply, update, or remove, gamma ramp meta-data must match the CRTC's +@param ctx The state of the library, must be connected +@return Zero on success, -1 on error, in which case `ctx->error` + (rather than `errno`) is read for information about the error +''' + |