esdee - v1.0.0

esdee

Provides the base functionality for DNS-SD discovery and Selector-based functions to listen to discovery messages. For an actor-based discovery client, see discoverer.

Types

Options

opaque </>

Holds the options for DNS-SD discovery.

pub opaque type Options

ServiceDescription

</>

Describes a service fully discovered via DNS-SD. Note that the same service might be discovered through both IPv4 and IPv6.

pub type ServiceDescription {
  ServiceDescription(
    service_type: String,
    instance_name: String,
    target_name: String,
    priority: Int,
    weight: Int,
    port: Int,
    txt_values: List(String),
    ip: glip.IpAddress,
  )
}

Constructors 

  • ServiceDescription(
  service_type: String,
  instance_name: String,
  target_name: String,
  priority: Int,
  weight: Int,
  port: Int,
  txt_values: List(String),
  ip: glip.IpAddress,
)

    Arguments

    service_type

    The service type string, e.g. _googlecast._tcp.local

    instance_name

    The unique instance name for a peer providing the service, e.g. SHIELD-Android-TV-9693d58e3537dddb118b7b7d17f9c1c2._googlecast._tcp.local

    target_name

    The target host name, which can be used to actually connect to the service, e.g. 9693d58e-3537-dddb-118b-7b7d17f9c1c2.local

    priority

    The priority of the target host, lower value means more preferred. Originates from the SRV record.

    weight

    A relative weight for records with the same priority, higher value means higher chance of getting picked. Originates from the SRV record.

    port

    The port the service is served on.

    txt_values

    Any TXT records that the service advertises (can be empty).

    ip

    The resolved IP address

ServiceDiscveryUpdate

</>

The result of successfully parsing a UDP datagram into a DNS-SD update.

pub type ServiceDiscveryUpdate {
  ServiceTypeDiscovered(String)
  ServiceDiscovered(ServiceDescription)
}

Constructors

SocketSetupError

</>

An error that can happen while setting up the UDP sockets.

pub type SocketSetupError {
  NoAddressFamilyEnabled
  FailedToOpenSocket(glip.AddressFamily)
  FailedToJoinMulticastGroup
  SetActiveModeFailed
}

Constructors 

  • NoAddressFamilyEnabled

    The options had no address family selected

  • FailedToOpenSocket(glip.AddressFamily)

    Opening the socket failed

  • FailedToJoinMulticastGroup

    Joining the multicast group failed (only relevant for IPv4)

  • SetActiveModeFailed

    Setting the socket(s) to active mode failed

Sockets

opaque </>

The collection of sockets used for service discovery (one for each address family used)

pub opaque type Sockets

UdpMessage

</>

A UDP message, which has either been parsed into a DNS-SD update, or was not recognised and is passed along unmodified.

pub type UdpMessage {
  DnsSdMessage(ServiceDiscveryUpdate)
  OtherUdpMessage(toss.UdpMessage)
}

Constructors

Values

all_services_type

</> 
pub const all_services_type: String

The meta-service type for polling for all services (_services._dns-sd._udp.local).

broadcast_service_question

</> 
pub fn broadcast_service_question(
  sockets: Sockets,
  service_type: String,
) -> Result(Nil, toss.Error)

Broadcasts the DNS-SD question for the given service type.

classify_message

</> 
pub fn classify_message(message: toss.UdpMessage) -> UdpMessage

Classifies a UDP message to determine if it is related to DNS-SD.

close_sockets

</> 
pub fn close_sockets(sockets: Sockets) -> Nil

Closes all the sockets in the socket collection.

describe_setup_error

</> 
pub fn describe_setup_error(error: SocketSetupError) -> String

Converts a setup error value to a description string.

new

</> 
pub fn new() -> Options

Create default options for DNS-SD discovery. Can be used either with a full-fledged actor implementation which can be found in the discoverer module, or used with the set_up_sockets function.

parse_sd_update

</> 
pub fn parse_sd_update(
  data: BitArray,
) -> Result(ServiceDiscveryUpdate, Nil)

Parses the contents of a UDP datagram into a DNS-SD update, or returns an error, if the data was not a DNS-SD update, or had incomplete data. If you don’t want to use toss for IO, this function can be used directly to parse DNS-SD data. (Note: if you have a use case for this, and would prefer it to be in a separate package, please open an issue on GitHub!)

receive_next_datagram_as_message

</> 
pub fn receive_next_datagram_as_message(
  sockets: Sockets,
) -> Result(Nil, toss.Error)

Sets the underlying sockets to receive the next datagram as a message. See toss.receive_next_datagram_as_message for details.

select_processed_udp_messages

</> 
pub fn select_processed_udp_messages(
  selector: process.Selector(a),
  mapper: fn(UdpMessage) -> a,
) -> process.Selector(a)

Configure a selector to receive messages from UDP sockets, pre-processing them to separate DNS-SD messages from other messages. You will also need to call receive_next_datagram_as_message to use the selector successfully - once initially, and again after receiving each message.

Note that this will receive messages from all gen_udp sockets that the process controls, rather than any specific one. If you wish to only handle messages from one socket then use one process per socket.

set_up_sockets

</> 
pub fn set_up_sockets(
  options: Options,
) -> Result(Sockets, SocketSetupError)

Opens and sets up the service discovery UDP socket(s).

use_address_families

</> 
pub fn use_address_families(
  options: Options,
  families: List(glip.AddressFamily),
) -> Options

Sets the used address families explicitly

use_ipv4

</> 
pub fn use_ipv4(options: Options, enabled: Bool) -> Options

Sets whether IPv4 will be used. True by default.

use_ipv6

</> 
pub fn use_ipv6(options: Options, enabled: Bool) -> Options

Sets whether IPv6 will be used. False by default.

with_max_data_size

</> 
pub fn with_max_data_size(
  options: Options,
  max_data_size: Int,
) -> Options

Configures the maximum data size when receiving UDP datagrams. Affects UDP performance, 8 KiB by default.

✨ Search Document