\href{http://travis-ci.org/socketio/engine.io-client}{\texttt{ }} \href{http://badge.fury.io/js/engine.io-client}{\texttt{ }}

This is the client for \href{http://github.com/socketio/engine.io}{\texttt{ Engine.\+IO}}, the implementation of transport-\/based cross-\/browser/cross-\/device bi-\/directional communication layer for \href{http://github.com/socketio/socket.io}{\texttt{ Socket.\+IO}}.\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8692}{}\doxysection{How to use}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8692}
\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8693}{}\doxysubsection{Standalone}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8693}
You can find an {\ttfamily engine.\+io.\+js} file in this repository, which is a standalone build you can use as follows\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{<script src="{}/path/to/engine.io.js"{}></script>}
\DoxyCodeLine{<script>}
\DoxyCodeLine{  // eio = Socket}
\DoxyCodeLine{  var socket = eio('ws://localhost');}
\DoxyCodeLine{  socket.on('open', function()\{}
\DoxyCodeLine{    socket.on('message', function(data)\{\});}
\DoxyCodeLine{    socket.on('close', function()\{\});}
\DoxyCodeLine{  \});}
\DoxyCodeLine{</script> }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8694}{}\doxysubsection{With browserify}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8694}
Engine.\+IO is a commonjs module, which means you can include it by using {\ttfamily require} on the browser and package using \href{http://browserify.org/}{\texttt{ browserify}}\+:


\begin{DoxyEnumerate}
\item install the client package

\`{}\`{}\`{}bash \$ npm install engine.\+io-\/client \`{}\`{}\`{}
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item write your app code

\`{}\`{}`js var socket = require(\textquotesingle{}engine.\+io-\/client')(\textquotesingle{}ws\+://localhost\textquotesingle{}); socket.\+on(\textquotesingle{}open\textquotesingle{}, function()\{ socket.\+on(\textquotesingle{}message\textquotesingle{}, function(data)\{\}); socket.\+on(\textquotesingle{}close\textquotesingle{}, function()\{\}); \}); \`{}\`{}\`{}
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item build your app bundle

\`{}\`{}\`{}bash \$ browserify app.\+js $>$ bundle.\+js \`{}\`{}\`{}
\end{DoxyEnumerate}
\begin{DoxyEnumerate}
\item include on your page

\`{}\`{}\`{}html $<$script src=\char`\"{}/path/to/bundle.\+js\char`\"{}$>$$<$/script$>$ \`{}\`{}\`{}
\end{DoxyEnumerate}\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8695}{}\doxysubsection{Sending and receiving binary}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8695}

\begin{DoxyCode}{0}
\DoxyCodeLine{<script src="{}/path/to/engine.io.js"{}></script>}
\DoxyCodeLine{<script>}
\DoxyCodeLine{  var socket = new eio.Socket('ws://localhost/');}
\DoxyCodeLine{  socket.binaryType = 'blob';}
\DoxyCodeLine{  socket.on('open', function () \{}
\DoxyCodeLine{    socket.send(new Int8Array(5));}
\DoxyCodeLine{    socket.on('message', function(blob)\{\});}
\DoxyCodeLine{    socket.on('close', function()\{ \});}
\DoxyCodeLine{  \});}
\DoxyCodeLine{</script> }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8696}{}\doxysubsection{Node.\+JS}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8696}
Add {\ttfamily engine.\+io-\/client} to your {\ttfamily package.\+json} and then\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var socket = require('engine.io-\/client')('ws://localhost');}
\DoxyCodeLine{socket.on('open', function()\{}
\DoxyCodeLine{  socket.on('message', function(data)\{\});}
\DoxyCodeLine{  socket.on('close', function()\{\});}
\DoxyCodeLine{\}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8697}{}\doxysubsection{Node.\+js with certificates}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8697}

