Skip to content

Latest commit

 

History

History
250 lines (176 loc) · 9.75 KB

README.md

File metadata and controls

250 lines (176 loc) · 9.75 KB

@devioarts/capacitor-mdns

mDNS plugin for Capacitor that supports Bonjour/mDNS advertisements and discovery.

Supported platforms: ✓ iOS ✓ Android ✓ Electron

Demo (sources): application or directly file

Install

npm install @devioarts/capacitor-mdns
npx cap sync

Android

/android/app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />

iOS

/ios/App/App/Info.plist

<key>NSLocalNetworkUsageDescription</key>
<string>It is needed for the correct functioning of the application</string>
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>
<key>NSBonjourServices</key>
<array>
    <string>_http._tcp</string>
</array>

ElectronJS

npm i bonjour-service@1.3.0

Implementation example was developed on capacitor-electron base, if you run electron differently, you may need to adjust the code.

/electron/main.ts

// ...
import { mDNS } from '@devioarts/capacitor-mdns/electron/mdns'
// ...
const mdns = new mDNS();
// ...
app.whenReady().then(() => {
	//...
	mdns.init();
	//...
});
/* Or you can use app.on:ready (whenReady is recomended)
app.on('ready', () => {
	// ...
	mdns.init();
	// ...
});
*/

app.on('before-quit', async () => {
	// ...
	mdns.destroy();
	// ...
})
//...

electron/preload.cjs

//...
// THIS IS IMPORTANT FOR PLUGIN!
const {createMDNSAPI} = require("@devioarts/capacitor-mdns/electron/mdns-bridge.cjs");
//...
// THIS IS IMPORTANT FOR PLUGIN!
contextBridge.exposeInMainWorld('mDNS', createMDNSAPI({ ipcRenderer }));
contextBridge.exposeInMainWorld('mdns', createMDNSAPI({ ipcRenderer })) // alias

API

Public API surface of the Capacitor mDNS plugin.

startBroadcast(...)

startBroadcast(options: MdnsBroadcastOptions) => Promise<MdnsBroadcastResult>

Start advertising a Bonjour/mDNS service.

Param Type Description
options MdnsBroadcastOptions - {@link MdnsBroadcastOptions}

Returns: Promise<MdnsBroadcastResult>

stopBroadcast()

stopBroadcast() => Promise<MdnsStopResult>

Stop advertising the currently registered service (no-op if none).

Returns: Promise<MdnsStopResult>

discover(...)

discover(options?: MdnsDiscoverOptions | undefined) => Promise<MdnsDiscoverResult>

Discover services of a given type and optionally filter by instance name.

Param Type Description
options MdnsDiscoverOptions - {@link MdnsDiscoverOptions}

Returns: Promise<MdnsDiscoverResult>

Interfaces

MdnsBroadcastResult

Result of startBroadcast(). Indicates whether advertising is active and the final service name. On failure, error is true and errorMessage describes the issue.

Prop Type Description
error boolean True if the operation failed.
errorMessage string | null Error description or null on success.
name string Final (possibly uniquified) service instance name. Empty on failure.
publishing boolean Whether the advertiser is currently active.

MdnsBroadcastOptions

Options for starting a Bonjour/mDNS advertisement.

Prop Type Description
type string Service type (including the trailing dot).
name string Service instance name.
port number TCP port to advertise.
txt MdnsTxt Optional TXT key–value pairs (UTF-8 strings).

MdnsStopResult

Result of stopBroadcast(). Indicates whether the advertiser is active after the call (normally false) and includes error information.

Prop Type Description
error boolean True if an error occurred while stopping.
errorMessage string | null Error description or null on success.
publishing boolean Whether the advertiser remains active (should be false on success).

MdnsDiscoverResult

Result of discover(). Contains normalized services and error information.

Prop Type Description
error boolean True if discovery encountered an error (partial results may still be present).
errorMessage string | null Error description or null when no error occurred.
servicesFound number Convenience count equal to services.length.
services MdnsService[] Normalized list of discovered services.

MdnsService

Normalized description of a discovered Bonjour/mDNS service. Returned from {@link mDNSPlugin.discover}.

Prop Type Description
name string Instance name of the service (may be uniqued by the OS, e.g. "My App (2)").
type string Full service type including the trailing dot, e.g. "_http._tcp.".
domain string Service domain; typically "local.".
port number TCP port the service advertises.
hosts string[] Resolved numeric IP addresses (IPv4/IPv6).
txt MdnsTxt TXT dictionary (key → value). Usually present on iOS; Android NSD does not populate this.

MdnsDiscoverOptions

Options for Bonjour/mDNS discovery.

Prop Type Description
type string Service type (including the trailing dot).
name string Optional instance name filter (prefix-safe).
timeout number Discovery timeout in milliseconds.
useNW boolean iOS-only hint to use NWBrowser instead of NetServiceBrowser.

Type Aliases

MdnsTxt

Key–value map for TXT records of a Bonjour/mDNS service. Values are UTF-8 strings; binary payloads are not supported by this API.

Record<string, string>

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }