{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1752320589, "reponame":"libwebsockets", "desc":"libwebsockets lightweight C networking library", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/libwebsockets", "f":3, "items": [ {"schema":"libjg2-1", "cid":"32941f4b62a3c5e30ad508cb12df4fd2", "oid":{ "oid": "e05d27d0de4dc220c726fc9fcc0f2957c6d9c81b", "alias": [ "refs/heads/main"]},"blobname": "include/libwebsockets/lws-write.h", "blob": "/*\n * libwebsockets - small server side websockets and web server implementation\n *\n * Copyright (C) 2010 - 2019 Andy Green \u003candy@warmcat.com\u003e\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \u0022Software\u0022), to\n * deal in the Software without restriction, including without limitation the\n * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\n * sell copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in\n * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \u0022AS IS\u0022, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\n * IN THE SOFTWARE.\n */\n\n/*! \u005cdefgroup sending-data Sending data\n\n APIs related to writing data on a connection\n*/\n//@{\n#define LWS_WRITE_RAW LWS_WRITE_HTTP\n\n/*\n * NOTE: These public enums are part of the abi. If you want to add one,\n * add it at where specified so existing users are unaffected.\n */\nenum lws_write_protocol {\n\tLWS_WRITE_TEXT\t\t\t\t\t\t\u003d 0,\n\t/**\u003c Send a ws TEXT message,the pointer must have LWS_PRE valid\n\t * memory behind it.\n\t *\n\t * The receiver expects only valid utf-8 in the payload */\n\tLWS_WRITE_BINARY\t\t\t\t\t\u003d 1,\n\t/**\u003c Send a ws BINARY message, the pointer must have LWS_PRE valid\n\t * memory behind it.\n\t *\n\t * Any sequence of bytes is valid */\n\tLWS_WRITE_CONTINUATION\t\t\t\t\t\u003d 2,\n\t/**\u003c Continue a previous ws message, the pointer must have LWS_PRE valid\n\t * memory behind it */\n\tLWS_WRITE_HTTP\t\t\t\t\t\t\u003d 3,\n\t/**\u003c Send HTTP content */\n\n\t/* LWS_WRITE_CLOSE is handled by lws_close_reason() */\n\tLWS_WRITE_PING\t\t\t\t\t\t\u003d 5,\n\tLWS_WRITE_PONG\t\t\t\t\t\t\u003d 6,\n\n\t/* Same as write_http but we know this write ends the transaction */\n\tLWS_WRITE_HTTP_FINAL\t\t\t\t\t\u003d 7,\n\n\t/* HTTP2 */\n\n\tLWS_WRITE_HTTP_HEADERS\t\t\t\t\t\u003d 8,\n\t/**\u003c Send http headers (http2 encodes this payload and LWS_WRITE_HTTP\n\t * payload differently, http 1.x links also handle this correctly. so\n\t * to be compatible with both in the future,header response part should\n\t * be sent using this regardless of http version expected)\n\t */\n\tLWS_WRITE_HTTP_HEADERS_CONTINUATION\t\t\t\u003d 9,\n\t/**\u003c Continuation of http/2 headers\n\t */\n\n\t/****** add new things just above ---^ ******/\n\n\t/* flags */\n\n\tLWS_WRITE_BUFLIST \u003d 0x20,\n\t/**\u003c Don't actually write it... stick it on the output buflist and\n\t * write it as soon as possible. Useful if you learn you have to\n\t * write something, have the data to write to hand but the timing is\n\t * unrelated as to whether the connection is writable or not, and were\n\t * otherwise going to have to allocate a temp buffer and write it\n\t * later anyway */\n\n\tLWS_WRITE_NO_FIN \u003d 0x40,\n\t/**\u003c This part of the message is not the end of the message */\n\n\tLWS_WRITE_H2_STREAM_END \u003d 0x80,\n\t/**\u003c Flag indicates this packet should go out with STREAM_END if h2\n\t * STREAM_END is allowed on DATA or HEADERS.\n\t */\n\n\tLWS_WRITE_CLIENT_IGNORE_XOR_MASK \u003d 0x80\n\t/**\u003c client packet payload goes out on wire unmunged\n\t * only useful for security tests since normal servers cannot\n\t * decode the content if used */\n};\n\n/* used with LWS_CALLBACK_CHILD_WRITE_VIA_PARENT */\n\nstruct lws_write_passthru {\n\tstruct lws *wsi;\n\tunsigned char *buf;\n\tsize_t len;\n\tenum lws_write_protocol wp;\n};\n\n\n/**\n * lws_write() - Apply protocol then write data to client\n *\n * \u005cparam wsi:\tWebsocket instance (available from user callback)\n * \u005cparam buf:\tThe data to send. For data being sent on a websocket\n *\t\tconnection (ie, not default http), this buffer MUST have\n *\t\tLWS_PRE bytes valid BEFORE the pointer.\n *\t\tThis is so the protocol header data can be added in-situ.\n * \u005cparam len:\tCount of the data bytes in the payload starting from buf\n * \u005cparam protocol:\tUse LWS_WRITE_HTTP to reply to an http connection, and one\n *\t\tof LWS_WRITE_BINARY or LWS_WRITE_TEXT to send appropriate\n *\t\tdata on a websockets connection. Remember to allow the extra\n *\t\tbytes before and after buf if LWS_WRITE_BINARY or LWS_WRITE_TEXT\n *\t\tare used.\n *\n * This function provides the way to issue data back to the client, for any\n * role (h1, h2, ws, raw, etc). It can only be called from the WRITEABLE\n * callback.\n *\n * IMPORTANT NOTICE!\n *\n * When sending with ws protocol\n *\n * LWS_WRITE_TEXT,\n * LWS_WRITE_BINARY,\n * LWS_WRITE_CONTINUATION,\n * LWS_WRITE_PING,\n * LWS_WRITE_PONG,\n *\n * or sending on http/2... the send buffer has to have LWS_PRE bytes valid\n * BEFORE the buffer pointer you pass to lws_write(). Since you'll probably\n * want to use http/2 before too long, it's wise to just always do this with\n * lws_write buffers... LWS_PRE is typically 16 bytes it's not going to hurt\n * usually.\n *\n * start of alloc ptr passed to lws_write end of allocation\n * | | |\n * v \u003c-- LWS_PRE bytes --\u003e v v\n * [---------------- allocated memory ---------------]\n * (for lws use) [\u003d\u003d\u003d\u003d\u003d\u003d user buffer \u003d\u003d\u003d\u003d\u003d\u003d]\n *\n * This allows us to add protocol info before the data, and send as one packet\n * on the network without payload copying, for maximum efficiency.\n *\n * So for example you need this kind of code to use lws_write with a\n * 128-byte payload\n *\n * char buf[LWS_PRE + 128];\n *\n * // fill your part of the buffer... for example here it's all zeros\n * memset(\u0026buf[LWS_PRE], 0, 128);\n *\n * if (lws_write(wsi, \u0026buf[LWS_PRE], 128, LWS_WRITE_TEXT) \u003c 128) {\n * \t\t... the connection is dead ...\n * \t\treturn -1;\n * }\n *\n * LWS_PRE is currently 16, which covers ws and h2 frame headers, and is\n * compatible with 32 and 64-bit alignment requirements.\n *\n * (LWS_SEND_BUFFER_POST_PADDING is deprecated, it's now 0 and can be left off.)\n *\n * Return may be -1 is the write failed in a way indicating that the connection\n * has ended already, in which case you can close your side, or a positive\n * number that is at least the number of bytes requested to send (under some\n * encapsulation scenarios, it can indicate more than you asked was sent).\n *\n * The recommended test of the return is less than what you asked indicates\n * the connection has failed.\n *\n * Truncated Writes\n * \u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\n *\n * The OS may not accept everything you asked to write on the connection.\n *\n * Posix defines POLLOUT indication from poll() to show that the connection\n * will accept more write data, but it doesn't specifiy how much. It may just\n * accept one byte of whatever you wanted to send.\n *\n * LWS will buffer the remainder automatically, and send it out autonomously.\n *\n * During that time, WRITABLE callbacks to user code will be suppressed and\n * instead used internally. After it completes, it will send an extra WRITEABLE\n * callback to the user code, in case any request was missed. So it is possible\n * to receive unasked-for WRITEABLE callbacks, the user code should have enough\n * state to know if it wants to write anything and just return if not.\n *\n * This is to handle corner cases where unexpectedly the OS refuses what we\n * usually expect it to accept. It's not recommended as the way to randomly\n * send huge payloads, since it is being copied on to heap and is inefficient.\n *\n * Huge payloads should instead be sent in fragments that are around 2 x mtu,\n * which is almost always directly accepted by the OS. To simplify this for\n * ws fragments, there is a helper lws_write_ws_flags() below that simplifies\n * selecting the correct flags to give lws_write() for each fragment.\n *\n * In the case of RFC8441 ws-over-h2, you cannot send ws fragments larger than\n * the max h2 frame size, typically 16KB, but should further restrict it to\n * the same ~2 x mtu limit mentioned above.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_write(struct lws *wsi, unsigned char *buf, size_t len,\n\t enum lws_write_protocol protocol);\n\n/* helper for case where buffer may be const */\n#define lws_write_http(wsi, buf, len) \u005c\n\tlws_write(wsi, (unsigned char *)(buf), len, LWS_WRITE_HTTP)\n\n/**\n * lws_write_ws_flags() - Helper for multi-frame ws message flags\n *\n * \u005cparam initial: the lws_write flag to use for the start fragment, eg,\n *\t\t LWS_WRITE_TEXT\n * \u005cparam is_start: nonzero if this is the first fragment of the message\n * \u005cparam is_end: nonzero if this is the last fragment of the message\n *\n * Returns the correct LWS_WRITE_ flag to use for each fragment of a message\n * in turn.\n */\nstatic LWS_INLINE int\nlws_write_ws_flags(int initial, int is_start, int is_end)\n{\n\tint r;\n\n\tif (is_start)\n\t\tr \u003d initial;\n\telse\n\t\tr \u003d LWS_WRITE_CONTINUATION;\n\n\tif (!is_end)\n\t\tr |\u003d LWS_WRITE_NO_FIN;\n\n\treturn r;\n}\n\n/**\n * lws_raw_transaction_completed() - Helper for flushing before close\n *\n * \u005cparam wsi: the struct lws to operate on\n *\n * Returns -1 if the wsi can close now. However if there is buffered, unsent\n * data, the wsi is marked as to be closed when the output buffer data is\n * drained, and it returns 0.\n *\n * For raw cases where the transaction completed without failure,\n * `return lws_raw_transaction_completed(wsi)` should better be used than\n * return -1.\n */\nLWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT\nlws_raw_transaction_completed(struct lws *wsi);\n\n///@}\n","s":{"c":1752320589,"u": 290}} ],"g": 4442,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 1, "si": 0, "db":0, "di":0, "sat":0, "lfc": "0000"}