\begin{DoxyCode}{0}
\DoxyCodeLine{var opts = \{}
\DoxyCodeLine{  key: fs.readFileSync('test/fixtures/client.key'),}
\DoxyCodeLine{  cert: fs.readFileSync('test/fixtures/client.crt'),}
\DoxyCodeLine{  ca: fs.readFileSync('test/fixtures/ca.crt')}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{var socket = require('engine.io-\/client')('ws://localhost', opts);}
\DoxyCodeLine{socket.on('open', function()\{}
\DoxyCodeLine{  socket.on('message', function(data)\{\});}
\DoxyCodeLine{  socket.on('close', function()\{\});}
\DoxyCodeLine{\}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8698}{}\doxysubsection{Node.\+js with extra\+Headers}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8698}

\begin{DoxyCode}{0}
\DoxyCodeLine{var opts = \{}
\DoxyCodeLine{  extraHeaders: \{}
\DoxyCodeLine{    'X-\/Custom-\/Header-\/For-\/My-\/Project': 'my-\/secret-\/access-\/token',}
\DoxyCodeLine{    'Cookie': 'user\_session=NI2JlCKF90aE0sJZD9ZzujtdsUqNYSBYxzlTsvdSUe35ZzdtVRGqYFr0kdGxbfc5gUOkR9RGp20GVKza; path=/; expires=Tue, 07-\/Apr-\/2015 18:18:08 GMT; secure; HttpOnly'}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{var socket = require('engine.io-\/client')('ws://localhost', opts);}
\DoxyCodeLine{socket.on('open', function()\{}
\DoxyCodeLine{  socket.on('message', function(data)\{\});}
\DoxyCodeLine{  socket.on('close', function()\{\});}
\DoxyCodeLine{\}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8699}{}\doxysection{Features}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8699}

\begin{DoxyItemize}
\item Lightweight
\item Runs on browser and node.\+js seamlessly
\item Transports are independent of {\ttfamily Engine}
\begin{DoxyItemize}
\item Easy to debug
\item Easy to unit test
\end{DoxyItemize}
\item Runs inside HTML5 Web\+Worker
\item Can send and receive binary data
\begin{DoxyItemize}
\item Receives as Array\+Buffer or Blob when in browser, and Buffer or Array\+Buffer in Node
\item When XHR2 or Web\+Sockets are used, binary is emitted directly. Otherwise binary is encoded into base64 strings, and decoded when binary types are supported.
\item With browsers that don\textquotesingle{}t support Array\+Buffer, an object \{ base64\+: true, data\+: data\+As\+Base64\+String \} is emitted on the {\ttfamily message} event.
\end{DoxyItemize}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8700}{}\doxysection{API}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8700}
\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8701}{}\doxysubsection{Socket}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8701}
The client class. Mixes in \href{http://github.com/component/emitter}{\texttt{ Emitter}}. Exposed as {\ttfamily eio} in the browser standalone build.\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8702}{}\doxysubsubsection{Properties}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8702}

\begin{DoxyItemize}
\item {\ttfamily protocol} \+\_\+(\+Number)\+\_\+\+: protocol revision number
\item {\ttfamily binary\+Type} \+\_\+(\+String)\+\_\+ \+: can be set to \textquotesingle{}arraybuffer\textquotesingle{} or \textquotesingle{}blob\textquotesingle{} in browsers, and {\ttfamily buffer} or {\ttfamily arraybuffer} in Node. Blob is only used in browser if it\textquotesingle{}s supported.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8703}{}\doxysubsubsection{Events}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8703}

