cloudpilot-emu-embedded/dist/cloudpilot-emu.d.ts

Embedded version of the CloudpilotEmu PalmOS emulator

// Generated by dts-bundle-generator v9.5.1

/**
 * This enumerates all supported devices.
 */
export declare enum DeviceId {
	palmPilot = "PalmPilot",
	pilot = "Pilot",
	iii = "PalmIII",
	palmVx = "PalmVx",
	palmV = "PalmV",
	palmVII = "PalmVII",
	palmVIIEZ = "PalmVIIEZ",
	palmVIIx = "PalmVIIx",
	iiic = "PalmIIIc",
	iiix = "PalmIIIx",
	iiixe = "PalmIIIxe",
	iiie = "PalmIIIe",
	m500 = "PalmM500",
	m505 = "PalmM505",
	m515 = "PalmM515",
	m520 = "PalmM520",
	m100 = "PalmM100",
	m105 = "PalmM105",
	m125 = "PalmM125",
	m130 = "PalmM130",
	i705 = "Palmi705",
	i710 = "PalmI710",
	handera330 = "HandEra330",
	handera330c = "HandEra330c",
	pegS300 = "PEG-S300",
	pegS320 = "PEG-S320",
	pegS500c = "PEG-S500C",
	pegT400 = "PEG-T400",
	pegN600c = "PEG-N600C/N610C",
	pegT600c = "PEG-T600",
	pegN700c = "PEG-N700C/N710C",
	pegT650c = "YSX1230",
	pegNR70 = "NR70",
	acerS11 = "Acer-S11",
	lp168 = "Legend-P168",
	te2 = "Tungsten-E2",
	frankene2 = "Franken-E2"
}
/**
 * The four different orientation settings.
 */
export declare enum DeviceOrientation {
	portrait = "portrait",
	landscape90 = "landscape90",
	landscape270 = "landscape270",
	portrait180 = "portrait180"
}
/**
 * Runtime statistics for Cloudpilot.
 */
export interface EmulationStatisticsCloudpilot {
	type: "cloudpilot";
	/**
	 * The ratio between the duration of an emulated timeslice and the time that
	 * is required by the host to emulate it. If this drops below one the host
	 * cannot keep up with the emulation, and CloudpilotEmu automatically reduces
	 * emulation speed.
	 */
	hostSpeed: number;
	/**
	 * The relative speed of the emulated device. One means full speed, lower
	 * values indicate that CloudpilotEmu reduced speed in order to compensate for
	 * a slow host.
	 */
	emulationSpeed: number;
	/**
	 * The average number of frames per second. Note that only frames are only
	 * rendered if the screen content actually changed.
	 */
	averageFps: number;
}
/**
 * Runtime statistics for uARM.
 */
export interface EmulationStatisticsUarm {
	type: "uarm";
	/**
	 * Current emulation speed in MIPS (million instructions per second).
	 */
	currentSpeedMips: number;
	/**
	 * Current maximum emulation speed without throttling in MIPS (million
	 * instructions per second).
	 */
	currentMaxSpeedMips: number;
}
/**
 * This set of performance statistics can be queried at runtime from the emulator.
 */
export type EmulationStatistics = EmulationStatisticsCloudpilot | EmulationStatisticsUarm;
/**
 * DOM event handler callback.
 */
export type EventHandler<K extends keyof HTMLElementEventMap> = (ev: HTMLElementEventMap[K]) => void;
/**
 * A DOM event target.
 */
interface EmulatorEventTarget {
	addEventListener<K extends keyof HTMLElementEventMap>(type: K, handler: EventHandler<K>, options?: boolean | AddEventListenerOptions): void;
	removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: EventHandler<K>, options?: boolean | EventListenerOptions): void;
}
/**
 * A CloudpilotEmu event.
 */
interface CloudpilotEvent<Payload> {
	/**
	 * Bind an handler callback to the event.
	 *
	 * CAUTION: a handler that is bound multiple times will be called multiple times, too!
	 *
	 * @param handler Handler callback.
	 * @param context Optional context that is passed to the callback.
	 */
	addHandler<Context>(handler: Handler<Payload, Context>, context?: Context): CloudpilotEvent<Payload>;
	/**
	 * Remove a previously bound handler. Both callback and context must be identical for
	 * the handler to be removed.
	 *
	 * CAUTION: this method will only remove one callback each call, even if a handler / callback
	 * combo is bound multiple times.
	 *
	 * @param handler Handler callback.
	 * @param context Optional callback context.
	 */
	removeHandler<Context>(handler: Handler<Payload, Context>, context?: Context): CloudpilotEvent<Payload>;
}
/**
 * Handler callback type.
 */
