aboutsummaryrefslogtreecommitdiffstats
path: root/src/libcoopgamma_native.pyx.gpp
diff options
context:
space:
mode:
authorMattias Andrée <maandree@kth.se>2016-08-08 19:26:04 +0200
committerMattias Andrée <maandree@kth.se>2016-08-08 19:31:19 +0200
commitf5a1ad4f34d3dfd906b63f3e38054e3b4df54bd6 (patch)
tree700dab5f35d8a72ff5ba66b548ee33bebf73ea7a /src/libcoopgamma_native.pyx.gpp
parentstruct and enums (diff)
downloadpylibcoopgamma-f5a1ad4f34d3dfd906b63f3e38054e3b4df54bd6.tar.gz
pylibcoopgamma-f5a1ad4f34d3dfd906b63f3e38054e3b4df54bd6.tar.bz2
pylibcoopgamma-f5a1ad4f34d3dfd906b63f3e38054e3b4df54bd6.tar.xz
native functions
Signed-off-by: Mattias Andrée <maandree@kth.se>
Diffstat (limited to 'src/libcoopgamma_native.pyx.gpp')
-rw-r--r--src/libcoopgamma_native.pyx.gpp544
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
+'''
+