Introduction to DNS Service Discovery

This document describes how to use the DNS Service Discovery API in your program.

The DNS Service Discovery API helps you to perform three main tasks:

In support of these main tasks, this API can directly assist you in performing two subsidiary tasks:

The DNS Service Discovery API is part of Bonjour, Apple’s implementation of zero-configuration networking (ZEROCONF). For an overview of how Bonjour works, please read Bonjour Overview prior to using DNS Service Discovery.

Who Should Read This Document?

This document is meant for developers who want to use Bonjour in their applications. There are a number of reasons to use the DNS Service Discovery API over the Network Services APIs (NSNetServices and CFNetServices):

If none of those features are necessary for your program, it is highly recommended that you take a look at NSNetService and CFNetService first.

Organization of This Document

This document contains the following articles:

Before You Start

The next few paragraphs describe some things you should know about this API before attempting any of the tasks.

Most functions in this API do not return all of their data using their function return or parameter block. Instead, they require you to provide a callback function that can handle data sent asynchronously.

Your callback function may be called multiple times in response to a single function call on your part. For example, you might request a list of available services. Your callback would be called once for each available service that matches your request, then called again whenever a matching service is added or removed.

Some functions return error codes in the usual way, but many do not. In these cases, any error code and status flags are sent to your callback function as part of the asynchronous reply, along with—or instead of—any returned data.

Most of the functions in this API use a common set of parameters to describe services. You will need to supply some or all of these parameters, depending on the purpose of your call. In many cases, you will provide some parameters, such as the domain and type of service, and your callback function will receive data corresponding to other parameters, such as the service name of a matching service.

Here is a list of the common parameters required by the DNS Service Discovery API:

Requirements

The DNS Service Discovery API requires the services of the mDNSResponder daemon. OS X (version 10.2 and later) and iOS include an mDNSResponder daemon as part of the operating system. Apple also provides the source code for its mDNSResponder daemon on Apple's Open Source site. This API is also available in Bonjour for Windows and (if mDNSResponder is installed) in the Linux, Solaris, and FreeBSD operating systems.

Limitations

The DNS Service Discovery API does not perform network access setup for services. Similarly, the DNS Service Discovery API does not provide a network connection from an application to a service. It allows applications to browse for services, or to ask for them by name, and provides the IP address, port, and so on. You can use BSD sockets to connect to a service over the network.

For More Information

For additional information on Bonjour, including links to standards, specifications, and resources, see http://developer.apple.com/networking/bonjour and read Bonjour Overview.

Documentation on the Java-based DNS Service Discovery API is available at DNS Service Discovery Java Reference.

For information on dynamic update and shared secrets, see http://www.ietf.org/rfc/rfc2136.txt and http://www.ietf.org/rfc/rfc2845.txt, respectively.

For information Network Address Translation (NAT), see http://www.ietf.org/rfc/rfc3022.txt, and for information on automatic NAT port mapping, see http://files.dns-sd.org/draft-nat-port-mapping.txt.

For sample code, download the mDNSResponder source code at Apple's Open Source site.