path: root/man3/libaxl_receive_handshake.3

.TH libaxl_receive_handshake 3 libaxl
.SH NAME
libaxl_receive_handshake - Finish connection handshake
.B (ADVANCED)
.SH SYNOPSIS
.nf
#include <libaxl.h>

#define LIBAXL_HANDSHAKE_FAILED       0
#define LIBAXL_HANDSHAKE_SUCCESS      1
#define LIBAXL_HANDSHAKE_AUTHENTICATE 2

int libaxl_receive_handshake(LIBAXL_CONTEXT *\fIctx\fP, int *\fImajorp\fP, int *\fIminorp\fP, char **\fIreasonp\fP, int \fIflags\fP);
.fi
.SH DESCRIPTION
The
.BR libaxl_receive_handshake ()
function receives the display server's part of
the handshake, which is sent in response to the
client's handshake message which is sent with the
.BR libaxl_send_handshake ()
function.
.PP
The value of the
.I ctx
parameter shall be the thread's state for the
connection to the display server.
.PP
If the
.I majorp
parameter is set to a
.RI non- NULL
pointer and the
.BR libaxl_receive_handshake ()
function returns
.B LIBAXL_HANDSHAKE_SUCCESS
or
.BR LIBAXL_HANDSHAKE_FAILED ,
.I *majorp
will be set to 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.
.PP
If the
.I minorp
parameter is set to a
.RI non- NULL
pointer and the
.BR libaxl_receive_handshake ()
function returns
.B LIBAXL_HANDSHAKE_SUCCESS
or
.BR LIBAXL_HANDSHAKE_FAILED ,
.I *minorp
will be set to the minor version number for the
verison for which the major version number was
returned in
.I *majorp
(or if
.I majorp
is
.IR NULL :
would have been returned).
.PP
If the
.I reasonp
parameter is set to a
.RI non- NULL
pointer and the
.BR libaxl_receive_handshake ()
function returns
.B LIBAXL_HANDSHAKE_FAILED
or
.BR LIBAXL_HANDSHAKE_AUTHENTICATE ,
.I *reasonp
will be set to a dynamically allocated string
(which the caller must deallocate with the
.BR free (3)
function) providing an authorisation
protocol-specific reason which the handshake
failed. If The
.BR libaxl_receive_handshake ()
function returns any other value, and the
.I reasonp
paramater is set to a
.RI non- NULL ,
.I *reasonp
will be set to
.IR NULL .
.PP
Flags to used in the fourth argument when the
.BR libaxl_receive_handshake ()
function calls the
.BR recv (3)
function shall be specified in the
.I flags
parameter.
.SH RETURN VALUE
The
.BR libaxl_receive_handshake ()
function return
.B LIBAXL_HANDSHAKE_SUCCESS
upon successful completion with successful handshake
(beware, this value is not 0!),
.B LIBAXL_HANDSHAKE_FAILURE
upon successful completion with handshake failure,
.B LIBAXL_HANDSHAKE_AUTHENTICATE
upon successful completion handshake rejection
due to insufficient or incorrect authentication,
or a negative libaxl error code on failure.
.SH ERRORS
The
.BR libaxl_receive_handshake ()
function can only fail if:
.TP
TODO errors
.SH NOTES
The
.BR libaxl_receive_handshake ()
function's behaviour is unspecified if the
.I SO_PEEK_OFF
socket option is active or the
.I MSG_PEEK
flag is used.
.SH SEE ALSO
.BR libaxl_connect (3),
.BR libaxl_send_handshake (3),
.BR libaxl_send (3),
.BR libaxl_connect_without_handshake (3)