# SDK: Host > @pithyx/sdk/host: die Seite des Desktops im Protokoll, die ein App-Fenster bedient. Source: https://pithyx.org/de/docs/reference/sdk/host/ Markdown: https://pithyx.org/de/docs/reference/sdk/host.md `@pithyx/sdk/host` ist die Seite des Desktops im Protokoll: Es bedient ein App-Fenster über ein Transportende, prüft die Parameter jedes Aufrufs und die Berechtigungen der App und sendet Ereignisse und Fragen. Apps nutzen es nicht; `pithyx dev` und der Desktop schon. Beim Build aus den TSDoc-Kommentaren von @pithyx/sdk 1.0.0-rc.9 erzeugt; der Text unter den Überschriften ist der Kommentar im Quelltext und bleibt Englisch. ## Schnittstellen ### ServeOptions What [serveApp](#serveapp) serves an app window with. #### Eigenschaften ##### context ```ts context: Omit; ``` The init context; `capabilities` is filled in from the handlers. ##### methods ```ts methods: MethodHandlers; ``` The handlers of the protocol methods this host serves. ##### extensions? ```ts optional extensions?: HostExtensions; ``` Host-only methods for the host's own apps; see [HostExtensions](#hostextensions). ##### onReady? ```ts optional onReady?: (hello) => void; ``` Called when the app completed the handshake. ###### Parameter | Parameter | Typ | Beschreibung | | ---------------- | -------------------------------------------- | --------------------------------------- | | `hello` | \{ `protocol`: `number`; `sdk`: `string`; \} | - | | `hello.protocol` | `number` | The protocol version the app speaks. | | `hello.sdk` | `string` | The SDK version the app was built with. | ###### Rückgabewert `void` --- ### AppConnection The host's side of one app window's connection. #### Methoden ##### emit() ```ts emit(event, data): void; ``` Sends an event; an event that needs a permission the app does not hold (`sharesChanged`) is dropped. `permissionsChange` also updates the permissions the host checks. ###### Typenparameter | Typenparameter | | ----------------------------------------------------------------------------- | | `E` _extends_ keyof [`Events`](https://pithyx.org/de/docs/reference/sdk/events-context/#events) | ###### Parameter | Parameter | Typ | Beschreibung | | --------- | ---------------------------------------------------------------- | ----------------- | | `event` | `E` | The event name. | | `data` | [`Events`](https://pithyx.org/de/docs/reference/sdk/events-context/#events)\[`E`\] | The event's data. | ###### Rückgabewert `void` ##### ask() ```ts ask( query, data, timeout ): Promise; ``` Asks the app and waits; resolves undefined when it does not answer in time. ###### Typenparameter | Typenparameter | | ------------------------------------------------------------------------------- | | `Q` _extends_ keyof [`Queries`](https://pithyx.org/de/docs/reference/sdk/events-context/#queries) | ###### Parameter | Parameter | Typ | Beschreibung | | --------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- | | `query` | `Q` | The question. | | `data` | [`Queries`](https://pithyx.org/de/docs/reference/sdk/events-context/#queries)\[`Q`\]\[`"data"`\] | What the question carries. | | `timeout` | `number` | How long to wait in milliseconds, for example `BEFORE_CLOSE_TIMEOUT`. | ###### Rückgabewert `Promise`\<[`Queries`](https://pithyx.org/de/docs/reference/sdk/events-context/#queries)\[`Q`\]\[`"answer"`\] \| `undefined`\> The app's answer, or undefined after the timeout or when the connection closed. ##### close() ```ts close(): void; ``` Ends the connection; questions still waiting resolve undefined. ###### Rückgabewert `void` ## Typenaliasse ### MethodHandlers ```ts type MethodHandlers = { [M in MethodName]?: ( params: Methods[M]['params'], ) => Methods[M]['result'] | Promise; }; ``` The host's handler per protocol method; a method without a handler is not in `capabilities`. A handler gets the checked parameters and returns the result or throws a [PithyxError](https://pithyx.org/de/docs/reference/sdk/errors/#pithyxerror), which goes back to the app as a problem. --- ### HostExtensions ```ts type HostExtensions = Record< string, { validate: boolean; handle: unknown; } >; ``` Methods outside the public protocol that a host serves to its own apps, each with its own parameter check. They are not versioned, not listed in `capabilities`, and a host never gives them to a third-party app. ## Funktionen ### keepsBrowserMenu() ```ts function keepsBrowserMenu(target): boolean; ``` Text fields keep the browser's menu, so paste and spelling suggestions still work there. #### Parameter | Parameter | Typ | Beschreibung | | --------- | ----------------------- | ------------------------------------ | | `target` | `EventTarget` \| `null` | The target of a `contextmenu` event. | #### Rückgabewert `boolean` Whether the target is inside an input, a text area, a select or an editable element. --- ### sdkError() ```ts function sdkError(code, params?, detail?): PithyxError; ``` A [PithyxError](https://pithyx.org/de/docs/reference/sdk/errors/#pithyxerror) with one of the SDK's own transport codes. #### Parameter | Parameter | Typ | Beschreibung | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | `code` | \| `"sdk.method.unknown"` \| `"sdk.request.invalid"` \| `"sdk.request.timeout"` \| `"sdk.transport.closed"` \| `"sdk.protocol.unsupported"` \| `"sdk.transfer.cancelled"` \| `"sdk.backend.endpoint_unknown"` \| `"sdk.backend.unreachable"` | One of [sdkErrorCodes](https://pithyx.org/de/docs/reference/sdk/errors/#sdkerrorcodes). | | `params` | `Record`\<`string`, `unknown`\> | Values for the translated message. | | `detail?` | `string` | English fallback text. | #### Rückgabewert [`PithyxError`](https://pithyx.org/de/docs/reference/sdk/errors/#pithyxerror) The error, to throw or to reject with. --- ### serveApp() ```ts function serveApp(endpoint, options): AppConnection; ``` Serves one app window over a transport end. Answers `hello` with `init` (or `refuse` with [`sdk.protocol.unsupported`](https://pithyx.org/de/docs/reference/errors/#sdk.protocol.unsupported)), then checks each request's parameters ([`sdk.request.invalid`](https://pithyx.org/de/docs/reference/errors/#sdk.request.invalid)), the permissions the host itself checks ([`app.permission.denied`](https://pithyx.org/de/docs/reference/errors/#app.permission.denied)) and whether a handler exists ([`sdk.method.unknown`](https://pithyx.org/de/docs/reference/errors/#sdk.method.unknown)) before the handler runs. #### Parameter | Parameter | Typ | Beschreibung | | ---------- | -------------------------------------------------- | ------------------------------------------------------- | | `endpoint` | [`Endpoint`](https://pithyx.org/de/docs/reference/sdk/app/#endpoint) | The host's end of the transport. | | `options` | [`ServeOptions`](#serveoptions) | The context, the handlers and the host-only extensions. | #### Rückgabewert [`AppConnection`](#appconnection) The connection, to send events and questions and to close it. ## Referenzen ### PithyxError Re-Exports [PithyxError](https://pithyx.org/de/docs/reference/sdk/errors/#pithyxerror)