Websocket-Extension/websocket/api/api.script_api

- name: websocket
  type: table
  desc: Functions and constants for using websockets. Supported on all platforms.
  members:

#*****************************************************************************************************

  - name: connect
    type: function
    desc: Connects to a remote address
    parameters:
      - name: url
        type: string
        desc: url of the remote connection

      - name: params
        type: table
        desc: optional parameters as properties. The following parameters can be set
        members:
          - name: timeout
            type: number
            desc: Timeout for the connection sequence (milliseconds). Not used on HTML5. (Default is 3000)

          - name: protocol
            type: string
            desc: the protocol to use (e.g. 'chat'). If not set, no `Sec-WebSocket-Protocol` header is sent.

          - name: headers
            type: string
            desc: list of http headers. Each pair is separated with "\r\n". Not used on HTML5.

      - name: callback
        type: function
        desc: callback that receives all messages from the connection
        parameters:
        - name: self
          type: object
          desc: The script instance that was used to register the callback

        - name: connection
          type: object
          desc: the connection

        - name: data
          type: table
          desc: the event payload
          members:
          - name: event
            type: number
            desc: The current event. One of the following

               - `websocket.EVENT_CONNECTED`

               - `websocket.EVENT_DISCONNECTED`

               - `websocket.EVENT_ERROR`

               - `websocket.EVENT_MESSAGE`

          - name: message
            type: string
            desc: The received data if event is `websocket.EVENT_MESSAGE`. Error message otherwise

          - name: handshake_response
            type: table
            desc: Handshake response information (status, headers etc)

          - name: code
            type: number
            desc: Status code received from the server if the server closed the connection. Only present if event is `EVENT_DISCONNECTED`.


    returns:
      - name: connection
        type: object
        desc: the connection

    examples:
      - desc: |-
            ```lua
              local function websocket_callback(self, conn, data)
                if data.event == websocket.EVENT_DISCONNECTED then
                  log("Disconnected: " .. tostring(conn))
                  self.connection = nil
                  update_gui(self)
                elseif data.event == websocket.EVENT_CONNECTED then
                  update_gui(self)
                  log("Connected: " .. tostring(conn))
                elseif data.event == websocket.EVENT_ERROR then
                  log("Error: '" .. data.message .. "'")
                elseif data.event == websocket.EVENT_MESSAGE then
                  log("Receiving: '" .. tostring(data.message) .. "'")
                end
              end

              function init(self)
                self.url = "ws://echo.websocket.events"
                local params = {
                  timeout = 3000,
                  headers = "Sec-WebSocket-Protocol: chat\r\nOrigin: mydomain.com\r\n"
                }
                self.connection = websocket.connect(self.url, params, websocket_callback)
              end

              function finalize(self)
                  if self.connection ~= nil then
                    websocket.disconnect(self.connection)
                  end
              end
            ```

#*****************************************************************************************************

  - name: disconnect
    type: function
    desc: Explicitly close a websocket
    parameters:
      - name: connection
        type: object
        desc: the websocket connection

#*****************************************************************************************************

  - name: send
    type: function
    desc: Send data on a websocket
    parameters:
      - name: connection
        type: object
        desc: the websocket connection
      - name: message
        type: string
        desc: the message to send
      - name: options
        type: table
        desc: options for this particular message. May be `nil`
        members:
        - name: type
          type: number
          desc: The data type of the message

             - `websocket.DATA_TYPE_BINARY` (default)

             - `websocket.DATA_TYPE_TEXT`

    examples:
      - desc: |-
            ```lua
              local function websocket_callback(self, conn, data)
                if data.event == websocket.EVENT_CONNECTED then
                  websocket.send(conn, "Hello from the other side")
                end
              end

              function init(self)
                self.url = "ws://echo.websocket.org"
                local params = {}
                self.connection = websocket.connect(self.url, params, websocket_callback)
              end
            ```

#*****************************************************************************************************

  - name: EVENT_CONNECTED
    type: number
    desc: The websocket was connected

  - name: EVENT_DISCONNECTED
    type: number
    desc: The websocket disconnected

  - name: EVENT_MESSAGE
    type: number
    desc: The websocket received data

  - name: EVENT_ERROR
    type: number
    desc: The websocket encountered an error