NsdManager
public
final
class
NsdManager
extends Object
java.lang.Object | |
↳ | android.net.nsd.NsdManager |
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 separate internal 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
registerService(NsdServiceInfo, int, 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
RegistrationListener#onServiceRegistered
and a failure to register is notified
over RegistrationListener#onRegistrationFailed
A peer application looking for http services can initiate a discovery for "_http._tcp"
with a call to discoverServices(DiscoveryRequest, Executor, DiscoveryListener)
. A service found is notified with a callback
to DiscoveryListener#onServiceFound
and a service lost is notified on
DiscoveryListener#onServiceLost
.
Once the peer application discovers the "Example" http service, and either needs to read the
attributes of the service or wants to receive data from the "Example" application, it can
initiate a resolve with resolveService(NsdServiceInfo, ResolveListener)
to resolve the attributes, host, and port
details. A successful resolve is notified on ResolveListener#onServiceResolved
and a
failure is notified on ResolveListener#onResolveFailed
.
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
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
Callback for use with |
interface |
NsdManager.ServiceInfoCallback
Callback to listen to service info updates. |
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_BAD_PARAMETERS
Indicates that the service has failed to resolve because of bad parameters. |
int |
FAILURE_INTERNAL_ERROR
Failures are passed with |
int |
FAILURE_MAX_LIMIT
Indicates that the operation failed because the maximum outstanding requests from the applications have reached. |
int |
FAILURE_OPERATION_NOT_RUNNING
Indicates that the stop operation failed because it is not running. |
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, NetworkRequest networkRequest, Executor executor, NsdManager.DiscoveryListener listener)
Initiate service discovery to browse for instances of a service type. |
void
|
discoverServices(DiscoveryRequest discoveryRequest, Executor executor, NsdManager.DiscoveryListener listener)
Initiates service discovery to browse for instances of a service type. |
void
|
discoverServices(String serviceType, int protocolType, NsdManager.DiscoveryListener listener)
Initiate service discovery to browse for instances of a service type. |
void
|
discoverServices(String serviceType, int protocolType, Network network, Executor executor, 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
|
registerService(NsdServiceInfo serviceInfo, int protocolType, Executor executor, NsdManager.RegistrationListener listener)
Register a service to be discovered by other services. |
void
|
registerServiceInfoCallback(NsdServiceInfo serviceInfo, Executor executor, NsdManager.ServiceInfoCallback listener)
Register a callback to listen for updates to a service. |
void
|
resolveService(NsdServiceInfo serviceInfo, Executor executor, NsdManager.ResolveListener listener)
This method was deprecated
in API level 36.
the returned ServiceInfo may get stale at any time after resolution, including
immediately after the callback is called, and may not contain some service information that
could be delivered later, like additional host addresses. Prefer using
|
void
|
resolveService(NsdServiceInfo serviceInfo, NsdManager.ResolveListener listener)
This method was deprecated
in API level 36.
the returned ServiceInfo may get stale at any time after resolution, including
immediately after the callback is called, and may not contain some service information that
could be delivered later, like additional host addresses. Prefer using
|
void
|
stopServiceDiscovery(NsdManager.DiscoveryListener listener)
Stop service discovery initiated with |
void
|
stopServiceResolution(NsdManager.ResolveListener listener)
Stop service resolution initiated with |
void
|
unregisterService(NsdManager.RegistrationListener listener)
Unregister a service registered through |
void
|
unregisterServiceInfoCallback(NsdManager.ServiceInfoCallback listener)
Unregister a callback registered with |
Inherited methods | |
---|---|
Constants
ACTION_NSD_STATE_CHANGED
public static final String ACTION_NSD_STATE_CHANGED
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"
EXTRA_NSD_STATE
public static final String EXTRA_NSD_STATE
The lookup key for an int that indicates whether network service discovery is enabled
or disabled. Retrieve it with Intent.getIntExtra(String, int)
.
See also:
Constant Value: "nsd_state"
FAILURE_ALREADY_ACTIVE
public static final int FAILURE_ALREADY_ACTIVE
Indicates that the operation failed because it is already active.
Constant Value: 3 (0x00000003)
FAILURE_BAD_PARAMETERS
public static final int FAILURE_BAD_PARAMETERS
Indicates that the service has failed to resolve because of bad parameters.
This failure is passed with
ServiceInfoCallback#onServiceInfoCallbackRegistrationFailed
.
Constant Value: 6 (0x00000006)
FAILURE_INTERNAL_ERROR
public static final int FAILURE_INTERNAL_ERROR
Failures are passed with RegistrationListener#onRegistrationFailed
,
RegistrationListener#onUnregistrationFailed
,
DiscoveryListener#onStartDiscoveryFailed
,
DiscoveryListener#onStopDiscoveryFailed
or ResolveListener#onResolveFailed
.
Indicates that the operation failed due to an internal error.
Constant Value: 0 (0x00000000)
FAILURE_MAX_LIMIT
public static final int FAILURE_MAX_LIMIT
Indicates that the operation failed because the maximum outstanding requests from the applications have reached.
Constant Value: 4 (0x00000004)
FAILURE_OPERATION_NOT_RUNNING
public static final int FAILURE_OPERATION_NOT_RUNNING
Indicates that the stop operation failed because it is not running.
This failure is passed with ResolveListener#onStopResolutionFailed
.
Constant Value: 5 (0x00000005)
NSD_STATE_DISABLED
public static final int NSD_STATE_DISABLED
Network service discovery is disabled
See also:
Constant Value: 1 (0x00000001)
NSD_STATE_ENABLED
public static final int NSD_STATE_ENABLED
Network service discovery is enabled
See also:
Constant Value: 2 (0x00000002)
PROTOCOL_DNS_SD
public static final int PROTOCOL_DNS_SD
Dns based service discovery protocol
Constant Value: 1 (0x00000001)
Public methods
discoverServices
public void discoverServices (String serviceType, int protocolType, NetworkRequest networkRequest, Executor executor, NsdManager.DiscoveryListener listener)
Initiate service discovery to browse for instances of a service type. Service discovery
consumes network bandwidth and will continue until the application calls
stopServiceDiscovery(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 DiscoveryListener#onDiscoveryStarted
or a failure
through DiscoveryListener#onStartDiscoveryFailed
.
Upon successful start, application is notified when a service is found with
DiscoveryListener#onServiceFound
or when a service is lost with
DiscoveryListener#onServiceLost
.
Upon failure to start, service discovery is not active and application does
not need to invoke stopServiceDiscovery(DiscoveryListener)
The application should call stopServiceDiscovery(DiscoveryListener)
when discovery of this
service type is no longer required, and/or whenever the application is paused or
stopped.
During discovery, new networks may connect or existing networks may disconnect - for
example if wifi is reconnected. When a service was found on a network that disconnects,
DiscoveryListener#onServiceLost
will be called. If a new network connects that
matches the NetworkRequest
, DiscoveryListener#onServiceFound
will be called
for services found on that network. Applications that do not want to track networks
themselves are encouraged to use this method instead of other overloads of
discoverServices
, as they will receive proper notifications when a service becomes
available or unavailable due to network changes.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
serviceType |
String : The service type being discovered. Examples include "_http._tcp" for
http services or "_ipp._tcp" for printers
This value cannot be null . |
protocolType |
int : The service discovery protocol |
networkRequest |
NetworkRequest : Request specifying networks that should be considered when discovering
This value cannot be null . |
executor |
Executor : Executor to run listener callbacks with
This value cannot be null . |
listener |
NsdManager.DiscoveryListener : The listener notifies of a successful discovery and is used
to stop discovery on this serviceType through a call on stopServiceDiscovery(DiscoveryListener) .
This value cannot be null . |
discoverServices
public void discoverServices (DiscoveryRequest discoveryRequest, Executor executor, NsdManager.DiscoveryListener listener)
Initiates service discovery to browse for instances of a service type. Service discovery
consumes network bandwidth and will continue until the application calls
stopServiceDiscovery(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 DiscoveryListener#onDiscoveryStarted
or a failure
through DiscoveryListener#onStartDiscoveryFailed
.
Upon successful start, application is notified when a service is found with
DiscoveryListener#onServiceFound
or when a service is lost with
DiscoveryListener#onServiceLost
.
Upon failure to start, service discovery is not active and application does
not need to invoke stopServiceDiscovery(DiscoveryListener)
The application should call stopServiceDiscovery(DiscoveryListener)
when discovery of this
service type is no longer required, and/or whenever the application is paused or
stopped.
Parameters | |
---|---|
discoveryRequest |
DiscoveryRequest : the DiscoveryRequest object which specifies the discovery
parameters such as service type, subtype and network
This value cannot be null . |
executor |
Executor : Executor to run listener callbacks with
This value cannot be null . |
listener |
NsdManager.DiscoveryListener : The listener notifies of a successful discovery and is used
to stop discovery on this serviceType through a call on stopServiceDiscovery(DiscoveryListener) .
This value cannot be null . |
discoverServices
public void discoverServices (String serviceType, int protocolType, NsdManager.DiscoveryListener listener)
Initiate service discovery to browse for instances of a service type. Service discovery
consumes network bandwidth and will continue until the application calls
stopServiceDiscovery(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 DiscoveryListener#onDiscoveryStarted
or a failure
through DiscoveryListener#onStartDiscoveryFailed
.
Upon successful start, application is notified when a service is found with
DiscoveryListener#onServiceFound
or when a service is lost with
DiscoveryListener#onServiceLost
.
Upon failure to start, service discovery is not active and application does
not need to invoke stopServiceDiscovery(DiscoveryListener)
The application should call stopServiceDiscovery(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(DiscoveryListener) .
Cannot be null. Cannot be in use for an active service discovery. |
discoverServices
public void discoverServices (String serviceType, int protocolType, Network network, Executor executor, NsdManager.DiscoveryListener listener)
Initiate service discovery to browse for instances of a service type. Service discovery
consumes network bandwidth and will continue until the application calls
stopServiceDiscovery(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 DiscoveryListener#onDiscoveryStarted
or a failure
through DiscoveryListener#onStartDiscoveryFailed
.
Upon successful start, application is notified when a service is found with
DiscoveryListener#onServiceFound
or when a service is lost with
DiscoveryListener#onServiceLost
.
Upon failure to start, service discovery is not active and application does
not need to invoke stopServiceDiscovery(DiscoveryListener)
The application should call stopServiceDiscovery(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
This value cannot be null . |
protocolType |
int : The service discovery protocol |
network |
Network : Network to discover services on, or null to discover on all available networks |
executor |
Executor : Executor to run listener callbacks with
This value cannot be null . |
listener |
NsdManager.DiscoveryListener : The listener notifies of a successful discovery and is used
to stop discovery on this serviceType through a call on stopServiceDiscovery(DiscoveryListener) .
This value cannot be null . |
registerService
public void registerService (NsdServiceInfo serviceInfo, int protocolType, NsdManager.RegistrationListener listener)
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 RegistrationListener#onServiceRegistered
or a failure
through RegistrationListener#onRegistrationFailed
.
The application should call unregisterService(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(RegistrationListener) . Cannot be null.
Cannot be in use for an active service registration. |
registerService
public void registerService (NsdServiceInfo serviceInfo, int protocolType, Executor executor, NsdManager.RegistrationListener listener)
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 RegistrationListener#onServiceRegistered
or a failure
through RegistrationListener#onRegistrationFailed
.
The application should call unregisterService(RegistrationListener)
when the service
registration is no longer required, and/or whenever the application is stopped.
Parameters | |
---|---|
serviceInfo |
NsdServiceInfo : The service being registered
This value cannot be null . |
protocolType |
int : The service discovery protocol |
executor |
Executor : Executor to run listener callbacks with
This value cannot be null . |
listener |
NsdManager.RegistrationListener : The listener notifies of a successful registration and is used to
unregister this service through a call on unregisterService(RegistrationListener) . Cannot be null. |
registerServiceInfoCallback
public void registerServiceInfoCallback (NsdServiceInfo serviceInfo, Executor executor, NsdManager.ServiceInfoCallback listener)
Register a callback to listen for updates to a service.
An application can listen to a service to continuously monitor availability of given service.
The callback methods will be called on the passed executor. And service updates are sent with
continuous calls to ServiceInfoCallback#onServiceUpdated
.
This is different from resolveService(NsdServiceInfo, ResolveListener)
which provides one shot service information.
An application can listen to a service once a time. It needs to cancel the registration
before registering other callbacks. Upon failure to register a callback for example if
it's a duplicated registration, the application is notified through
ServiceInfoCallback#onServiceInfoCallbackRegistrationFailed
with
FAILURE_BAD_PARAMETERS
.
Parameters | |
---|---|
serviceInfo |
NsdServiceInfo : the service to receive updates for
This value cannot be null . |
executor |
Executor : Executor to run callbacks with
This value cannot be null . |
listener |
NsdManager.ServiceInfoCallback : to receive callback upon service update
This value cannot be null . |
resolveService
public void resolveService (NsdServiceInfo serviceInfo, Executor executor, NsdManager.ResolveListener listener)
This method was deprecated
in API level 36.
the returned ServiceInfo may get stale at any time after resolution, including
immediately after the callback is called, and may not contain some service information that
could be delivered later, like additional host addresses. Prefer using
registerServiceInfoCallback(NsdServiceInfo, Executor, ServiceInfoCallback)
, which will keep the application up-to-date with the
state of the service.
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
This value cannot be null . |
executor |
Executor : Executor to run listener callbacks with
This value cannot be null . |
listener |
NsdManager.ResolveListener : to receive callback upon success or failure.
This value cannot be null . |
resolveService
public void resolveService (NsdServiceInfo serviceInfo, NsdManager.ResolveListener listener)
This method was deprecated
in API level 36.
the returned ServiceInfo may get stale at any time after resolution, including
immediately after the callback is called, and may not contain some service information that
could be delivered later, like additional host addresses. Prefer using
registerServiceInfoCallback(NsdServiceInfo, Executor, ServiceInfoCallback)
, which will keep the application up-to-date with the
state of the service.
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. |
stopServiceDiscovery
public void stopServiceDiscovery (NsdManager.DiscoveryListener listener)
Stop service discovery initiated with discoverServices(DiscoveryRequest, Executor, DiscoveryListener)
. An active service
discovery is notified to the application with DiscoveryListener#onDiscoveryStarted
and it stays active until the application invokes a stop service discovery. A successful
stop is notified to with a call to DiscoveryListener#onDiscoveryStopped
.
Upon failure to stop service discovery, application is notified through
DiscoveryListener#onStopDiscoveryFailed
.
Parameters | |
---|---|
listener |
NsdManager.DiscoveryListener : This should be the listener object that was passed to discoverServices(DiscoveryRequest, Executor, 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. |
stopServiceResolution
public void stopServiceResolution (NsdManager.ResolveListener listener)
Stop service resolution initiated with resolveService(NsdServiceInfo, ResolveListener)
.
A successful stop is notified with a call to ResolveListener#onResolutionStopped
.
Upon failure to stop service resolution for example if resolution is done or the
requester stops resolution repeatedly, the application is notified
ResolveListener#onStopResolutionFailed
with FAILURE_OPERATION_NOT_RUNNING
Parameters | |
---|---|
listener |
NsdManager.ResolveListener : This should be a listener object that was passed to resolveService(NsdServiceInfo, ResolveListener) .
It identifies the resolution that should be stopped and notifies of a
successful or unsuccessful stop. Throws IllegalArgumentException if
the listener was not passed to resolveService before.
This value cannot be null . |
unregisterService
public void unregisterService (NsdManager.RegistrationListener listener)
Unregister a service registered through registerService(NsdServiceInfo, int, RegistrationListener)
. A successful
unregister is notified to the application with a call to
RegistrationListener#onServiceUnregistered
.
Parameters | |
---|---|
listener |
NsdManager.RegistrationListener : This should be the listener object that was passed to
registerService(NsdServiceInfo, int, 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. |
unregisterServiceInfoCallback
public void unregisterServiceInfoCallback (NsdManager.ServiceInfoCallback listener)
Unregister a callback registered with registerServiceInfoCallback(NsdServiceInfo, Executor, ServiceInfoCallback)
.
A successful unregistration is notified with a call to
ServiceInfoCallback#onServiceInfoCallbackUnregistered
. The same callback can only be
reused after this is called.
If the callback is not already registered, this will throw with
IllegalArgumentException
.
Parameters | |
---|---|
listener |
NsdManager.ServiceInfoCallback : This should be a listener object that was passed to
registerServiceInfoCallback(NsdServiceInfo, Executor, ServiceInfoCallback) . It identifies the registration that
should be unregistered and notifies of a successful or unsuccessful stop.
Throws IllegalArgumentException if the listener was not passed to
registerServiceInfoCallback(NsdServiceInfo, Executor, ServiceInfoCallback) before.
This value cannot be null . |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-07-18 UTC.