1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
25/*! \defgroup wsclose Websocket Close
26 *
27 * ##Websocket close frame control
28 *
29 * When we close a ws connection, we can send a reason code and a short
30 * UTF-8 description back with the close packet.
31 */
32///@{
33
34/*
35 * NOTE: These public enums are part of the abi. If you want to add one,
36 * add it at where specified so existing users are unaffected.
37 */
38/** enum lws_close_status - RFC6455 close status codes */
39enum lws_close_status {
40 LWS_CLOSE_STATUS_NOSTATUS = 0,
41 LWS_CLOSE_STATUS_NORMAL = 1000,
42 /**< 1000 indicates a normal closure, meaning that the purpose for
43 which the connection was established has been fulfilled. */
44 LWS_CLOSE_STATUS_GOINGAWAY = 1001,
45 /**< 1001 indicates that an endpoint is "going away", such as a server
46 going down or a browser having navigated away from a page. */
47 LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002,
48 /**< 1002 indicates that an endpoint is terminating the connection due
49 to a protocol error. */
50 LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003,
51 /**< 1003 indicates that an endpoint is terminating the connection
52 because it has received a type of data it cannot accept (e.g., an
53 endpoint that understands only text data MAY send this if it
54 receives a binary message). */
55 LWS_CLOSE_STATUS_RESERVED = 1004,
56 /**< Reserved. The specific meaning might be defined in the future. */
57 LWS_CLOSE_STATUS_NO_STATUS = 1005,
58 /**< 1005 is a reserved value and MUST NOT be set as a status code in a
59 Close control frame by an endpoint. It is designated for use in
60 applications expecting a status code to indicate that no status
61 code was actually present. */
62 LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006,
63 /**< 1006 is a reserved value and MUST NOT be set as a status code in a
64 Close control frame by an endpoint. It is designated for use in
65 applications expecting a status code to indicate that the
66 connection was closed abnormally, e.g., without sending or
67 receiving a Close control frame. */
68 LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007,
69 /**< 1007 indicates that an endpoint is terminating the connection
70 because it has received data within a message that was not
71 consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
72 data within a text message). */
73 LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008,
74 /**< 1008 indicates that an endpoint is terminating the connection
75 because it has received a message that violates its policy. This
76 is a generic status code that can be returned when there is no
77 other more suitable status code (e.g., 1003 or 1009) or if there
78 is a need to hide specific details about the policy. */
79 LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009,
80 /**< 1009 indicates that an endpoint is terminating the connection
81 because it has received a message that is too big for it to
82 process. */
83 LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010,
84 /**< 1010 indicates that an endpoint (client) is terminating the
85 connection because it has expected the server to negotiate one or
86 more extension, but the server didn't return them in the response
87 message of the WebSocket handshake. The list of extensions that
88 are needed SHOULD appear in the /reason/ part of the Close frame.
89 Note that this status code is not used by the server, because it
90 can fail the WebSocket handshake instead */
91 LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011,
92 /**< 1011 indicates that a server is terminating the connection because
93 it encountered an unexpected condition that prevented it from
94 fulfilling the request. */
95 LWS_CLOSE_STATUS_TLS_FAILURE = 1015,
96 /**< 1015 is a reserved value and MUST NOT be set as a status code in a
97 Close control frame by an endpoint. It is designated for use in
98 applications expecting a status code to indicate that the
99 connection was closed due to a failure to perform a TLS handshake
100 (e.g., the server certificate can't be verified). */
101
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};
108
109/**
110 * lws_close_reason - Set reason and aux data to send with Close packet
111 * If you are going to return nonzero from the callback
112 * requesting the connection to close, you can optionally
113 * call this to set the reason the peer will be told if
114 * possible.
115 *
116 * \param wsi: The websocket connection to set the close reason on
117 * \param status: A valid close status from websocket standard
118 * \param buf: NULL or buffer containing up to 124 bytes of auxiliary data
119 * \param len: Length of data in \p buf to send
120 */
121LWS_VISIBLE LWS_EXTERN void
122lws_close_reason(struct lws *wsi, enum lws_close_status status,
123 unsigned char *buf, size_t len);
124
125///@}
126