NAME

       wslay_event_context_free - Initialize an event-based API context

SYNOPSIS

       #include <wslay/wslay.h>

       int     wslay_event_context_server_init(wslay_event_context_ptr *ctx,     const     struct
       wslay_event_callbacks *callbacks, void *user_data)

       int     wslay_event_context_client_init(wslay_event_context_ptr *ctx,     const     struct
       wslay_event_callbacks *callbacks, void *user_data)

       void wslay_event_context_free(wslay_event_context_ptr ctx)

DESCRIPTION

       wslay_event_context_server_init()  function  initializes an :c:event-based API context for
       WebSocket  server  use.    wslay_event_context_client_init()   function   initializes   an
       :c:event-based  API context for WebSocket client use.  If they return :c:successfully, ctx
       will point to a structure  which  holds  any  :c:necessary  resources  needed  to  process
       WebSocket protocol transfers.

       callbacks is a pointer to struct wslay_event_callbacks, which is defined as follows:

          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;
          };

       recv_callback

          typedef ssize_t (*wslay_event_recv_callback)(wslay_event_context_ptr ctx, uint8_t *buf,
          size_t len, int flags, void *user_data)

          recv_callback is invoked by wslay_event_recv() when it wants to receive more data  from
          peer.   The  implementation  of this callback function must read data at most len bytes
          from peer and store them in buf and return the number of bytes read.  flags is always 0
          in this version.

          If  there  is  an  error, return -1 and set error code WSLAY_ERR_CALLBACK_FAILURE using
          wslay_event_set_error().  Wslay event-based API on the whole assumes non-blocking  I/O.
          If  the cause of error is EAGAIN or EWOULDBLOCK, set WSLAY_ERR_WOULDBLOCK instead. This
          is important because it tells wslay_event_recv() to stop  receiving  further  data  and
          return.

       send_callback

          typedef    ssize_t    (*wslay_event_send_callback)(wslay_event_context_ptr ctx,   const
          uint8_t *data, size_t len, int flags, void *user_data)

          send_callback is invoked by wslay_event_send() when it wants to send more data to peer.
          The  implementation  of this callback function must send data at most len bytes to peer
          and return the number of bytes sent.  flags is the bitwise OR of zero or  more  of  the
          following flag:

          WSLAY_MSG_MORE
                 There is more data to send

          It provides some hints to tune performance and behaviour.

          If  there  is  an  error, return -1 and set error code WSLAY_ERR_CALLBACK_FAILURE using
          wslay_event_set_error().  Wslay event-based API on the whole assumes non-blocking  I/O.
          If  the cause of error is EAGAIN or EWOULDBLOCK, set WSLAY_ERR_WOULDBLOCK instead. This
          is important because it tells wslay_event_send() to stop sending data and return.

       genmask_callback

          typedef int (*wslay_event_genmask_callback)(wslay_event_context_ptr ctx,  uint8_t *buf,
          size_t len, void *user_data)

          genmask_callback  is  invoked  by  wslay_event_send()  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  len  bytes
          of  data in buf and return 0 on success.  If there is an error, return -1 and set error
          code WSLAY_ERR_CALLBACK_FAILURE using wslay_event_set_error().

       on_frame_recv_start_callback

          typedef  void  (*wslay_event_on_frame_recv_start_callback)(wslay_event_context_ptr ctx,
          const struct wslay_event_on_frame_recv_start_arg *arg, void *user_data)

          on_frame_recv_start_callback  is  invoked by wslay_event_recv() when a new frame starts
          to be received.  This callback function is only invoked once  for  each  frame.  struct
          wslay_event_on_frame_recv_start_arg is defined as follows:

              struct wslay_event_on_frame_recv_start_arg {
                  uint8_t  fin;
                  uint8_t  rsv;
                  uint8_t  opcode;
                  uint64_t payload_length;
              };

          fin, rsv and opcode is fin bit and reserved bits and opcode of a frame.  payload_length
          is a payload length of a frame.

       on_frame_recv_chunk_callback

          typedef  void  (*wslay_event_on_frame_recv_chunk_callback)(wslay_event_context_ptr ctx,
          const struct wslay_event_on_frame_recv_chunk_arg *arg, void *user_data)

          on_frame_recv_chunk_callback  is  invoked  by  wslay_event_recv() when a chunk of frame
          payload is received.  struct wslay_event_on_frame_recv_chunk_arg is defined as follows:

              struct wslay_event_on_frame_recv_chunk_arg {
                  const uint8_t *data;
                  size_t         data_length;
              };

          data points to a chunk of payload data.  data_length is the length of a chunk.

       on_frame_recv_end_callback

          typedef   void   (*wslay_event_on_frame_recv_end_callback)(wslay_event_context_ptr ctx,
          void *user_data)

          on_frame_recv_end_callback  is invoked by wslay_event_recv() when a frame is completely
          received.

       on_msg_recv_callback

          typedef  void  (*wslay_event_on_msg_recv_callback)(wslay_event_context_ptr ctx,   const
          struct wslay_event_on_msg_recv_arg *arg, void *user_data)

          on_msg_recv_callback  is  invoked  by  wslay_event_recv()  when a message is completely
          received. struct wslay_event_on_msg_recv_arg is defined as follows:

              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;
              };

          The rsv member and the opcode member are reserved bits and opcode of  received  message
          respectively.  The rsv member is constructed as follows:

              rsv = (RSV1 << 2) | (RSV2 << 1) | RSV3

          The msg member points to the message of the received message.  The msg_length member is
          the length of message.  If a message is close control frame, in other words, opcode  ==
          WSLAY_CONNECTION_CLOSE,  status_code  is  set  to  the status code in the close control
          frame.  If no status code is included in the close control frame, status_code set to 0.

       user_data is an arbitrary pointer, which is directly passed to each callback functions  as
       user_data argument.

       When    initialized    event-based    API   context   ctx   is   no   longer   used,   use
       wslay_event_context_free() to free any resources allocated for ctx.

RETURN VALUE

       wslay_event_context_server_init() and wslay_event_context_client_init() returns  0  if  it
       succeeds, or one of the following negative error codes:

       WSLAY_ERR_NOMEM
              Out of memory.

SEE ALSO

       wslay_event_send(), wslay_event_recv(), wslay_event_set_error()

AUTHOR

       Tatsuhiro Tsujikawa

COPYRIGHT

       2017, 2015, Tatsuhiro Tsujikawa

@PACKAGE_VERSION@                          Dec 29, 2017               WSLAY_EVENT_CONTEXT_FREE(3)