Use network service discovery

Network service discovery (NSD) gives your app access to services that other devices provide on a local network. Devices that support NSD include printers, webcams, HTTPS servers, and other mobile devices.

NSD implements the DNS-based Service Discovery (DNS-SD) mechanism, which allows your app to request services by specifying a type of service and the name of a device instance that provides the desired type of service. DNS-SD is supported both on Android and on other mobile platforms.

Adding NSD to your app allows your users to identify other devices on the local network that support the services your app requests. This is useful for a variety of peer-to-peer applications such as file sharing or multi-player gaming. Android's NSD APIs simplify the effort required for you to implement such features.

This lesson shows you how to build an application that can broadcast its name and connection information to the local network and scan for information from other applications doing the same. Finally, this lesson shows you how to connect to the same application running on another device.

Register your service on the network

Note: This step is optional. If you don't care about broadcasting your app's services over the local network, you can skip forward to the next section, Discover Services on the Network.

To register your service on the local network, first create a NsdServiceInfo object. This object provides the information that other devices on the network use when they're deciding whether to connect to your service.

Kotlin

funregisterService(port:Int){
// Create the NsdServiceInfo object, and populate it.
valserviceInfo=NsdServiceInfo().apply{
// The name is subject to change based on conflicts
// with other services advertised on the same network.
serviceName="NsdChat"
serviceType="_nsdchat._tcp"
setPort(port)
...
}
}

Java

publicvoidregisterService(intport){
// Create the NsdServiceInfo object, and populate it.
NsdServiceInfoserviceInfo=newNsdServiceInfo();
// The name is subject to change based on conflicts
// with other services advertised on the same network.
serviceInfo.setServiceName("NsdChat");
serviceInfo.setServiceType("_nsdchat._tcp");
serviceInfo.setPort(port);
...
}

This code snippet sets the service name to "NsdChat". The service name is the instance name: it is the visible name to other devices on the network. The name is visible to any device on the network that is using NSD to look for local services. Keep in mind that the name must be unique for any service on the network, and Android automatically handles conflict resolution. If two devices on the network both have the NsdChat application installed, one of them changes the service name automatically, to something like "NsdChat (1)".

The second parameter sets the service type, specifies which protocol and transport layer the application uses. The syntax is "_<protocol>._<transportlayer>". In the code snippet, the service uses HTTP protocol running over TCP. An application offering a printer service (for instance, a network printer) would set the service type to "_ipp._tcp".

Note: The International Assigned Numbers Authority (IANA) manages a centralized, authoritative list of service types used by service discovery protocols such as NSD and Bonjour. You can download the list from the IANA list of service names and port numbers. If you intend to use a new service type, you should reserve it by filling out the IANA Ports and Service registration form.

When setting the port for your service, avoid hardcoding it as this conflicts with other applications. For instance, assuming that your application always uses port 1337 puts it in potential conflict with other installed applications that use the same port. Instead, use the device's next available port. Because this information is provided to other apps by a service broadcast, there's no need for the port your application uses to be known by other applications at compile-time. Instead, the applications can get this information from your service broadcast, right before connecting to your service.

If you're working with sockets, here's how you can initialize a socket to any available port simply by setting it to 0.

Kotlin

funinitializeServerSocket(){
// Initialize a server socket on the next available port.
serverSocket=ServerSocket(0).also{socket->
// Store the chosen port.
mLocalPort=socket.localPort
...
}
}

Java

publicvoidinitializeServerSocket(){
// Initialize a server socket on the next available port.
serverSocket=newServerSocket(0);
// Store the chosen port.
localPort=serverSocket.getLocalPort();
...
}

Now that you've defined the NsdServiceInfo object, you need to implement the RegistrationListener interface. This interface contains callbacks used by Android to alert your application of the success or failure of service registration and unregistration.

Kotlin

privatevalregistrationListener=object:NsdManager.RegistrationListener{
overridefunonServiceRegistered(NsdServiceInfo:NsdServiceInfo){
// Save the service name. Android may have changed it in order to
// resolve a conflict, so update the name you initially requested
// with the name Android actually used.
mServiceName=NsdServiceInfo.serviceName
}
overridefunonRegistrationFailed(serviceInfo:NsdServiceInfo,errorCode:Int){
// Registration failed! Put debugging code here to determine why.
}
overridefunonServiceUnregistered(arg0:NsdServiceInfo){
// Service has been unregistered. This only happens when you call
// NsdManager.unregisterService() and pass in this listener.
}
overridefunonUnregistrationFailed(serviceInfo:NsdServiceInfo,errorCode:Int){
// Unregistration failed. Put debugging code here to determine why.
}
}

Java

