From ac602b5c0d0be8ecd78f3a1a8638f53d10be2c82 Mon Sep 17 00:00:00 2001 From: Ben <43026681+bwp91@users.noreply.github.com> Date: Wed, 10 Apr 2024 21:08:08 +0100 Subject: [PATCH] update doc links in README --- CHANGELOG.md | 1 + README.md | 26 +++++++++++++------------- docs/classes/CiaoService.html | 22 +++++++++++----------- docs/classes/Responder.html | 6 +++--- docs/enums/Protocol.html | 4 ++-- docs/enums/ServiceEvent.html | 6 +++--- docs/enums/ServiceType.html | 4 ++-- docs/functions/getResponder.html | 2 +- docs/index.html | 26 +++++++++++++------------- docs/interfaces/MDNSServerOptions.html | 6 +++--- docs/interfaces/ServiceOptions.html | 22 +++++++++++----------- docs/types/ResponderOptions.html | 2 +- docs/types/ServiceTxt.html | 2 +- docs/variables/default.html | 2 +- 14 files changed, 66 insertions(+), 65 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 10c38d3..0fb4613 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,3 +14,4 @@ All notable changes to `@homebridge/ciao` will be documented in this file. This - updated eslint rule - update to match renamed `latest` branch - regenerate docs +- update doc links in README diff --git a/README.md b/README.md index c4a0ff1..7426e3e 100644 --- a/README.md +++ b/README.md @@ -84,34 +84,34 @@ service.destroy(); ## Documentation -The full documentation can be found [here](https://developers.homebridge.io/ciao/globals.html). +The full documentation can be found [here](https://developers.homebridge.io/ciao/modules.html). ### API overview This section links to the most important aspects of the documentation as used in the example above. -First of all the [getResponder](https://developers.homebridge.io/ciao/globals.html#getresponder) function -should be used to get a reference to a [Responder](https://developers.homebridge.io/ciao/classes/responder.html) object. -The function takes some optional [options](https://developers.homebridge.io/ciao/interfaces/mdnsserveroptions.html) +First of all the [getResponder](https://developers.homebridge.io/ciao/functions/getResponder.html) function +should be used to get a reference to a [Responder](https://developers.homebridge.io/ciao/classes/Responder.html) object. +The function takes some optional [options](https://developers.homebridge.io/ciao/interfaces/MDNSServerOptions.html) to configure the underlying mdns server. -The [createService](https://developers.homebridge.io/ciao/classes/responder.html#createservice) method of the `Responder` -object can now be used to create a new [CiaoService](https://developers.homebridge.io/ciao/classes/ciaoservice.html) -supplying the desired [configuration](https://developers.homebridge.io/ciao/interfaces/serviceoptions.html) +The [createService](https://developers.homebridge.io/ciao/classes/Responder.html#createService) method of the `Responder` +object can now be used to create a new [CiaoService](https://developers.homebridge.io/ciao/classes/CiaoService.html) +supplying the desired [configuration](https://developers.homebridge.io/ciao/interfaces/ServiceOptions.html) as the first parameter. You might have a look at the -_[restrictedAddresses](https://developers.homebridge.io/ciao/interfaces/serviceoptions.html#restrictedAddresses)_ -(and _[disableIpv6](https://developers.homebridge.io/ciao/interfaces/serviceoptions.html#disableIpv6)_) configuration +_[restrictedAddresses](https://developers.homebridge.io/ciao/interfaces/ServiceOptions.html#restrictedAddresses)_ +(and _[disabledIpv6](https://developers.homebridge.io/ciao/interfaces/ServiceOptions.html#disabledIpv6)_) configuration if you don't want to advertise on all available addresses/network interfaces. -The [advertise](https://developers.homebridge.io/ciao/classes/ciaoservice.html#advertise) method can now be called +The [advertise](https://developers.homebridge.io/ciao/classes/CiaoService.html#advertise) method can now be called on the `service` object to start advertising the service on the network. -An application should ideally listen to the [NAME_CHANGE](https://developers.homebridge.io/ciao/enums/serviceevent.html#name_changed) +An application should ideally listen to the [NAME_CHANGED](https://developers.homebridge.io/ciao/enums/ServiceEvent.html#NAME_CHANGED) event, in oder to persist any changes happening to the service name resulting of the conflict resolution algorithm. -The method [updateTxt](https://developers.homebridge.io/ciao/classes/ciaoservice.html#updatetxt) can be used +The method [updateTxt](https://developers.homebridge.io/ciao/classes/CiaoService.html#updateTxt) can be used to update the contest of the txt exposed by the service. Any application SHOULD hook up a listener on events like SIGTERM or SIGINT and call the -[shutdown](https://developers.homebridge.io/ciao/classes/responder.html#shutdown) method of the responder object. +[shutdown](https://developers.homebridge.io/ciao/classes/Responder.html#shutdown) method of the responder object. This will ensure, that goodbye packets are sent out on all connected network interfaces and all hosts on the network get instantly notified of the shutdown. Otherwise, stale data will remain in the caches of surrounding mdns browsers. diff --git a/docs/classes/CiaoService.html b/docs/classes/CiaoService.html index 0d6170b..f4cdc04 100644 --- a/docs/classes/CiaoService.html +++ b/docs/classes/CiaoService.html @@ -7,7 +7,7 @@

