From 1403b687ea39dd93e7241c7bdbc8bf2276f0f399 Mon Sep 17 00:00:00 2001 From: robrechtme Date: Fri, 3 May 2024 11:54:46 +0200 Subject: [PATCH] docs: add docs --- README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++- src/index.ts | 66 +++++++++++++++++++++++++++++- 2 files changed, 174 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 834cc0f..f82fd22 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,120 @@ [![npm](https://img.shields.io/npm/v/@inthepocket/react-native-service-discovery)](https://www.npmjs.com/package/@inthepocket/react-native-service-discovery) ![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg) +This library allows you to discover services on your local network using mDNS (DNS-SD, Bonjour, Zeroconf, Avahi, ...). Devices that support service discovery include printers, webcams, HTTPS servers, and other mobile devices. The library uses [NSNetServiceBrowser](https://developer.apple.com/documentation/foundation/nsnetservicebrowser) on iOS and [NsdManager](https://developer.android.com/develop/connectivity/wifi/use-nsd) on Android. + ## Installation ```sh npm install @inthepocket/react-native-service-discovery ``` +Add the services you want to search for in `Info.plist`: + +```xml +NSBonjourServices + + + _ssh._tcp + _http._tcp + +``` + +Add a custom Local Network prompt message in `Info.plist`: + +```xml +NSLocalNetworkUsageDescription +${PRODUCT_NAME} uses the local network to discover and connect to devices on your Wi-Fi network. +``` + ## Usage -TODO +```ts +import * as ServiceDiscovery from '@inthepocket/react-native-service-discovery'; + +const foundListener = ServiceDiscovery.addEventListener('serviceFound', (service) => { + console.log('Service found:', service); +}); + +const lostListener = ServiceDiscovery.addEventListener('serviceLost', (service) => { + console.log('Service lost:', service); +}); + +// Start searching for _http._tcp. services +await ServiceDiscovery.startSearch('http'); + +// ... +await ServiceDiscovery.stopSearch('http'); +foundListener.remove(); +lostListener.remove(); +``` + +### startSearch + +Start searching for services of a specific type. Searching for multiple services can be done in parallel. + +| Parameter | Type | Description | +| --------- | ------ | ----------- | +| type | string | The service type to search for, e.g. 'http'. The device will search for services of type `_serviceType._tcp.`. | + +#### Returns + +`Promise` - Resolves when the search has started. Rejects when the search could not be started. + +### stopSearch + +Stop searching for a specific service. This will not stop searching for any other services that are being searched for. + +| Parameter | Type | Description | +| --------- | ------ | ----------- | +| type | string | The service type to stop searching for, e.g. 'http'. | + +#### Returns + +`Promise` - Resolves when the search has stopped. Rejects when the search could not be stopped. Does not reject when the search was already stopped or was not started in the first place. + +### addEventListener + +| Parameter | Type | Description | +| --------- | ------ | ----------- | +| event | `'serviceFound' \| 'serviceLost'` | Start listening for found or lost services. | +| listener | `(service: Service) => void` | The listener that will be called when a service is found or lost. | + +#### Returns + +An `EmitterSubscription` that can be used to remove the listener, by calling `remove()`. + +### Service + +| Attribute | Type | Description | +| --------- | ------ | ----------- | +| name | `string` | Service name. | +| type | `string` | Service type, e.g. `_http._tcp.`. | +| domain | `string` | Domain, can be `local.` or any other domain. | +| hostName | `string` | The domain name of the IP advertising the service. On local networks this is usually the host name. | +| addresses | `string[]` | The IP addresses of the service. This is an array of IPv4 and IPv6 addresses. | +| port | `number` | The port number where the service can be reached. | +| txt | `Record` | The TXT record of the service. The TXT record gives additional information about the service. | + + +### Listening for multiple service types + +You can listen for multiple service types with the same listener: + +```ts +import * as ServiceDiscovery from '@inthepocket/react-native-service-discovery'; + +ServiceDiscovery.addEventListener('serviceFound', (service) => { + if(service.type === '_http._tcp.') { + console.log('HTTP service found:', service); + } else if(service.type === '_ssh._tcp.') { + console.log('SSH service found:', service); + } +}); + +await ServiceDiscovery.startSearch('http'); +await ServiceDiscovery.startSearch('ssh'); +``` ## Contributing @@ -24,5 +129,7 @@ See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the MIT --- +Many thanks to -Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob) +- [react-native-dnssd](https://github.com/kopera/react-native-dnssd) +- [create-react-native-library](https://github.com/callstack/react-native-builder-bob) diff --git a/src/index.ts b/src/index.ts index 04463dd..c1754bf 100644 --- a/src/index.ts +++ b/src/index.ts @@ -24,17 +24,44 @@ const ServiceDiscovery = ServiceDiscoveryModule } ); +/** + * A service that is found or lost on the network. + */ export interface Service { + /** + * Service name. + */ readonly name: string; + /** + * Service type, e.g. `_http._tcp.`. + */ readonly type: string; + /** + * Domain, can be `local.` or any other domain. + */ readonly domain: string; + /** + * The domain name of the IP advertising the service. + * On local networks this is usually the host name. + */ readonly hostName: string; + /** + * The IP addresses of the service. + * This is an array of IPv4 and IPv6 addresses. + */ readonly addresses: string[]; + /** + * The port number where the service can be reached. + */ readonly port: number; + /** + * The TXT record of the service. The TXT record gives additional information + * about the service. + */ readonly txt: Record; } -export type ServiceEvent = 'serviceFound' | 'serviceLost' | 'error'; +export type ServiceEvent = 'serviceFound' | 'serviceLost'; export type ServiceCallback = (service: Service) => void; @@ -44,13 +71,50 @@ export interface Subscription { const EventEmitter = new NativeEventEmitter(ServiceDiscovery); +/** + * + * @example + * ```ts + * import * as ServiceDiscovery from '@inthepocket/react-native-service-discovery'; + * + * ServiceDiscovery.addEventListener('serviceFound', (service) => console.log('Service found:', service)); + * + * // Start searching for _http._tcp. services + * await ServiceDiscovery.startSearch('http'); + * ``` + */ export const addEventListener = ( event: ServiceEvent, listener: ServiceCallback ): Subscription => EventEmitter.addListener(event, listener); +/** + * Start searching for services of a specific type. Searching for + * multiple services can be done in parallel. + * + * @param serviceType The service type to search for, e.g. 'http'. The device + * will search for services of type `_serviceType._tcp.`. + * + * @example + * ```ts + * import * as ServiceDiscovery from '@inthepocket/react-native-service-discovery'; + * + * ServiceDiscovery.addEventListener('serviceFound', (service) => console.log('Service found:', service)); + * + * // Start searching for _http._tcp. services + * await ServiceDiscovery.startSearch('http'); + * ``` + */ export const startSearch = (serviceType: string): Promise => ServiceDiscovery.startSearch(serviceType); +/** + * Stop searching for a specific service. This will not stop searching for any + * other services that are being searched for. + * + * @returns A promise that resolves when the search has been stopped, and + * rejects if the search cannot be stopped. Does not reject if the search has + * already been stopped. + */ export const stopSearch = (serviceType: string): Promise => ServiceDiscovery.stopSearch(serviceType);