export type Handler<Payload, Context> = (payload: Payload, context: Context) => void;
/**
 * Emitted by the emulator.
 */
export interface ReceivePayload {
	/**
	 * Serial data sent by PalmOS. This can be `undefined` in order to
	 * communicate a frame boundary or the absence of a frame response
	 * in 'sync' mode.
	 */
	data: Uint8Array | undefined;
	/**
	 * Marks a transmission frame as complete. This is always `true` in
	 * 'simple' mode.
	 */
	isFrameComplete: boolean;
}
export interface SerialPort {
	/**
	 * Send serial data to the emulator.
	 *
	 * @param data Serial data to transmit (or undefined in order to communicate
	 * a frame boundary or response timeout in 'sync' mode).
	 *
	 * @param isFrameComplete Marks a transmission frame as complete. Should always
	 * be `true` in 'simple' mode.
	 */
	send(data: Uint8Array | undefined, isFrameComplete: boolean): void;
	/**
	 * Switch between 'simple' and 'sync' mode. Sync mode consumes more CPU and should
	 * only be used to connect two emulator instances via IrDA.
	 *
	 * @param modeSync Set `true` for 'sync' mode.
	 */
	setModeSync(modeSync: boolean): void;
	/**
	 * Query mode.
	 */
	getModeSync(): boolean;
	/**
	 * This is fired by the emulator for data or synchronization events. In 'sync' mode,
	 * **every** such event needs to be sent to the remote instance.
	 */
	receiveEvent: CloudpilotEvent<ReceivePayload>;
}
/**
 * The main emulator interface. Most methods that interact with the emulator are async and
 * should be awaited.
 */
