Module: webSocketClient

Construct an instance of a socket client that can send or receive messages to a server at the specified host and port. The returned object subclasses EventEmitter. You can register handlers for events 'open', 'message', 'close', or 'error'. The event 'open' will be emitted when the socket has been successfully opened. The event 'message' will be emitted with the body of the message as an argument when an incoming message arrives on the socket. You can invoke the send() function to send data to the server.

The type of data sent and received can be specified with the 'sendType' and 'receiveType' options. In principle, any MIME type can be specified, but the host may support only a subset of MIME types. The client and the server have to agree on the type, or the data will not get through correctly.

The default type for both sending and receiving is 'application/json'. The types supported by this implementation include at least:

• application/json: The this.send() function uses JSON.stringify() and sends the result with a UTF-8 encoding. An incoming byte stream will be parsed as JSON, and if the parsing fails, will be provided as a string interpretation of the byte stream.
• text/*: Any text type is sent as a string encoded in UTF-8.

• image/x: Where x is one of json, png, gif, and more (FIXME: which, exactly?). In this case, the data passed to this.send() is assumed to be an image, as encoded on the host, and the image will be encoded as a byte stream in the specified format before sending. A received byte stream will be decoded as an image, if possible. FIXME: What happens if decoding fails?

  The event 'close' will be emitted when the socket is closed, and 'error' if an an error occurs (with an error message as an argument). For example,

    var WebSocket = require('@accessors-modules/web-socket-client');
    var client = new WebSocket.Client({'host': 'localhost', 'port': 8080});
    client.send({'foo': 'bar'});
    client.on('message', function(message) {
        console.log('Received from web socket: ' + message);
    });
    client.open();
  

  The above code may send a message even before the socket is opened. This module implementation will queue that message to be sent later when the socket is opened.

  The options argument is a JSON object that can contain the following properties:

• host: The IP address or host name for the host. Defaults to 'localhost'.
• port: The port on which the host is listening. Defaults to 80.
• receiveType: The MIME type for incoming messages, which defaults to 'application/json'.
• sendType: The MIME type for outgoing messages, which defaults to 'application/json'.
• connectTimeout: The time to wait before giving up on a connection, in milliseconds (defaults to 1000).
• numberOfRetries: The number of times to retry connecting. Defaults to 10.
• timeBetweenRetries: The time between retries, in milliseconds. Defaults to 500.
• discardMessagesBeforeOpen: If true, discard messages before the socket is open. Defaults to false.
• throttleFactor: The number milliseconds to stall for each item that is queued waiting to be sent. Defaults to 0.

Return an array of the types supported by the current host for receiveType arguments.

Return an array of the types supported by the current host for sendType arguments.