@itwin/core-frontend
Version:
iTwin.js frontend components
117 lines • 6.42 kB
TypeScript
/** @packageDocumentation
* @module NativeApp
*/
import { PickAsyncMethods } from "@itwin/core-bentley";
import { IpcAppFunctions, IpcListener, IpcSocketFrontend, RemoveFunction } from "@itwin/core-common";
import { _callIpcChannel } from "./common/internal/Symbols";
import { IModelAppOptions } from "./IModelApp";
/**
* Options for [[IpcApp.startup]]
* @public
*/
export interface IpcAppOptions {
iModelApp?: IModelAppOptions;
}
/**
* The frontend of apps with a dedicated backend that can use [Ipc]($docs/learning/IpcInterface.md).
* @public
*/
export declare class IpcApp {
private static _ipc;
private static _removeAppNotify;
/** Get the implementation of the [[IpcSocketFrontend]] interface. */
private static get ipc();
/** Determine whether Ipc is available for this frontend. This will only be true if [[startup]] has been called on this class. */
static get isValid(): boolean;
/**
* Establish a message handler function for the supplied channel over Ipc. The handler will be called when messages are sent for
* the channel via [[BackendIpc.send]].
* @param channel the name of the channel
* @param handler the message handler
* @returns A function to remove the handler
* @note Ipc is only supported if [[isValid]] is true.
*/
static addListener(channel: string, handler: IpcListener): RemoveFunction;
/**
* Remove a previously registered listener
* @param channel The name of the channel for the listener previously registered with [[addListener]]
* @param listener The function passed to [[addListener]]
*/
static removeListener(channel: string, listener: IpcListener): void;
/**
* Send a message to the backend via `channel` and expect a result asynchronously. The handler must be established on the backend via [[BackendIpc.handle]]
* @param channel The name of the channel for the method.
* @see Electron [ipcRenderer.invoke](https://www.electronjs.org/docs/api/ipc-renderer) documentation for details.
* Note that this interface may be implemented via Electron for desktop apps, or via
* [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for mobile or web-based
* Ipc connections. In either case, the Electron documentation provides the specifications for how it works.
* @note `args` are serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only
* primitive types and `ArrayBuffers` are allowed.
*/
static invoke(channel: string, ...args: any[]): Promise<any>;
/**
* Send a message over the socket.
* @param channel The name of the channel for the message.
* @param data The optional data of the message.
* @note `data` is serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only
* primitive types and `ArrayBuffers` are allowed.
*/
static send(channel: string, ...data: any[]): void;
/**
* Call a method on the backend through an Ipc channel.
* @param channelName the channel registered by the backend handler.
* @param methodName the name of a method implemented by the backend handler.
* @param args arguments to `methodName`
* @return a Promise with the return value from `methodName`
* @note If the backend implementation throws an exception, this method will throw an exception with its contents
* @internal Use [[makeIpcProxy]] for a type-safe interface.
*/
static [_callIpcChannel](channelName: string, methodName: string, ...args: any[]): Promise<any>;
/** @internal
* @deprecated in 4.8 - will not be removed until after 2026-06-13. Use [[makeIpcProxy]] for a type-safe interface.
*/
static callIpcChannel(channelName: string, methodName: string, ...args: any[]): Promise<any>;
/** Create a type safe Proxy object to make IPC calls to a registered backend interface.
* @param channelName the channel registered by the backend handler.
*/
static makeIpcProxy<K, C extends string = string>(channelName: C): PickAsyncMethods<K>;
/** Create a type safe Proxy object to call an IPC function on a of registered backend handler that accepts a "methodName" argument followed by optional arguments
* @param channelName the channel registered by the backend handler.
* @param functionName the function to call on the handler.
*/
static makeIpcFunctionProxy<K>(channelName: string, functionName: string): PickAsyncMethods<K>;
/** A Proxy to call one of the [IpcAppFunctions]($common) functions via IPC. */
static appFunctionIpc: PickAsyncMethods<IpcAppFunctions>;
/** start an IpcApp.
* @note this should not be called directly. It is called by NativeApp.startup */
static startup(ipc: IpcSocketFrontend, opts?: IpcAppOptions): Promise<void>;
/** @internal */
static shutdown(): Promise<void>;
}
/**
* Base class for all implementations of an Ipc notification response interface. This class is implemented on your frontend to supply
* methods to receive notifications from your backend.
*
* Create a subclass to implement your Ipc response interface. Your class should be declared like this:
* ```ts
* class MyNotificationHandler extends NotificationHandler implements MyNotifications
* ```
* to ensure all method names and signatures are correct. Your methods cannot have a return value.
*
* Then, call `MyNotificationHandler.register` at startup to connect your class to your channel.
* @public
* @extensions
*/
export declare abstract class NotificationHandler {
/** All subclasses must implement this method to specify their response channel name. */
abstract get channelName(): string;
registerImpl(): RemoveFunction;
/**
* Register this class as the handler for notifications on its channel. This static method creates a new instance
* that becomes the notification handler and is `this` when its methods are called.
* @returns A function that can be called to remove the handler.
* @note this method should only be called once per channel. If it is called multiple times, multiple handlers are established.
*/
static register(): RemoveFunction;
}
//# sourceMappingURL=IpcApp.d.ts.map