/******************************************************************************** * Copyright (c) 2021-2024 EclipseSource and others. * * This program and the accompanying materials are made available under the * terms of the Eclipse Public License v. 2.0 which is available at * http://www.eclipse.org/legal/epl-2.0. * * This Source Code may also be made available under the following Secondary * Licenses when the conditions for such availability set forth in the Eclipse * Public License v. 2.0 are satisfied: GNU General Public License, version 2 * with the GNU Classpath Exception which is available at * https://www.gnu.org/software/classpath/license.html. * * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 ********************************************************************************/ import { GLSPClient, InitializeResult } from '@eclipse-glsp/protocol'; import * as vscode from 'vscode'; import { WebviewEndpoint } from '.'; /** * Any clients registered on the GLSP VSCode integration need to implement this * interface. */ export interface GlspVscodeClient { /** * A unique identifier for the client/panel with which the client will be registered * on the server. */ readonly clientId: string; /** * Unique identifier of the diagram type that this client can handle. */ readonly diagramType: string; /** * The {@link WebviewEndpoint} belonging to the client. */ readonly webviewEndpoint: WebviewEndpoint; /** * The document object belonging to the client; */ readonly document: D; } /** * The server or server wrapper used by the VSCode integration needs to implement * this interface. */ export interface GlspVscodeServer { /** * An event emitter used by the VSCode extension to send messages to the server. * * You should subscribe to the event attached to this emitter to receive messages * from the client/VSCode integration and pass them to the server. * * Use the properties `onBeforeReceiveMessageFromClient` and `onBeforePropagateMessageToServer` * of the GlspVscodeConnector in order to control what messages are propagated * and processed. */ readonly onSendToServerEmitter: vscode.EventEmitter; /** * An event the VSCode integration uses to receive messages from the server. * The messages are then propagated to the client or processed by the VSCode * integration to provide functionality. * * Fire this event with the message the server wants to send to the client. * * Use the properties `onBeforeReceiveMessageFromServer` and `onBeforePropagateMessageToClient` * of the GlspVscodeConnector in order to control what messages are propagated * and processed. */ readonly onServerMessage: vscode.Event; /** * The {@link GLSPClient} instance that is used by this server wrapper to communicate with the * GLSP server process. */ readonly glspClient: Promise; /** * The result of the {@link GLSPClient.initializeServer} call. Implementing classes are expected * to call this method during the their initialization phase. */ readonly initializeResult: Promise; /** * A promise that resolves once the `GLSPVscodeServer` is ready i.e. has been started. */ readonly onReady: Promise; /** * Starts up the GLSP client and connects it to a GLSP server. */ start(): Promise; } interface InterceptorCallback { /** * This callback controls what message should be propagated to the VSCode integration * and whether the VSCode integration should process it (ie. provide functionality * based on the message). * * @param newMessage The message to be propagated. This value can be anything, * however if it is `undefined` the message will not be propagated further. * @param shouldBeProcessedByConnector Optional parameter indicating whether the * VSCode integration should process the message. That usually means providing * functionality based on the message but also modifying it or blocking it from * being propagated further. */ (newMessage: unknown | undefined, shouldBeProcessedByConnector?: boolean): void; } export interface GlspVscodeConnectorOptions { /** * The GLSP server (or its wrapper) that the VSCode integration should use. */ server: GlspVscodeServer; /** * Wether the GLSP-VSCode integration should log various events. This is useful * if you want to find out what events the VSCode integration is receiving from * and sending to the server and clients. * * Defaults to `false`. */ logging?: boolean; /** * Optional property to intercept (and/or modify) messages sent from the client * to the VSCode integration via `GlspVscodeClient.onClientSend`. * * @param message Contains the original message sent by the client. * @param callback A callback to control how messages are handled further. */ onBeforeReceiveMessageFromClient?: (message: unknown, callback: InterceptorCallback) => void; /** * Optional property to intercept (and/or modify) messages sent from the server * to the VSCode integration via `GlspVscodeServer.onServerSend`. * * @param message Contains the original message sent by the client. * @param callback A callback to control how messages are handled further. */ onBeforeReceiveMessageFromServer?(message: unknown, callback: InterceptorCallback): void; /** * Optional property to intercept (and/or modify) messages sent from the VSCode * integration to the server via the `GlspVscodeServer.onServerReceiveEmitter`. * * The returned value from this function is the message that will be propagated * to the server. It can be modified to anything. Returning `undefined` will * cancel the propagation. * * @param originalMessage The original message received by the VSCode integration * from the client. * @param processedMessage If the VSCode integration modified the received message * in any way, this parameter will contain the modified message. If the VSCode * integration did not modify the message, this parameter will be identical to * `originalMessage`. * @param messageChanged This parameter will indicate wether the VSCode integration * modified the incoming message. In other words: Whether `originalMessage` * and `processedMessage` are different. * @returns A message that will be propagated to the server. If the message * is `undefined` the propagation will be cancelled. */ onBeforePropagateMessageToServer?(originalMessage: unknown, processedMessage: unknown, messageChanged: boolean): unknown | undefined; /** * Optional property to intercept (and/or modify) messages sent from the VSCode * integration to a client via the `GlspVscodeClient.onClientReceiveEmitter`. * * The returned value from this function is the message that will be propagated * to the client. It can be modified to anything. Returning `undefined` will * cancel the propagation. * * @param originalMessage The original message received by the VSCode integration * from the server. * @param processedMessage If the VSCode integration modified the received message * in any way, this parameter will contain the modified message. If the VSCode * integration did not modify the message, this parameter will be identical to * `originalMessage`. * @param messageChanged This parameter will indicate wether the VSCode integration * modified the incoming message. In other words: Whether `originalMessage` * and `processedMessage` are different. * @returns A message that will be propagated to the client. If the message * is `undefined` the propagation will be cancelled. */ onBeforePropagateMessageToClient?(originalMessage: unknown, processedMessage: unknown, messageChanged: boolean): unknown | undefined; } export declare const GLSPDiagramIdentifier: unique symbol; export interface GLSPDiagramIdentifier { clientId: string; diagramType: string; uri: string; } export declare function isDiagramIdentifier(object: any): object is GLSPDiagramIdentifier; export interface WebviewReadyMessage { readyMessage: string; } export declare namespace WebviewReadyMessage { function is(object: unknown): object is WebviewReadyMessage; } export {}; //# sourceMappingURL=types.d.ts.map