com.apple.dnssd
Class DNSSD

java.lang.Object
  extended by com.apple.dnssd.DNSSD

public abstract class DNSSD
extends java.lang.Object

DNSSD provides access to DNS Service Discovery features of ZeroConf networking.

It is a factory class that is used to invoke registration and discovery-related operations. Most operations are non-blocking; clients are called back through an interface with the result of an operation. Callbacks are made from a separate worker thread.

For example, in this program


    class   MyClient implements BrowseListener {
        void    lookForWebServers() {
            myBrowser = DNSSD.browse("_http_.tcp", this);
        }

        public void serviceFound(DNSSDService browser, int flags, int ifIndex, 
                            String serviceName, String regType, String domain) {}
        ... 
    }
MyClient.serviceFound() would be called for every HTTP server discovered in the default browse domain(s).


Field Summary
static int ALL_INTERFACES
          Pass for ifIndex to specify all available interfaces.
static int BROWSE_DOMAINS
          Set flag when calling enumerateDomains() to restrict results to domains recommended for browsing.
static int DEFAULT
          If flag is set in a DomainListener callback, indicates that the result is the default domain.
static int LOCALHOST_ONLY
          Pass for ifIndex to specify the localhost interface.
static int MAX_DOMAIN_NAME
          Maximum length, in bytes, of a domain name represented as an escaped C-String.
static int MORE_COMING
          Flag indicates to a BrowseListener that another result is queued.
static int NO_AUTO_RENAME
          If flag is set, a name conflict will trigger an exception when registering non-shared records.
static int REGISTRATION_DOMAINS
          Set flag when calling enumerateDomains() to restrict results to domains recommended for registration.
static int SHARED
          If flag is set, allow multiple records with this name on the network (e.g.
static int UNIQUE
          If flag is set, records with this name must be unique on the network (e.g.
 
Method Summary
static DNSSDService browse(int flags, int ifIndex, java.lang.String regType, java.lang.String domain, BrowseListener listener)
          Browse for instances of a service.
static DNSSDService browse(java.lang.String regType, BrowseListener listener)
          Browse for instances of a service.
static java.lang.String constructFullName(java.lang.String serviceName, java.lang.String regType, java.lang.String domain)
          Concatenate a three-part domain name (as provided to the listeners) into a properly-escaped full domain name.
static DNSSDRecordRegistrar createRecordRegistrar(RegisterRecordListener listener)
          Create a DNSSDRecordRegistrar allowing efficient registration of multiple individual records.
static DNSSDService enumerateDomains(int flags, int ifIndex, DomainListener listener)
          Asynchronously enumerate domains available for browsing and registration.
static int getIfIndexForName(java.lang.String ifName)
          Return the index of a named interface.
static java.lang.String getNameForIfIndex(int ifIndex)
          Return the canonical name of a particular interface index.
static DNSSDService queryRecord(int flags, int ifIndex, java.lang.String serviceName, int rrtype, int rrclass, QueryListener listener)
          Query for an arbitrary DNS record.
static void reconfirmRecord(int flags, int ifIndex, java.lang.String fullName, int rrtype, int rrclass, byte[] rdata)
          Instruct the daemon to verify the validity of a resource record that appears to be out of date.
static DNSSDRegistration register(int flags, int ifIndex, java.lang.String serviceName, java.lang.String regType, java.lang.String domain, java.lang.String host, int port, TXTRecord txtRecord, RegisterListener listener)
          Register a service, to be discovered via browse() and resolve() calls.
static DNSSDRegistration register(java.lang.String serviceName, java.lang.String regType, int port, RegisterListener listener)
          Register a service, to be discovered via browse() and resolve() calls.
static DNSSDService resolve(int flags, int ifIndex, java.lang.String serviceName, java.lang.String regType, java.lang.String domain, ResolveListener listener)
          Resolve a service name discovered via browse() to a target host name, port number, and txt record.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MORE_COMING

public static final int MORE_COMING
Flag indicates to a BrowseListener that another result is queued. Applications should not update their UI to display browse results if the MORE_COMING flag is set; they will be called at least once more with the flag clear.

See Also:
Constant Field Values

DEFAULT

public static final int DEFAULT
If flag is set in a DomainListener callback, indicates that the result is the default domain.

See Also:
Constant Field Values

NO_AUTO_RENAME

public static final int NO_AUTO_RENAME
If flag is set, a name conflict will trigger an exception when registering non-shared records.

A name must be explicitly specified when registering a service if this bit is set (i.e. the default name may not not be used).

See Also:
Constant Field Values

SHARED

public static final int SHARED
If flag is set, allow multiple records with this name on the network (e.g. PTR records) when registering individual records on a DNSSDRegistration.

See Also:
Constant Field Values

UNIQUE

public static final int UNIQUE
If flag is set, records with this name must be unique on the network (e.g. SRV records).

See Also:
Constant Field Values

BROWSE_DOMAINS

public static final int BROWSE_DOMAINS
Set flag when calling enumerateDomains() to restrict results to domains recommended for browsing.

See Also:
Constant Field Values

REGISTRATION_DOMAINS

public static final int REGISTRATION_DOMAINS
Set flag when calling enumerateDomains() to restrict results to domains recommended for registration.

See Also:
Constant Field Values

MAX_DOMAIN_NAME

public static final int MAX_DOMAIN_NAME
Maximum length, in bytes, of a domain name represented as an escaped C-String.

See Also:
Constant Field Values

ALL_INTERFACES

public static final int ALL_INTERFACES
Pass for ifIndex to specify all available interfaces.

See Also:
Constant Field Values

LOCALHOST_ONLY

public static final int LOCALHOST_ONLY
Pass for ifIndex to specify the localhost interface.

See Also:
Constant Field Values
Method Detail

browse

public static DNSSDService browse(int flags,
                                  int ifIndex,
                                  java.lang.String regType,
                                  java.lang.String domain,
                                  BrowseListener listener)
                           throws DNSSDException
Browse for instances of a service.

Note: browsing consumes network bandwidth. Call DNSSDService.stop() when you have finished browsing.

Parameters:
flags - Currently ignored, reserved for future use.

ifIndex - If non-zero, specifies the interface on which to browse for services (the index for a given interface is determined via the if_nametoindex() family of calls.) Most applications will pass 0 to browse on all available interfaces. Pass -1 to only browse for services provided on the local host.

regType - The registration type being browsed for followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".

domain - If non-null, specifies the domain on which to browse for services. Most applications will not specify a domain, instead browsing on the default domain(s).

listener - This object will get called when instances of the service are discovered (or disappear).

Returns:
A DNSSDService that represents the active browse operation.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
DNSSDException
See Also:
RuntimePermission

browse

public static DNSSDService browse(java.lang.String regType,
                                  BrowseListener listener)
                           throws DNSSDException
Browse for instances of a service. Use default flags, ifIndex and domain.

Parameters:
regType - The registration type being browsed for followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".

listener - This object will get called when instances of the service are discovered (or disappear).

Returns:
A DNSSDService that represents the active browse operation.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
DNSSDException
See Also:
RuntimePermission

resolve

public static DNSSDService resolve(int flags,
                                   int ifIndex,
                                   java.lang.String serviceName,
                                   java.lang.String regType,
                                   java.lang.String domain,
                                   ResolveListener listener)
                            throws DNSSDException
Resolve a service name discovered via browse() to a target host name, port number, and txt record.

Note: Applications should NOT use resolve() solely for txt record monitoring - use queryRecord() instead, as it is more efficient for this task.

Note: When the desired results have been returned, the client MUST terminate the resolve by calling DNSSDService.stop().

Note: resolve() behaves correctly for typical services that have a single SRV record and a single TXT record (the TXT record may be empty.) To resolve non-standard services with multiple SRV or TXT records, use queryRecord().

Parameters:
flags - Currently ignored, reserved for future use.

ifIndex - The interface on which to resolve the service. The client should pass the interface on which the serviceName was discovered (i.e. the ifIndex passed to the serviceFound() callback) or 0 to resolve the named service on all available interfaces.

serviceName - The servicename to be resolved.

regType - The registration type being resolved followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".

domain - The domain on which the service is registered, i.e. the domain passed to the serviceFound() callback.

listener - This object will get called when the service is resolved.

Returns:
A DNSSDService that represents the active resolve operation.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
DNSSDException
See Also:
RuntimePermission

register

public static DNSSDRegistration register(int flags,
                                         int ifIndex,
                                         java.lang.String serviceName,
                                         java.lang.String regType,
                                         java.lang.String domain,
                                         java.lang.String host,
                                         int port,
                                         TXTRecord txtRecord,
                                         RegisterListener listener)
                                  throws DNSSDException
Register a service, to be discovered via browse() and resolve() calls.

Parameters:
flags - Possible values are: NO_AUTO_RENAME.

ifIndex - If non-zero, specifies the interface on which to register the service (the index for a given interface is determined via the if_nametoindex() family of calls.) Most applications will pass 0 to register on all available interfaces. Pass -1 to register a service only on the local machine (service will not be visible to remote hosts).

serviceName - If non-null, specifies the service name to be registered. Applications need not specify a name, in which case the computer name is used (this name is communicated to the client via the serviceRegistered() callback).

regType - The registration type being registered followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".

domain - If non-null, specifies the domain on which to advertise the service. Most applications will not specify a domain, instead automatically registering in the default domain(s).

host - If non-null, specifies the SRV target host name. Most applications will not specify a host, instead automatically using the machine's default host name(s). Note that specifying a non-null host does NOT create an address record for that host - the application is responsible for ensuring that the appropriate address record exists, or creating it via DNSSDRegistration.addRecord(int, int, byte[], int).

port - The port on which the service accepts connections. Pass 0 for a "placeholder" service (i.e. a service that will not be discovered by browsing, but will cause a name conflict if another client tries to register that same name.) Most clients will not use placeholder services.

txtRecord - The txt record rdata. May be null. Note that a non-null txtRecord MUST be a properly formatted DNS TXT record, i.e. <length byte> <data> <length byte> <data> ...

listener - This object will get called when the service is registered.

Returns:
A DNSSDRegistration that controls the active registration.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
DNSSDException
See Also:
RuntimePermission

register

public static DNSSDRegistration register(java.lang.String serviceName,
                                         java.lang.String regType,
                                         int port,
                                         RegisterListener listener)
                                  throws DNSSDException
Register a service, to be discovered via browse() and resolve() calls. Use default flags, ifIndex, domain, host and txtRecord.

Parameters:
serviceName - If non-null, specifies the service name to be registered. Applications need not specify a name, in which case the computer name is used (this name is communicated to the client via the serviceRegistered() callback).

regType - The registration type being registered followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".

port - The port on which the service accepts connections. Pass 0 for a "placeholder" service (i.e. a service that will not be discovered by browsing, but will cause a name conflict if another client tries to register that same name.) Most clients will not use placeholder services.

listener - This object will get called when the service is registered.

Returns:
A DNSSDRegistration that controls the active registration.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
DNSSDException
See Also:
RuntimePermission

createRecordRegistrar

public static DNSSDRecordRegistrar createRecordRegistrar(RegisterRecordListener listener)
                                                  throws DNSSDException
Create a DNSSDRecordRegistrar allowing efficient registration of multiple individual records.

Returns:
A DNSSDRecordRegistrar that can be used to register records.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
DNSSDException
See Also:
RuntimePermission

queryRecord

public static DNSSDService queryRecord(int flags,
                                       int ifIndex,
                                       java.lang.String serviceName,
                                       int rrtype,
                                       int rrclass,
                                       QueryListener listener)
                                throws DNSSDException
Query for an arbitrary DNS record.

Parameters:
flags - Possible values are: MORE_COMING.

ifIndex - If non-zero, specifies the interface on which to issue the query (the index for a given interface is determined via the if_nametoindex() family of calls.) Passing 0 causes the name to be queried for on all interfaces. Passing -1 causes the name to be queried for only on the local host.

serviceName - The full domain name of the resource record to be queried for.

rrtype - The numerical type of the resource record to be queried for (e.g. PTR, SRV, etc) as defined in nameser.h.

rrclass - The class of the resource record, as defined in nameser.h (usually 1 for the Internet class).

listener - This object will get called when the query completes.

Returns:
A DNSSDService that controls the active query.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
DNSSDException
See Also:
RuntimePermission

enumerateDomains

public static DNSSDService enumerateDomains(int flags,
                                            int ifIndex,
                                            DomainListener listener)
                                     throws DNSSDException
Asynchronously enumerate domains available for browsing and registration.

Currently, the only domain returned is "local.", but other domains will be returned in future.

The enumeration MUST be cancelled by calling DNSSDService.stop() when no more domains are to be found.

Parameters:
flags - Possible values are: BROWSE_DOMAINS, REGISTRATION_DOMAINS.

ifIndex - If non-zero, specifies the interface on which to look for domains. (the index for a given interface is determined via the if_nametoindex() family of calls.) Most applications will pass 0 to enumerate domains on all interfaces.

listener - This object will get called when domains are found.

Returns:
A DNSSDService that controls the active enumeration.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
DNSSDException
See Also:
RuntimePermission

constructFullName

public static java.lang.String constructFullName(java.lang.String serviceName,
                                                 java.lang.String regType,
                                                 java.lang.String domain)
                                          throws DNSSDException
Concatenate a three-part domain name (as provided to the listeners) into a properly-escaped full domain name. Note that strings passed to listeners are ALREADY ESCAPED where necessary.

Parameters:
serviceName - The service name - any dots or slashes must NOT be escaped. May be null (to construct a PTR record name, e.g. "_ftp._tcp.apple.com").

regType - The registration type followed by the protocol, separated by a dot (e.g. "_ftp._tcp").

domain - The domain name, e.g. "apple.com". Any literal dots or backslashes must be escaped.

Returns:
The full domain name.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
DNSSDException
See Also:
RuntimePermission

reconfirmRecord

public static void reconfirmRecord(int flags,
                                   int ifIndex,
                                   java.lang.String fullName,
                                   int rrtype,
                                   int rrclass,
                                   byte[] rdata)
Instruct the daemon to verify the validity of a resource record that appears to be out of date. (e.g. because tcp connection to a service's target failed.)

Causes the record to be flushed from the daemon's cache (as well as all other daemons' caches on the network) if the record is determined to be invalid.

Parameters:
flags - Currently unused, reserved for future use.

ifIndex - If non-zero, specifies the interface on which to reconfirm the record (the index for a given interface is determined via the if_nametoindex() family of calls.) Passing 0 causes the name to be reconfirmed on all interfaces. Passing -1 causes the name to be reconfirmed only on the local host.

fullName - The resource record's full domain name.

rrtype - The resource record's type (e.g. PTR, SRV, etc) as defined in nameser.h.

rrclass - The class of the resource record, as defined in nameser.h (usually 1).

rdata - The raw rdata of the resource record.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
See Also:
RuntimePermission

getNameForIfIndex

public static java.lang.String getNameForIfIndex(int ifIndex)
Return the canonical name of a particular interface index.

Parameters:
ifIndex - A valid interface index. Must not be ALL_INTERFACES.

Returns:
The name of the interface, which should match java.net.NetworkInterface.getName().
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
See Also:
RuntimePermission

getIfIndexForName

public static int getIfIndexForName(java.lang.String ifName)
Return the index of a named interface.

Parameters:
ifName - A valid interface name. An example is java.net.NetworkInterface.getName().

Returns:
The interface index.
Throws:
java.lang.SecurityException - If a security manager is present and denies RuntimePermission("getDNSSDInstance").
See Also:
RuntimePermission