@devioarts/capacitor-mdns 0.0.2

package/android/src/main/java/com/devioarts/capacitor/mdns/mDNSPlugin.kt

@@ -0,0 +1,157 @@
+package com.devioarts.capacitor.mdns
+
+import com.getcapacitor.*
+import com.getcapacitor.annotation.CapacitorPlugin
+import com.getcapacitor.PluginMethod
+import kotlinx.coroutines.*
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Capacitor Android bridge for the mDNS plugin.
+ *
+ * Responsibilities:
+ * - Own a single instance of the mDNS manager (Android NSD wrapper).
+ * - Translate Capacitor calls (JS) to Kotlin calls and normalize results.
+ * - Never reject for runtime errors; always resolve with { error, errorMessage }.
+ *
+ * Parameters (strict, no legacy):
+ * - startBroadcast: { type?: string, name?: string, port: number, txt?: Record<string,string> }  // txt ignored by Android
+ * - stopBroadcast:  {}
+ * - discover:       { type?: string, name?: string, timeout?: number }
+ *
+ * Return shapes:
+ * - startBroadcast -> { publishing: boolean, name: string, error: boolean, errorMessage: string|null }
+ * - stopBroadcast  -> { publishing: false, error: boolean, errorMessage: string|null }
+ * - discover       -> {
+ *       error: boolean, errorMessage: string|null,
+ *       servicesFound: number,
+ *       services: Array<{ name, type, domain: "local.", port, hosts?: string[] }>
+ *   }
+ */
+@CapacitorPlugin(name = "mDNS")
+class mDNSPlugin : Plugin() {
+
+    private val scope = MainScope()
+    private lateinit var mdns: mDNS
+
+    override fun load() {
+        val ctx = context ?: throw IllegalStateException("No Android context")
+        mdns = mDNS(ctx, scope)
+    }
+
+    override fun handleOnDestroy() {
+        mdns.close()
+        scope.cancel()
+    }
+
+    // ----------------------- Helpers -----------------------
+
+    private fun toErrorMessage(t: Throwable?): String =
+        t?.message ?: "Unknown error"
+
+    private fun jnull(msg: String?): Any = msg ?: JSONObject.NULL
+
+    private fun jsResultBroadcast(publishing: Boolean, name: String, error: Boolean, msg: String?): JSObject =
+        JSObject().put("publishing", publishing)
+            .put("name", name)
+            .put("error", error)
+            .put("errorMessage", jnull(msg))
+
+    private fun jsResultStop(error: Boolean, msg: String?): JSObject =
+        JSObject().put("publishing", false)
+            .put("error", error)
+            .put("errorMessage", jnull(msg))
+
+    private fun jsResultDiscover(error: Boolean, msg: String?, services: JSONArray): JSObject =
+        JSObject()
+            .put("error", error)
+            .put("errorMessage", jnull(msg))
+            .put("servicesFound", services.length())
+            .put("services", services)
+
+    // ----------------------- API -----------------------
+
+    /**
+     * Start advertising a Bonjour/mDNS service.
+     * - type: default "_http._tcp."
+     * - name: default packageName
+     * - port: required (> 0)
+     */
+    @PluginMethod
+    fun startBroadcast(call: PluginCall) {
+        val type = call.getString("type") ?: "_http._tcp."
+        val name = call.getString("name") ?: (context?.packageName ?: "DevIOArtsMDNS")
+        val port = call.getInt("port") ?: 0
+
+        if (port <= 0) {
+            call.resolve(jsResultBroadcast(false, "", true, "Missing/invalid port"))
+            return
+        }
+
+        try {
+            mdns.broadcast(
+                typeRaw = type,
+                name = name,
+                port = port,
+                onSuccess = { published ->
+                    call.resolve(jsResultBroadcast(true, published, false, null))
+                },
+                onError = { err ->
+                    call.resolve(jsResultBroadcast(false, "", true, toErrorMessage(err)))
+                }
+            )
+        } catch (t: Throwable) {
+            call.resolve(jsResultBroadcast(false, "", true, toErrorMessage(t)))
+        }
+    }
+
+    /**
+     * Stop advertising the currently registered service.
+     */
+    @PluginMethod
+    fun stopBroadcast(call: PluginCall) {
+        try {
+            mdns.stopBroadcast()
+            call.resolve(jsResultStop(false, null))
+        } catch (t: Throwable) {
+            call.resolve(jsResultStop(true, toErrorMessage(t)))
+        }
+    }
+
+    /**
+     * Discover services of a given type and optional name filter (exact/prefix, normalized).
+     * - type: default "_http._tcp."
+     * - name: optional filter
+     * - timeout: default 3000
+     */
+    @PluginMethod
+    fun discover(call: PluginCall) {
+        val type = call.getString("type") ?: "_http._tcp."
+        val targetName = call.getString("name")
+        val timeout = call.getInt("timeout") ?: 3000
+
+        scope.launch {
+            try {
+                val list = mdns.discover(type, targetName, timeout)
+                val arr = JSONArray(list.map { s ->
+                    JSObject().apply {
+                        put("name", s.name)
+                        put("type", s.type)         // Android returns full type with dot
+                        put("domain", "local.")     // NSD is mDNS only
+                        // normalize hosts to [] or [addr]
+                        val hosts = JSONArray()
+                        val addr = s.host
+                        if (!addr.isNullOrEmpty()) hosts.put(addr)
+                        put("hosts", hosts)
+                        put("port", s.port)
+                        // TXT not available via NSD -> omitted on Android
+                    }
+                })
+                call.resolve(jsResultDiscover(false, null, arr))
+            } catch (t: Throwable) {
+                call.resolve(jsResultDiscover(true, toErrorMessage(t), JSONArray()))
+            }
+        }
+    }
+}