A CiaoService class is always bound to a Responder and can be created using the Responder.createService method in the Responder class. Once the instance is created, advertise can be called to announce the service on the network.

-

Hierarchy

Methods

Hierarchy

  • EventEmitter
    • CiaoService

Methods

advertise destroy end getFQDN @@ -29,24 +29,24 @@
  • Prober could not find a unique service name while trying for a minute (timeout)
  • One of the announcement packets could not be sent successfully
  • -

    Returns Promise<void>

    • This method must be called if you want to free the memory used by this service. +

      Returns Promise<void>

    • This method must be called if you want to free the memory used by this service. The service instance is not usable anymore after this call.

      If the service is still announced, the service will first be removed from the network by calling end.

      -

      Returns Promise<void>

    • This method will remove the advertisement for the service on all connected network interfaces. +

      Returns Promise<void>

    • This method will remove the advertisement for the service on all connected network interfaces. If the service is still in the Probing state, probing will simply be cancelled.

      Returns Promise<void>

      Promise will resolve once the last goodbye packet was sent out

      -
    • Returns string

      The fully qualified domain name of the service, used to identify the service.

      -
    • Returns string

      The current hostname of the service.

      -
    • Returns undefined | string[]

      Array of subtype pointers (undefined if no subtypes are specified).

      -
    • Returns number

      The port the service is advertising for. +

    • Returns string

      The fully qualified domain name of the service, used to identify the service.

      +
    • Returns string

      The current hostname of the service.

      +
    • Returns undefined | string[]

      Array of subtype pointers (undefined if no subtypes are specified).

      +
    • Returns number

      The port the service is advertising for. {@code -1} is returned when the port is not yet set.

      -
    • Returns string

      The service type pointer.

      -
    • Sets or updates the port of the service. +

    • Returns string

      The service type pointer.

      +
    • Sets or updates the port of the service. A new port number can only be set when the service is still UNANNOUNCED. Otherwise, an assertion error will be thrown.

      Parameters

      • port: number

        The new port number.

        -

      Returns void

    • Sets or updates the txt of the service.

      +

    Returns void

    • Sets or updates the txt of the service.

      Parameters

      • txt: ServiceTxt

        The updated txt record.

      • silent: boolean = false

        If set to true no announcement is sent for the updated record.

        -

      Returns void

    \ No newline at end of file +

    Returns void

    \ No newline at end of file diff --git a/docs/classes/Responder.html b/docs/classes/Responder.html index b9576c2..f8a5be4 100644 --- a/docs/classes/Responder.html +++ b/docs/classes/Responder.html @@ -1,17 +1,17 @@ Responder | @homebridge/ciao - v1.1.8

    A Responder instance represents a running MDNSServer and a set of advertised services.

    It will handle any service related operations, like advertising, sending goodbye packets or sending record updates. It handles answering questions arriving at the multicast address.

    -

    Implements

    • PacketHandler

    Methods

    Implements

    • PacketHandler

    Methods

    • Creates a new CiaoService instance and links it to this Responder instance.

      Parameters

      • options: ServiceOptions

        Defines all information about the service which should be created.

      Returns CiaoService

      The newly created CiaoService instance can be used to advertise and manage the created service.

      -
    • This method should be called when you want to unpublish all service exposed by this Responder. +

    • This method should be called when you want to unpublish all service exposed by this Responder. This method SHOULD be called before the node application exists, so any host on the network is informed of the shutdown of this machine. Calling the shutdown method is mandatory for a clean termination (sending goodbye packets).

      The shutdown method must only be called ONCE.

      Returns Promise<void>

      The Promise resolves once all goodbye packets were sent (or immediately if any other users have a reference to this Responder instance).

      -
    \ No newline at end of file +
    \ No newline at end of file diff --git a/docs/enums/Protocol.html b/docs/enums/Protocol.html index 4f76945..f9f1c17 100644 --- a/docs/enums/Protocol.html +++ b/docs/enums/Protocol.html @@ -2,6 +2,6 @@

    As of RFC 6763 7. TCP must be used for any applications using tcp. For applications using any other transport protocol UDP must be used. This applies to all other transport protocols like SCTP, DCCP, RTMFP, etc

    -

    Enumeration Members

    TCP +

    Enumeration Members

    Enumeration Members

    TCP: "tcp"
    UDP: "udp"
    \ No newline at end of file +

    Enumeration Members

    TCP: "tcp"
    UDP: "udp"
    \ No newline at end of file diff --git a/docs/enums/ServiceEvent.html b/docs/enums/ServiceEvent.html index c6d9839..72bb8be 100644 --- a/docs/enums/ServiceEvent.html +++ b/docs/enums/ServiceEvent.html @@ -1,5 +1,5 @@ ServiceEvent | @homebridge/ciao - v1.1.8

    Enumeration ServiceEventConst

    Events thrown by a CiaoService

    -

    Enumeration Members

    Enumeration Members

    Enumeration Members

    HOSTNAME_CHANGED: "hostname-change"

    Event is called when the Prober identifies that the hostname for the service is already used and thus resolve the name conflict by adjusting the hostname (e.g. adding '(2)' to the hostname). @@ -7,8 +7,8 @@ from the service name if not supplied. If you supply a custom hostname (not automatically derived from the service name) you must hook up a listener to this event in order for the hostname to be persisted.

    -
    NAME_CHANGED: "name-change"

    Event is called when the Prober identifies that the name for the service is already used +

    NAME_CHANGED: "name-change"

    Event is called when the Prober identifies that the name for the service is already used and thus resolve the name conflict by adjusting the name (e.g. adding '(2)' to the name). This change must be persisted and thus a listener must hook up to this event in order for the name to be persisted.

    -
    \ No newline at end of file +
    \ No newline at end of file diff --git a/docs/enums/ServiceType.html b/docs/enums/ServiceType.html index 42be89b..ec4b94e 100644 --- a/docs/enums/ServiceType.html +++ b/docs/enums/ServiceType.html @@ -1,7 +1,7 @@ ServiceType | @homebridge/ciao - v1.1.8

    Enumeration ServiceTypeConst

    This enum defines some commonly used service types. This is also referred to as service name (as of RFC 6763). A service name must not be longer than 15 characters (RFC 6763 7.2).

    -

    Enumeration Members

    Enumeration Members

    Enumeration Members

    AIRDROP: "airdrop"
    AIRPLAY: "airplay"
    AIRPORT: "airport"
    COMPANION_LINK: "companion-link"
    DACP: "dacp"
    DNS_SD: "dns-sd"
    HAP: "hap"
    HOMEKIT: "homekit"
    HTTP: "http"
    HTTP_ALT: "http_alt"
    IPP: "ipp"
    IPPS: "ipps"
    PRINTER: "printer"
    RAOP: "raop"
    TOUCH_ABLE: "touch-able"
    scanner: "scanner"
    \ No newline at end of file +

    Enumeration Members

    AIRDROP: "airdrop"
    AIRPLAY: "airplay"
    AIRPORT: "airport"
    COMPANION_LINK: "companion-link"
    DACP: "dacp"
    DNS_SD: "dns-sd"
    HAP: "hap"
    HOMEKIT: "homekit"
    HTTP: "http"
    HTTP_ALT: "http_alt"
    IPP: "ipp"
    IPPS: "ipps"
    PRINTER: "printer"
    RAOP: "raop"
    TOUCH_ABLE: "touch-able"
    scanner: "scanner"
    \ No newline at end of file diff --git a/docs/functions/getResponder.html b/docs/functions/getResponder.html index f7844ca..3076b2e 100644 --- a/docs/functions/getResponder.html +++ b/docs/functions/getResponder.html @@ -3,4 +3,4 @@ Thus, it will share the same Responder instance for the same set of options.

    Parameters

    Returns Responder

    A Responder instance for the given options. Might be shared with others using the same options.

    -
    \ No newline at end of file +
    \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 8d68d6f..bc80b7f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -29,27 +29,27 @@

    Example

    const ciao = require("@homebridge/ciao");

    const responder = ciao.getResponder();

    // create a service defining a web server running on port 3000
    const service = responder.createService({
    name: 'My Web Server',
    type: 'http',
    port: 3000, // optional, can also be set via updatePort() before advertising
    txt: { // optional
    key: "value",
    }
    })


    service.advertise().then(() => {
    // stuff you do when the service is published
    console.log("Service is published :)");
    });

    // ....

    service.updateTxt({ // replaces current txt
    newKey: "newValue",
    });

    // ....

    service.end().then(() => {
    // service is now UNANNOUNCED and can be published again
    });

    // ....

    // frees the service objects (and calls end() if still announced).
    // The service object cannot be used again afterwards.
    service.destroy();
    -

    Documentation

    The full documentation can be found here.

    +

    Documentation

    The full documentation can be found here.

    API overview

    This section links to the most important aspects of the documentation as used in the example above.

    -

    First of all the getResponder function -should be used to get a reference to a Responder object. -The function takes some optional options +

    First of all the getResponder function +should be used to get a reference to a Responder object. +The function takes some optional options to configure the underlying mdns server.

    -

    The createService method of the Responder -object can now be used to create a new CiaoService -supplying the desired configuration +

    The createService method of the Responder +object can now be used to create a new CiaoService +supplying the desired configuration as the first parameter. You might have a look at the -restrictedAddresses -(and disableIpv6) configuration +restrictedAddresses +(and disabledIpv6) configuration if you don't want to advertise on all available addresses/network interfaces.

    -

    The advertise method can now be called +

    The advertise method can now be called on the service object to start advertising the service on the network. -An application should ideally listen to the NAME_CHANGE +An application should ideally listen to the NAME_CHANGED event, in oder to persist any changes happening to the service name resulting of the conflict resolution algorithm. -The method updateTxt can be used +The method updateTxt can be used to update the contest of the txt exposed by the service.

    Any application SHOULD hook up a listener on events like SIGTERM or SIGINT and call the -shutdown method of the responder object. +shutdown method of the responder object. This will ensure, that goodbye packets are sent out on all connected network interfaces and all hosts on the network get instantly notified of the shutdown. Otherwise, stale data will remain in the caches of surrounding mdns browsers.

    diff --git a/docs/interfaces/MDNSServerOptions.html b/docs/interfaces/MDNSServerOptions.html index 9b63462..a049e81 100644 --- a/docs/interfaces/MDNSServerOptions.html +++ b/docs/interfaces/MDNSServerOptions.html @@ -1,12 +1,12 @@ MDNSServerOptions | @homebridge/ciao - v1.1.8

    Interface MDNSServerOptions

    Defines the options passed to the underlying mdns server.

    -
    interface MDNSServerOptions {
        disableIpv6?: boolean;
        interface?: string | string[];
    }

    Properties

    interface MDNSServerOptions {
        disableIpv6?: boolean;
        interface?: string | string[];
    }

    Properties

    disableIpv6?: boolean

    If specified, the mdns server will not include any ipv6 address records and not bind any udp6 sockets. This is handy if you want to "bind" on 0.0.0.0 only.

    -
    interface?: string | string[]

    If specified, the mdns server will only listen on the specified interfaces (allowlist). +

    interface?: string | string[]

    If specified, the mdns server will only listen on the specified interfaces (allowlist). It can be supplied as a string (representing a single interface) or as an array of strings to define multiple interfaces. The interface can be defined by specifying the interface name (like 'en0') or by specifying an ip address.

    -
    \ No newline at end of file +
    \ No newline at end of file diff --git a/docs/interfaces/ServiceOptions.html b/docs/interfaces/ServiceOptions.html index 0ffc66b..bbbd3c1 100644 --- a/docs/interfaces/ServiceOptions.html +++ b/docs/interfaces/ServiceOptions.html @@ -1,5 +1,5 @@ ServiceOptions | @homebridge/ciao - v1.1.8

    Interface ServiceOptions

    Service options supplied when creating a new ciao service.

    -
    interface ServiceOptions {
        disabledIpv6?: boolean;
        domain?: string;
        hostname?: string;
        name: string;
        port?: number;
        protocol?: Protocol;
        restrictedAddresses?: string[];
        subtypes?: string[];
        txt?: ServiceTxt;
        type: string;
    }

    Properties

    interface ServiceOptions {
        disabledIpv6?: boolean;
        domain?: string;
        hostname?: string;
        name: string;
        port?: number;
        protocol?: Protocol;
        restrictedAddresses?: string[];
        subtypes?: string[];
        txt?: ServiceTxt;
        type: string;
    }

    Properties

    disabledIpv6? domain? hostname? name @@ -12,16 +12,16 @@

    Properties

    disabledIpv6?: boolean

    The service won't advertise ipv6 address records. This can be used to simulate binding on 0.0.0.0. May be combined with restrictedAddresses.

    -
    domain?: string

    Adds ability to set custom domain. Will default to "local". +

    domain?: string

    Adds ability to set custom domain. Will default to "local". The domain will also be automatically appended to the hostname.

    -
    hostname?: string

    Defines a hostname under which the service can be reached. +

    hostname?: string

    Defines a hostname under which the service can be reached. The specified hostname must not include the TLD. If undefined the service name will be used as default.

    -
    name: string

    Instance name of the service

    -
    port?: number

    Port of the service. +

    name: string

    Instance name of the service

    +
    port?: number

    Port of the service. If not supplied it must be set later via updatePort BEFORE advertising the service.

    -
    protocol?: Protocol

    The protocol the service uses. Default is TCP.

    -
    restrictedAddresses?: string[]

    If defined it restricts the service to be advertised on the specified +

    protocol?: Protocol

    The protocol the service uses. Default is TCP.

    +
    restrictedAddresses?: string[]

    If defined it restricts the service to be advertised on the specified ip addresses or interface names.

    If an interface name is specified, ANY address on that given interface will be advertised (if an IP address of the given interface is also given in the array, it will be overridden). @@ -30,8 +30,8 @@ If an ip address is given, the ip address must be valid at the time of service creation.

    If the service is set to advertise on a given interface, though the MDNSServer is configured to ignore this interface, the service won't be advertised on the interface.

    -
    subtypes?: string[]

    Optional array of subtypes of the service. +

    subtypes?: string[]

    Optional array of subtypes of the service. Refer to ServiceType for some known examples.

    -

    If defined, a txt record will be published with the given service.

    -
    type: string

    Type of the service.

    -
    \ No newline at end of file +
    txt?: ServiceTxt

    If defined, a txt record will be published with the given service.

    +
    type: string

    Type of the service.

    +
    \ No newline at end of file diff --git a/docs/types/ResponderOptions.html b/docs/types/ResponderOptions.html index 26109c6..4bd262d 100644 --- a/docs/types/ResponderOptions.html +++ b/docs/types/ResponderOptions.html @@ -1 +1 @@ -ResponderOptions | @homebridge/ciao - v1.1.8

    Type alias ResponderOptions

    ResponderOptions: {} & MDNSServerOptions

    Type declaration

      \ No newline at end of file +ResponderOptions | @homebridge/ciao - v1.1.8

      Type alias ResponderOptions

      ResponderOptions: {} & MDNSServerOptions

      Type declaration

        \ No newline at end of file diff --git a/docs/types/ServiceTxt.html b/docs/types/ServiceTxt.html index 0337ac9..73973bf 100644 --- a/docs/types/ServiceTxt.html +++ b/docs/types/ServiceTxt.html @@ -1,3 +1,3 @@ ServiceTxt | @homebridge/ciao - v1.1.8

        Type alias ServiceTxt

        ServiceTxt: Record<string, any>

        A service txt consist of multiple key=value pairs, which get advertised on the network.

        -
        \ No newline at end of file +
        \ No newline at end of file diff --git a/docs/variables/default.html b/docs/variables/default.html index ad8a439..f76c6d2 100644 --- a/docs/variables/default.html +++ b/docs/variables/default.html @@ -3,4 +3,4 @@ Thus, it will share the same Responder instance for the same set of options.

        Parameters

        Returns Responder

        A Responder instance for the given options. Might be shared with others using the same options.

        -
        \ No newline at end of file +
        \ No newline at end of file