path: root/src/libcoopgamma_native.pyx.gpp

# -*- python -*-
'''
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
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this library.  If not, see <http://www.gnu.org/licenses/>.
'''
cimport cython

from libc.stddef cimport size_t
from libc.stdlib cimport malloc, free
from libc.stdint cimport int64_t, uint8_t, uint16_t, uint32_t, uint64_t, intptr_t
from libc.errno cimport errno



ctypedef int libcoopgamma_support_t
# Values used to indicate the support for gamma adjustments

ctypedef int libcoopgamma_depth_t
# Values used to tell which datatype is used for the gamma ramp stops
# 
# The values will always be the number of bits for integral types, and
# negative for floating-point types

ctypedef int libcoopgamma_lifespan_t
# Values used to tell when a filter should be removed

ctypedef int libcoopgamma_colourspace_t
# Colourspaces



cdef extern from "include-libcoopgamma.h":

    ctypedef struct libcoopgamma_ramps_t:
    # Gamma ramp structure
        size_t red_size
        # The number of stops in the red ramp
        size_t green_size
        # The number of stops in the green ramp
        size_t blue_size
        # The number of stops in the blue ramp
        void* red
        # The red ramp
        void* green
        # The green ramp
        void* blue
        # The blue ramp

    ctypedef struct libcoopgamma_filter_t:
    # Data set to the coopgamma server to apply, update, or remove a filter
        int64_t priority
        # The priority of the filter, higher priority is applied first.
        # The gamma correction should have priority 0.
        char* crtc
        # The CRTC for which this filter shall be applied
        char* fclass
        # Identifier for the filter
        # 
        # The syntax must be "${PACKAGE_NAME}::${COMMAND_NAME}::${RULE}"
        libcoopgamma_lifespan_t lifespan
        # When shall the filter be removed?
        # 
        # If this member's value is `LIBCOOPGAMMA_REMOVE`,
        # only `.crtc` and `.class` need also be defined
        libcoopgamma_depth_t depth
        # The data type and bit-depth of the ramp stops
        libcoopgamma_ramps_t ramps
        # The gamma ramp adjustments of the filter

    ctypedef struct libcoopgamma_crtc_info_t:
    # Gamma ramp meta information for a CRTC
        int cooperative
        # Is cooperative gamma server running?
        libcoopgamma_depth_t depth
        # The data type and bit-depth of the ramp stops
$$<cpp <<EOF | tail -n 1 | sed '/#/d'
#include <limits.h>
#if INT_MAX != LONG_MAX
        int padding__
#endif
EOF
$$>
        size_t red_size
        # The number of stops in the red ramp
        size_t green_size
        # The number of stops in the green ramp
        size_t blue_size
        # The number of stops in the blue ramp
        libcoopgamma_colourspace_t colourspace
        # The monitor's colurspace
        int have_gamut
        # Whether `.red_x`, `.red_y`, `.green_x`, `.green_y`, `.blue_x`, `.blue_y`,
        # `.white_x`, and `.white_y` are set.
        # 
        # If this is true, but the colourspace is not RGB (or sRGB),
        # there is something wrong. Please also check the colourspace.
        unsigned red_x
        # The x-value (CIE xyY) of the monitor's red colour, multiplied by 1024
        unsigned red_y
        # The y-value (CIE xyY) of the monitor's red colour, multiplied by 1024
        unsigned green_x
        # The x-value (CIE xyY) of the monitor's green colour, multiplied by 1024
        unsigned green_y
        # The y-value (CIE xyY) of the monitor's green colour, multiplied by 1024
        unsigned blue_x
        # The x-value (CIE xyY) of the monitor's blue colour, multiplied by 1024
        unsigned blue_y
        # The y-value (CIE xyY) of the monitor's blue colour, multiplied by 1024
        unsigned white_x
        # The x-value (CIE xyY) of the monitor's default white point, multiplied by 1024
        unsigned white_y
        # The y-value (CIE xyY) of the monitor's default white point, multiplied by 1024

    ctypedef struct libcoopgamma_filter_query_t:
    # Data sent to the coopgamma server when requestng the current filter table
        int64_t high_priority
        # Do no return filters with higher priority than this value
        int64_t low_priority
        # Do no return filters with lower priority than this value
        char* crtc
        # The CRTC for which the the current filters shall returned
        int coalesce
        # Whether to coalesce all filters into one gamma ramp triplet
