diff options
Diffstat (limited to '')
| -rw-r--r-- | libaxl.h | 227 |
1 files changed, 31 insertions, 196 deletions
@@ -1,6 +1,6 @@ /* See LICENSE file for copyright and license details. */ #ifndef LIBAXL_H -#define LIBAXL_H +#define LIBAXL_H 2 #include <stddef.h> #include <stdint.h> @@ -11,39 +11,29 @@ # define _LIBAXL_GCC_ONLY(...) #endif -#include "libaxl-types.h" -#include "libaxl-consts.h" -#include "libaxl-atoms.h" -#include "libaxl-events.h" -#include "libaxl-errors.h" -#include "libaxl-requests.h" -#include "libaxl-replies.h" -#include "libaxl-display-info.h" - /** - * The major version number of the highest version of X protocol - * of the library supports (the lowest version is 11.0). If you - * are using dynamic linking, you make also want to use the - * libaxl_protocol_major() function. - */ -#define LIBAXL_PROTOCOL_MAJOR 11 - -/** - * The minor version number of the highest version of X protocol - * of the library supports (the lowest version is 11.0). If you - * are using dynamic linking, you make also want to use the - * libaxl_protocol_minor() function. + * Opaque structure for connection to the X display server */ -#define LIBAXL_PROTOCOL_MINOR 0 +typedef struct libaxl_connection LIBAXL_CONNECTION; /* TODO man */ /** - * The version number of the highest version of X protocol of - * the library supports, as one integer where the major number - * is multiped by 100000, (the lowest version is 11.0, which is - * encoded as 1100000). If you are using dynamic linking, you - * make also want to use the libaxl_protocol_version() function. + * Opaque structure that wraps LIBAXL_CONNECTION with + * private data for the thread, all threads running at + * the same time shall access the display server + * via a unique LIBAXL_CONTEXT */ -#define LIBAXL_PROTOCOL_VERSION ((LIBAXL_PROTOCOL_MAJOR) * 100000 + (LIBAXL_PROTOCOL_MINOR)) +typedef struct libaxl_context LIBAXL_CONTEXT; /* TODO man */ + +#include "libaxl/types.h" +#include "libaxl/consts.h" +#include "libaxl/atoms.h" +#include "libaxl/events.h" +#include "libaxl/errors.h" +#include "libaxl/requests.h" +#include "libaxl/replies.h" +#include "libaxl/display-info.h" +#include "libaxl/advanced.h" +#include "libaxl/low-level.h" /* libaxl error codes */ #define LIBAXL_ERROR_SYSTEM -1 /* use `errno` */ @@ -60,16 +50,6 @@ #define LIBAXL_ERROR_INVALID_HANDSHAKE_RESPONSE -12 #define LIBAXL_ERROR_OUT_OF_RESOURCE_IDS -13 -#define LIBAXL_HANDSHAKE_FAILED 0 -#define LIBAXL_HANDSHAKE_SUCCESS 1 -#define LIBAXL_HANDSHAKE_AUTHENTICATE 2 - -/* - * The largest possible return of the libaxl_get_decnet_object() - * function, plus 1 for the terminal NUL byte - */ -#define LIBAXL_DECNET_OBJECT_MAX (5 + 3 * sizeof(int) - sizeof(int) / 2) - union libaxl_input { /* TODO doc, man */ uint8_t type; union libaxl_error error; /* if .type = LIBAXL_ERROR */ @@ -78,49 +58,13 @@ union libaxl_input { /* TODO doc, man */ }; /** - * Opaque structure for connection to the X display server - */ -typedef struct libaxl_connection LIBAXL_CONNECTION; - -/** - * Opaque structure that wraps LIBAXL_CONNECTION with - * private data for the thread, all threads running at - * the same time shall access the display server - * via a unique LIBAXL_CONTEXT - */ -typedef struct libaxl_context LIBAXL_CONTEXT; - -/** - * Returns the major version number of the highest version of - * X protocol of the library supports (the lowest version is - * 11.0). If you are using static linking, you make also want - * to use the LIBAXL_PROTOCOL_MAJOR constant. + * Deallocation and close a connection * - * @return The major version number of highest support version of the protocol - */ -int libaxl_protocol_version_major(void); - -/** - * Returns the minor version number of the highest version of - * X protocol of the library supports (the lowest version is - * 11.0). If you are using static linking, you make also want - * to use the LIBAXL_PROTOCOL_MINOR constant. - * - * @return The minor version number of highest support version of the protocol - */ -int libaxl_protocol_version_minor(void); - -/** - * Returns the minor version number of the highest version of - * X protocol of the library supports (the lowest version is 11.0, - * which is encoded as 1100000). If you are using static linking, - * you make also want to use the LIBAXL_PROTOCOL_VERSION constant. - * - * @return The version number of highest support version of the protocol, - * encoded as a sum of the major number multipled by 100000 (1e5) - * and the minor number, e.g. 1100000 for 11.0 (X11) + * @param conn The connection to the display server + * @return 0 on success, -1 of there was an asynchronous error */ -int libaxl_protocol_version(void); +_LIBAXL_GCC_ONLY(__attribute__((__nonnull__))) +int libaxl_close(LIBAXL_CONNECTION *); /* TODO man */ /** * Get the file description used for a connection to @@ -131,7 +75,7 @@ int libaxl_protocol_version(void); * the connection to the display server */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__))) -int libaxl_fileno(LIBAXL_CONNECTION *); /* TODO man */ +int libaxl_fileno(LIBAXL_CONNECTION *); /** * Get information about a connection and the display @@ -212,14 +156,14 @@ libaxl_next_screen(const struct libaxl_screen *screen) /* TODO man */ * @return The context, NULL on failure (can only be out of memory) */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__, __malloc__, __warn_unused_result__))) -LIBAXL_CONTEXT *libaxl_context_create(LIBAXL_CONNECTION *); /* TODO man */ +LIBAXL_CONTEXT *libaxl_context_create(LIBAXL_CONNECTION *); /** * Deallocate a context * * @param ctx The context to deallocate */ -void libaxl_context_free(LIBAXL_CONTEXT *); /* TODO man */ +void libaxl_context_free(LIBAXL_CONTEXT *); /** * Generate a resource ID @@ -234,7 +178,7 @@ void libaxl_context_free(LIBAXL_CONTEXT *); /* TODO man */ * is always LIBAXL_ERROR_OUT_OF_RESOURCE_IDS */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__))) -libaxl_id_t libaxl_generate_id(LIBAXL_CONTEXT *); /* TODO man */ +libaxl_id_t libaxl_generate_id(LIBAXL_CONTEXT *); /** * Deallocate a resource ID so that it can be reused later @@ -244,86 +188,7 @@ libaxl_id_t libaxl_generate_id(LIBAXL_CONTEXT *); /* TODO man */ * @return 0 on success, a negative libaxl error code on failure */ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__))) -int libaxl_deallocate_id(LIBAXL_CONTEXT *, libaxl_id_t); /* TODO man, implement */ - -/** - * Parse a display name string - * - * The format for the display name string shall be either - * - * [<protocol>/][<host>]:<display>[.<screen>] - * - * or for the "unix" protocol - * - * <path>[.<screen>] - * - * @param name The display name string, $DISPLAY will be used if NULL or empty - * @param hostp Output parameter for the host of or (if the protocol is "unix") path - * to the display, remember to free after successful completion - * @param protocolp Output parameter for the network protocol used to access the display, - * remember to free after successful completion - * @param displayp Output parameter for the display's index (0 if the protocol is "unix") - * @param screenp Output parameter for the screen's index - * @return 0 on success, a negative libaxl error code on failure - */ -_LIBAXL_GCC_ONLY(__attribute__((__nonnull__(2, 3, 4, 5)))) -int libaxl_parse_display(const char *, char **, char **, int *, int *); /* TODO man */ - -/** - * Get the TCP port that is used for a display - * - * @param display The display's number, the function will assume that it is a valid number - * @return The TCP port used for the display - */ -_LIBAXL_GCC_ONLY(__attribute__((__warn_unused_result__, __const__))) -inline uint16_t libaxl_get_tcp_port(int display) /* TODO man */ -{ - return (uint16_t)(display + 6000); -} - -/** - * Get the DECnet object name that is used for a display - * - * @param buf Buffer that the object name shall be written to, it is recommended - * that is size, if static, is LIBAXL_DECNET_OBJECT_MAX (which is - * always sufficient), otherwise it should be at least the return value - * of this function (for the same last argument but with NULL and 0 - * as the first two arguments) plus 1 - * @param size The size of the buffer in the `buf` argument - * @param display The display's number - * @return The length of the object name, will not exceed LIBAXL_DECNET_OBJECT_MAX - * less 1; an additional uncounted NUL byte will be written to the buffer - * if it is large enough; or -1 on failure (specifically snprintf(3), which - * the function calls, by fail with EOVERFLOW if the `size` argument is - * greater than {INT_MAX}) - */ -int libaxl_get_decnet_object(char *, size_t, int); /* TODO man */ - -/** - * This function is to be called once and only once, excluding any - * failure that does not set `errno` to EINPROGRESS and excluding - * any call for which the display server respond that the handshake - * failed or requires authentication, immediately after connecting - * to the socket for the display - * - * The libaxl_receive_handshake() shall be called immediately after - * calling this function - * - * @param ctx The thread's context for the connection to the display to send the handshake over - * @param auth_name The protocol name of the authorisation the client expects the server to use; - * valid authorisation mechanisms are not part of the core X protocol - * @param auth_name_len The length of `auth_name`, 0 if `auth_name` is NULL - * @param auth_data The authorisation data, which is specific to the choosen authorisation mechanism - * @param auth_data_len The length of `auth_data`, 0 if `auth_data` is NULL - * @param flags Flags to use for the 4th parameter when calling send(3) - * @return 0 on success, a negative libaxl error code on failure - * - * If the function returns LIBAXL_ERROR_SYSTEM and sets `errno` - * to EINPROGRESS, the message has been saved (possibly partially - * sent) and pending to be sent by calling libaxl_flush(). - */ -_LIBAXL_GCC_ONLY(__attribute__((__nonnull__(1)))) -int libaxl_send_handshake(LIBAXL_CONTEXT *restrict, const char *, size_t, const char *, size_t, int); /* TODO man */ +int libaxl_deallocate_id(LIBAXL_CONTEXT *, libaxl_id_t); /* TODO implement */ /** * Send a request to the display server @@ -367,38 +232,6 @@ _LIBAXL_GCC_ONLY(__attribute__((__nonnull__))) int libaxl_flush(LIBAXL_CONNECTION *restrict, int); /* TODO man */ /** - * Receive the server's part of the handshake, this function - * shall be called once immediately after each successful call - * to the libaxl_send_handshake() function or successful call - * to the libaxl_flush() function due to EINPROGRESS failure - * of call to the libaxl_send_handshake() function - * - * @param ctx The thread's context for the connection to the display server - * @param majorp Output parameter for the major version number for a version - * of the X protocol that the display server supports, which is - * not necessarily the version that the library uses. Will only - * be set if the function returns LIBAXL_HANDSHAKE_FAILED or - * LIBAXL_HANDSHAKE_SUCCESS. - * @param minorp Output parameter for the minor version number for a version - * of the X protocol that the display server supports, which is - * not necessarily the version that the library uses. Will only - * be set if the function returns LIBAXL_HANDSHAKE_FAILED or - * LIBAXL_HANDSHAKE_SUCCESS. - * @param reasonp Output parameter for the reason the handshake or authorisation - * failed. Will be set to NULL unless the function returns - * LIBAXL_HANDSHAKE_FAILED or LIBAXL_HANDSHAKE_AUTHENTICATE. - * Remember to free after successful completion (non-negative return) - * @param flags Flags to use for the 4th parameter when calling recv(3) - * @return 0 on success, a negative libaxl error code on failure - * - * Behaviour is unspecified if SO_PEEK_OFF is active on the - * connection to the display server or if the MSG_PEEK flag - * is used - */ -_LIBAXL_GCC_ONLY(__attribute__((__nonnull__(1)))) -int libaxl_receive_handshake(LIBAXL_CONTEXT *restrict, int *restrict, int *restrict, char **restrict, int); /* TODO man */ - -/** * Receive the next pending message from the display server * * Be aware: order of replies and events is not guaranteed, @@ -424,4 +257,6 @@ int libaxl_receive_handshake(LIBAXL_CONTEXT *restrict, int *restrict, int *restr _LIBAXL_GCC_ONLY(__attribute__((__nonnull__))) int libaxl_receive(LIBAXL_CONTEXT *restrict, union libaxl_input *restrict, int); /* TODO man */ +#undef LIBAXL_H +#define LIBAXL_H 1 #endif |