publicvoidinitializeRegistrationListener(){
registrationListener=newNsdManager.RegistrationListener(){
@Override
publicvoidonServiceRegistered(NsdServiceInfoNsdServiceInfo){
// Save the service name. Android may have changed it in order to
// resolve a conflict, so update the name you initially requested
// with the name Android actually used.
serviceName=NsdServiceInfo.getServiceName();
}
@Override
publicvoidonRegistrationFailed(NsdServiceInfoserviceInfo,interrorCode){
// Registration failed! Put debugging code here to determine why.
}
@Override
publicvoidonServiceUnregistered(NsdServiceInfoarg0){
// Service has been unregistered. This only happens when you call
// NsdManager.unregisterService() and pass in this listener.
}
@Override
publicvoidonUnregistrationFailed(NsdServiceInfoserviceInfo,interrorCode){
// Unregistration failed. Put debugging code here to determine why.
}
};
}

Now you have all the pieces to register your service. Call the method registerService() .

Note that this method is asynchronous, so any code that needs to run after the service has been registered must go in the onServiceRegistered() method.

Kotlin

funregisterService(port:Int){
// Create the NsdServiceInfo object, and populate it.
valserviceInfo=NsdServiceInfo().apply{
// The name is subject to change based on conflicts
// with other services advertised on the same network.
serviceName="NsdChat"
serviceType="_nsdchat._tcp"
setPort(port)
}
nsdManager=(getSystemService(Context.NSD_SERVICE)asNsdManager).apply{
registerService(serviceInfo,NsdManager.PROTOCOL_DNS_SD,registrationListener)
}
}

Java

publicvoidregisterService(intport){
NsdServiceInfoserviceInfo=newNsdServiceInfo();
serviceInfo.setServiceName("NsdChat");
serviceInfo.setServiceType("_http._tcp.");
serviceInfo.setPort(port);
nsdManager=Context.getSystemService(Context.NSD_SERVICE);
nsdManager.registerService(
serviceInfo,NsdManager.PROTOCOL_DNS_SD,registrationListener);
}

Discover services on the network

The network is teeming with life, from the beastly network printers to the docile network webcams, to the brutal, fiery battles of nearby tic-tac-toe players. The key to letting your application see this vibrant ecosystem of functionality is service discovery. Your application needs to listen to service broadcasts on the network to see what services are available, and filter out anything the application can't work with.

Service discovery, like service registration, has two steps: setting up a discovery listener with the relevant callbacks, and making a single asynchronous API call to discoverServices() .

First, instantiate an anonymous class that implements NsdManager.DiscoveryListener . The following snippet shows a simple example:

Kotlin

// Instantiate a new DiscoveryListener
privatevaldiscoveryListener=object:NsdManager.DiscoveryListener{
// Called as soon as service discovery begins.
overridefunonDiscoveryStarted(regType:String){
Log.d(TAG,"Service discovery started")
}
overridefunonServiceFound(service:NsdServiceInfo){
// A service was found! Do something with it.
Log.d(TAG,"Service discovery success$service")
when{
service.serviceType!=SERVICE_TYPE->// Service type is the string containing the protocol and
// transport layer for this service.
Log.d(TAG,"Unknown Service Type: ${service.serviceType}")
service.serviceName==mServiceName->// The name of the service tells the user what they'd be
// connecting to. It could be "Bob's Chat App".
Log.d(TAG,"Same machine: $mServiceName")
service.serviceName.contains("NsdChat")->nsdManager.resolveService(service,resolveListener)
}
}
overridefunonServiceLost(service:NsdServiceInfo){
// When the network service is no longer available.
// Internal bookkeeping code goes here.
Log.e(TAG,"service lost: $service")
}
overridefunonDiscoveryStopped(serviceType:String){
Log.i(TAG,"Discovery stopped: $serviceType")
}
overridefunonStartDiscoveryFailed(serviceType:String,errorCode:Int){
Log.e(TAG,"Discovery failed: Error code:$errorCode")
nsdManager.stopServiceDiscovery(this)
}
overridefunonStopDiscoveryFailed(serviceType:String,errorCode:Int){
Log.e(TAG,"Discovery failed: Error code:$errorCode")
nsdManager.stopServiceDiscovery(this)
}
}

Java

publicvoidinitializeDiscoveryListener(){
// Instantiate a new DiscoveryListener
discoveryListener=newNsdManager.DiscoveryListener(){
// Called as soon as service discovery begins.
@Override
publicvoidonDiscoveryStarted(StringregType){
Log.d(TAG,"Service discovery started");
}
@Override
publicvoidonServiceFound(NsdServiceInfoservice){
// A service was found! Do something with it.
Log.d(TAG,"Service discovery success"+service);
if(!service.getServiceType().equals(SERVICE_TYPE)){
// Service type is the string containing the protocol and
// transport layer for this service.
Log.d(TAG,"Unknown Service Type: "+service.getServiceType());
}elseif(service.getServiceName().equals(serviceName)){
// The name of the service tells the user what they'd be
// connecting to. It could be "Bob's Chat App".
Log.d(TAG,"Same machine: "+serviceName);
}elseif(service.getServiceName().contains("NsdChat")){
nsdManager.resolveService(service,resolveListener);
}
}
@Override
publicvoidonServiceLost(NsdServiceInfoservice){
// When the network service is no longer available.
// Internal bookkeeping code goes here.
Log.e(TAG,"service lost: "+service);
}
@Override
publicvoidonDiscoveryStopped(StringserviceType){
Log.i(TAG,"Discovery stopped: "+serviceType);
}
@Override
publicvoidonStartDiscoveryFailed(StringserviceType,interrorCode){
Log.e(TAG,"Discovery failed: Error code:"+errorCode);
nsdManager.stopServiceDiscovery(this);
}
@Override
publicvoidonStopDiscoveryFailed(StringserviceType,interrorCode){
Log.e(TAG,"Discovery failed: Error code:"+errorCode);
nsdManager.stopServiceDiscovery(this);
}
};
}

