Interface WebSocket

The WebSocket module provides a simple interface to create local WebSocket servers, therefore enabling the plugin to communicate with other applications. It is only available on macOS 10.15 or later.

Currently, TLS (thus the wss:// protocol) is not supported. When connecting to the server, a client should use the ws:// protocol.

Example

ws.createServer({ port: 10010 });
ws.onStateUpdate((s, err) => {
  if (s == "failed") {
    console.log(err);
  }
})

ws.onNewConnection(conn => console.log("new connection"));
ws.onConnectionStateUpdate((conn, s) => console.log(conn + ": " + s));
ws.onMessage((conn, m) => {
  console.log(`Message from ${conn}: ${m.text()}`);
  ws.sendText(conn, "Received!");
)

ws.startServer();

Available In Entry

Main and Global

Hierarchy

  • WebSocket

Methods

createServer startServer onStateUpdate onNewConnection onConnectionStateUpdate onMessage sendText

Methods

createServer

  • Create a WebSocket server.

    Throws

    If the option is invalid, an error will be thrown.

    Parameters

    • options: Partial<{
          port: number;
      }>

      The options for the server.

    Returns void

startServer

  • Start the WebSocket server. Must be called after createServer(). You should setup state update handlers before calling this method, since some errors (e.g. port already in use) may occur after starting the server and will be reported through a state update.

    Throws

    If the server is not in the correct state, an error will be thrown.

    Returns void

onStateUpdate

  • Handle the server's state update. You should respond properly to the "failed" or "cancelled" state. The server will be removed if the state is "failed" or "cancelled", and you must call createServer() and startServer() again to create a new one.

    It is possible that you receive a "failed" state immediately after calling startServer(), which indicates that an error occurred when starting the server.

    Parameters

    • callback: ((state: "setup" | "ready" | "waiting" | "failed" | "cancelled", error?: {
          message: string;
          description: string;
      }) => void)

      The callback function.

        • (state: "setup" | "ready" | "waiting" | "failed" | "cancelled", error?: {
              message: string;
              description: string;
          }): void

        • Parameters

          • state: "setup" | "ready" | "waiting" | "failed" | "cancelled"

            The server's new state.

          • Optional error: {
                message: string;
                description: string;
            }

            The error if the state is failed or waiting.

            • message: string
            • description: string

          Returns void

    Returns void

onNewConnection

  • Handle a new connection to the server.

    Parameters

    • callback: ((conn: string, info: {
          path: string;
      }) => void)

      The callback function.

        • (conn: string, info: {
              path: string;
          }): void

        • Parameters

          • conn: string

            An unique ID for this connection.

          • info: {
                path: string;
            }

            The information of the client.

            • path: string

          Returns void

    Returns void

onConnectionStateUpdate

  • Handle a connection's state change. You should respond properly to the "failed" or "cancelled" state, e.g. remove the connection ID from your cached list.

    Parameters

    • callback: ((conn: string, state: "setup" | "ready" | "waiting" | "failed" | "cancelled" | "preparing", error?: {
          message: string;
          description: string;
      }) => void)

      The callback function.

        • (conn: string, state: "setup" | "ready" | "waiting" | "failed" | "cancelled" | "preparing", error?: {
              message: string;
              description: string;
          }): void

        • Parameters

          • conn: string

            The connection ID.

          • state: "setup" | "ready" | "waiting" | "failed" | "cancelled" | "preparing"

            The connection's new state.

          • Optional error: {
                message: string;
                description: string;
            }

            The error if the state is failed or waiting.

            • message: string
            • description: string

          Returns void

    Returns void

onMessage

  • Handle a message from a connection.

    Parameters

    • callback: ((conn: string, message: {
          data: (() => Uint8Array);
          text: (() => string);
      }) => void)
        • (conn: string, message: {
              data: (() => Uint8Array);
              text: (() => string);
          }): void

        • Parameters

          • conn: string

            The connection ID.

          • message: {
                data: (() => Uint8Array);
                text: (() => string);
            }

            The message content.

            • data: (() => Uint8Array)
                • (): Uint8Array

                • Returns Uint8Array

            • text: (() => string)
                • (): string

                • Returns string

          Returns void

    Returns void

sendText

  • Send a message to a connection. The message will be encoded as UTF-8 and sent as binary data.

    Returns

    "no_connection" if the connection does not exist, "success" if the message is sent successfully.

    Throws

    Any error occurred when sending the message.

    Parameters

    • conn: string

      The connection ID.

    • text: string

      The text to send.

    Returns Promise<"no_connection" | "success">

Settings

Member Visibility

Theme

Generated using TypeDoc