Emscripten WebSockets API

WebSockets API provides connection-oriented message-framed bidirectionalasynchronous networking communication to the browser. It is the closest to TCPon the web that web sites can access, direct access to TCP sockets is notpossible from web browsers.

Emscripten provides a passthrough API for accessing the WebSockets API fromC/C++ code. This is useful for developers who would prefer not to write anyJavaScript code, or deal with the C/C++ and JavaScript language interop. See thesystem include file<emscripten/websocket.h> for details. One benefit thatthe Emscripten WebSockets API provides over manual WebSockets access inJavaScript is the ability to share access to a WebSocket handle across multiplethreads, something that can be time consuming to develop from scratch.

To target Emscripten WebSockets API, you must link it in with a-lwebsocket.js linker directive.

Emulated POSIX TCP Sockets over WebSockets

If you have existing TCP networking code written in C/C++ that utilizes thePosix Sockets API, by default Emscripten attempts to emulate such connections totake place over the WebSocket protocol instead. For this to work, you will needto use something like WebSockify on the server side to enable the TCP serverstack to receive incoming WebSocket connections. This emulation is not verycomplete at the moment, it is likely that you will run into problems out of thebox and need to adapt the code to work within the limitations that thisemulation provides.

This is the default build mode for Emscripten. Use the linker flag-sWEBSOCKET_URL orModule['websocket']['url'] to specify the WebSocket URLto connect to, and the linker flag-sWEBSOCKET_SUBPROTOCOL orModule['websocket']['subprotocol'] to control the connection type('binary' or'text').

Full POSIX Sockets over WebSocket Proxy Server

Emscripten provides a native POSIX Sockets proxy server program, located indirectorytools/websocket_to_posix_proxy/, that allows full POSIX SocketsAPI access from a web browser. This support works by proxying all POSIX SocketsAPI calls from the browser to the Emscripten POSIX Sockets proxy server (viatransparent use of the WebSockets API), and the proxy server then performs thenative TCP/UDP calls on behalf of the page. This allows a web browser page torun full TCP & UDP connections, act as a server to accept incoming connections,and perform host name lookups and reverse lookups. Because all API calls areindividually proxied, this support can be slow. This support is mostly usefulfor developing testing infrastructure and debugging.

The following POSIX sockets functions are proxied in this manner:

• socket(),socketpair(),shutdown(),bind(),connect(),listen(),accept(),getsockname(),getpeername(),send(),recv(),sendto(),recvfrom(),sendmsg(),recvmsg(),getsockopt(),setsockopt(),getaddrinfo(),getnameinfo().

The following POSIX sockets functions are currently not proxied (and will not work):

• poll(),close() (useshutdown() instead),select()

To use POSIX sockets proxying, link the application with flags-lwebsocket.js-sPROXY_POSIX_SOCKETS-pthread-sPROXY_TO_PTHREAD. That is,POSIX sockets proxying builds on top of the Emscripten WebSockets library, andrequires multithreading and proxying the applicationmain() to a pthread.

For an example of how the POSIX Sockets proxy server works in an Emscriptenclient program, see the filetest/websocket/tcp_echo_client.c.

XmlHttpRequests and Fetch API

For HTTP transfers, one can use the browser built-in XmlHttpRequest (XHR) APIand the newer Fetch API. These can be accessed directly from JavaScript.Emscripten also provides passthrough APIs to perform HTTP requests. For moreinformation, see theemscripten_async_wget*() C API and the Emscripten FetchAPI.

WebRTC and UDP

Direct UDP communication is not available in browsers, but as a closealternative, the WebRTC specification provides a mechanism to perform UDP-likecommunication with WebRTC Data Channels. Currently Emscripten does not provide aC/C++ API for interacting with WebRTC.