The NSD API uses the methods in this interface to inform your application when discovery is started, when it fails, and when services are found and lost (lost means "is no longer available"). Notice that this snippet does several checks when a service is found.

  1. The service name of the found service is compared to the service name of the local service to determine if the device just picked up its own broadcast (which is valid).
  2. The service type is checked, to verify it's a type of service your application can connect to.
  3. The service name is checked to verify connection to the correct application.

Checking the service name isn't always necessary, and is only relevant if you want to connect to a specific application. For instance, the application might only want to connect to instances of itself running on other devices. However, if the application wants to connect to a network printer, it's enough to see that the service type is "_ipp._tcp".

After setting up the listener, call discoverServices() , passing in the service type your application should look for, the discovery protocol to use, and the listener you just created.

Kotlin

nsdManager.discoverServices(SERVICE_TYPE,NsdManager.PROTOCOL_DNS_SD,discoveryListener)

Java

nsdManager.discoverServices(
SERVICE_TYPE,NsdManager.PROTOCOL_DNS_SD,discoveryListener);

Connect to services on the network

When your application finds a service on the network to connect to, it must first determine the connection information for that service, using the resolveService() method. Implement a NsdManager.ResolveListener to pass into this method, and use it to get a NsdServiceInfo containing the connection information.

Kotlin

privatevalresolveListener=object:NsdManager.ResolveListener{
overridefunonResolveFailed(serviceInfo:NsdServiceInfo,errorCode:Int){
// Called when the resolve fails. Use the error code to debug.
Log.e(TAG,"Resolve failed: $errorCode")
}
overridefunonServiceResolved(serviceInfo:NsdServiceInfo){
Log.e(TAG,"Resolve Succeeded. $serviceInfo")
if(serviceInfo.serviceName==mServiceName){
Log.d(TAG,"Same IP.")
return
}
mService=serviceInfo
valport:Int=serviceInfo.port
valhost:InetAddress=serviceInfo.host
}
}

Java

publicvoidinitializeResolveListener(){
resolveListener=newNsdManager.ResolveListener(){
@Override
publicvoidonResolveFailed(NsdServiceInfoserviceInfo,interrorCode){
// Called when the resolve fails. Use the error code to debug.
Log.e(TAG,"Resolve failed: "+errorCode);
}
@Override
publicvoidonServiceResolved(NsdServiceInfoserviceInfo){
Log.e(TAG,"Resolve Succeeded. "+serviceInfo);
if(serviceInfo.getServiceName().equals(serviceName)){
Log.d(TAG,"Same IP.");
return;
}
mService=serviceInfo;
intport=mService.getPort();
InetAddresshost=mService.getHost();
}
};
}

Once the service is resolved, your application receives detailed service information including an IP address and port number. This is everything you need to create your own network connection to the service.

Unregister your service on application close

It's important to enable and disable NSD functionality as appropriate during the application's lifecycle. Unregistering your application when it closes down helps prevent other applications from thinking it's still active and attempting to connect to it. Also, service discovery is an expensive operation, and should be stopped when the parent Activity is paused, and re-enabled when the Activity is resumed. Override the lifecycle methods of your main Activity and insert code to start and stop service broadcast and discovery as appropriate.

Kotlin

// In your application's Activity
overridefunonPause(){
nsdHelper?.tearDown()
super.onPause()
}
overridefunonResume(){
super.onResume()
nsdHelper?.apply{
registerService(connection.localPort)
discoverServices()
}
}
overridefunonDestroy(){
nsdHelper?.tearDown()
connection.tearDown()
super.onDestroy()
}
// NsdHelper's tearDown method
funtearDown(){
nsdManager.apply{
unregisterService(registrationListener)
stopServiceDiscovery(discoveryListener)
}
}

Java

// In your application's Activity
@Override
protectedvoidonPause(){
if(nsdHelper!=null){
nsdHelper.tearDown();
}
super.onPause();
}
@Override
protectedvoidonResume(){
super.onResume();
if(nsdHelper!=null){
nsdHelper.registerService(connection.getLocalPort());
nsdHelper.discoverServices();
}
}
@Override
protectedvoidonDestroy(){
nsdHelper.tearDown();
connection.tearDown();
super.onDestroy();
}
// NsdHelper's tearDown method
publicvoidtearDown(){
nsdManager.unregisterService(registrationListener);
nsdManager.stopServiceDiscovery(discoveryListener);
}

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年01月03日 UTC.