.\" Man page generated from reStructuredText.
.
.TH "WSLAY_EVENT_CONTEXT_CLIENT_INIT" "3" "Sep 28, 2017" "@PACKAGE_VERSION@" "wslay"
.SH NAME
wslay_event_context_client_init \- Initialize an event-based API context
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
#include <wslay/wslay.h>
.INDENT 0.0
.TP
.B int wslay_event_context_server_init(wslay_event_context_ptr\fI\ *ctx\fP, const struct wslay_event_callbacks\fI\ *callbacks\fP, void\fI\ *user_data\fP)
.UNINDENT
.INDENT 0.0
.TP
.B int wslay_event_context_client_init(wslay_event_context_ptr\fI\ *ctx\fP, const struct wslay_event_callbacks\fI\ *callbacks\fP, void\fI\ *user_data\fP)
.UNINDENT
.INDENT 0.0
.TP
.B void wslay_event_context_free(wslay_event_context_ptr\fI\ ctx\fP)
.UNINDENT
.SH DESCRIPTION
.sp
\fI\%wslay_event_context_server_init()\fP function initializes an
:c:event\-based API context for WebSocket server use.
\fI\%wslay_event_context_client_init()\fP function initializes an
:c:event\-based API context for WebSocket client use.  If they return
:c:successfully, \fIctx\fP will point to a structure which holds any
:c:necessary resources needed to process WebSocket protocol transfers.
.sp
\fIcallbacks\fP is a pointer to \fBstruct wslay_event_callbacks\fP,
which is defined as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct wslay_event_callbacks {
    wslay_event_recv_callback                recv_callback;
    wslay_event_send_callback                send_callback;
    wslay_event_genmask_callback             genmask_callback;
    wslay_event_on_frame_recv_start_callback on_frame_recv_start_callback;
    wslay_event_on_frame_recv_chunk_callback on_frame_recv_chunk_callback;
    wslay_event_on_frame_recv_end_callback   on_frame_recv_end_callback;
    wslay_event_on_msg_recv_callback         on_msg_recv_callback;
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBrecv_callback\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B typedef ssize_t (*wslay_event_recv_callback)(wslay_event_context_ptr\fI\ ctx\fP, uint8_t\fI\ *buf\fP, size_t\fI\ len\fP, int\fI\ flags\fP, void\fI\ *user_data\fP)
.UNINDENT
.sp
\fIrecv_callback\fP is invoked by \fBwslay_event_recv()\fP when it
wants to receive more data from peer.
The implementation of this callback function must read data at most \fIlen\fP
bytes from peer and store them in \fIbuf\fP and return the number of bytes read.
\fIflags\fP is always 0 in this version.
.sp
If there is an error, return \-1 and
set error code \fBWSLAY_ERR_CALLBACK_FAILURE\fP
using \fBwslay_event_set_error()\fP\&.
Wslay event\-based API on the whole assumes non\-blocking I/O.
If the cause of error is \fBEAGAIN\fP or \fBEWOULDBLOCK\fP,
set \fBWSLAY_ERR_WOULDBLOCK\fP instead. This is important because it tells
\fBwslay_event_recv()\fP to stop receiving further data and return.
.UNINDENT
.UNINDENT
.sp
\fBsend_callback\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B typedef ssize_t (*wslay_event_send_callback)(wslay_event_context_ptr\fI\ ctx\fP, const uint8_t\fI\ *data\fP, size_t\fI\ len\fP, int\fI\ flags\fP, void\fI\ *user_data\fP)
.UNINDENT
.sp
\fIsend_callback\fP is invoked by \fBwslay_event_send()\fP when it
wants to send more data to peer.
The implementation of this callback function must send data at most \fIlen\fP
bytes to peer and return the number of bytes sent.
\fIflags\fP is the bitwise OR of zero or more of the following flag:
.INDENT 0.0
.TP
.B \fBWSLAY_MSG_MORE\fP
There is more data to send
.UNINDENT
.sp
It provides some hints to tune performance and behaviour.
.sp
If there is an error, return \-1 and
set error code \fBWSLAY_ERR_CALLBACK_FAILURE\fP
using \fBwslay_event_set_error()\fP\&.
Wslay event\-based API on the whole assumes non\-blocking I/O.
If the cause of error is \fBEAGAIN\fP or \fBEWOULDBLOCK\fP,
set \fBWSLAY_ERR_WOULDBLOCK\fP instead. This is important because it tells
\fBwslay_event_send()\fP to stop sending data and return.
.UNINDENT
.UNINDENT
.sp
\fBgenmask_callback\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B typedef int (*wslay_event_genmask_callback)(wslay_event_context_ptr\fI\ ctx\fP, uint8_t\fI\ *buf\fP, size_t\fI\ len\fP, void\fI\ *user_data\fP)
.UNINDENT
.sp
\fIgenmask_callback\fP is invoked by \fBwslay_event_send()\fP when it
wants new mask key. As described in RFC6455, only the traffic from
WebSocket client is masked, so this callback function is only needed
if an event\-based API is initialized for WebSocket client use.
The implementation of this callback function must fill exactly \fIlen\fP bytes
of data in \fIbuf\fP and return 0 on success.
If there is an error, return \-1 and
set error code \fBWSLAY_ERR_CALLBACK_FAILURE\fP
using \fBwslay_event_set_error()\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBon_frame_recv_start_callback\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B typedef void (*wslay_event_on_frame_recv_start_callback)(wslay_event_context_ptr\fI\ ctx\fP, const struct wslay_event_on_frame_recv_start_arg\fI\ *arg\fP, void\fI\ *user_data\fP)
.UNINDENT
.sp
\fIon_frame_recv_start_callback\fP is invoked by \fBwslay_event_recv()\fP when
a new frame starts to be received.
This callback function is only invoked once for each
frame. \fBstruct wslay_event_on_frame_recv_start_arg\fP is defined as
follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct wslay_event_on_frame_recv_start_arg {
    uint8_t  fin;
    uint8_t  rsv;
    uint8_t  opcode;
    uint64_t payload_length;
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fIfin\fP, \fIrsv\fP and \fIopcode\fP is fin bit and reserved bits and opcode of a frame.
\fIpayload_length\fP is a payload length of a frame.
.UNINDENT
.UNINDENT
.sp
\fBon_frame_recv_chunk_callback\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B typedef void (*wslay_event_on_frame_recv_chunk_callback)(wslay_event_context_ptr\fI\ ctx\fP, const struct wslay_event_on_frame_recv_chunk_arg\fI\ *arg\fP, void\fI\ *user_data\fP)
.UNINDENT
.sp
\fIon_frame_recv_chunk_callback\fP is invoked by \fBwslay_event_recv()\fP when
a chunk of frame payload is received.
\fBstruct wslay_event_on_frame_recv_chunk_arg\fP is defined as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct wslay_event_on_frame_recv_chunk_arg {
    const uint8_t *data;
    size_t         data_length;
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fIdata\fP points to a chunk of payload data.
\fIdata_length\fP is the length of a chunk.
.UNINDENT
.UNINDENT
.sp
\fBon_frame_recv_end_callback\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B typedef void (*wslay_event_on_frame_recv_end_callback)(wslay_event_context_ptr\fI\ ctx\fP, void\fI\ *user_data\fP)
.UNINDENT
.sp
\fIon_frame_recv_end_callback\fP is invoked by \fBwslay_event_recv()\fP when
a frame is completely received.
.UNINDENT
.UNINDENT
.sp
\fBon_msg_recv_callback\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B typedef void (*wslay_event_on_msg_recv_callback)(wslay_event_context_ptr\fI\ ctx\fP, const struct wslay_event_on_msg_recv_arg\fI\ *arg\fP, void\fI\ *user_data\fP)
.UNINDENT
.sp
\fIon_msg_recv_callback\fP is invoked by \fBwslay_event_recv()\fP
when a message
is completely received. \fBstruct wslay_event_on_msg_recv_arg\fP is
defined as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct wslay_event_on_msg_recv_arg {
    uint8_t        rsv;
    uint8_t        opcode;
    const uint8_t *msg;
    size_t         msg_length;
    uint16_t       status_code;
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIrsv\fP member and the \fIopcode\fP member are reserved bits and opcode of
received message respectively.
The \fIrsv\fP member is constructed as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rsv = (RSV1 << 2) | (RSV2 << 1) | RSV3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fImsg\fP member points to the message of the received message.
The \fImsg_length\fP member is the length of message.
If a message is close control frame, in other words,
\fBopcode == WSLAY_CONNECTION_CLOSE\fP, \fIstatus_code\fP is set to
the status code in the close control frame.
If no status code is included in the close control frame,
\fIstatus_code\fP set to 0.
.UNINDENT
.UNINDENT
.sp
\fIuser_data\fP is an arbitrary pointer, which is directly
passed to each callback functions as \fIuser_data\fP argument.
.sp
When initialized event\-based API context \fIctx\fP is no longer used,
use \fI\%wslay_event_context_free()\fP to free any
resources allocated for \fIctx\fP\&.
.SH RETURN VALUE
.sp
\fI\%wslay_event_context_server_init()\fP and
\fI\%wslay_event_context_client_init()\fP returns 0 if it succeeds,
or one of the following negative error codes:
.INDENT 0.0
.TP
.B WSLAY_ERR_NOMEM
Out of memory.
.UNINDENT
.SH SEE ALSO
.sp
\fBwslay_event_send()\fP, \fBwslay_event_recv()\fP,
\fBwslay_event_set_error()\fP
.SH AUTHOR
Tatsuhiro Tsujikawa
.SH COPYRIGHT
2017, 2015, Tatsuhiro Tsujikawa
.\" Generated by docutils manpage writer.
.