react-native-zeroconf 0.16.1 → 0.17.0

package/dist/index.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = exports.ImplType = void 0;
+exports.useServiceTypes = useServiceTypes;
 exports.useZeroconf = useZeroconf;
 var _react = require("react");
 var _reactNative = require("react-native");
@@ -42,6 +43,12 @@ const withDefaults = (defaults, options) => {
 };
 const isOptionsObject = value => value !== null && typeof value === 'object';
 
+// Options passed to native code, without the undefined ones
+const nativeOptions = options => Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined));
+
+// Android 17 (API 37) runtime permission, enforced for apps targeting API 37 or declaring it
+const ACCESS_LOCAL_NETWORK = 'android.permission.ACCESS_LOCAL_NETWORK';
+
 // Each instance runs its own scan, identified by this id in native events
 let instanceCount = 0;
 
@@ -97,6 +104,20 @@ const withAddressFamilies = service => {
 /**
  * TXT records as ordered [key, value] pairs, from an object or an array of pairs
  */
+// Browsing this type lists the service types on the network instead of services
+const SERVICE_TYPES = {
+  type: 'services._dns-sd',
+  protocol: 'udp'
+};
+
+// "_http._tcp" -> { type: 'http', protocol: 'tcp' }
+const parseServiceType = name => {
+  const match = /^_([^.]+)\._(tcp|udp)$/.exec(name);
+  return match ? {
+    type: match[1],
+    protocol: match[2]
+  } : null;
+};
 const toTxtPairs = txt => {
   const entries = Array.isArray(txt) ? txt : Object.entries(txt || {});
   return entries.map(([key, value]) => [String(key), String(value)]);
@@ -108,6 +129,8 @@ class Zeroconf extends _events.EventEmitter {
       throw new Error('react-native-zeroconf: native module not found. Make sure the library is linked and the app rebuilt. Expo Go is not supported, use a development build instead.');
     }
     this._services = {};
+    this._serviceTypes = {};
+    this._scanningTypes = false;
     this._publishedServices = {};
     this._publishedImplTypes = {};
     this._scanImplType = null;
@@ -146,6 +169,15 @@ class Zeroconf extends _events.EventEmitter {
       const {
         name
       } = service;
+      if (this._scanningTypes) {
+        const serviceType = parseServiceType(name);
+        if (serviceType && !this._serviceTypes[name]) {
+          this._serviceTypes[name] = serviceType;
+          this.emit('typeFound', serviceType);
+          this.emit('update');
+        }
+        return;
+      }
       this._services[name] = {
         name
       };
@@ -159,6 +191,15 @@ class Zeroconf extends _events.EventEmitter {
       const {
         name
       } = service;
+      if (this._scanningTypes) {
+        const serviceType = this._serviceTypes[name];
+        if (serviceType) {
+          delete this._serviceTypes[name];
+          this.emit('typeRemove', serviceType);
+          this.emit('update');
+        }
+        return;
+      }
       delete this._services[name];
       this.emit('remove', name);
       this.emit('update');
@@ -226,6 +267,33 @@ class Zeroconf extends _events.EventEmitter {
     return this._services;
   }
 
+  /**
+   * Get the service types found by scanServiceTypes, as [{ type, protocol }]
+   */
+  getServiceTypes() {
+    return Object.values(this._serviceTypes);
+  }
+
+  /**
+   * Scan for the service types advertised on the network (_http._tcp, _ipp._tcp...), emits typeFound and typeRemove.
+   * On iOS, only types declared in NSBonjourServices can then be scanned.
+   * On iOS it requires the multicast entitlement. On Android with NSD and on Windows, services other apps publish on the same device are left out.
+   *
+   * scanServiceTypes({ domain, implType })
+   */
+  scanServiceTypes({
+    domain,
+    implType,
+    networkInterface
+  } = {}) {
+    this._startScan({
+      ...SERVICE_TYPES,
+      domain,
+      implType,
+      networkInterface
+    }, true);
+  }
+
   /**
    * Scan for Zeroconf services, defaults to _http._tcp. on the local. domain
    *
@@ -233,19 +301,26 @@ class Zeroconf extends _events.EventEmitter {
    * scan(type, protocol, domain, implType) is deprecated
    */
   scan(options, protocolArg, domainArg, implTypeArg) {
+    this._startScan(isOptionsObject(options) ? options : {
+      type: options,
+      protocol: protocolArg,
+      domain: domainArg,
+      implType: implTypeArg
+    }, false);
+  }
+  _startScan(options, scanningTypes) {
     const {
       type,
       protocol,
       domain,
       implType,
-      resolveTimeout
-    } = withDefaults(SCAN_DEFAULTS, isOptionsObject(options) ? options : {
-      type: options,
-      protocol: protocolArg,
-      domain: domainArg,
-      implType: implTypeArg
-    });
+      resolveTimeout,
+      subtype,
+      networkInterface
+    } = withDefaults(SCAN_DEFAULTS, options);
     this._services = {};
+    this._serviceTypes = {};
+    this._scanningTypes = scanningTypes;
     this._hasScanned = true;
     this.emit('update');
     if (_reactNative.Platform.OS === 'android') {
@@ -254,9 +329,16 @@ class Zeroconf extends _events.EventEmitter {
         RNZeroconf.stop(this._scanId, this._scanImplType);
       }
       this._scanImplType = implType;
-      RNZeroconf.scan(this._scanId, type, protocol, domain, implType);
+      RNZeroconf.scan(this._scanId, type, protocol, domain, implType, nativeOptions({
+        subtype,
+        networkInterface
+      }));
     } else {
-      RNZeroconf.scan(this._scanId, type, protocol, domain, resolveTimeout);
+      RNZeroconf.scan(this._scanId, type, protocol, domain, nativeOptions({
+        resolveTimeout,
+        subtype,
+        networkInterface
+      }));
     }
   }
 
@@ -273,17 +355,27 @@ class Zeroconf extends _events.EventEmitter {
   }
 
   /**
-   * Checks the iOS Local Network permission, resolves 'granted', 'denied' or 'unknown'.
-   * Uses a service type from NSBonjourServices (the first one by default) and can show the permission prompt.
-   * Android has no equivalent permission to check and resolves 'unknown'.
+   * Checks the Local Network permission, resolves 'granted', 'denied' or 'unknown'.
+   * iOS: uses a service type from NSBonjourServices (the first one by default) and can show the permission prompt.
+   * Android: apps targeting Android 17 (API 37) need ACCESS_LOCAL_NETWORK on Android 17 devices, it is requested
+   * when missing unless request is false. 'granted' when there is nothing to grant.
    */
-  checkLocalNetworkAccess({
+  async checkLocalNetworkAccess({
     type,
     protocol = 'tcp',
-    timeout = 5
+    timeout = 5,
+    request = true
   } = {}) {
     if (_reactNative.Platform.OS === 'android') {
-      return Promise.resolve('unknown');
+      if (!RNZeroconf.checkLocalNetworkAccess) {
+        return 'unknown';
+      }
+      const status = await asPromise(RNZeroconf.checkLocalNetworkAccess());
+      if (status !== 'denied' || !request) {
+        return status;
+      }
+      const result = await _reactNative.PermissionsAndroid.request(ACCESS_LOCAL_NETWORK);
+      return result === _reactNative.PermissionsAndroid.RESULTS.GRANTED ? 'granted' : 'denied';
     }
     const serviceType = type ? `_${type}._${protocol}` : null;
     return asPromise(RNZeroconf.checkLocalNetworkAccess(serviceType, timeout));
@@ -304,7 +396,9 @@ class Zeroconf extends _events.EventEmitter {
       name,
       port,
       txt,
-      implType
+      implType,
+      subtypes,
+      networkInterface
     } = withDefaults(PUBLISH_DEFAULTS, isOptionsObject(options) ? options : {
       type: options,
       protocol: protocolArg,
@@ -315,11 +409,59 @@ class Zeroconf extends _events.EventEmitter {
       implType: implTypeArg
     });
     const txtRecord = toTxtPairs(txt);
+    const native = nativeOptions({
+      subtypes,
+      networkInterface
+    });
     if (_reactNative.Platform.OS === 'android') {
       this._publishedImplTypes[name] = implType;
-      return asPromise(RNZeroconf.registerService(type, protocol, domain, name, port, txtRecord, implType));
+      return asPromise(RNZeroconf.registerService(type, protocol, domain, name, port, txtRecord, implType, native));
+    }
+    return asPromise(RNZeroconf.registerService(type, protocol, domain, name, port, txtRecord, native));
+  }
+
+  /**
+   * Replace the TXT record of a published service, resolves with the updated service.
+   * Android NSD has no update, the service is published again under the same name.
+   *
+   * updateService(name, { txt })
+   */
+  updateService(name, {
+    txt = {},
+    implType = this._publishedImplTypes[name] || ImplType.NSD
+  } = {}) {
+    const txtRecord = toTxtPairs(txt);
+    if (_reactNative.Platform.OS === 'android') {
+      return asPromise(RNZeroconf.updateService(name, txtRecord, implType));
     }
-    return asPromise(RNZeroconf.registerService(type, protocol, domain, name, port, txtRecord));
+    return asPromise(RNZeroconf.updateService(name, txtRecord));
+  }
+
+  /**
+   * Resolve one service by name without scanning, for a device found before.
+   * Resolves with the service, rejects with code 'TIMEOUT' when it doesn't answer in time.
+   *
+   * resolveService({ name, type, protocol, domain, implType, timeout, networkInterface })
+   */
+  resolveService(options) {
+    const {
+      name,
+      type,
+      protocol,
+      domain,
+      implType,
+      timeout,
+      networkInterface
+    } = withDefaults({
+      ...SCAN_DEFAULTS,
+      timeout: 5
+    }, options);
+    const native = nativeOptions({
+      timeout,
+      networkInterface
+    });
+    const promise = _reactNative.Platform.OS === 'android' ? RNZeroconf.resolveService(name, type, protocol, domain, implType, native) : RNZeroconf.resolveService(name, type, protocol, domain, native);
+    return asPromise(asPromise(promise).then(service => service && withAddressFamilies(service)));
   }
 
   /**
@@ -335,34 +477,20 @@ class Zeroconf extends _events.EventEmitter {
   }
 }
 
-/**
- * Scans while mounted and returns the resolved services.
- * Scans again when the options change, stops and cleans up on unmount.
- * Each hook runs its own scan, several can run at once.
- *
- * const { services, isScanning, error, stop, restart } = useZeroconf({ type: 'http' })
- */
+// Runs a scan while mounted and enabled, and again when deps change or on restart
 exports.default = Zeroconf;
-function useZeroconf(options = {}) {
-  const {
-    type,
-    protocol,
-    domain,
-    implType,
-    resolveTimeout,
-    enabled = true
-  } = options;
+function useScan(enabled, startScan, read, deps) {
   const zeroconfRef = (0, _react.useRef)(null);
-  const [services, setServices] = (0, _react.useState)([]);
+  const [items, setItems] = (0, _react.useState)([]);
   const [isScanning, setIsScanning] = (0, _react.useState)(false);
   const [error, setError] = (0, _react.useState)(null);
   const [scanCount, setScanCount] = (0, _react.useState)(0);
+  const readRef = (0, _react.useRef)(read);
+  readRef.current = read;
   (0, _react.useEffect)(() => {
     const zeroconf = new Zeroconf();
     zeroconfRef.current = zeroconf;
-    // Found services only have a name until they are resolved
-    const updateServices = () => setServices(Object.values(zeroconf.getServices()).filter(service => service.addresses));
-    const unsubscribes = [zeroconf.subscribe('start', () => setIsScanning(true)), zeroconf.subscribe('stop', () => setIsScanning(false)), zeroconf.subscribe('update', updateServices), zeroconf.subscribe('error', setError)];
+    const unsubscribes = [zeroconf.subscribe('start', () => setIsScanning(true)), zeroconf.subscribe('stop', () => setIsScanning(false)), zeroconf.subscribe('update', () => setItems(readRef.current(zeroconf))), zeroconf.subscribe('error', setError)];
     return () => {
       unsubscribes.forEach(unsubscribe => unsubscribe());
       zeroconf.stop();
@@ -375,17 +503,11 @@ function useZeroconf(options = {}) {
     if (!zeroconf || !enabled) {
       return undefined;
     }
-    setServices([]);
+    setItems([]);
     setError(null);
-    zeroconf.scan({
-      type,
-      protocol,
-      domain,
-      implType,
-      resolveTimeout
-    });
+    startScan(zeroconf);
     return () => zeroconf.stop();
-  }, [enabled, type, protocol, domain, implType, resolveTimeout, scanCount]);
+  }, [enabled, scanCount, ...deps]);
   const stop = (0, _react.useCallback)(() => {
     if (zeroconfRef.current) {
       zeroconfRef.current.stop();
@@ -393,10 +515,74 @@ function useZeroconf(options = {}) {
   }, []);
   const restart = (0, _react.useCallback)(() => setScanCount(count => count + 1), []);
   return {
-    services,
+    items,
     isScanning,
     error,
     stop,
     restart
   };
 }
+
+/**
+ * Scans while mounted and returns the resolved services.
+ * Scans again when the options change, stops and cleans up on unmount.
+ * Each hook runs its own scan, several can run at once.
+ *
+ * const { services, isScanning, error, stop, restart } = useZeroconf({ type: 'http' })
+ */
+function useZeroconf(options = {}) {
+  const {
+    type,
+    protocol,
+    domain,
+    implType,
+    resolveTimeout,
+    subtype,
+    networkInterface,
+    enabled = true
+  } = options;
+  const {
+    items,
+    ...scan
+  } = useScan(enabled, zeroconf => zeroconf.scan({
+    type,
+    protocol,
+    domain,
+    implType,
+    resolveTimeout,
+    subtype,
+    networkInterface
+  }),
+  // Found services only have a name until they are resolved
+  zeroconf => Object.values(zeroconf.getServices()).filter(service => service.addresses), [type, protocol, domain, implType, resolveTimeout, subtype, networkInterface]);
+  return {
+    services: items,
+    ...scan
+  };
+}
+
+/**
+ * Lists the service types advertised on the network while mounted.
+ *
+ * const { serviceTypes, isScanning, error, stop, restart } = useServiceTypes()
+ */
+function useServiceTypes(options = {}) {
+  const {
+    domain,
+    implType,
+    networkInterface,
+    enabled = true
+  } = options;
+  const {
+    items,
+    ...scan
+  } = useScan(enabled, zeroconf => zeroconf.scanServiceTypes({
+    domain,
+    implType,
+    networkInterface
+  }), zeroconf => zeroconf.getServiceTypes(), [domain, implType, networkInterface]);
+  return {
+    serviceTypes: items,
+    ...scan
+  };
+}

package/index.d.ts

@@ -38,6 +38,13 @@ export interface ScanOptions {
   implType?: ImplType
   /** iOS only, seconds to try resolving a service before retrying once and giving up. Defaults to `5` */
   resolveTimeout?: number
+  /** Only find services registered with this subtype, e.g. `'printer'` */
+  subtype?: string
+  /**
+   * Network interface to scan on, e.g. `'en0'` on iOS or `'wlan0'` on Android. All of them by default.
+   * Android `NSD` needs Android 13 or later for it
+   */
+  networkInterface?: string
 }
 
 export interface PublishOptions {
@@ -53,6 +60,34 @@ export interface PublishOptions {
   txt?: TxtRecord
   /** Android only, defaults to `NSD` */
   implType?: ImplType
+  /** Subtypes to register the service with, e.g. `['printer']` */
+  subtypes?: string[]
+  /** Network interface to publish on, all of them by default. Android `NSD` needs Android 13 or later for it */
+  networkInterface?: string
+}
+
+export interface UpdateOptions {
+  /** The new TXT record, replaces the current one */
+  txt?: TxtRecord
+  /** Android only, defaults to the implementation the service was published with */
+  implType?: ImplType
+}
+
+export interface ResolveOptions {
+  /** Name of the service */
+  name: string
+  /** Service type without underscore, e.g. `'http'`. Defaults to `'http'` */
+  type?: string
+  /** Defaults to `'tcp'` */
+  protocol?: string
+  /** Defaults to `'local.'` */
+  domain?: string
+  /** Android only, defaults to `NSD` */
+  implType?: ImplType
+  /** Seconds before rejecting with code `'TIMEOUT'`, defaults to `5` */
+  timeout?: number
+  /** Network interface to resolve on, all of them by default */
+  networkInterface?: string
 }
 
 /**
@@ -61,11 +96,12 @@ export interface PublishOptions {
  * - `DNSSD`: DNSServiceErrorType, on iOS and from Android's embedded mDNSResponder,
  *   e.g. `-65555` type missing from NSBonjourServices, `-65570` Local Network access denied
  * - `NsdManager`: Android NsdManager failure code
- * - `RNZeroconf`: the library's own errors, e.g. `'EXCEPTION'`
+ * - `Windows`: Win32 / DNS_STATUS code from the Windows DNS-SD functions
+ * - `RNZeroconf`: the library's own errors, e.g. `'EXCEPTION'`, `'TIMEOUT'`, `'UNKNOWN_INTERFACE'`
  */
 export interface ZeroconfError extends Error {
   code: number | string
-  domain: 'DNSSD' | 'NsdManager' | 'RNZeroconf'
+  domain: 'DNSSD' | 'NsdManager' | 'RNZeroconf' | 'Windows'
   /** The service the error is about, when there is one */
   serviceName?: string
 }
@@ -75,8 +111,10 @@ export interface LocalNetworkAccessOptions {
   type?: string
   /** Defaults to `'tcp'` */
   protocol?: string
-  /** Seconds to wait for an answer, defaults to `5` */
+  /** iOS: seconds to wait for an answer, defaults to `5` */
   timeout?: number
+  /** Android: request `ACCESS_LOCAL_NETWORK` when it is missing, defaults to `true` */
+  request?: boolean
 }
 
 /** Published services don't carry the address family fields */
@@ -91,13 +129,32 @@ export interface ZeroconfEvents {
   resolved: (service: Service) => void
   /** Service removed from the network */
   remove: (name: string) => void
-  /** Services list changed */
+  /** Services or service types list changed */
   update: () => void
+  /** Service type found by `scanServiceTypes` */
+  typeFound: (serviceType: ServiceType) => void
+  /** Service type no longer advertised, during `scanServiceTypes` */
+  typeRemove: (serviceType: ServiceType) => void
   error: (error: ZeroconfError) => void
   published: (service: PublishedService) => void
   unpublished: (service: PublishedService) => void
 }
 
+/** A service type advertised on the network, e.g. `{ type: 'http', protocol: 'tcp' }` for `_http._tcp` */
+export interface ServiceType {
+  type: string
+  protocol: 'tcp' | 'udp'
+}
+
+export interface ServiceTypesScanOptions {
+  /** Defaults to `local.` */
+  domain?: string
+  /** Android only, defaults to `ImplType.NSD`. With `NSD`, services other apps publish on the same phone are left out (this app's own are included), `DNSSD` includes them */
+  implType?: ImplType
+  /** Network interface to list the types on, all of them by default */
+  networkInterface?: string
+}
+
 /** Extends the `events` package EventEmitter */
 export default class Zeroconf {
   constructor()
@@ -121,14 +178,24 @@ export default class Zeroconf {
   /** All the services found so far, keyed by name */
   getServices(): Record<string, Service>
 
+  /** Service types found by `scanServiceTypes` */
+  getServiceTypes(): ServiceType[]
+
+  /**
+   * Scan for the service types advertised on the network, emits `typeFound` and `typeRemove`.
+   * On iOS it requires the `com.apple.developer.networking.multicast` entitlement.
+   */
+  scanServiceTypes(options?: ServiceTypesScanOptions): void
+
   /** Scan for services, defaults to `_http._tcp.` on the `local.` domain */
   scan(options?: ScanOptions): void
   /** @deprecated Use `scan({ type, protocol, domain, implType })` */
   scan(type?: string, protocol?: string, domain?: string, implType?: ImplType): void
 
   /**
-   * Checks the iOS Local Network permission. Can show the permission prompt when it hasn't been answered yet.
-   * Resolves `'unknown'` on Android, which has no equivalent permission to check.
+   * Checks the Local Network permission. iOS can show the permission prompt when it hasn't been answered yet.
+   * Android 17 (API 37): apps targeting API 37 need `ACCESS_LOCAL_NETWORK`, requested when missing unless
+   * `request` is `false`. Resolves `'granted'` when there is nothing to grant.
    */
   checkLocalNetworkAccess(
     options?: LocalNetworkAccessOptions,
@@ -162,6 +229,15 @@ export default class Zeroconf {
    * @param implType Android only, defaults to the implementation the service was published with
    */
   unpublishService(name: string, implType?: ImplType): Promise<PublishedService | null>
+
+  /**
+   * Replace the TXT record of a published service, resolves with the updated service.
+   * Android `NSD` has no update: the service is published again under the same name.
+   */
+  updateService(name: string, options: UpdateOptions): Promise<PublishedService>
+
+  /** Resolve one service by name without scanning. Rejects with code `'TIMEOUT'` when it doesn't answer in time */
+  resolveService(options: ResolveOptions): Promise<Service>
 }
 
 export interface UseZeroconfOptions extends ScanOptions {
@@ -185,3 +261,22 @@ export interface UseZeroconfResult {
  * stops and cleans up on unmount. Each hook runs its own scan, several can run at once.
  */
 export function useZeroconf(options?: UseZeroconfOptions): UseZeroconfResult
+
+export interface UseServiceTypesOptions extends ServiceTypesScanOptions {
+  /** Scan only while true, defaults to `true` */
+  enabled?: boolean
+}
+
+export interface UseServiceTypesResult {
+  /** Service types advertised on the network, updated as they appear and disappear */
+  serviceTypes: ServiceType[]
+  isScanning: boolean
+  /** Last error, reset when a new scan starts */
+  error: ZeroconfError | null
+  stop(): void
+  /** Clears the service types and scans again */
+  restart(): void
+}
+
+/** Lists the service types advertised on the network while mounted */
+export function useServiceTypes(options?: UseServiceTypesOptions): UseServiceTypesResult