lws-ws-close.h (6056B)
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///@}