\begin{DoxyItemize}
\item {\ttfamily open}
\begin{DoxyItemize}
\item Fired upon successful connection.
\end{DoxyItemize}
\item {\ttfamily message}
\begin{DoxyItemize}
\item Fired when data is received from the server.
\item {\bfseries{Arguments}}
\begin{DoxyItemize}
\item {\ttfamily String} $\vert$ {\ttfamily Array\+Buffer}\+: utf-\/8 encoded data or Array\+Buffer containing binary data
\end{DoxyItemize}
\end{DoxyItemize}
\item {\ttfamily close}
\begin{DoxyItemize}
\item Fired upon disconnection. In compliance with the Web\+Socket API spec, this event may be fired even if the {\ttfamily open} event does not occur (i.\+e. due to connection error or {\ttfamily close()}).
\end{DoxyItemize}
\item {\ttfamily error}
\begin{DoxyItemize}
\item Fired when an error occurs.
\end{DoxyItemize}
\item {\ttfamily flush}
\begin{DoxyItemize}
\item Fired upon completing a buffer flush
\end{DoxyItemize}
\item {\ttfamily drain}
\begin{DoxyItemize}
\item Fired after {\ttfamily drain} event of transport if write\+Buffer is empty
\end{DoxyItemize}
\item {\ttfamily upgrade\+Error}
\begin{DoxyItemize}
\item Fired if an error occurs with a transport we\textquotesingle{}re trying to upgrade to.
\end{DoxyItemize}
\item {\ttfamily upgrade}
\begin{DoxyItemize}
\item Fired upon upgrade success, after the new transport is set
\end{DoxyItemize}
\item {\ttfamily ping}
\begin{DoxyItemize}
\item Fired upon {\itshape flushing} a ping packet (ie\+: actual packet write out)
\end{DoxyItemize}
\item {\ttfamily pong}
\begin{DoxyItemize}
\item Fired upon receiving a pong packet.
\end{DoxyItemize}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8704}{}\doxysubsubsection{Methods}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8704}