package/dist/docs.json

@@ -0,0 +1,457 @@
+{
+  "api": {
+    "name": "mDNSPlugin",
+    "slug": "mdnsplugin",
+    "docs": "Public API surface of the Capacitor mDNS plugin.",
+    "tags": [
+      {
+        "text": "```ts\nimport { mDNS } from 'capacitor-mdns';\n\n// Start advertising\nawait mDNS.startBroadcast({ type: '_http._tcp.', name: 'my.app.id', port: 9235 });\n\n// Discover services\nconst { services } = await mDNS.discover({ type: '_http._tcp.', timeout: 3000 });\n\n// Stop advertising\nawait mDNS.stopBroadcast();\n```",
+        "name": "example"
+      },
+      {
+        "name": "public"
+      }
+    ],
+    "methods": [
+      {
+        "name": "startBroadcast",
+        "signature": "(options: MdnsBroadcastOptions) => Promise<MdnsBroadcastResult>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- {@link MdnsBroadcastOptions}",
+            "type": "MdnsBroadcastOptions"
+          }
+        ],
+        "returns": "Promise<MdnsBroadcastResult>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options - {@link MdnsBroadcastOptions}"
+          },
+          {
+            "name": "returns",
+            "text": "Promise resolving to `MdnsBroadcastResult` (`true` on success)."
+          }
+        ],
+        "docs": "Start advertising a Bonjour/mDNS service.",
+        "complexTypes": [
+          "MdnsBroadcastResult",
+          "MdnsBroadcastOptions"
+        ],
+        "slug": "startbroadcast"
+      },
+      {
+        "name": "stopBroadcast",
+        "signature": "() => Promise<MdnsStopResult>",
+        "parameters": [],
+        "returns": "Promise<MdnsStopResult>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Promise resolving to `MdnsStopResult`."
+          },
+          {
+            "name": "remarks",
+            "text": "The `publishing` flag may be `false` after a successful stop."
+          }
+        ],
+        "docs": "Stop advertising the currently registered service (no-op if none).",
+        "complexTypes": [
+          "MdnsStopResult"
+        ],
+        "slug": "stopbroadcast"
+      },
+      {
+        "name": "discover",
+        "signature": "(options?: MdnsDiscoverOptions | undefined) => Promise<MdnsDiscoverResult>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- {@link MdnsDiscoverOptions}",
+            "type": "MdnsDiscoverOptions | undefined"
+          }
+        ],
+        "returns": "Promise<MdnsDiscoverResult>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options - {@link MdnsDiscoverOptions}"
+          },
+          {
+            "name": "returns",
+            "text": "Promise resolving to `MdnsDiscoverResult`."
+          },
+          {
+            "name": "remarks",
+            "text": "The result list is normalized across platforms. On Android, `txt` is typically absent."
+          }
+        ],
+        "docs": "Discover services of a given type and optionally filter by instance name.",
+        "complexTypes": [
+          "MdnsDiscoverResult",
+          "MdnsDiscoverOptions"
+        ],
+        "slug": "discover"
+      }
+    ],
+    "properties": []
+  },
+  "interfaces": [
+    {
+      "name": "MdnsBroadcastResult",
+      "slug": "mdnsbroadcastresult",
+      "docs": "Result of startBroadcast(). Indicates whether advertising is active\nand the final service name. On failure, `error` is true and `errorMessage`\ndescribes the issue.",
+      "tags": [
+        {
+          "name": "public"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "error",
+          "tags": [],
+          "docs": "True if the operation failed.",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "errorMessage",
+          "tags": [],
+          "docs": "Error description or null on success.",
+          "complexTypes": [],
+          "type": "string | null"
+        },
+        {
+          "name": "name",
+          "tags": [],
+          "docs": "Final (possibly uniquified) service instance name. Empty on failure.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "publishing",
+          "tags": [],
+          "docs": "Whether the advertiser is currently active.",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
+    {
+      "name": "MdnsBroadcastOptions",
+      "slug": "mdnsbroadcastoptions",
+      "docs": "Options for starting a Bonjour/mDNS advertisement.",
+      "tags": [
+        {
+          "text": "- The `type` **must** end with a dot (`.`). If omitted, the implementation appends it.\n- Instance `name` should be short and human-readable; the OS may append `\" (n)\"` to ensure uniqueness.\n- Android NSD does not expose TXT records to other apps; advertising TXT is supported on iOS.",
+          "name": "remarks"
+        },
+        {
+          "name": "public"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "type",
+          "tags": [
+            {
+              "text": "`\"_http._tcp.\"`",
+              "name": "defaultValue"
+            },
+            {
+              "text": "`\"_myapp._tcp.\"`",
+              "name": "example"
+            }
+          ],
+          "docs": "Service type (including the trailing dot).",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "name",
+          "tags": [],
+          "docs": "Service instance name.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "port",
+          "tags": [
+            {
+              "text": "Must be a positive integer (1–65535).",
+              "name": "remarks"
+            }
+          ],
+          "docs": "TCP port to advertise.",
+          "complexTypes": [],
+          "type": "number"
+        },
+        {
+          "name": "txt",
+          "tags": [
+            {
+              "text": "May be ignored on Android due to platform limitations.",
+              "name": "remarks"
+            }
+          ],
+          "docs": "Optional TXT key–value pairs (UTF-8 strings).",
+          "complexTypes": [
+            "MdnsTxt"
+          ],
+          "type": "MdnsTxt"
+        }
+      ]
+    },
+    {
+      "name": "MdnsStopResult",
+      "slug": "mdnsstopresult",
+      "docs": "Result of stopBroadcast(). Indicates whether the advertiser is active\nafter the call (normally false) and includes error information.",
+      "tags": [
+        {
+          "name": "public"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "error",
+          "tags": [],
+          "docs": "True if an error occurred while stopping.",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "errorMessage",
+          "tags": [],
+          "docs": "Error description or null on success.",
+          "complexTypes": [],
+          "type": "string | null"
+        },
+        {
+          "name": "publishing",
+          "tags": [],
+          "docs": "Whether the advertiser remains active (should be false on success).",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
+    {
+      "name": "MdnsDiscoverResult",
+      "slug": "mdnsdiscoverresult",
+      "docs": "Result of discover(). Contains normalized services and error information.",
+      "tags": [
+        {
+          "name": "public"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "error",
+          "tags": [],
+          "docs": "True if discovery encountered an error (partial results may still be present).",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "errorMessage",
+          "tags": [],
+          "docs": "Error description or null when no error occurred.",
+          "complexTypes": [],
+          "type": "string | null"
+        },
+        {
+          "name": "servicesFound",
+          "tags": [],
+          "docs": "Convenience count equal to services.length.",
+          "complexTypes": [],
+          "type": "number"
+        },
+        {
+          "name": "services",
+          "tags": [],
+          "docs": "Normalized list of discovered services.",
+          "complexTypes": [
+            "MdnsService"
+          ],
+          "type": "MdnsService[]"
+        }
+      ]
+    },
+    {
+      "name": "MdnsService",
+      "slug": "mdnsservice",
+      "docs": "Normalized description of a discovered Bonjour/mDNS service.\nReturned from {@link mDNSPlugin.discover}.",
+      "tags": [
+        {
+          "text": "- `hosts` contains resolved IPv4/IPv6 numeric addresses (no DNS names).\n- iOS returns `txt` when present. Android (NSD) does not expose TXT records via public APIs,\n  so `txt` is usually omitted on Android.\n- `domain` is typically `\"local.\"`.",
+          "name": "remarks"
+        },
+        {
+          "name": "public"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "name",
+          "tags": [],
+          "docs": "Instance name of the service (may be uniqued by the OS, e.g. \"My App (2)\").",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "type",
+          "tags": [],
+          "docs": "Full service type including the trailing dot, e.g. `\"_http._tcp.\"`.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "domain",
+          "tags": [],
+          "docs": "Service domain; typically `\"local.\"`.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "port",
+          "tags": [],
+          "docs": "TCP port the service advertises.",
+          "complexTypes": [],
+          "type": "number"
+        },
+        {
+          "name": "hosts",
+          "tags": [
+            {
+              "text": "`[\"192.168.1.42\", \"fe80::1234:abcd:...\"]`",
+              "name": "example"
+            }
+          ],
+          "docs": "Resolved numeric IP addresses (IPv4/IPv6).",
+          "complexTypes": [],
+          "type": "string[]"
+        },
+        {
+          "name": "txt",
+          "tags": [
+            {
+              "text": "Not all services publish TXT data.",
+              "name": "remarks"
+            }
+          ],
+          "docs": "TXT dictionary (key → value). Usually present on iOS; Android NSD does not populate this.",
+          "complexTypes": [
+            "MdnsTxt"
+          ],
+          "type": "MdnsTxt"
+        }
+      ]
+    },
+    {
+      "name": "MdnsDiscoverOptions",
+      "slug": "mdnsdiscoveroptions",
+      "docs": "Options for Bonjour/mDNS discovery.",
+      "tags": [
+        {
+          "text": "- The `id` filter matches the normalized name and also accepts prefix matches\n  (to handle OS-added `\" (n)\"` suffixes).\n- When `useNW` is `true` on iOS, discovery uses `NWBrowser` for better P2P behavior.",
+          "name": "remarks"
+        },
+        {
+          "name": "public"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "type",
+          "tags": [
+            {
+              "text": "`\"_http._tcp.\"`",
+              "name": "defaultValue"
+            },
+            {
+              "text": "`\"_comm._tcp.\"`",
+              "name": "example"
+            }
+          ],
+          "docs": "Service type (including the trailing dot).",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "name",
+          "tags": [
+            {
+              "text": "`\"MyAppName\"`",
+              "name": "example"
+            }
+          ],
+          "docs": "Optional instance name filter (prefix-safe).",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "timeout",
+          "tags": [
+            {
+              "text": "`3000`",
+              "name": "defaultValue"
+            }
+          ],
+          "docs": "Discovery timeout in milliseconds.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "useNW",
+          "tags": [
+            {
+              "text": "`true`",
+              "name": "defaultValue"
+            }
+          ],
+          "docs": "iOS-only hint to use `NWBrowser` instead of `NetServiceBrowser`.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        }
+      ]
+    }
+  ],
+  "enums": [],
+  "typeAliases": [
+    {
+      "name": "MdnsTxt",
+      "slug": "mdnstxt",
+      "docs": "Key–value map for TXT records of a Bonjour/mDNS service.\nValues are UTF-8 strings; binary payloads are not supported by this API.",
+      "types": [
+        {
+          "text": "Record<string, string>",
+          "complexTypes": [
+            "Record"
+          ]
+        }
+      ]
+    },
+    {
+      "name": "Record",
+      "slug": "record",
+      "docs": "Construct a type with a set of properties K of type T",
+      "types": [
+        {
+          "text": "{\r\n    [P in K]: T;\r\n}",
+          "complexTypes": [
+            "K",
+            "T"
+          ]
+        }
+      ]
+    }
+  ],
+  "pluginConfigs": []
+}