Android APIs
public final class

NsdManager

extends Object
java.lang.Object
   ↳ android.net.nsd.NsdManager

Class Overview

The Network Service Discovery Manager class provides the API to discover services on a network. As an example, if device A and device B are connected over a Wi-Fi network, a game registered on device A can be discovered by a game on device B. Another example use case is an application discovering printers on the network.

The API currently supports DNS based service discovery and discovery is currently limited to a local network over Multicast DNS. DNS service discovery is described at http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt

The API is asynchronous and responses to requests from an application are on listener callbacks on a seperate thread.

There are three main operations the API supports - registration, discovery and resolution.

                          Application start
                                 |
                                 |
                                 |                  onServiceRegistered()
                     Register any local services  /
                      to be advertised with       \
                       registerService()            onRegistrationFailed()
                                 |
                                 |
                          discoverServices()
                                 |
                      Maintain a list to track
                        discovered services
                                 |
                                 |--------->
                                 |          |
                                 |      onServiceFound()
                                 |          |
                                 |     add service to list
                                 |          |
                                 |<----------
                                 |
                                 |--------->
                                 |          |
                                 |      onServiceLost()
                                 |          |
                                 |   remove service from list
                                 |          |
                                 |<----------
                                 |
                                 |
                                 | Connect to a service
                                 | from list ?
                                 |
                          resolveService()
                                 |
                         onServiceResolved()
                                 |
                     Establish connection to service
                     with the host and port information

 
An application that needs to advertise itself over a network for other applications to discover it can do so with a call to registerService(NsdServiceInfo, int, NsdManager.RegistrationListener). If Example is a http based application that can provide HTML data to peer services, it can register a name "Example" with service type "_http._tcp". A successful registration is notified with a callback to onServiceRegistered(NsdServiceInfo) and a failure to register is notified over onRegistrationFailed(NsdServiceInfo, int)

A peer application looking for http services can initiate a discovery for "_http._tcp" with a call to discoverServices(String, int, NsdManager.DiscoveryListener). A service found is notified with a callback to onServiceFound(NsdServiceInfo) and a service lost is notified on onServiceLost(NsdServiceInfo).

Once the peer application discovers the "Example" http srevice, and needs to receive data from the "Example" application, it can initiate a resolve with resolveService(NsdServiceInfo, NsdManager.ResolveListener) to resolve the host and port details for the purpose of establishing a connection. A successful resolve is notified on onServiceResolved(NsdServiceInfo) and a failure is notified on onResolveFailed(NsdServiceInfo, int). Applications can reserve for a service type at http://www.iana.org/form/ports-service. Existing services can be found at http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml Get an instance of this class by calling Context.getSystemService(Context.NSD_SERVICE).

See also:

Summary

Nested Classes
interface NsdManager.DiscoveryListener Interface for callback invocation for service discovery  
interface NsdManager.RegistrationListener Interface for callback invocation for service registration  
interface NsdManager.ResolveListener Interface for callback invocation for service resolution  
Constants
String ACTION_NSD_STATE_CHANGED Broadcast intent action to indicate whether network service discovery is enabled or disabled.
String EXTRA_NSD_STATE The lookup key for an int that indicates whether network service discovery is enabled or disabled.
int FAILURE_ALREADY_ACTIVE Indicates that the operation failed because it is already active.
int FAILURE_INTERNAL_ERROR Failures are passed with onRegistrationFailed(NsdServiceInfo, int), onUnregistrationFailed(NsdServiceInfo, int), onStartDiscoveryFailed(String, int), onStopDiscoveryFailed(String, int) or onResolveFailed(NsdServiceInfo, int).
int FAILURE_MAX_LIMIT Indicates that the operation failed because the maximum outstanding requests from the applications have reached.
int NSD_STATE_DISABLED Network service discovery is disabled
int NSD_STATE_ENABLED Network service discovery is enabled
int PROTOCOL_DNS_SD Dns based service discovery protocol
Public Methods
void discoverServices(String serviceType, int protocolType, NsdManager.DiscoveryListener listener)
Initiate service discovery to browse for instances of a service type.
void registerService(NsdServiceInfo serviceInfo, int protocolType, NsdManager.RegistrationListener listener)
Register a service to be discovered by other services.
void resolveService(NsdServiceInfo serviceInfo, NsdManager.ResolveListener listener)
Resolve a discovered service.
void stopServiceDiscovery(NsdManager.DiscoveryListener listener)
Stop service discovery initiated with discoverServices(String, int, NsdManager.DiscoveryListener).
void unregisterService(NsdManager.RegistrationListener listener)
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_NSD_STATE_CHANGED

Added in API level 16

Broadcast intent action to indicate whether network service discovery is enabled or disabled. An extra EXTRA_NSD_STATE provides the state information as int.

See also:

Constant Value: "android.net.nsd.STATE_CHANGED"

public static final String EXTRA_NSD_STATE

Added in API level 16

The lookup key for an int that indicates whether network service discovery is enabled or disabled. Retrieve it with getIntExtra(String, int).

Constant Value: "nsd_state"

public static final int FAILURE_ALREADY_ACTIVE

Added in API level 16

Indicates that the operation failed because it is already active.

Constant Value: 3 (0x00000003)

