{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1757099166, "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":"0c5db7cae2ad11901660b7ded2864e51", "oid":{ "oid": "fc0e52da9eae137038e22fa15fd819147c5d0c81", "alias": []},"blobname": "doc/latex/md_README.coding.tex", "blob": "\u005csubsection*{Daemonization }\n\nThere\u005ctextquotesingle{}s a helper api {\u005cttfamily lws\u005c+\u005c_\u005c+daemonize} built by default that does everything you need to daemonize well, including creating a lock file. If you\u005ctextquotesingle{}re making what\u005ctextquotesingle{}s basically a daemon, just call this early in your init to fork to a headless background process and exit the starting process.\n\nNotice stdout, stderr, stdin are all redirected to /dev/null to enforce your daemon is headless, so you\u005ctextquotesingle{}ll need to sort out alternative logging, by, eg, syslog.\n\n\u005csubsection*{Maximum number of connections }\n\nThe maximum number of connections the library can deal with is decided when it starts by querying the OS to find out how many file descriptors it is allowed to open (1024 on Fedora for example). It then allocates arrays that allow up to that many connections, minus whatever other file descriptors are in use by the user code.\n\nIf you want to restrict that allocation, or increase it, you can use ulimit or similar to change the avaiable number of file descriptors, and when restarted {\u005cbfseries libwebsockets} will adapt accordingly.\n\n\u005csubsection*{Libwebsockets is singlethreaded }\n\nDirectly performing websocket actions from other threads is not allowed. Aside from the internal data being inconsistent in {\u005cttfamily forked()} processes, the scope of a {\u005cttfamily wsi} ({\u005cttfamily struct websocket}) can end at any time during service with the socket closing and the {\u005cttfamily wsi} freed.\n\nWebsocket write activities should only take place in the {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+S\u005c+E\u005c+R\u005c+V\u005c+E\u005c+R\u005c+\u005c_\u005c+\u005c+W\u005c+R\u005c+I\u005c+T\u005c+E\u005c+A\u005c+B\u005c+LE} callback as described below.\n\n\u005cmbox{[}This network-\u005c/programming necessity to link the issue of new data to the peer taking the previous data is not obvious to all users so let\u005ctextquotesingle{}s repeat that in other words\u005c+:\n\n$\u005cast$$\u005cast$$\u005cast$\u005c+O\u005c+N\u005c+LY DO L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+W\u005c+R\u005c+I\u005c+TE F\u005c+R\u005c+OM T\u005c+HE W\u005c+R\u005c+I\u005c+T\u005c+E\u005c+A\u005c+B\u005c+LE C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K$\u005cast$$\u005cast$$\u005cast$\n\nThere is another network-\u005c/programming truism that surprises some people which is if the sink for the data cannot accept more\u005c+:\n\n$\u005cast$$\u005cast$$\u005cast$\u005c+Y\u005c+OU M\u005c+U\u005c+ST P\u005c+E\u005c+R\u005c+F\u005c+O\u005c+RM RX F\u005c+L\u005c+OW C\u005c+O\u005c+N\u005c+T\u005c+R\u005c+O\u005c+L$\u005cast$$\u005cast$$\u005cast$\n\nSee the mirror protocol implementations for example code.\n\nOnly live connections appear in the user callbacks, so this removes any possibility of trying to used closed and freed wsis.\n\nIf you need to service other socket or file descriptors as well as the websocket ones, you can combine them together with the websocket ones in one poll loop, see \u005cchar`\u005c\u0022{}\u005c+External Polling Loop support\u005cchar`\u005c\u0022{} below, and still do it all in one thread / process context.\n\nIf you insist on trying to use it from multiple threads, take special care if you might simultaneously create more than one context from different threads.\n\nS\u005c+S\u005c+L\u005c+\u005c_\u005c+library\u005c+\u005c_\u005c+init() is called from the context create api and it also is not reentrant. So at least create the contexts sequentially.\n\n\u005csubsection*{Only send data when socket writeable }\n\nYou should only send data on a websocket connection from the user callback {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+S\u005c+E\u005c+R\u005c+V\u005c+E\u005c+R\u005c+\u005c_\u005c+\u005c+W\u005c+R\u005c+I\u005c+T\u005c+E\u005c+A\u005c+B\u005c+LE} (or {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+C\u005c+L\u005c+I\u005c+E\u005c+N\u005c+T\u005c+\u005c_\u005c+\u005c+W\u005c+R\u005c+I\u005c+T\u005c+E\u005c+A\u005c+B\u005c+LE} for clients).\n\nIf you want to send something, do not just send it but request a callback when the socket is writeable using\n\n\n\u005cbegin{DoxyItemize}\n\u005citem {\u005cttfamily lws\u005c+\u005c_\u005c+callback\u005c+\u005c_\u005c+on\u005c+\u005c_\u005c+writable(context, wsi)} for a specific {\u005cttfamily wsi}, or\n\u005citem {\u005cttfamily lws\u005c+\u005c_\u005c+callback\u005c+\u005c_\u005c+on\u005c+\u005c_\u005c+writable\u005c+\u005c_\u005c+all\u005c+\u005c_\u005c+protocol(protocol)} for all connections using that protocol to get a callback when next writeable.\n\u005cend{DoxyItemize}\n\nUsually you will get called back immediately next time around the service loop, but if your peer is slow or temporarily inactive the callback will be delayed accordingly. Generating what to write and sending it should be done in the ...W\u005c+R\u005c+I\u005c+T\u005c+E\u005c+A\u005c+B\u005c+LE callback.\n\nSee the test server code for an example of how to do this.\n\n\u005csubsection*{Do not rely on only your own W\u005c+R\u005c+I\u005c+T\u005c+E\u005c+A\u005c+B\u005c+LE requests appearing }\n\nLibwebsockets may generate additional {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+C\u005c+L\u005c+I\u005c+E\u005c+N\u005c+T\u005c+\u005c_\u005c+\u005c+W\u005c+R\u005c+I\u005c+T\u005c+E\u005c+A\u005c+B\u005c+LE} events if it met network conditions where it had to buffer your send data internally.\n\nSo your code for {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+C\u005c+L\u005c+I\u005c+E\u005c+N\u005c+T\u005c+\u005c_\u005c+\u005c+W\u005c+R\u005c+I\u005c+T\u005c+E\u005c+A\u005c+B\u005c+LE} needs to own the decision about what to send, it can\u005ctextquotesingle{}t assume that just because the writeable callback came it really is time to send something.\n\nIt\u005ctextquotesingle{}s quite possible you get an \u005ctextquotesingle{}extra\u005ctextquotesingle{} writeable callback at any time and just need to {\u005cttfamily return 0} and wait for the expected callback later.\n\n\u005csubsection*{Closing connections from the user side }\n\nWhen you want to close a connection, you do it by returning {\u005cttfamily -\u005c/1} from a callback for that connection.\n\nYou can provoke a callback by calling {\u005cttfamily lws\u005c+\u005c_\u005c+callback\u005c+\u005c_\u005c+on\u005c+\u005c_\u005c+writable} on the wsi, then notice in the callback you want to close it and just return -\u005c/1. But usually, the decision to close is made in a callback already and returning -\u005c/1 is simple.\n\nIf the socket knows the connection is dead, because the peer closed or there was an affirmitive network error like a F\u005c+IN coming, then {\u005cbfseries libwebsockets} will take care of closing the connection automatically.\n\nIf you have a silently dead connection, it\u005ctextquotesingle{}s possible to enter a state where the send pipe on the connection is choked but no ack will ever come, so the dead connection will never become writeable. To cover that, you can use T\u005c+CP keepalives (see later in this document)\n\n\u005csubsection*{Fragmented messages }\n\nTo support fragmented messages you need to check for the final frame of a message with {\u005cttfamily lws\u005c+\u005c_\u005c+is\u005c+\u005c_\u005c+final\u005c+\u005c_\u005c+fragment}. This check can be combined with {\u005cttfamily libwebsockets\u005c+\u005c_\u005c+remaining\u005c+\u005c_\u005c+packet\u005c+\u005c_\u005c+payload} to gather the whole contents of a message, eg\u005c+:\n\n\n\u005cbegin{DoxyCode}\n1 case LWS\u005c_CALLBACK\u005c_RECEIVE:\n2 \u005c{\n3 Client * const client \u003d (Client *)user;\n4 const size\u005c_t remaining \u003d lws\u005c_remaining\u005c_packet\u005c_payload(wsi);\n5 \n6 if (!remaining \u0026\u0026 lws\u005c_is\u005c_final\u005c_fragment(wsi)) \u005c{\n7 if (client-\u003eHasFragments()) \u005c{\n8 client-\u003eAppendMessageFragment(in, len, 0);\n9 in \u003d (void *)client-\u003eGetMessage();\n10 len \u003d client-\u003eGetMessageLength();\n11 \u005c}\n12 \n13 client-\u003eProcessMessage((char *)in, len, wsi);\n14 client-\u003eResetMessage();\n15 \u005c} else\n16 client-\u003eAppendMessageFragment(in, len, remaining);\n17 \u005c}\n18 break;\n\u005cend{DoxyCode}\n\n\nThe test app libwebsockets-\u005c/test-\u005c/fraggle sources also show how to deal with fragmented messages.\n\n\u005csubsection*{Debug Logging }\n\nAlso using {\u005cttfamily lws\u005c+\u005c_\u005c+set\u005c+\u005c_\u005c+log\u005c+\u005c_\u005c+level} api you may provide a custom callback to actually emit the log string. By default, this points to an internal emit function that sends to stderr. Setting it to {\u005cttfamily N\u005c+U\u005c+LL} leaves it as it is instead.\n\nA helper function {\u005cttfamily \u005chyperlink{group__log_gab7c0fc936cc9f1eb58e2bb234c15147c}{lwsl\u005c+\u005c_\u005c+emit\u005c+\u005c_\u005c+syslog()}} is exported from the library to simplify logging to syslog. You still need to use {\u005cttfamily setlogmask}, {\u005cttfamily openlog} and {\u005cttfamily closelog} in your user code.\n\nThe logging apis are made available for user code.\n\n\n\u005cbegin{DoxyItemize}\n\u005citem {\u005cttfamily lwsl\u005c+\u005c_\u005c+err(...)}\n\u005citem {\u005cttfamily lwsl\u005c+\u005c_\u005c+warn(...)}\n\u005citem {\u005cttfamily lwsl\u005c+\u005c_\u005c+notice(...)}\n\u005citem {\u005cttfamily lwsl\u005c+\u005c_\u005c+info(...)}\n\u005citem {\u005cttfamily lwsl\u005c+\u005c_\u005c+debug(...)}\n\u005cend{DoxyItemize}\n\nThe difference between notice and info is that notice will be logged by default whereas info is ignored by default.\n\n\u005csubsection*{External Polling Loop support }\n\n{\u005cbfseries libwebsockets} maintains an internal {\u005cttfamily poll()} array for all of its sockets, but you can instead integrate the sockets into an external polling array. That\u005ctextquotesingle{}s needed if {\u005cbfseries libwebsockets} will cooperate with an existing poll array maintained by another server.\n\nFour callbacks {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+A\u005c+D\u005c+D\u005c+\u005c_\u005c+\u005c+P\u005c+O\u005c+L\u005c+L\u005c+\u005c_\u005c+\u005c+FD}, {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+D\u005c+E\u005c+L\u005c+\u005c_\u005c+\u005c+P\u005c+O\u005c+L\u005c+L\u005c+\u005c_\u005c+\u005c+FD}, {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+S\u005c+E\u005c+T\u005c+\u005c_\u005c+\u005c+M\u005c+O\u005c+D\u005c+E\u005c+\u005c_\u005c+\u005c+P\u005c+O\u005c+L\u005c+L\u005c+\u005c_\u005c+\u005c+FD} and {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+C\u005c+L\u005c+E\u005c+A\u005c+R\u005c+\u005c_\u005c+\u005c+M\u005c+O\u005c+D\u005c+E\u005c+\u005c_\u005c+\u005c+P\u005c+O\u005c+L\u005c+L\u005c+\u005c_\u005c+\u005c+FD} appear in the callback for protocol 0 and allow interface code to manage socket descriptors in other poll loops.\n\nYou can pass all pollfds that need service to {\u005cttfamily \u005chyperlink{group__service_gad82efa5466d14a9f05aa06416375b28d}{lws\u005c+\u005c_\u005c+service\u005c+\u005c_\u005c+fd()}}, even if the socket or file does not belong to {\u005cbfseries libwebsockets} it is safe.\n\nIf {\u005cbfseries libwebsocket} handled it, it zeros the pollfd {\u005cttfamily revents} field before returning. So you can let {\u005cbfseries libwebsockets} try and if {\u005cttfamily pollfd-\u005c/$\u003e$revents} is nonzero on return, you know it needs handling by your code.\n\nAlso note that when integrating a foreign event loop like libev or libuv where it doesn\u005ctextquotesingle{}t natively use poll() semantics, and you must return a fake pollfd reflecting the real event\u005c+:\n\n\n\u005cbegin{DoxyItemize}\n\u005citem be sure you set .events to .revents value as well in the synthesized pollfd\n\u005citem check the built-\u005c/in support for the event loop if possible (eg, ./lib/libuv.c) to see how it interfaces to lws\n\u005citem use L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+P\u005c+O\u005c+L\u005c+L\u005c+H\u005c+UP / L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+P\u005c+O\u005c+L\u005c+L\u005c+IN / L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+P\u005c+O\u005c+L\u005c+L\u005c+O\u005c+UT from \u005chyperlink{libwebsockets_8h}{libwebsockets.\u005c+h} to avoid losing windows compatibility\n\u005cend{DoxyItemize}\n\n\u005csubsection*{Using with in c++ apps }\n\nThe library is ready for use by C++ apps. You can get started quickly by copying the test server\n\n\n\u005cbegin{DoxyCode}\n1 $ cp test-server/test-server.c test.cpp\n\u005cend{DoxyCode}\n\n\nand building it in C++ like this\n\n\n\u005cbegin{DoxyCode}\n1 $ g++ -DINSTALL\u005c_DATADIR\u003d\u005c(\u005cbackslash\u005c)\u0022/usr/share\u005c(\u005cbackslash\u005c)\u0022 -ocpptest test.cpp -lwebsockets\n\u005cend{DoxyCode}\n\n\n{\u005cttfamily I\u005c+N\u005c+S\u005c+T\u005c+A\u005c+L\u005c+L\u005c+\u005c_\u005c+\u005c+D\u005c+A\u005c+T\u005c+A\u005c+D\u005c+IR} is only needed because the test server uses it as shipped, if you remove the references to it in your app you don\u005ctextquotesingle{}t need to define it on the g++ line either.\n\n\u005csubsection*{Availability of header information }\n\nFrom v1.\u005c+2 of the library onwards, the H\u005c+T\u005c+TP header content is {\u005cttfamily free()}d as soon as the websocket connection is established. For websocket servers, you can copy interesting headers by handling {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+F\u005c+I\u005c+L\u005c+T\u005c+E\u005c+R\u005c+\u005c_\u005c+\u005c+P\u005c+R\u005c+O\u005c+T\u005c+O\u005c+C\u005c+O\u005c+L\u005c+\u005c_\u005c+\u005c+C\u005c+O\u005c+N\u005c+N\u005c+E\u005c+C\u005c+T\u005c+I\u005c+ON} callback, for clients there\u005ctextquotesingle{}s a new callback just for this purpose {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+C\u005c+L\u005c+I\u005c+E\u005c+N\u005c+T\u005c+\u005c_\u005c+\u005c+F\u005c+I\u005c+L\u005c+T\u005c+E\u005c+R\u005c+\u005c_\u005c+\u005c+P\u005c+R\u005c+E\u005c+\u005c_\u005c+\u005c+E\u005c+S\u005c+T\u005c+A\u005c+B\u005c+L\u005c+I\u005c+SH}.\n\n\u005csubsection*{T\u005c+CP Keepalive }\n\nIt is possible for a connection which is not being used to send to die silently somewhere between the peer and the side not sending. In this case by default T\u005c+CP will just not report anything and you will never get any more incoming data or sign the link is dead until you try to send.\n\nTo deal with getting a notification of that situation, you can choose to enable T\u005c+CP keepalives on all {\u005cbfseries libwebsockets} sockets, when you create the context.\n\nTo enable keepalive, set the ka\u005c+\u005c_\u005c+time member of the context creation parameter struct to a nonzero value (in seconds) at context creation time. You should also fill ka\u005c+\u005c_\u005c+probes and ka\u005c+\u005c_\u005c+interval in that case.\n\nWith keepalive enabled, the T\u005c+CP layer will send control packets that should stimulate a response from the peer without affecting link traffic. If the response is not coming, the socket will announce an error at {\u005cttfamily poll()} forcing a close.\n\nNote that B\u005c+S\u005c+Ds don\u005ctextquotesingle{}t support keepalive time / probes / interval per-\u005c/socket like Linux does. On those systems you can enable keepalive by a nonzero value in {\u005cttfamily ka\u005c+\u005c_\u005c+time}, but the systemwide kernel settings for the time / probes/ interval are used, regardless of what nonzero value is in {\u005cttfamily ka\u005c+\u005c_\u005c+time}.\n\n\u005csubsection*{Optimizing S\u005c+SL connections }\n\nThere\u005ctextquotesingle{}s a member {\u005cttfamily ssl\u005c+\u005c_\u005c+cipher\u005c+\u005c_\u005c+list} in the {\u005cttfamily \u005chyperlink{structlws__context__creation__info}{lws\u005c+\u005c_\u005c+context\u005c+\u005c_\u005c+creation\u005c+\u005c_\u005c+info}} struct which allows the user code to restrict the possible cipher selection at context-\u005c/creation time.\n\nYou might want to look into that to stop the ssl peers selecting a cipher which is too computationally expensive. To use it, point it to a string like \u005cbegin{DoxyVerb} `\u0022RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL\u0022`\n\u005cend{DoxyVerb}\n\n\nif left {\u005cttfamily N\u005c+U\u005c+LL}, then the \u005cchar`\u005c\u0022{}\u005c+D\u005c+E\u005c+F\u005c+A\u005c+U\u005c+L\u005c+T\u005cchar`\u005c\u0022{} set of ciphers are all possible to select.\n\nYou can also set it to {\u005cttfamily \u005cchar`\u005c\u0022{}\u005c+A\u005c+L\u005c+L\u005cchar`\u005c\u0022{}} to allow everything (including insecure ciphers).\n\n\u005csubsection*{Async nature of client connections }\n\nWhen you call {\u005cttfamily \u005chyperlink{structlws__client__connect__info}{lws\u005c+\u005c_\u005c+client\u005c+\u005c_\u005c+connect\u005c+\u005c_\u005c+info}(..)} and get a {\u005cttfamily wsi} back, it does not mean your connection is active. It just means it started trying to connect.\n\nYour client connection is actually active only when you receive {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+C\u005c+L\u005c+I\u005c+E\u005c+N\u005c+T\u005c+\u005c_\u005c+\u005c+E\u005c+S\u005c+T\u005c+A\u005c+B\u005c+L\u005c+I\u005c+S\u005c+H\u005c+ED} for it.\n\nThere\u005ctextquotesingle{}s a 5 second timeout for the connection, and it may give up or die for other reasons, if any of that happens you\u005ctextquotesingle{}ll get a {\u005cttfamily L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+C\u005c+L\u005c+I\u005c+E\u005c+N\u005c+T\u005c+\u005c_\u005c+\u005c+C\u005c+O\u005c+N\u005c+N\u005c+E\u005c+C\u005c+T\u005c+I\u005c+O\u005c+N\u005c+\u005c_\u005c+\u005c+E\u005c+R\u005c+R\u005c+OR} callback on protocol 0 instead for the {\u005cttfamily wsi}.\n\nAfter attempting the connection and getting back a non-\u005c/{\u005cttfamily N\u005c+U\u005c+LL} {\u005cttfamily wsi} you should loop calling {\u005cttfamily \u005chyperlink{group__service_gaf95bd0c663d6516a0c80047d9b1167a8}{lws\u005c+\u005c_\u005c+service()}} until one of the above callbacks occurs.\n\nAs usual, see \u005chref{test-server/test-client.c}{\u005ctt test-\u005c/client.\u005c+c} for example code.\n\n\u005csubsection*{Lws platform-\u005c/independent file access apis }\n\nlws now exposes his internal platform file abstraction in a way that can be both used by user code to make it platform-\u005c/agnostic, and be overridden or subclassed by user code. This allows things like handling the U\u005c+RI \u005cchar`\u005c\u0022{}directory\nspace\u005cchar`\u005c\u0022{} as a virtual filesystem that may or may not be backed by a regular filesystem. One example use is serving files from inside large compressed archive storage without having to unpack anything except the file being requested.\n\nThe test server shows how to use it, basically the platform-\u005c/specific part of lws prepares a file operations structure that lives in the lws context.\n\nThe user code can get a pointer to the file operations struct\n\n\n\u005cbegin{DoxyCode}\n1 LWS\u005c_VISIBLE LWS\u005c_EXTERN struct lws\u005c_plat\u005c_file\u005c_ops *\n2 `lws\u005c_get\u005c_fops`(struct lws\u005c_context *context);\n\u005cend{DoxyCode}\n\n\nand then can use helpers to also leverage these platform-\u005c/independent file handling apis\n\n\n\u005cbegin{DoxyCode}\n1 static inline lws\u005c_filefd\u005c_type\n2 `lws\u005c_plat\u005c_file\u005c_open`(struct lws *wsi, const char *filename, unsigned long *filelen, int flags)\n3 \n4 static inline int\n5 `lws\u005c_plat\u005c_file\u005c_close`(struct lws *wsi, lws\u005c_filefd\u005c_type fd)\n6 \n7 static inline unsigned long\n8 `lws\u005c_plat\u005c_file\u005c_seek\u005c_cur`(struct lws *wsi, lws\u005c_filefd\u005c_type fd, long offset\u005c_from\u005c_cur\u005c_pos)\n9 \n10 static inline int\n11 `lws\u005c_plat\u005c_file\u005c_read`(struct lws *wsi, lws\u005c_filefd\u005c_type fd, unsigned long *amount, unsigned char *buf,\n unsigned long len)\n12 \n13 static inline int\n14 `lws\u005c_plat\u005c_file\u005c_write`(struct lws *wsi, lws\u005c_filefd\u005c_type fd, unsigned long *amount, unsigned char *buf,\n unsigned long len)\n\u005cend{DoxyCode}\n\n\nThe user code can also override or subclass the file operations, to either wrap or replace them. An example is shown in test server.\n\n\u005csubsection*{E\u005c+C\u005c+DH Support }\n\nE\u005c+C\u005c+DH Certs are now supported. Enable the C\u005c+Make option \u005cbegin{DoxyVerb} cmake .. -DLWS_SSL_SERVER_WITH_ECDH_CERT\u003d1 \n\u005cend{DoxyVerb}\n\n\n{\u005cbfseries and} the info-\u005c/$\u003e$options flag \u005cbegin{DoxyVerb} LWS_SERVER_OPTION_SSL_ECDH\n\u005cend{DoxyVerb}\n\n\nto build in support and select it at runtime.\n\n\u005csubsection*{S\u005c+MP / Multithreaded service }\n\nS\u005c+MP support is integrated into L\u005c+WS without any internal threading. It\u005ctextquotesingle{}s very simple to use, libwebsockets-\u005c/test-\u005c/server-\u005c/pthread shows how to do it, use -\u005c/j $\u003c$n$\u003e$ argument there to control the number of service threads up to 32.\n\nTwo new members are added to the info struct \u005cbegin{DoxyVerb} unsigned int count_threads;\n unsigned int fd_limit_per_thread;\n\u005cend{DoxyVerb}\n\n\nleave them at the default 0 to get the normal singlethreaded service loop.\n\nSet count\u005c+\u005c_\u005c+threads to n to tell lws you will have n simultaneous service threads operating on the context.\n\nThere is still a single listen socket on one port, no matter how many service threads.\n\nWhen a connection is made, it is accepted by the service thread with the least connections active to perform load balancing.\n\nThe user code is responsible for spawning n threads running the service loop associated to a specific tsi (Thread Service Index, 0 .. n -\u005c/ 1). See the libwebsockets-\u005c/test-\u005c/server-\u005c/pthread for how to do.\n\nIf you leave fd\u005c+\u005c_\u005c+limit\u005c+\u005c_\u005c+per\u005c+\u005c_\u005c+thread at 0, then the process limit of fds is shared between the service threads; if you process was allowed 1024 fds overall then each thread is limited to 1024 / n.\n\nYou can set fd\u005c+\u005c_\u005c+limit\u005c+\u005c_\u005c+per\u005c+\u005c_\u005c+thread to a nonzero number to control this manually, eg the overall supported fd limit is less than the process allowance.\n\nYou can control the context basic data allocation for multithreading from Cmake using -\u005c/\u005c+D\u005c+L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+M\u005c+A\u005c+X\u005c+\u005c_\u005c+\u005c+S\u005c+MP\u003d, if not given it\u005ctextquotesingle{}s set to 32. The serv\u005c+\u005c_\u005c+buf allocation for the threads (currently 4096) is made at runtime only for active threads.\n\nBecause lws will limit the requested number of actual threads supported according to L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+M\u005c+A\u005c+X\u005c+\u005c_\u005c+\u005c+S\u005c+MP, there is an api lws\u005c+\u005c_\u005c+get\u005c+\u005c_\u005c+count\u005c+\u005c_\u005c+threads(context) to discover how many threads were actually allowed when the context was created.\n\nIt\u005ctextquotesingle{}s required to implement locking in the user code in the same way that libwebsockets-\u005c/test-\u005c/server-\u005c/pthread does it, for the FD locking callbacks.\n\nThere is no knowledge or dependency in lws itself about pthreads. How the locking is implemented is entirely up to the user code.\n\n\u005csubsection*{Libev / Libuv support }\n\nYou can select either or both \u005cbegin{DoxyVerb} -DLWS_WITH_LIBEV\u003d1\n -DLWS_WITH_LIBUV\u003d1\n\u005cend{DoxyVerb}\n\n\nat cmake configure-\u005c/time. The user application may use one of the context init options flags \u005cbegin{DoxyVerb} LWS_SERVER_OPTION_LIBEV\n LWS_SERVER_OPTION_LIBUV\n\u005cend{DoxyVerb}\n\n\nto indicate it will use either of the event libraries.\n\n\u005csubsection*{Extension option control from user code }\n\nUser code may set per-\u005c/connection extension options now, using a new api {\u005cttfamily \u005chyperlink{group__extensions_gae0e24e1768f83a7fb07896ce975704b9}{lws\u005c+\u005c_\u005c+set\u005c+\u005c_\u005c+extension\u005c+\u005c_\u005c+option()}}.\n\nThis should be called from the E\u005c+S\u005c+T\u005c+A\u005c+B\u005c+L\u005c+I\u005c+S\u005c+H\u005c+ED callback like this \n\u005cbegin{DoxyCode}\n1 lws\u005c_set\u005c_extension\u005c_option(wsi, \u0022permessage-deflate\u0022,\n2 \u0022rx\u005c_buf\u005c_size\u0022, \u002212\u0022); /* 1 \u003c\u003c 12 */\n\u005cend{DoxyCode}\n\n\nIf the extension is not active (missing or not negotiated for the connection, or extensions are disabled on the library) the call is just returns -\u005c/1. Otherwise the connection\u005ctextquotesingle{}s extension has its named option changed.\n\nThe extension may decide to alter or disallow the change, in the example above permessage-\u005c/deflate restricts the size of his rx output buffer also considering the protocol\u005ctextquotesingle{}s rx\u005c+\u005c_\u005c+buf\u005c+\u005c_\u005c+size member.\n\n\u005csubsection*{Client connections as H\u005c+T\u005c+TP\u005cmbox{[}S\u005cmbox{]} rather than WS\u005cmbox{[}S\u005cmbox{]} }\n\nYou may open a generic http client connection using the same struct \u005chyperlink{structlws__client__connect__info}{lws\u005c+\u005c_\u005c+client\u005c+\u005c_\u005c+connect\u005c+\u005c_\u005c+info} used to create client ws\u005cmbox{[}s\u005cmbox{]} connections.\n\nTo stay in http\u005cmbox{[}s\u005cmbox{]}, set the optional info member \u005cchar`\u005c\u0022{}method\u005cchar`\u005c\u0022{} to point to the string \u005cchar`\u005c\u0022{}\u005c+G\u005c+E\u005c+T\u005cchar`\u005c\u0022{} instead of the default N\u005c+U\u005c+LL.\n\nAfter the server headers are processed, when payload from the server is available the callback L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+C\u005c+K\u005c+\u005c_\u005c+\u005c+R\u005c+E\u005c+C\u005c+E\u005c+I\u005c+V\u005c+E\u005c+\u005c_\u005c+\u005c+C\u005c+L\u005c+I\u005c+E\u005c+N\u005c+T\u005c+\u005c_\u005c+\u005c+H\u005c+T\u005c+TP will be made.\n\nYou can choose whether to process the data immediately, or queue a callback when an outgoing socket is writeable to provide flow control, and process the data in the writable callback.\n\nEither way you use the api {\u005cttfamily lws\u005c+\u005c_\u005c+http\u005c+\u005c_\u005c+client\u005c+\u005c_\u005c+read()} to access the data, eg\n\n\n\u005cbegin{DoxyCode}\n1 case LWS\u005c_CALLBACK\u005c_RECEIVE\u005c_CLIENT\u005c_HTTP:\n2 \u005c{\n3 char buffer[1024 + LWS\u005c_PRE];\n4 char *px \u003d buffer + LWS\u005c_PRE;\n5 int lenx \u003d sizeof(buffer) - LWS\u005c_PRE;\n6 \n7 lwsl\u005c_notice(\u0022LWS\u005c_CALLBACK\u005c_RECEIVE\u005c_CLIENT\u005c_HTTP\u005c(\u005cbackslash\u005c)n\u0022);\n8 \n9 /*\n10 * Often you need to flow control this by something\n11 * else being writable. In that case call the api\n12 * to get a callback when writable here, and do the\n13 * pending client read in the writeable callback of\n14 * the output.\n15 */\n16 if (lws\u005c_http\u005c_client\u005c_read(wsi, \u0026px, \u0026lenx) \u003c 0)\n17 return -1;\n18 while (lenx--)\n19 putchar(*px++);\n20 \u005c}\n21 break;\n\u005cend{DoxyCode}\n\n\n\u005csubsection*{Using lws v2 vhosts }\n\nIf you set L\u005c+W\u005c+S\u005c+\u005c_\u005c+\u005c+S\u005c+E\u005c+R\u005c+V\u005c+E\u005c+R\u005c+\u005c_\u005c+\u005c+O\u005c+P\u005c+T\u005c+I\u005c+O\u005c+N\u005c+\u005c_\u005c+\u005c+E\u005c+X\u005c+P\u005c+L\u005c+I\u005c+C\u005c+I\u005c+T\u005c+\u005c_\u005c+\u005c+V\u005c+H\u005c+O\u005c+S\u005c+TS options flag when you create your context, it won\u005ctextquotesingle{}t create a default vhost using the info struct members for compatibility. Instead you can call \u005chyperlink{group__context-and-vhost_ga0c54c667ccd9b8b3dddcd123ca72f87c}{lws\u005c+\u005c_\u005c+create\u005c+\u005c_\u005c+vhost()} afterwards to attach one or more vhosts manually.\n\n\n\u005cbegin{DoxyCode}\n1 LWS\u005c_VISIBLE struct lws\u005c_vhost *\n2 lws\u005c_create\u005c_vhost(struct lws\u005c_context *context,\n3 struct lws\u005c_context\u005c_creation\u005c_info *info,\n4 struct lws\u005c_http\u005c_mount *mounts);\n\u005cend{DoxyCode}\n\n\n\u005chyperlink{group__context-and-vhost_ga0c54c667ccd9b8b3dddcd123ca72f87c}{lws\u005c+\u005c_\u005c+create\u005c+\u005c_\u005c+vhost()} uses the same info struct as \u005chyperlink{group__context-and-vhost_gaf2fff58562caab7510c41eeac85a8648}{lws\u005c+\u005c_\u005c+create\u005c+\u005c_\u005c+context()}, it ignores members related to context and uses the ones meaningful for vhost (marked with VH in \u005chyperlink{libwebsockets_8h}{libwebsockets.\u005c+h}).\n\n\n\u005cbegin{DoxyCode}\n1 struct lws\u005c_context\u005c_creation\u005c_info \u005c{\n2 int port; /* VH */\n3 const char *iface; /* VH */\n4 const struct lws\u005c_protocols *protocols; /* VH */\n5 const struct lws\u005c_extension *extensions; /* VH */\n6 ...\n\u005cend{DoxyCode}\n\n\nWhen you attach the vhost, if the vhost\u005ctextquotesingle{}s port already has a listen socket then both vhosts share it and use S\u005c+NI (is S\u005c+SL in use) or the Host\u005c+: header from the client to select the right one. Or if no other vhost already listening the a new listen socket is created.\n\nThere are some new members but mainly it\u005ctextquotesingle{}s stuff you used to set at context creation time.\n\n\u005csubsection*{Using lws v2 mounts on a vhost }\n\nThe last argument to \u005chyperlink{group__context-and-vhost_ga0c54c667ccd9b8b3dddcd123ca72f87c}{lws\u005c+\u005c_\u005c+create\u005c+\u005c_\u005c+vhost()} lets you associate a linked list of \u005chyperlink{structlws__http__mount}{lws\u005c+\u005c_\u005c+http\u005c+\u005c_\u005c+mount} structures with that vhost\u005ctextquotesingle{}s U\u005c+RL \u005ctextquotesingle{}namespace\u005ctextquotesingle{}, in a similar way that unix lets you mount filesystems into areas of your / filesystem how you like and deal with the contents transparently.\n\n\n\u005cbegin{DoxyCode}\n1 struct lws\u005c_http\u005c_mount \u005c{\n2 struct lws\u005c_http\u005c_mount *mount\u005c_next;\n3 const char *mountpoint; /* mountpoint in http pathspace, eg, \u0022/\u0022 */\n4 const char *origin; /* path to be mounted, eg, \u0022/var/www/warmcat.com\u0022 */\n5 const char *def; /* default target, eg, \u0022index.html\u0022 */\n6 \n7 struct lws\u005c_protocol\u005c_vhost\u005c_options *cgienv;\n8 \n9 int cgi\u005c_timeout;\n10 int cache\u005c_max\u005c_age;\n11 \n12 unsigned int cache\u005c_reusable:1;\n13 unsigned int cache\u005c_revalidate:1;\n14 unsigned int cache\u005c_intermediaries:1;\n15 \n16 unsigned char origin\u005c_protocol;\n17 unsigned char mountpoint\u005c_len;\n18 \u005c};\n\u005cend{DoxyCode}\n\n\nThe last mount structure should have a N\u005c+U\u005c+LL mount\u005c+\u005c_\u005c+next, otherwise it should point to the \u005ctextquotesingle{}next\u005ctextquotesingle{} mount structure in your list.\n\nBoth the mount structures and the strings must persist until the context is destroyed, since they are not copied but used in place.\n\n{\u005cttfamily .origin\u005c+\u005c_\u005c+protocol} should be one of\n\n\n\u005cbegin{DoxyCode}\n1 enum \u005c{\n2 LWSMPRO\u005c_HTTP,\n3 LWSMPRO\u005c_HTTPS,\n4 LWSMPRO\u005c_FILE,\n5 LWSMPRO\u005c_CGI,\n6 LWSMPRO\u005c_REDIR\u005c_HTTP,\n7 LWSMPRO\u005c_REDIR\u005c_HTTPS,\n8 LWSMPRO\u005c_CALLBACK,\n9 \u005c};\n\u005cend{DoxyCode}\n\n\n\n\u005cbegin{DoxyItemize}\n\u005citem L\u005c+W\u005c+S\u005c+M\u005c+P\u005c+R\u005c+O\u005c+\u005c_\u005c+\u005c+F\u005c+I\u005c+LE is used for mapping url namespace to a filesystem directory and serve it automatically.\n\u005citem L\u005c+W\u005c+S\u005c+M\u005c+P\u005c+R\u005c+O\u005c+\u005c_\u005c+\u005c+C\u005c+GI associates the url namespace with the given C\u005c+GI executable, which runs when the U\u005c+RL is accessed and the output provided to the client.\n\u005citem L\u005c+W\u005c+S\u005c+M\u005c+P\u005c+R\u005c+O\u005c+\u005c_\u005c+\u005c+R\u005c+E\u005c+D\u005c+I\u005c+R\u005c+\u005c_\u005c+\u005c+H\u005c+T\u005c+TP and L\u005c+W\u005c+S\u005c+M\u005c+P\u005c+R\u005c+O\u005c+\u005c_\u005c+\u005c+R\u005c+E\u005c+D\u005c+I\u005c+R\u005c+\u005c_\u005c+\u005c+H\u005c+T\u005c+T\u005c+PS auto-\u005c/redirect clients to the given origin U\u005c+RL.\n\u005citem L\u005c+W\u005c+S\u005c+M\u005c+P\u005c+R\u005c+O\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+CK causes the http connection to attach to the callback associated with the named protocol (which may be a plugin).\n\u005cend{DoxyItemize}\n\n\u005csubsection*{Operation of L\u005c+W\u005c+S\u005c+M\u005c+P\u005c+R\u005c+O\u005c+\u005c_\u005c+\u005c+C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+CK mounts }\n\nThe feature provided by C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+CK type mounts is binding a part of the U\u005c+RL namespace to a named protocol callback handler.\n\nThis allows protocol plugins to handle areas of the U\u005c+RL namespace. For example in test-\u005c/server-\u005c/v2.\u005c+0.\u005c+c, the U\u005c+RL area \u005cchar`\u005c\u0022{}/formtest\u005cchar`\u005c\u0022{} is associated with the plugin providing \u005cchar`\u005c\u0022{}protocol-\u005c/post-\u005c/demo\u005cchar`\u005c\u0022{} like this\n\n\n\u005cbegin{DoxyCode}\n1 static const struct lws\u005c_http\u005c_mount mount\u005c_post \u003d \u005c{\n2 NULL, /* linked-list pointer to next*/\n3 \u0022/formtest\u0022, /* mountpoint in URL namespace on this vhost */\n4 \u0022protocol-post-demo\u0022, /* handler */\n5 NULL, /* default filename if none given */\n6 NULL,\n7 0,\n8 0,\n9 0,\n10 0,\n11 0,\n12 LWSMPRO\u005c_CALLBACK, /* origin points to a callback */\n13 9, /* strlen(\u0022/formtest\u0022), ie length of the mountpoint */\n14 \u005c};\n\u005cend{DoxyCode}\n\n\nClient access to /formtest\u005cmbox{[}anything\u005cmbox{]} will be passed to the callback registered with the named protocol, which in this case is provided by a protocol plugin.\n\nAccess by all methods, eg, G\u005c+ET and P\u005c+O\u005c+ST are handled by the callback.\n\nprotocol-\u005c/post-\u005c/demo deals with accepting and responding to the html form that is in the test server H\u005c+T\u005c+ML.\n\nWhen a connection accesses a U\u005c+RL related to a C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+CK type mount, the connection protocol is changed until the next access on the connection to a U\u005c+RL outside the same C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+CK mount area. User space on the connection is arranged to be the size of the new protocol user space allocation as given in the protocol struct.\n\nThis allocation is only deleted / replaced when the connection accesses a U\u005c+RL region with a different protocol (or the default protocols\u005cmbox{[}0\u005cmbox{]} if no C\u005c+A\u005c+L\u005c+L\u005c+B\u005c+A\u005c+CK area matches it). ","s":{"c":1757099166,"u": 1081}} ],"g": 9238,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 1, "si": 0, "db":0, "di":0, "sat":0, "lfc": "0000"}