native functions

Signed-off-by: Mattias Andrée <maandree@kth.se>

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
+'''
+