libwebsockets
Lightweight C library for HTML5 websockets
Websocket Close

Enumerations

enum  lws_close_status {
  LWS_CLOSE_STATUS_NOSTATUS = 0 , LWS_CLOSE_STATUS_NORMAL = 1000 , LWS_CLOSE_STATUS_GOINGAWAY = 1001 , LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002 ,
  LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003 , LWS_CLOSE_STATUS_RESERVED = 1004 , LWS_CLOSE_STATUS_NO_STATUS = 1005 , LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006 ,
  LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007 , LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008 , LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009 , LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010 ,
  LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011 , LWS_CLOSE_STATUS_TLS_FAILURE = 1015 , LWS_CLOSE_STATUS_CLIENT_TRANSACTION_DONE = 2000 , LWS_CLOSE_STATUS_NOSTATUS_CONTEXT_DESTROY = 9999
}
 

Functions

LWS_VISIBLE LWS_EXTERN void lws_close_reason (struct lws *wsi, enum lws_close_status status, unsigned char *buf, size_t len)
 

Detailed Description

Websocket close frame control

When we close a ws connection, we can send a reason code and a short UTF-8 description back with the close packet.

Enumeration Type Documentation

◆ lws_close_status

#include <include/libwebsockets/lws-ws-close.h>

enum lws_close_status - RFC6455 close status codes

Enumerator
LWS_CLOSE_STATUS_NORMAL 

1000 indicates a normal closure, meaning that the purpose for which the connection was established has been fulfilled.

LWS_CLOSE_STATUS_GOINGAWAY 

1001 indicates that an endpoint is "going away", such as a server going down or a browser having navigated away from a page.

LWS_CLOSE_STATUS_PROTOCOL_ERR 

1002 indicates that an endpoint is terminating the connection due to a protocol error.

LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE 

1003 indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept (e.g., an endpoint that understands only text data MAY send this if it receives a binary message).

LWS_CLOSE_STATUS_RESERVED 

Reserved. The specific meaning might be defined in the future.

LWS_CLOSE_STATUS_NO_STATUS 

1005 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that no status code was actually present.

LWS_CLOSE_STATUS_ABNORMAL_CLOSE 

1006 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed abnormally, e.g., without sending or receiving a Close control frame.

LWS_CLOSE_STATUS_INVALID_PAYLOAD 

1007 indicates that an endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the message (e.g., non-UTF-8 [RFC3629] data within a text message).

LWS_CLOSE_STATUS_POLICY_VIOLATION 

1008 indicates that an endpoint is terminating the connection because it has received a message that violates its policy. This is a generic status code that can be returned when there is no other more suitable status code (e.g., 1003 or 1009) or if there is a need to hide specific details about the policy.

LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE 

1009 indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process.

LWS_CLOSE_STATUS_EXTENSION_REQUIRED 

1010 indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the server didn't return them in the response message of the WebSocket handshake. The list of extensions that are needed SHOULD appear in the /reason/ part of the Close frame. Note that this status code is not used by the server, because it can fail the WebSocket handshake instead

LWS_CLOSE_STATUS_UNEXPECTED_CONDITION 

1011 indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.

LWS_CLOSE_STATUS_TLS_FAILURE 

1015 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed due to a failure to perform a TLS handshake (e.g., the server certificate can't be verified).

39  {
40  LWS_CLOSE_STATUS_NOSTATUS = 0,
102  LWS_CLOSE_STATUS_CLIENT_TRANSACTION_DONE = 2000,
103 
104  /****** add new things just above ---^ ******/
105 
106  LWS_CLOSE_STATUS_NOSTATUS_CONTEXT_DESTROY = 9999,
107 };
@ LWS_CLOSE_STATUS_PROTOCOL_ERR
Definition: lws-ws-close.h:47
@ LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE
Definition: lws-ws-close.h:79
@ LWS_CLOSE_STATUS_NORMAL
Definition: lws-ws-close.h:41
@ LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE
Definition: lws-ws-close.h:50
@ LWS_CLOSE_STATUS_NO_STATUS
Definition: lws-ws-close.h:57
@ LWS_CLOSE_STATUS_ABNORMAL_CLOSE
Definition: lws-ws-close.h:62
@ LWS_CLOSE_STATUS_INVALID_PAYLOAD
Definition: lws-ws-close.h:68
@ LWS_CLOSE_STATUS_GOINGAWAY
Definition: lws-ws-close.h:44
@ LWS_CLOSE_STATUS_EXTENSION_REQUIRED
Definition: lws-ws-close.h:83
@ LWS_CLOSE_STATUS_UNEXPECTED_CONDITION
Definition: lws-ws-close.h:91
@ LWS_CLOSE_STATUS_POLICY_VIOLATION
Definition: lws-ws-close.h:73
@ LWS_CLOSE_STATUS_TLS_FAILURE
Definition: lws-ws-close.h:95
@ LWS_CLOSE_STATUS_RESERVED
Definition: lws-ws-close.h:55

Function Documentation

◆ lws_close_reason()

LWS_VISIBLE LWS_EXTERN void lws_close_reason ( struct lws *  wsi,
enum lws_close_status  status,
unsigned char *  buf,
size_t  len 
)

#include <include/libwebsockets/lws-ws-close.h>

lws_close_reason - Set reason and aux data to send with Close packet If you are going to return nonzero from the callback requesting the connection to close, you can optionally call this to set the reason the peer will be told if possible.

Parameters
wsiThe websocket connection to set the close reason on
statusA valid close status from websocket standard
bufNULL or buffer containing up to 124 bytes of auxiliary data
lenLength of data in buf to send