LanguageClient

A LanguageClient is an interface for adding a language server compatible with the Language Server Protocol specification. Creating an instance of a LanguageClient object sets up configuration for the server, at which point communication with the server is handed-off to the application.

The LanguageClient class is not subclassable.

Class Methods

constructor(identifier, name, serverOptions, clientOptions)

Creates a LanguageClient object for communication with a language server.

The identifier parameter should be a simple, unique string that can be used to identify the server (such as "typescript"). It will not be displayed to the user.

The name parameter is the name of the server that can potentially be shown to the user, to indicate that the server has been enabled and is in use.

The serverOptions object defines configuration settings for launching and communicating with the server executable:

Value Description Note
type The type of transport to use (“stdio”, “socket”, “pipe”) Defaults to “stdio” if not value is specified
path The path to the server executable Absolute, or relative to the extension’s bundle)
args Additional arguments to pass (array)
env Additional environment variables to set (object)

The clientOptions object defines configuration settings for how the editor invokes the language client:

Value Description
syntaxes An array of syntax names for which the client is valid
var serverOptions = {
    path: path
};
var clientOptions = {
    syntaxes: ['typescript']
};
var client = new LanguageClient('typescript', 'TypeScript Language Server', serverOptions, clientOptions);

client.start();

Supported Language Server Transport Types

The LanguageClient interface and extension APIs support three methods of standard communication with language server subprocesses:

Standard I/O

When the stdio transport type is specified, the subprocess receives no additional launch arguments.

Sockets

When the socket transport type is specified, the subprocess will receive a launch argument --socket whose value is a port on which the client will attempt to connect on the TCP/IP nameserver. The server is responsible for opening a communication channel to listen for connections on this port.

Unix Domain Sockets (Pipe)

When the pipe transport type is specified, the subprocess will receive a launch argument --pipe whose value is a filename on disk on which the client will attempt to open a domain socket channel. The server is responsible for opening a communication channel and listening for messages from the client.

Properties

identifier

The identifier of the language client specified when it was created.

This property is readonly.

name

The visible name of the language client specified when it was created.

This property is readonly.

running

A boolean indicating whether the client’s language server is currently running.

This property is readonly.

Methods

onNotification(method, callback)

Registers a notification handler with the language client. If the language service sends a notification with the provided method name to the host it will be forwarded to the provided callback. The callback will receive the parameters objects as an argument.

If another handler was previously registered for the provided method name it will be replaced.

Note: This should only be used for methods that are not part of the core Language Server Protocol specification. Attempting to register handlers for core methods will not invoke the provided callback.

onRequest(method, callback)

Registers a request handler with the language client. If the language service sends a request with the provided method name to the host it will be forwarded to the provided callback. The callback will receive the parameters objects as an argument, and the return value will be returned to the language service as the response. If the return value is a Promise, it will be returned once the promise resolves or rejects.

If another handler was previously registered for the provided method name it will be replaced.

Note: This should only be used for methods that are not part of the core Language Server Protocol specification. Attempting to register handlers for core methods will not invoke the provided callback.

sendRequest(method, [params])

Sends a request with the provided method name to the language service, and returns a Promise object that resolves when the reply or an error is received by the host. The resolved value will be the parameters returned in the response.

sendNotification(method, [params])

Sends a notification with the provided method name to the language service.

start()

Starts the language server. If the server’s process could not be launched because an executable was not found at the specified path or module, this method will raise an Error. Likewise, if the process has already been launched, this method will also raise an Error.

stop()

Stops the language server. If the server was not running, this method does nothing. After this method has been invoked, it is not valid to attempt to call .start() again. Doing so will raise an Error.