public final class NsdManager extends Object
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 informationAn application that needs to advertise itself over a network for other applications to discover it can do so with a call to
registerService(android.net.nsd.NsdServiceInfo, int, android.net.nsd.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
NsdManager.RegistrationListener.onServiceRegistered(android.net.nsd.NsdServiceInfo)
and a failure to register is notified
over NsdManager.RegistrationListener.onRegistrationFailed(android.net.nsd.NsdServiceInfo, int)
A peer application looking for http services can initiate a discovery for "_http._tcp"
with a call to discoverServices(java.lang.String, int, android.net.nsd.NsdManager.DiscoveryListener)
. A service found is notified with a callback
to NsdManager.DiscoveryListener.onServiceFound(android.net.nsd.NsdServiceInfo)
and a service lost is notified on
NsdManager.DiscoveryListener.onServiceLost(android.net.nsd.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(android.net.nsd.NsdServiceInfo, android.net.nsd.NsdManager.ResolveListener)
to
resolve the host and port details for the purpose of establishing a connection. A successful
resolve is notified on NsdManager.ResolveListener.onServiceResolved(android.net.nsd.NsdServiceInfo)
and a failure is notified
on NsdManager.ResolveListener.onResolveFailed(android.net.nsd.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)
.
NsdServiceInfo
Modifier and Type | Class and Description |
---|---|
static interface |
NsdManager.DiscoveryListener
Interface for callback invocation for service discovery
|
static interface |
NsdManager.RegistrationListener
Interface for callback invocation for service registration
|
static interface |
NsdManager.ResolveListener
Interface for callback invocation for service resolution
|
Constructor and Description |
---|
NsdManager(Context context,
INsdManager service)
Create a new Nsd instance.
|
Modifier and Type | Method and Description |
---|---|
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 |
setEnabled(boolean enabled)
Internal use only @hide
|
void |
stopServiceDiscovery(NsdManager.DiscoveryListener listener)
Stop service discovery initiated with
discoverServices(java.lang.String, int, android.net.nsd.NsdManager.DiscoveryListener) . |
void |
unregisterService(NsdManager.RegistrationListener listener)
Unregister a service registered through
registerService(android.net.nsd.NsdServiceInfo, int, android.net.nsd.NsdManager.RegistrationListener) . |
public static final String ACTION_NSD_STATE_CHANGED
EXTRA_NSD_STATE
provides the state
information as int.EXTRA_NSD_STATE
,
Constant Field Valuespublic static final String EXTRA_NSD_STATE
Intent.getIntExtra(String,int)
.NSD_STATE_DISABLED
,
NSD_STATE_ENABLED
,
Constant Field Valuespublic static final int NSD_STATE_DISABLED
ACTION_NSD_STATE_CHANGED
,
Constant Field Valuespublic static final int NSD_STATE_ENABLED
ACTION_NSD_STATE_CHANGED
,
Constant Field Valuespublic static final int DISCOVER_SERVICES
public static final int DISCOVER_SERVICES_STARTED
public static final int DISCOVER_SERVICES_FAILED
public static final int SERVICE_FOUND
public static final int SERVICE_LOST
public static final int STOP_DISCOVERY
public static final int STOP_DISCOVERY_FAILED
public static final int STOP_DISCOVERY_SUCCEEDED
public static final int REGISTER_SERVICE
public static final int REGISTER_SERVICE_FAILED
public static final int REGISTER_SERVICE_SUCCEEDED
public static final int UNREGISTER_SERVICE
public static final int UNREGISTER_SERVICE_FAILED
public static final int UNREGISTER_SERVICE_SUCCEEDED
public static final int RESOLVE_SERVICE
public static final int RESOLVE_SERVICE_FAILED
public static final int RESOLVE_SERVICE_SUCCEEDED
public static final int ENABLE
public static final int DISABLE
public static final int NATIVE_DAEMON_EVENT
public static final int PROTOCOL_DNS_SD
public static final int FAILURE_INTERNAL_ERROR
NsdManager.RegistrationListener.onRegistrationFailed(android.net.nsd.NsdServiceInfo, int)
,
NsdManager.RegistrationListener.onUnregistrationFailed(android.net.nsd.NsdServiceInfo, int)
,
NsdManager.DiscoveryListener.onStartDiscoveryFailed(java.lang.String, int)
,
NsdManager.DiscoveryListener.onStopDiscoveryFailed(java.lang.String, int)
or NsdManager.ResolveListener.onResolveFailed(android.net.nsd.NsdServiceInfo, int)
.
Indicates that the operation failed due to an internal error.public static final int FAILURE_ALREADY_ACTIVE
public static final int FAILURE_MAX_LIMIT
public NsdManager(Context context, INsdManager service)
Context.getSystemService()
to retrieve
Context.NSD_SERVICE
.service
- the Binder interfacepublic void registerService(NsdServiceInfo serviceInfo, int protocolType, NsdManager.RegistrationListener listener)
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 NsdManager.RegistrationListener.onServiceRegistered(android.net.nsd.NsdServiceInfo)
or a failure
through NsdManager.RegistrationListener.onRegistrationFailed(android.net.nsd.NsdServiceInfo, int)
.
The application should call unregisterService(android.net.nsd.NsdManager.RegistrationListener)
when the service
registration is no longer required, and/or whenever the application is stopped.
serviceInfo
- The service being registeredprotocolType
- The service discovery protocollistener
- The listener notifies of a successful registration and is used to
unregister this service through a call on unregisterService(android.net.nsd.NsdManager.RegistrationListener)
. Cannot be null.
Cannot be in use for an active service registration.public void unregisterService(NsdManager.RegistrationListener listener)
registerService(android.net.nsd.NsdServiceInfo, int, android.net.nsd.NsdManager.RegistrationListener)
. A successful
unregister is notified to the application with a call to
NsdManager.RegistrationListener.onServiceUnregistered(android.net.nsd.NsdServiceInfo)
.listener
- This should be the listener object that was passed to
registerService(android.net.nsd.NsdServiceInfo, int, android.net.nsd.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.public void discoverServices(String serviceType, int protocolType, NsdManager.DiscoveryListener listener)
stopServiceDiscovery(android.net.nsd.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 NsdManager.DiscoveryListener.onDiscoveryStarted(java.lang.String)
or a failure
through NsdManager.DiscoveryListener.onStartDiscoveryFailed(java.lang.String, int)
.
Upon successful start, application is notified when a service is found with
NsdManager.DiscoveryListener.onServiceFound(android.net.nsd.NsdServiceInfo)
or when a service is lost with
NsdManager.DiscoveryListener.onServiceLost(android.net.nsd.NsdServiceInfo)
.
Upon failure to start, service discovery is not active and application does
not need to invoke stopServiceDiscovery(android.net.nsd.NsdManager.DiscoveryListener)
The application should call stopServiceDiscovery(android.net.nsd.NsdManager.DiscoveryListener)
when discovery of this
service type is no longer required, and/or whenever the application is paused or
stopped.
serviceType
- The service type being discovered. Examples include "_http._tcp" for
http services or "_ipp._tcp" for printersprotocolType
- The service discovery protocollistener
- The listener notifies of a successful discovery and is used
to stop discovery on this serviceType through a call on stopServiceDiscovery(android.net.nsd.NsdManager.DiscoveryListener)
.
Cannot be null. Cannot be in use for an active service discovery.public void stopServiceDiscovery(NsdManager.DiscoveryListener listener)
discoverServices(java.lang.String, int, android.net.nsd.NsdManager.DiscoveryListener)
. An active service
discovery is notified to the application with NsdManager.DiscoveryListener.onDiscoveryStarted(java.lang.String)
and it stays active until the application invokes a stop service discovery. A successful
stop is notified to with a call to NsdManager.DiscoveryListener.onDiscoveryStopped(java.lang.String)
.
Upon failure to stop service discovery, application is notified through
NsdManager.DiscoveryListener.onStopDiscoveryFailed(java.lang.String, int)
.
listener
- This should be the listener object that was passed to discoverServices(java.lang.String, int, android.net.nsd.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 resolveService(NsdServiceInfo serviceInfo, NsdManager.ResolveListener listener)
serviceInfo
- service to be resolvedlistener
- to receive callback upon success or failure. Cannot be null.
Cannot be in use for an active service resolution.public void setEnabled(boolean enabled)