$$<cpp <<EOF | tail -n 1 | sed '/#/d'
#include <limits.h>
#if INT_MAX != LONG_MAX
        int padding__
#endif
EOF
$$>

    ctypedef struct libcoopgamma_queried_filter_t:
    # Stripped down version of `libcoopgamma_filter` which only contains
    # the information returned in response to "Command: get-gamma"
        int64_t priority
        # The filter's priority
        char* fclass
        # The filter's class
        libcoopgamma_ramps_t ramps
        # The gamma ramp adjustments of the filter

    ctypedef struct libcoopgamma_filter_table_t:
    # Response type for "Command: get-gamma": a list of applied filters
    # and meta-information that was necessary for decoding the response
        size_t red_size
        # The number of stops in the red ramp
        size_t green_size
        # The number of stops in the green ramp
        size_t blue_size
        # The number of stops in the blue ramp
        size_t filter_count
        # The number of filters
        libcoopgamma_queried_filter_t* filters
        # The filters, should be ordered by priority in descending order,
        # lest there is something wrong with the coopgamma server
        # 
        # If filter coalition was requested, there will be exactly one
        # filter (`.filter_count == 1`) and `.filters->class == NULL`
        # and `.filters->priority` is undefined.
        libcoopgamma_depth_t depth
        # The data type and bit-depth of the ramp stops
$$<cpp <<EOF | tail -n 1 | sed '/#/d'
#include <limits.h>
#if INT_MAX != LONG_MAX
        int padding__
#endif
EOF
$$>

    ctypedef struct libcoopgamma_error_t:
    # Error message from coopgamma server
        uint64_t number
        # Error code
        # 
        # If `.custom` is false, 0 indicates success, otherwise,
        # 0 indicates that no error code has been assigned
        int custom
        # Is this a custom error?
        int server_side
        # Did the error occur on the server-side?
        char* description
        # Error message, can be `NULL` if `.custom` is false

    ctypedef struct libcoopgamma_context_t:
    # Library state
    # 
    # Use of this structure is not thread-safe create one instance
    # per thread that uses this structure
        libcoopgamma_error_t error
        # The error of the last failed function call
        # 
        # This member is undefined after successful function call
        int fd
        # File descriptor for the socket
        int have_all_headers
        # Whether `libcoopgamma_synchronise` have read the empty end-of-headers line
        int bad_message
        # Whether `libcoopgamma_synchronise` is reading a corrupt but recoverable message
        int blocking
        # Is communication blocking?
        uint32_t message_id
        # Message ID of the next message
        uint32_t in_response_to
        # The ID of outbound message to which the inbound message being read by
        # `libcoopgamma_synchronise` is a response
        char* outbound
        # Buffer with the outbound message
        size_t outbound_head
        # The write head for `outbound`
        size_t outbound_tail
        # The read head for `outbound`
        size_t outbound_size
        # The allocation size of `outbound`
        char* inbound
        # Buffer with the inbound message
        size_t inbound_head
        # The write head for `inbound`
        size_t inbound_tail
        # The read head for `inbound`
        size_t inbound_size
        # The allocation size of `inbound`
        size_t length
        # The value of 'Length' header in the inbound message
        size_t curline
        # The beginning of the current line that is being read by `libcoopgamma_synchronise`

    ctypedef struct libcoopgamma_async_context_t:
    # Information necessary to identify and parse a response from the server
        uint32_t message_id
        # The value of the 'In response to' header in the waited message
        int coalesce
        # Whether to coalesce all filters into one gamma ramp triplet