export interface Emulator {
	/**
	 * Load a ROM and put the emulator in paused state.
	 *
	 * @param rom Device ROM
	 * @param nand Device NAND. OS5 devices only.
	 * @param deviceId Optional: device ID, autodetected if not specified
	 */
	loadRom(rom: Uint8Array, nand?: Uint8Array, deviceId?: DeviceId): Promise<void>;
	/**
	 * Load a Cloudpilot session and put the emulator in paused state.
	 *
	 * @param session Session image
	 */
	loadSession(session: Uint8Array): Promise<void>;
	/**
	 * Attach and mount a gzip compressed card image.
	 *
	 * @param cardImage Gzip compressed image data
	 */
	insertCompressedCardImage(cardImage: Uint8Array): Promise<void>;
	/**
	 * Attach and mount a plain card image.
	 *
	 * @param cardImage Image data
	 */
	insertCardImage(cardImage: Uint8Array): Promise<void>;
	/**
	 * Eject a previously inserted card image:
	 */
	ejectCard(): Promise<void>;
	/**
	 * Check whether a card is currently mounted.
	 */
	isCardMounted(): Promise<boolean>;
	/**
	 * Configure the canvas element used for displaying the emulator.
	 *
	 * @param canvas Canvas for displaying the emulator
	 */
	setCanvas(canvas: HTMLCanvasElement): void;
	/**
	 * Release the canvas element.
	 */
	releaseCanvas(): void;
	/**
	 * Receive input events from the specified sources. If this method is called
	 * multiple times the previous sources will be unbound.
	 *
	 * @param keyboardTarget Optional: target for keyboard events, default: `window`
	 */
	bindInput(keyboardTarget?: EmulatorEventTarget): void;
	/**
	 * Unbind the handlers previous bound with `bindInput`.
	 */
	releaseInput(): void;
	/**
	 * Install a prc or pdb database to the device.
	 *
	 * @param file The database data.
	 */
	installDatabase(file: Uint8Array): Promise<void>;
	/**
	 * Install a prc database to the device and attempt to launch it.
	 *
	 * @param file The database data.
	 */
	installAndLaunchDatabase(file: Uint8Array): Promise<void>;
	/**
	 * Extract all databases from a zip archive and install them.
	 *
	 * @param file The zip archive data.
	 */
	installFromZipfile(file: Uint8Array): Promise<void>;
	/**
	 * Extract all databases from a zip archive and install them, then attempt to
	 * launch the specified file.
	 *
	 * @param file The zip archive data.
	 * @param launchFile The file name of the database that Cloudpilot will try to launch.
	 */
	installFromZipfileAndLaunch(file: Uint8Array, launchFile: string): Promise<void>;
	/**
	 * Attempt to launch the database with the specified name.
	 *
	 * @param name Database name
	 */
	launchByName(name: string): Promise<void>;
	/**
	 * Attempt to extract the name from a database and launch it.
	 *
	 * @param database Database data (only the first 32 bytes are required)
	 */
	launchDatabase(database: Uint8Array): Promise<void>;
	/**
	 * Perform a soft reset (equivalent of pushing the reset button).
	 */
	reset(): Promise<void>;
	/**
	 * Reset w/o system extensions (equivalent to holding "down" while pushing the
	 * reset button).
	 */
	resetNoExtensions(): Promise<void>;
	/**
	 * Hard reset (equivalent to holding "power" while pushing the
	 * reset button).
	 */
	resetHard(): Promise<void>;
	/**
	 * Is the emulator running?
	 */
	isRunning(): Promise<boolean>;
	/**
	 * Is the device powered off?
	 */
	isPowerOff(): Promise<boolean>;
	/**
	 * Has the emulated device passed UI initialization (during boot)? This
	 * is required before software can be installed.
	 */
	isUiInitialized(): Promise<boolean>;
	/**
	 * Resume a paused device.
	 */
	resume(): Promise<void>;
	/**
	 * Pause a running device.
	 */
	pause(): Promise<void>;
	/**
	 * Push a hardware button.
	 *
	 * @param button The desired button
	 */
	buttonDown(button: Button): void;
	/**
	 * Release a hardware button.
	 *
	 * @param button The desired button
	 */
	buttonUp(button: Button): void;
	/**
	 * Adjust speed of the emulated device.
	 *
	 * @param speed Speed factor
	 */
	setSpeed(speed: number): void;
	/**
	 * Query configured speed factor.
	 */
	getSpeed(): number;
	/**
	 * Set audio volume.
	 *
	 * @param volume Volume (1 = 100%, 0 = silent)
	 */
	setVolume(volume: number): void;
	/**
	 * Query audio volume
	 */
	getVolume(): number;
	/**
	 * Disable PCM audio on OS5. This will improve emulation speed (by freeing cycles
	 * that would be used to generate audio) but may lead to * compatibility issues with
	 * some apps.
	 *
	 * @param disablePcmAudio Disable / enable PCM audio
	 */
	setDisablePcmAudio(disablePcmAudio: boolean): void;
	/**
	 * Query whether PCM audio is disabled.
	 */
	getDisablePcmAudio(): boolean;
	/**
	 * Set the maximum host load. This applies to OS5 emulation only.
	 *
	 * @param maxHostLoad Maximum host load (1 = full core)
	 */
	setMaxHostLoad(maxHostLoad: number): void;
	/**
	 * Get the maximum host load.
	 */
	getMaxHostLoad(): number;
	/**
	 * Disable the full d-pad on devices that support it.
	 *
	 * @param disableDpad  Disable / enable d-pad
	 */
	setDisableDpad(disableDpad: boolean): void;
	/**
	 * Query whether the d-pad has been disabled.
	 */
	getDisableDpad(): boolean;
	/**
	 * Initialize audio. This must be called from an event handler that was triggered
	 * by a user interaction, i.e. a click or a key press.
	 */
	initializeAudio(): Promise<boolean>;
	/**
	 * Was audio initialized succesfully?
	 */
	isAudioInitialized(): boolean;
	/**
	 * Enable or disable game mode (direct key mapping to hardware buttons).
	 *
	 * @param gameModeActive Desired state
	 */
	setGameMode(gameModeActive: boolean): void;
	/**
	 * Is game mode enabled?
	 */
	isGameMode(): boolean;
	/**
	 * Enable or disable shift-ctrl for toggling game mode (enabled by default).
	 *
	 * @param enableGamemodeHotkey Desired state
	 */
	setGameModeHotkeyEnabled(enableGamemodeHotkey: boolean): void;
	/**
	 * Can game mode be toggled via shift-ctrl?
	 */
	isGameModeHotkeyEnabled(): boolean;
	/**
	 * Enable or disable game mode indicator (overlays hard buttons if game mode is active)? Enabled
	 * by default.
	 *
	 * @param gameModeIndicatorEnabled Desired state
	 */
	setGameModeIndicatorEnabled(gameModeIndicatorEnabled: boolean): void;
	/**
	 * Is game mode overlay enabled?
	 */
	isGameModeIndicatorEnabled(): boolean;
	/**
	 * Change device orientation.
	 *
	 * @param orientation Desired orientation
	 */
	setOrientation(orientation: DeviceOrientation): void;
	/**
	 * Query device orientation
	 */
	getOrientation(): DeviceOrientation;
	/**
	 * Set hotsync name.
	 *
	 * @param hotsyncName Desired hotsync name
	 */
	setHotsyncName(hotsyncName: string | undefined): Promise<void>;
	/**
	 * Get hotsync name.
	 */
	getHotsyncName(): Promise<string | undefined>;
	/**
	 * Keep running if the emulator tab is not visible?
	 *
	 * @param toggle Desired state
	 */
	setRunHidden(toggle: boolean): void;
	/**
	 * Keep running if the emulator tab is not visible?
	 */
	getRunHidden(): boolean;
	/**
	 * Get performance statistics
	 */
	getStatistics(): EmulationStatistics | undefined;
	/**
	 * Get serial transport for IR transceiver.
	 */
	getSerialPortIR(): SerialPort | undefined;
	/**
	 * Get serial transport for serial port.
	 */
	getSerialPortSerial(): SerialPort | undefined;
	/**
	 * Fires when the device turns on or off.
	 */
	readonly powerOffChangeEvent: CloudpilotEvent<boolean>;
	/**
	 * Fires when PalmOS resets or passed UI initialization during boot.
	 */
	readonly isUiInitializedChangeEvent: CloudpilotEvent<boolean>;
	/**
	 * Fires when audio is initializd successfully.
	 */
	readonly audioInitializedEvent: CloudpilotEvent<void>;
	/**
	 * Fires after each emulated timeslice (typically 60 times per second)
	 */
	readonly timesliceEvent: CloudpilotEvent<void>;
	/**
	 * Fires when the hotsync name changes. This does not happen immediatelly when
	 * `setHotsyncName` is called, but only when the OS is notified of the new name.
	 */
	readonly hotsyncNameChangeEvent: CloudpilotEvent<string>;
	/**
	 * Fires if game mode is enabled or disabled.
	 */
	readonly gameModeChangeEvent: CloudpilotEvent<boolean>;
}
/**
 * The various supported hard buttons.
 */