\begin{DoxyItemize}
\item {\bfseries{constructor}}
\begin{DoxyItemize}
\item Initializes the client
\item {\bfseries{Parameters}}
\begin{DoxyItemize}
\item {\ttfamily String} uri
\item {\ttfamily Object}\+: optional, options object
\end{DoxyItemize}
\item {\bfseries{Options}}
\begin{DoxyItemize}
\item {\ttfamily agent} ({\ttfamily http.\+Agent})\+: {\ttfamily http.\+Agent} to use, defaults to {\ttfamily false} (Node\+JS only)
\item {\ttfamily upgrade} ({\ttfamily Boolean})\+: defaults to true, whether the client should try to upgrade the transport from long-\/polling to something better.
\item {\ttfamily force\+JSONP} ({\ttfamily Boolean})\+: forces JSONP for polling transport.
\item {\ttfamily jsonp} ({\ttfamily Boolean})\+: determines whether to use JSONP when necessary for polling. If disabled (by settings to false) an error will be emitted (saying \char`\"{}\+No transports available\char`\"{}) if no other transports are available. If another transport is available for opening a connection (e.\+g. Web\+Socket) that transport will be used instead.
\item {\ttfamily force\+Base64} ({\ttfamily Boolean})\+: forces base 64 encoding for polling transport even when XHR2 response\+Type is available and Web\+Socket even if the used standard supports binary.
\item {\ttfamily enables\+XDR} ({\ttfamily Boolean})\+: enables XDomain\+Request for IE8 to avoid loading bar flashing with click sound. default to {\ttfamily false} because XDomain\+Request has a flaw of not sending cookie.
\item {\ttfamily with\+Credentials} ({\ttfamily Boolean})\+: defaults to {\ttfamily true}, whether to include credentials (cookies, authorization headers, TLS client certificates, etc.) with cross-\/origin XHR polling requests.
\item {\ttfamily timestamp\+Requests} ({\ttfamily Boolean})\+: whether to add the timestamp with each transport request. Note\+: polling requests are always stamped unless this option is explicitly set to {\ttfamily false} ({\ttfamily false})
\item {\ttfamily timestamp\+Param} ({\ttfamily String})\+: timestamp parameter ({\ttfamily t})
\item {\ttfamily policy\+Port} ({\ttfamily Number})\+: port the policy server listens on ({\ttfamily 843})
\item {\ttfamily path} ({\ttfamily String})\+: path to connect to, default is {\ttfamily /engine.io}
\item {\ttfamily transports} ({\ttfamily Array})\+: a list of transports to try (in order). Defaults to `\mbox{[}\textquotesingle{}polling', \textquotesingle{}websocket\textquotesingle{}\mbox{]}{\ttfamily .}Engine\`{} always attempts to connect directly with the first one, provided the feature detection test for it passes.
\item {\ttfamily transport\+Options} ({\ttfamily Object})\+: hash of options, indexed by transport name, overriding the common options for the given transport
\item {\ttfamily remember\+Upgrade} ({\ttfamily Boolean})\+: defaults to false. If true and if the previous websocket connection to the server succeeded, the connection attempt will bypass the normal upgrade process and will initially try websocket. A connection attempt following a transport error will use the normal upgrade process. It is recommended you turn this on only when using SSL/\+TLS connections, or if you know that your network does not block websockets.
\item {\ttfamily pfx} ({\ttfamily String}$\vert${\ttfamily Buffer})\+: Certificate, Private key and CA certificates to use for SSL. Can be used in Node.\+js client environment to manually specify certificate information.
\item {\ttfamily key} ({\ttfamily String})\+: Private key to use for SSL. Can be used in Node.\+js client environment to manually specify certificate information.
\item {\ttfamily passphrase} ({\ttfamily String})\+: A string of passphrase for the private key or pfx. Can be used in Node.\+js client environment to manually specify certificate information.
\item {\ttfamily cert} ({\ttfamily String})\+: Public x509 certificate to use. Can be used in Node.\+js client environment to manually specify certificate information.
\item {\ttfamily ca} ({\ttfamily String}$\vert${\ttfamily Array})\+: An authority certificate or array of authority certificates to check the remote host against.. Can be used in Node.\+js client environment to manually specify certificate information.
\item {\ttfamily ciphers} ({\ttfamily String})\+: A string describing the ciphers to use or exclude. Consult the \href{http://www.openssl.org/docs/apps/ciphers.html\#CIPHER_LIST_FORMAT}{\texttt{ cipher format list}} for details on the format. Can be used in Node.\+js client environment to manually specify certificate information.
\item {\ttfamily reject\+Unauthorized} ({\ttfamily Boolean})\+: If true, the server certificate is verified against the list of supplied CAs. An \textquotesingle{}error\textquotesingle{} event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent. Can be used in Node.\+js client environment to manually specify certificate information.
\item {\ttfamily per\+Message\+Deflate} ({\ttfamily Object$\vert$\+Boolean})\+: parameters of the Web\+Socket permessage-\/deflate extension (see \href{https://github.com/einaros/ws}{\texttt{ ws module}} api docs). Set to {\ttfamily false} to disable. ({\ttfamily true})
\begin{DoxyItemize}
\item {\ttfamily threshold} ({\ttfamily Number})\+: data is compressed only if the byte size is above this value. This option is ignored on the browser. ({\ttfamily 1024})
\end{DoxyItemize}
\item {\ttfamily extra\+Headers} ({\ttfamily Object})\+: Headers that will be passed for each request to the server (via xhr-\/polling and via websockets). These values then can be used during handshake or for special proxies. Can only be used in Node.\+js client environment.
\item {\ttfamily only\+Binary\+Upgrades} ({\ttfamily Boolean})\+: whether transport upgrades should be restricted to transports supporting binary data ({\ttfamily false})
\item {\ttfamily force\+Node} ({\ttfamily Boolean})\+: Uses Node\+JS implementation for websockets -\/ even if there is a native Browser-\/\+Websocket available, which is preferred by default over the Node\+JS implementation. (This is useful when using hybrid platforms like nw.\+js or electron) ({\ttfamily false}, Node\+JS only)
\item {\ttfamily local\+Address} ({\ttfamily String})\+: the local IP address to connect to
\end{DoxyItemize}
\item {\bfseries{Polling-\/only options}}
\begin{DoxyItemize}
\item {\ttfamily request\+Timeout} ({\ttfamily Number})\+: Timeout for xhr-\/polling requests in milliseconds ({\ttfamily 0})
\end{DoxyItemize}
\item {\bfseries{Websocket-\/only options}}
\begin{DoxyItemize}
\item {\ttfamily protocols} ({\ttfamily Array})\+: a list of subprotocols (see \href{https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers\#Subprotocols}{\texttt{ MDN reference}})
\end{DoxyItemize}
\end{DoxyItemize}
\item {\ttfamily send}
\begin{DoxyItemize}
\item Sends a message to the server
\item {\bfseries{Parameters}}
\begin{DoxyItemize}
\item {\ttfamily String} $\vert$ {\ttfamily Array\+Buffer} $\vert$ {\ttfamily Array\+Buffer\+View} $\vert$ {\ttfamily Blob}\+: data to send
\item {\ttfamily Object}\+: optional, options object
\item {\ttfamily Function}\+: optional, callback upon {\ttfamily drain}
\end{DoxyItemize}
\item {\bfseries{Options}}
\begin{DoxyItemize}
\item {\ttfamily compress} ({\ttfamily Boolean})\+: whether to compress sending data. This option is ignored and forced to be {\ttfamily true} on the browser. ({\ttfamily true})
\end{DoxyItemize}
\end{DoxyItemize}
\item {\ttfamily close}
\begin{DoxyItemize}
\item Disconnects the client.
\end{DoxyItemize}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8705}{}\doxysubsection{Transport}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8705}
The transport class. Private. {\itshape Inherits from Event\+Emitter}.\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8706}{}\doxysubsubsection{Events}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8706}

\begin{DoxyItemize}
\item {\ttfamily poll}\+: emitted by polling transports upon starting a new request
\item {\ttfamily poll\+Complete}\+: emitted by polling transports upon completing a request
\item {\ttfamily drain}\+: emitted by polling transports upon a buffer drain
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8707}{}\doxysection{Tests}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8707}
{\ttfamily engine.\+io-\/client} is used to test \href{http://github.com/socketio/engine.io}{\texttt{ engine}}. Running the {\ttfamily engine.\+io} test suite ensures the client works and vice-\/versa.

Browser tests are run using \href{https://github.com/defunctzombie/zuul}{\texttt{ zuul}}. You can run the tests locally using the following command.


\begin{DoxyCode}{0}
\DoxyCodeLine{./node\_modules/.bin/zuul -\/-\/local 8080 -\/-\/ test/index.js }

\end{DoxyCode}


Additionally, {\ttfamily engine.\+io-\/client} has a standalone test suite you can run with {\ttfamily make test} which will run node.\+js and browser tests. You must have zuul setup with a saucelabs account.\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8708}{}\doxysection{Support}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8708}
The support channels for {\ttfamily engine.\+io-\/client} are the same as {\ttfamily socket.\+io}\+:
\begin{DoxyItemize}
\item \href{irc.freenode.net}{\texttt{ irc.\+freenode.\+net}} $\ast$$\ast$\#socket.\+io$\ast$$\ast$
\item \href{http://groups.google.com/group/socket_io}{\texttt{ Google Groups}}
\item \href{http://socket.io}{\texttt{ Website}}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8709}{}\doxysection{Development}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8709}
To contribute patches, run tests or benchmarks, make sure to clone the repository\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git clone git://github.com/socketio/engine.io-\/client.git }

\end{DoxyCode}


Then\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{cd engine.io-\/client}
\DoxyCodeLine{npm install }

\end{DoxyCode}


See the {\ttfamily Tests} section above for how to run tests before submitting any patches.\hypertarget{md_sfcode_node_modules_engine_io_client_README_autotoc_md8710}{}\doxysection{License}\label{md_sfcode_node_modules_engine_io_client_README_autotoc_md8710}
MIT -\/ Copyright (c) 2014 Automattic, Inc. 