cdef extern int libcoopgamma_ramps_initialise_(libcoopgamma_ramps_t* 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(libcoopgamma_ramps_t* 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
'''



def libcoopgamma_native_get_methods():
    '''
    List all recognised adjustment method
    
    SIGCHLD must not be ignored or blocked
    
    @return  :list<str>|int  Either the value of `errno` (on failure), or (on success) a list
                             of names. You should only free the outer pointer, inner pointers
                             are subpointers of the outer pointer and cannot be freed.
    '''
    cdef char** methods = libcoopgamma_get_methods()
    cdef bytes bs
    if methods is NULL:
        return int(errno)
    ret = []
    i = 0
    while methods[i] is not NULL:
        bs = methods[i]
        ret.append(bs.decode('utf-8', 'strict'))
    free(methods)


def libcoopgamma_native_get_method_and_site(method : str, site : str):
    '''
    Get the adjustment method and site
    
    SIGCHLD must not be ignored or blocked
    
    @param   method:str?         The adjustment method, `None` for automatic
    @param   site:str?           The site, `None` for automatic
    @return  :int|(:str, :str?)  Either the value of `errno` (on failure), or (on success)
                                 the selected adjustment method and the selected the
                                 selected site. If the adjustment method only supports
                                 one site or if `site` is `None` and no site can be
                                 selected automatically, the selected site (the second
                                 element in the returned tuple) will be `None`.
    '''
    cdef char* rcsmethod = NULL
    cdef char* rcssite = NULL
    cdef bytes rbsmethod
    cdef bytes rbssite
    rmethod, rsite = None, None
    if libcoopgamma_get_method_and_site(method, site, &rbsmethod, &rbssite) < 0:
        return int(errno)
    rbsmethod = rcsmethod
    rmethod = rbsmethod.decode('utf-8', 'strict')
    if rcssite is not None:
        rbssite = rcssite
        rsite = rbssite.decode('utf-8', 'strict')
    return (rmethod, rsite)


def libcoopgamma_native_get_pid_file(method : str, site : str):
    '''
    Get the PID file of the coopgamma server
    
    SIGCHLD must not be ignored or blocked
    
    @param   method:str?  The adjustment method, `None` for automatic
    @param   site:str?    The site, `None` for automatic
    @return  :int|str?    Either the value of `errno` (on failure), or (on success)
                          the pathname of the server's PID file. `None` if the server
                          does not use PID files.
    '''
    cdef char* path
    char bytes bs
    path = libcoopgamma_native_get_pid_file(method, site)
    if errno != 0 and path is NULL:
        bs = path
        return bs.decode('utf-8', 'strict')
    return int(errno)


def libcoopgamma_native_get_socket_file(method : str, site : str):
    '''
    Get the socket file of the coopgamma server
    
    SIGCHLD must not be ignored or blocked
    
    @param   method:int|str?  The adjustment method, `None` for automatic
    @param   site:str?        The site, `None` for automatic
    @return  :int|str?        Either the value of `errno` (on failure), or (on success)
                              the pathname of the server's socket, `None` if the server does have
                              its own socket, which is the case when communicating with a server
                              in a multi-server display server like mds
    '''
    cdef char* path
    char bytes bs
    path = libcoopgamma_native_get_socket_file(method, site)
    if errno != 0 and path is NULL:
        bs = path
        return bs.decode('utf-8', 'strict')
    return int(errno)


def libcoopgamma_native_context_create():
    '''
    Create an instance of `libcoopgamma_context_t`
    
    @return  :(:bool, :int)  Element 0: Whether the call was successful
                             Element 1: The value of `errno` on failure, and on
                                        success, the address of the created instance
    '''
    cdef libcoopgamma_context_t* this
    this = <libcoopgamma_context_t*>malloc(sizeof(*this))
    if this is None:
        return (False, int(errno))
    if libcoopgamma_context_initialise(this) < 0:
        saved_errno = int(errno)
        libcoopgamma_context_destroy(this, <int>0)
        free(this)
        return (False, saved_errno)
    return (True, int(<intptr_t><void*>this))


def libcoopgamma_native_context_free(address : int):
    '''
    Disconnect and free an instance of a `libcoopgamma_context_t`
    
    @param  address:int  The address of the `libcoopgamma_context_t` instance
    '''
    cdef libcoopgamma_context_t* this = <libcoopgamma_context_t*><void*><intptr_t>address
    libcoopgamma_context_destroy(this, <int>1)
    free(this)


def libcoopgamma_native_context_marshal(address : int):
    '''
    Marshal a `libcoopgamma_context_t` into a buffer
    
    @param   address:int  The address of the instance to marshal
    @return  :int|bytes   Either the value of `errno` (on failure), or (on success)
                          a byte representation of the instance
    '''
    cdef libcoopgamma_context_t* this = <libcoopgamma_context_t*><void*><intptr_t>address
    cdef size_t n = libcoopgamma_context_marshal(this, NULL)
    cdef char* buf = <char*>malloc(n)
    if buf is NULL:
        return int(errno)
    libcoopgamma_context_marshal(this, buf)
    ret = bytes(<int>(char[i]) for i in range(int(n)))
    free(buf)
    return ret


def libcoopgamma_native_context_unmarshal(buf : bytes):
    '''
    Unmarshal a `libcoopgamma_context_t` from a buffer
    
    @param   buf:bytes      The buffer with the marshalled instance
    @return  :(:int, :int)  Element 0: 0 = Success
                                       1 = Incompatible downgrade
                                       2 = Incompatible upgrade
                                       -1 = `errno` is returned
                            Element 1: If [0] = 0:  The address of the unmarshalled instance
                                       If [0] = -1: The value of `errno`
    '''
    cdef size_t ret1 = 0
    cdef libcoopgamma_context_t* this
    this = <libcoopgamma_context_t*>malloc(sizeof(*this))
    if this is None:
        return (-1, int(errno))
    if libcoopgamma_context_initialise(this) < 0:
        saved_errno = int(errno)
        libcoopgamma_context_destroy(this)
        return (-1, int(errno))
    ret0 = <int>libcoopgamma_context_unmarshal(this, <bytes>buf, &ret1)
    return (ret0, <int>ret1)


def libcoopgamma_native_context_set_fd(address : int, fd : int):
    '''
    Set the field for socket file descriptor in a `libcoopgamma_context_t` 
    
    @param  address:int  The address of the `libcoopgamma_context_t` instance
    @param  fd:int       The file descriptor
    '''
    cdef libcoopgamma_context_t* this = <libcoopgamma_context_t*><void*><intptr_t>address
    this->fd = fd


def libcoopgamma_native_context_create():
    '''
    Create an instance of `libcoopgamma_context_t`
    
    @return  :(:bool, :int)  Element 0: Whether the call was successful
                             Element 1: The value of `errno` on failure, and on
                                        success, the address of the created instance
    '''
    cdef libcoopgamma_context_t* this
    this = <libcoopgamma_context_t*>malloc(sizeof(*this))
    if this is None:
        return (False, int(errno))
    if libcoopgamma_context_initialise(this) < 0:
        saved_errno = int(errno)
        libcoopgamma_context_destroy(this, <int>0)
        free(this)
        return (False, saved_errno)
    return (True, int(<intptr_t><void*>this))


def libcoopgamma_native_async_context_free(address : int):
    '''
    Free an instance of a `libcoopgamma_async_context_t`
    
    @param  address:int  The address of the `libcoopgamma_async_context_t` instance
    '''
    cdef libcoopgamma_async_context_t* this = <libcoopgamma_async_context_t*><void*><intptr_t>address
    libcoopgamma_async_context_destroy(this)
    free(this)


def libcoopgamma_native_async_context_marshal(address : int):
    '''
    Marshal a `libcoopgamma_async_context_t` into a buffer
    
    @param   address:int  The address of the instance to marshal
    @return  :int|bytes   Either the value of `errno` (on failure), or (on success)
                          a byte representation of the instance
    '''
    cdef libcoopgamma_async_context_t* this = <libcoopgamma_async_context_t*><void*><intptr_t>address
    cdef size_t n = libcoopgamma_async_context_marshal(this, NULL)
    cdef char* buf = <char*>malloc(n)
    if buf is NULL:
        return int(errno)
    libcoopgamma_async_context_marshal(this, buf)
    ret = bytes(<int>(char[i]) for i in range(int(n)))
    free(buf)
    return ret


def libcoopgamma_native_async_context_unmarshal(buf : bytes):
    '''
    Unmarshal a `libcoopgamma_async_context_t` from a buffer
    
    @param   buf:bytes      The buffer with the marshalled instance
    @return  :(:int, :int)  Element 0: 0 = Success
                                       1 = Incompatible downgrade
                                       2 = Incompatible upgrade
                                       -1 = `errno` is returned
                            Element 1: If [0] = 0:  The address of the unmarshalled instance
                                       If [0] = -1: The value of `errno`
    '''
    cdef size_t ret1 = 0
    cdef libcoopgamma_async_context_t* this
    this = <libcoopgamma_async_context_t*>malloc(sizeof(*this))
    if this is None:
        return (-1, int(errno))
    if libcoopgamma_async_context_initialise(this) < 0:
        saved_errno = int(errno)
        libcoopgamma_async_context_destroy(this)
        return (-1, int(errno))
    ret0 = <int>libcoopgamma_async_context_unmarshal(this, <bytes>buf, &ret1)
    return (ret0, <int>ret1)


def libcoopgamma_native_connect(method : str, site : str, address : int):
    '''
    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:str?  The adjustment method, `NULL` for automatic
    @param   site:str?    The site, `NULL` for automatic
    @param   address:int  The address of the state of the library, must be initialised
    @return  :int?        `None`, 0 if the server on could not be initialised,
                          the value `errno` on other errors
    '''
    cdef libcoopgamma_context_t* ctx = <libcoopgamma_context_t*><void*><intptr_t>address
    if libcoopgamma_connect(method, site, ctx) < 0:
        return int(errno)
    return None


def libcoopgamma_native_set_nonblocking(address : int, nonblocking : bool):
    '''
    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   address:int       The address of the state of the library, must be connected
    @param   nonblocking:bool  Nonblocking mode?
    @return  :int              Zero on success, the value of `errno` on error
    '''
    cdef libcoopgamma_context_t* ctx = <libcoopgamma_context_t*><void*><intptr_t>address
    if libcoopgamma_set_nonblocking(ctx, <int>(1 if nonblocking else 0)) < 0:
        return int(errno)
    return 0


def libcoopgamma_native_flush(address : int):
    '''
    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   address:int  The address of the state of the library, must be connected
    @return  :int         Zero on success, the value of `errno` on error
    '''
    cdef libcoopgamma_context_t* ctx = <libcoopgamma_context_t*><void*><intptr_t>address
    if libcoopgamma_flush(ctx) < 0:
        return int(errno)
    return 0


def libcoopgamma_native_synchronise(address : int, pending : list):
    '''
    Wait for the next message to be received
    
    @param   address:int        The address of the state of the library, must be connected
    @param   pending:list<int>  Addresses of the information for each pending request
    @return  :(:bool, :int)     If [0] = 0: [1] is the value of `errno`
                                   [0] = 1: [1] is the selected request
    '''
    cdef libcoopgamma_context_t* ctx = <libcoopgamma_context_t*><void*><intptr_t>address
    cdef libcoopgamma_async_context_t* pends
    cdef size_t selected = 0
    pends = <libcoopgamma_async_context_t*>malloc(n * sizeof(*pends))
    if pends is None:
        pass
    for i in range(len(pending)):
        pends[i] = *<libcoopgamma_async_context_t*><void*><intptr_t>pendings[i]
    if libcoopgamma_synchronise(ctx, pends, <size_t>len(pending), &selected) < 0:
        return (False, int(errno))
    return (True, <int>selected)


def libcoopgamma_native_skip_message(address : int):
    '''
    Tell the library that you will not be parsing a receive message
    
    @param  address:int  The address of the state of the library, must be connected
    '''
    libcoopgamma_skip_message(<libcoopgamma_context_t*><void*><intptr_t>address)