export declare enum Button {
	cal = 0,
	phone = 1,
	todo = 2,
	notes = 3,
	up = 4,
	down = 5,
	power = 6,
	cradle = 7
}
export declare const VERSION: string | undefined;
/**
 * Options for loading the emulator.
 */
export interface LoadOptions {
	/**
	 * URL for loading the cloudpilot WASM binary.
	 */
	cloudpilotModuleUrl?: string;
	/**
	 * URL for loading the uARM WASM binary (for OS5 emulation).
	 */
	uarmModuleUrl?: string;
	/**
	 * URL for loading the uARM worker (for OS5 emulator).
	 */
	uarmWorkerUrl?: string;
	/**
	 * URL for loading the PCM worklet (for OS5 PCM audio).
	 */
	pcmWorkletUrl?: string;
	/**
	 * By default, the uARM WASM binary is loaded on demand when an OS5 session is
	 * launched. This option causes the binary to be preloaded on initialization.
	 */
	preloadUarm?: boolean;
}
/**
 * Create a new instance of the emulator.
 *
 * @param options Optional: options for loading the emulator
 *
 * @returns Emulator instance
 */
export declare function createEmulator(options?: LoadOptions): Promise<Emulator>;
/**
 * Create a factory function that creates new Emulator instances without redownloading
 * and recompiling the WASM module.
 *
 * @param options Optional: options for loading the emulator
 * @returns
 */
export declare function createEmulatorFactory(options?: LoadOptions): () => Promise<Emulator>;

export {
	CloudpilotEvent as Event,
	EmulatorEventTarget as EventTarget,
};

export as namespace cloudpilot;

export {};