public static final int FAILURE_INTERNAL_ERROR

Added in API level 16

Failures are passed with onRegistrationFailed(NsdServiceInfo, int), onUnregistrationFailed(NsdServiceInfo, int), onStartDiscoveryFailed(String, int), onStopDiscoveryFailed(String, int) or onResolveFailed(NsdServiceInfo, int). Indicates that the operation failed due to an internal error.

Constant Value: 0 (0x00000000)

public static final int FAILURE_MAX_LIMIT

Added in API level 16

Indicates that the operation failed because the maximum outstanding requests from the applications have reached.

Constant Value: 4 (0x00000004)

public static final int NSD_STATE_DISABLED

Added in API level 16

Network service discovery is disabled

Constant Value: 1 (0x00000001)

public static final int NSD_STATE_ENABLED

Added in API level 16

Network service discovery is enabled

Constant Value: 2 (0x00000002)

public static final int PROTOCOL_DNS_SD

Added in API level 16

Dns based service discovery protocol

Constant Value: 1 (0x00000001)

Public Methods

public void discoverServices (String serviceType, int protocolType, NsdManager.DiscoveryListener listener)

Added in API level 16

Initiate service discovery to browse for instances of a service type. Service discovery consumes network bandwidth and will continue until the application calls stopServiceDiscovery(NsdManager.DiscoveryListener).

The function call immediately returns after sending a request to start service discovery to the framework. The application is notified of a success to initiate discovery through the callback onDiscoveryStarted(String) or a failure through onStartDiscoveryFailed(String, int).

Upon successful start, application is notified when a service is found with onServiceFound(NsdServiceInfo) or when a service is lost with onServiceLost(NsdServiceInfo).

Upon failure to start, service discovery is not active and application does not need to invoke stopServiceDiscovery(NsdManager.DiscoveryListener)

The application should call stopServiceDiscovery(NsdManager.DiscoveryListener) when discovery of this service type is no longer required, and/or whenever the application is paused or stopped.

Parameters
serviceType String: The service type being discovered. Examples include "_http._tcp" for http services or "_ipp._tcp" for printers
protocolType int: The service discovery protocol
listener NsdManager.DiscoveryListener: The listener notifies of a successful discovery and is used to stop discovery on this serviceType through a call on stopServiceDiscovery(NsdManager.DiscoveryListener). Cannot be null. Cannot be in use for an active service discovery.

public void registerService (NsdServiceInfo serviceInfo, int protocolType, NsdManager.RegistrationListener listener)

Added in API level 16

Register a service to be discovered by other services.

The function call immediately returns after sending a request to register service to the framework. The application is notified of a successful registration through the callback onServiceRegistered(NsdServiceInfo) or a failure through onRegistrationFailed(NsdServiceInfo, int).

The application should call unregisterService(NsdManager.RegistrationListener) when the service registration is no longer required, and/or whenever the application is stopped.

Parameters
serviceInfo NsdServiceInfo: The service being registered
protocolType int: The service discovery protocol
listener NsdManager.RegistrationListener: The listener notifies of a successful registration and is used to unregister this service through a call on unregisterService(NsdManager.RegistrationListener). Cannot be null. Cannot be in use for an active service registration.

public void resolveService (NsdServiceInfo serviceInfo, NsdManager.ResolveListener listener)

Added in API level 16

Resolve a discovered service. An application can resolve a service right before establishing a connection to fetch the IP and port details on which to setup the connection.

Parameters
serviceInfo NsdServiceInfo: service to be resolved
listener NsdManager.ResolveListener: to receive callback upon success or failure. Cannot be null. Cannot be in use for an active service resolution.

public void stopServiceDiscovery (NsdManager.DiscoveryListener listener)

Added in API level 16

Stop service discovery initiated with discoverServices(String, int, NsdManager.DiscoveryListener). An active service discovery is notified to the application with onDiscoveryStarted(String) and it stays active until the application invokes a stop service discovery. A successful stop is notified to with a call to onDiscoveryStopped(String).

Upon failure to stop service discovery, application is notified through onStopDiscoveryFailed(String, int).

Parameters
listener NsdManager.DiscoveryListener: This should be the listener object that was passed to discoverServices(String, int, NsdManager.DiscoveryListener). It identifies the discovery that should be stopped and notifies of a successful or unsuccessful stop. In API versions 20 and above, the listener object may be used for another service discovery once the callback has been called. In API versions <= 19, there is no entirely reliable way to know when a listener may be re-used, and a new listener should be created for each service discovery request.

public void unregisterService (NsdManager.RegistrationListener listener)

Added in API level 16

Unregister a service registered through registerService(NsdServiceInfo, int, NsdManager.RegistrationListener). A successful unregister is notified to the application with a call to onServiceUnregistered(NsdServiceInfo).

Parameters
listener NsdManager.RegistrationListener: This should be the listener object that was passed to registerService(NsdServiceInfo, int, NsdManager.RegistrationListener). It identifies the service that should be unregistered and notifies of a successful or unsuccessful unregistration via the listener callbacks. In API versions 20 and above, the listener object may be used for another service registration once the callback has been called. In API versions <= 19, there is no entirely reliable way to know when a listener may be re-used, and a new listener should be created for each service registration request.