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 * ** An application that needs to advertise itself over a network for other applications to * discover it can do so with a call to {@link #registerService}. 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 * {@link RegistrationListener#onServiceRegistered} and a failure to register is notified * over {@link RegistrationListener#onRegistrationFailed} * *
A peer application looking for http services can initiate a discovery for "_http._tcp" * with a call to {@link #discoverServices}. A service found is notified with a callback * to {@link DiscoveryListener#onServiceFound} and a service lost is notified on * {@link 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 {@link #resolveService} to resolve the attributes, host, and port
* details. A successful resolve is notified on {@link ResolveListener#onServiceResolved} and a
* failure is notified on {@link 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 NsdServiceInfo
*/
@SystemService(Context.NSD_SERVICE)
public final class NsdManager {
private static final String TAG = NsdManager.class.getSimpleName();
private static final boolean DBG = false;
// TODO : remove this class when udc-mainline-prod is abandoned and android.net.flags.Flags is
// available here
/** @hide */
public static class Flags {
static final String REGISTER_NSD_OFFLOAD_ENGINE_API =
"com.android.net.flags.register_nsd_offload_engine_api";
static final String NSD_SUBTYPES_SUPPORT_ENABLED =
"com.android.net.flags.nsd_subtypes_support_enabled";
static final String ADVERTISE_REQUEST_API =
"com.android.net.flags.advertise_request_api";
static final String NSD_CUSTOM_HOSTNAME_ENABLED =
"com.android.net.flags.nsd_custom_hostname_enabled";
static final String NSD_CUSTOM_TTL_ENABLED =
"com.android.net.flags.nsd_custom_ttl_enabled";
}
/**
* A regex for the acceptable format of a type or subtype label.
* @hide
*/
public static final String TYPE_LABEL_REGEX = "_[a-zA-Z0-9-_]{1,61}[a-zA-Z0-9]";
/**
* A regex for the acceptable format of a subtype label.
*
* As per RFC 6763 7.1, "Subtype strings are not required to begin with an underscore, though
* they often do.", and "Subtype strings [...] may be constructed using arbitrary 8-bit data
* values. In many cases these data values may be UTF-8 [RFC3629] representations of text, or
* even (as in the example above) plain ASCII [RFC20], but they do not have to be.".
*
* This regex is overly conservative as it mandates the underscore and only allows printable
* ASCII characters (codes 0x20 to 0x7e, space to tilde), except for comma (0x2c) and dot
* (0x2e); so the NsdManager API does not allow everything the RFC allows. This may be revisited
* in the future, but using arbitrary bytes makes logging and testing harder, and using other
* characters would probably be a bad idea for interoperability for apps.
* @hide
*/
public static final String SUBTYPE_LABEL_REGEX = "_["
+ "\\x20-\\x2b"
+ "\\x2d"
+ "\\x2f-\\x7e"
+ "]{1,62}";
/**
* A regex for the acceptable format of a service type specification.
*
* When it matches, matcher group 1 is an optional leading subtype when using legacy dot syntax
* (_subtype._type._tcp). Matcher group 2 is the actual type, and matcher group 3 contains
* optional comma-separated subtypes.
* @hide
*/
public static final String TYPE_REGEX =
// Optional leading subtype (_subtype._type._tcp)
// (?: xxx) is a non-capturing parenthesis, don't capture the dot
"^(?:(" + SUBTYPE_LABEL_REGEX + ")\\.)?"
// Actual type (_type._tcp.local)
+ "(" + TYPE_LABEL_REGEX + "\\._(?:tcp|udp))"
// Drop '.' at the end of service type that is compatible with old backend.
// e.g. allow "_type._tcp.local."
+ "\\.?"
// Optional subtype after comma, for "_type._tcp,_subtype1,_subtype2" format
+ "((?:," + SUBTYPE_LABEL_REGEX + ")*)"
+ "$";
/**
* Broadcast intent action to indicate whether network service discovery is
* enabled or disabled. An extra {@link #EXTRA_NSD_STATE} provides the state
* information as int.
*
* @see #EXTRA_NSD_STATE
*/
@SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
public static final String ACTION_NSD_STATE_CHANGED = "android.net.nsd.STATE_CHANGED";
/**
* The lookup key for an int that indicates whether network service discovery is enabled
* or disabled. Retrieve it with {@link android.content.Intent#getIntExtra(String,int)}.
*
* @see #NSD_STATE_DISABLED
* @see #NSD_STATE_ENABLED
*/
public static final String EXTRA_NSD_STATE = "nsd_state";
/**
* Network service discovery is disabled
*
* @see #ACTION_NSD_STATE_CHANGED
*/
// TODO: Deprecate this since NSD service is never disabled.
public static final int NSD_STATE_DISABLED = 1;
/**
* Network service discovery is enabled
*
* @see #ACTION_NSD_STATE_CHANGED
*/
public static final int NSD_STATE_ENABLED = 2;
/** @hide */
public static final int DISCOVER_SERVICES = 1;
/** @hide */
public static final int DISCOVER_SERVICES_STARTED = 2;
/** @hide */
public static final int DISCOVER_SERVICES_FAILED = 3;
/** @hide */
public static final int SERVICE_FOUND = 4;
/** @hide */
public static final int SERVICE_LOST = 5;
/** @hide */
public static final int STOP_DISCOVERY = 6;
/** @hide */
public static final int STOP_DISCOVERY_FAILED = 7;
/** @hide */
public static final int STOP_DISCOVERY_SUCCEEDED = 8;
/** @hide */
public static final int REGISTER_SERVICE = 9;
/** @hide */
public static final int REGISTER_SERVICE_FAILED = 10;
/** @hide */
public static final int REGISTER_SERVICE_SUCCEEDED = 11;
/** @hide */
public static final int UNREGISTER_SERVICE = 12;
/** @hide */
public static final int UNREGISTER_SERVICE_FAILED = 13;
/** @hide */
public static final int UNREGISTER_SERVICE_SUCCEEDED = 14;
/** @hide */
public static final int RESOLVE_SERVICE = 15;
/** @hide */
public static final int RESOLVE_SERVICE_FAILED = 16;
/** @hide */
public static final int RESOLVE_SERVICE_SUCCEEDED = 17;
/** @hide */
public static final int DAEMON_CLEANUP = 18;
/** @hide */
public static final int DAEMON_STARTUP = 19;
/** @hide */
public static final int MDNS_SERVICE_EVENT = 20;
/** @hide */
public static final int REGISTER_CLIENT = 21;
/** @hide */
public static final int UNREGISTER_CLIENT = 22;
/** @hide */
public static final int MDNS_DISCOVERY_MANAGER_EVENT = 23;
/** @hide */
public static final int STOP_RESOLUTION = 24;
/** @hide */
public static final int STOP_RESOLUTION_FAILED = 25;
/** @hide */
public static final int STOP_RESOLUTION_SUCCEEDED = 26;
/** @hide */
public static final int REGISTER_SERVICE_CALLBACK = 27;
/** @hide */
public static final int REGISTER_SERVICE_CALLBACK_FAILED = 28;
/** @hide */
public static final int SERVICE_UPDATED = 29;
/** @hide */
public static final int SERVICE_UPDATED_LOST = 30;
/** @hide */
public static final int UNREGISTER_SERVICE_CALLBACK = 31;
/** @hide */
public static final int UNREGISTER_SERVICE_CALLBACK_SUCCEEDED = 32;
/** @hide */
public static final int REGISTER_OFFLOAD_ENGINE = 33;
/** @hide */
public static final int UNREGISTER_OFFLOAD_ENGINE = 34;
/** Dns based service discovery protocol */
public static final int PROTOCOL_DNS_SD = 0x0001;
/**
* The minimum TTL seconds which is allowed for a service registration.
*
* @hide
*/
public static final long TTL_SECONDS_MIN = 30L;
/**
* The maximum TTL seconds which is allowed for a service registration.
*
* @hide
*/
public static final long TTL_SECONDS_MAX = 10 * 3600L;
private static final SparseArray 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 {@link RegistrationListener#onServiceRegistered} or a failure
* through {@link RegistrationListener#onRegistrationFailed}.
*
* The application should call {@link #unregisterService} when the service
* registration is no longer required, and/or whenever the application is stopped.
*
* @param serviceInfo The service being registered
* @param protocolType The service discovery protocol
* @param listener The listener notifies of a successful registration and is used to
* unregister this service through a call on {@link #unregisterService}. Cannot be null.
* Cannot be in use for an active service registration.
*/
public void registerService(NsdServiceInfo serviceInfo, int protocolType,
RegistrationListener listener) {
registerService(serviceInfo, protocolType, Runnable::run, 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 {@link RegistrationListener#onServiceRegistered} or a failure
* through {@link RegistrationListener#onRegistrationFailed}.
*
* The application should call {@link #unregisterService} when the service
* registration is no longer required, and/or whenever the application is stopped.
* @param serviceInfo The service being registered
* @param protocolType The service discovery protocol
* @param executor Executor to run listener callbacks with
* @param listener The listener notifies of a successful registration and is used to
* unregister this service through a call on {@link #unregisterService}. Cannot be null.
*/
public void registerService(@NonNull NsdServiceInfo serviceInfo, int protocolType,
@NonNull Executor executor, @NonNull RegistrationListener listener) {
checkServiceInfoForRegistration(serviceInfo);
checkProtocol(protocolType);
final AdvertisingRequest.Builder builder = new AdvertisingRequest.Builder(serviceInfo,
protocolType);
// Optionally assume that the request is an update request if it uses subtypes and the same
// listener. This is not documented behavior as support for advertising subtypes via
// "_servicename,_sub1,_sub2" has never been documented in the first place, and using
// multiple subtypes was broken in T until a later module update. Subtype registration is
// documented in the NsdServiceInfo.setSubtypes API instead, but this provides a limited
// option for users of the older undocumented behavior, only for subtype changes.
if (isSubtypeUpdateRequest(serviceInfo, listener)) {
builder.setAdvertisingConfig(AdvertisingRequest.NSD_ADVERTISING_UPDATE_ONLY);
}
registerService(builder.build(), executor, listener);
}
private boolean isSubtypeUpdateRequest(@NonNull NsdServiceInfo serviceInfo, @NonNull
RegistrationListener listener) {
// If the listener is the same object, serviceInfo is for the same service name and
// type (outside of subtypes), and either of them use subtypes, treat the request as a
// subtype update request.
synchronized (mMapLock) {
int valueIndex = mListenerMap.indexOfValue(listener);
if (valueIndex == -1) {
return false;
}
final int key = mListenerMap.keyAt(valueIndex);
NsdServiceInfo existingService = mServiceMap.get(key);
if (existingService == null) {
return false;
}
final Pair This rejects specifications using dot syntax to specify subtypes ("_sub1._type._tcp").
*
* @return Type and comma-separated list of subtypes, or null if invalid format.
*/
@Nullable
private static Pair 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 {@link RegistrationListener#onServiceRegistered} or a failure
* through {@link RegistrationListener#onRegistrationFailed}.
*
* The application should call {@link #unregisterService} when the service
* registration is no longer required, and/or whenever the application is stopped.
* @param advertisingRequest service being registered
* @param executor Executor to run listener callbacks with
* @param listener The listener notifies of a successful registration and is used to
* unregister this service through a call on {@link #unregisterService}. Cannot be null.
*
* @hide
*/
// @FlaggedApi(Flags.ADVERTISE_REQUEST_API)
public void registerService(@NonNull AdvertisingRequest advertisingRequest,
@NonNull Executor executor,
@NonNull RegistrationListener listener) {
final NsdServiceInfo serviceInfo = advertisingRequest.getServiceInfo();
final int protocolType = advertisingRequest.getProtocolType();
checkServiceInfoForRegistration(serviceInfo);
checkProtocol(protocolType);
final int key;
// For update only request, the old listener has to be reused
if ((advertisingRequest.getAdvertisingConfig()
& AdvertisingRequest.NSD_ADVERTISING_UPDATE_ONLY) > 0) {
key = updateRegisteredListener(listener, executor, serviceInfo);
} else {
key = putListener(listener, executor, serviceInfo);
}
try {
mService.registerService(key, advertisingRequest);
} catch (RemoteException e) {
e.rethrowFromSystemServer();
}
}
/**
* Unregister a service registered through {@link #registerService}. A successful
* unregister is notified to the application with a call to
* {@link RegistrationListener#onServiceUnregistered}.
*
* @param listener This should be the listener object that was passed to
* {@link #registerService}. 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 unregisterService(RegistrationListener listener) {
int id = getListenerKey(listener);
try {
mService.unregisterService(id);
} catch (RemoteException e) {
e.rethrowFromSystemServer();
}
}
/**
* Initiate service discovery to browse for instances of a service type. Service discovery
* consumes network bandwidth and will continue until the application calls
* {@link #stopServiceDiscovery}.
*
* 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 {@link DiscoveryListener#onDiscoveryStarted} or a failure
* through {@link DiscoveryListener#onStartDiscoveryFailed}.
*
* Upon successful start, application is notified when a service is found with
* {@link DiscoveryListener#onServiceFound} or when a service is lost with
* {@link DiscoveryListener#onServiceLost}.
*
* Upon failure to start, service discovery is not active and application does
* not need to invoke {@link #stopServiceDiscovery}
*
* The application should call {@link #stopServiceDiscovery} when discovery of this
* service type is no longer required, and/or whenever the application is paused or
* stopped.
*
* @param serviceType The service type being discovered. Examples include "_http._tcp" for
* http services or "_ipp._tcp" for printers
* @param protocolType The service discovery protocol
* @param listener The listener notifies of a successful discovery and is used
* to stop discovery on this serviceType through a call on {@link #stopServiceDiscovery}.
* Cannot be null. Cannot be in use for an active service discovery.
*/
public void discoverServices(String serviceType, int protocolType, DiscoveryListener listener) {
discoverServices(serviceType, protocolType, (Network) null, Runnable::run, listener);
}
/**
* Initiate service discovery to browse for instances of a service type. Service discovery
* consumes network bandwidth and will continue until the application calls
* {@link #stopServiceDiscovery}.
*
* 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 {@link DiscoveryListener#onDiscoveryStarted} or a failure
* through {@link DiscoveryListener#onStartDiscoveryFailed}.
*
* Upon successful start, application is notified when a service is found with
* {@link DiscoveryListener#onServiceFound} or when a service is lost with
* {@link DiscoveryListener#onServiceLost}.
*
* Upon failure to start, service discovery is not active and application does
* not need to invoke {@link #stopServiceDiscovery}
*
* The application should call {@link #stopServiceDiscovery} when discovery of this
* service type is no longer required, and/or whenever the application is paused or
* stopped.
* @param serviceType The service type being discovered. Examples include "_http._tcp" for
* http services or "_ipp._tcp" for printers
* @param protocolType The service discovery protocol
* @param network Network to discover services on, or null to discover on all available networks
* @param executor Executor to run listener callbacks with
* @param listener The listener notifies of a successful discovery and is used
* to stop discovery on this serviceType through a call on {@link #stopServiceDiscovery}.
*/
public void discoverServices(@NonNull String serviceType, int protocolType,
@Nullable Network network, @NonNull Executor executor,
@NonNull DiscoveryListener listener) {
if (TextUtils.isEmpty(serviceType)) {
throw new IllegalArgumentException("Service type cannot be empty");
}
DiscoveryRequest request = new DiscoveryRequest.Builder(protocolType, serviceType)
.setNetwork(network).build();
discoverServices(request, executor, listener);
}
/**
* Initiates service discovery to browse for instances of a service type. Service discovery
* consumes network bandwidth and will continue until the application calls
* {@link #stopServiceDiscovery}.
*
* 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 {@link DiscoveryListener#onDiscoveryStarted} or a failure
* through {@link DiscoveryListener#onStartDiscoveryFailed}.
*
* Upon successful start, application is notified when a service is found with
* {@link DiscoveryListener#onServiceFound} or when a service is lost with
* {@link DiscoveryListener#onServiceLost}.
*
* Upon failure to start, service discovery is not active and application does
* not need to invoke {@link #stopServiceDiscovery}
*
* The application should call {@link #stopServiceDiscovery} when discovery of this
* service type is no longer required, and/or whenever the application is paused or
* stopped.
*
* @param discoveryRequest the {@link DiscoveryRequest} object which specifies the discovery
* parameters such as service type, subtype and network
* @param executor Executor to run listener callbacks with
* @param listener The listener notifies of a successful discovery and is used
* to stop discovery on this serviceType through a call on {@link #stopServiceDiscovery}.
*/
@FlaggedApi(Flags.NSD_SUBTYPES_SUPPORT_ENABLED)
public void discoverServices(@NonNull DiscoveryRequest discoveryRequest,
@NonNull Executor executor, @NonNull DiscoveryListener listener) {
int key = putListener(listener, executor, discoveryRequest);
try {
mService.discoverServices(key, discoveryRequest);
} catch (RemoteException e) {
e.rethrowFromSystemServer();
}
}
/**
* Initiate service discovery to browse for instances of a service type. Service discovery
* consumes network bandwidth and will continue until the application calls
* {@link #stopServiceDiscovery}.
*
* 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 {@link DiscoveryListener#onDiscoveryStarted} or a failure
* through {@link DiscoveryListener#onStartDiscoveryFailed}.
*
* Upon successful start, application is notified when a service is found with
* {@link DiscoveryListener#onServiceFound} or when a service is lost with
* {@link DiscoveryListener#onServiceLost}.
*
* Upon failure to start, service discovery is not active and application does
* not need to invoke {@link #stopServiceDiscovery}
*
* The application should call {@link #stopServiceDiscovery} 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,
* {@link DiscoveryListener#onServiceLost} will be called. If a new network connects that
* matches the {@link NetworkRequest}, {@link 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
* {@code discoverServices}, as they will receive proper notifications when a service becomes
* available or unavailable due to network changes.
* @param serviceType The service type being discovered. Examples include "_http._tcp" for
* http services or "_ipp._tcp" for printers
* @param protocolType The service discovery protocol
* @param networkRequest Request specifying networks that should be considered when discovering
* @param executor Executor to run listener callbacks with
* @param listener The listener notifies of a successful discovery and is used
* to stop discovery on this serviceType through a call on {@link #stopServiceDiscovery}.
*/
@RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE)
public void discoverServices(@NonNull String serviceType, int protocolType,
@NonNull NetworkRequest networkRequest, @NonNull Executor executor,
@NonNull DiscoveryListener listener) {
if (TextUtils.isEmpty(serviceType)) {
throw new IllegalArgumentException("Service type cannot be empty");
}
Objects.requireNonNull(networkRequest, "NetworkRequest cannot be null");
DiscoveryRequest discoveryRequest =
new DiscoveryRequest.Builder(protocolType, serviceType).build();
final int baseListenerKey = putListener(listener, executor, discoveryRequest);
final PerNetworkDiscoveryTracker discoveryInfo = new PerNetworkDiscoveryTracker(
serviceType, protocolType, executor, listener);
synchronized (mPerNetworkDiscoveryMap) {
mPerNetworkDiscoveryMap.put(baseListenerKey, discoveryInfo);
discoveryInfo.start(networkRequest);
}
}
/**
* Stop service discovery initiated with {@link #discoverServices}. An active service
* discovery is notified to the application with {@link DiscoveryListener#onDiscoveryStarted}
* and it stays active until the application invokes a stop service discovery. A successful
* stop is notified to with a call to {@link DiscoveryListener#onDiscoveryStopped}.
*
* Upon failure to stop service discovery, application is notified through
* {@link DiscoveryListener#onStopDiscoveryFailed}.
*
* @param listener This should be the listener object that was passed to {@link #discoverServices}.
* 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 stopServiceDiscovery(DiscoveryListener listener) {
int id = getListenerKey(listener);
// If this is a PerNetworkDiscovery request, handle it as such
synchronized (mPerNetworkDiscoveryMap) {
final PerNetworkDiscoveryTracker info = mPerNetworkDiscoveryMap.get(id);
if (info != null) {
info.requestStop();
return;
}
}
try {
mService.stopDiscovery(id);
} catch (RemoteException e) {
e.rethrowFromSystemServer();
}
}
/**
* 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.
*
* @param serviceInfo service to be resolved
* @param listener to receive callback upon success or failure. Cannot be null.
* Cannot be in use for an active service resolution.
*
* @deprecated 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
* {@link #registerServiceInfoCallback}, which will keep the application up-to-date with the
* state of the service.
*/
@Deprecated
public void resolveService(NsdServiceInfo serviceInfo, ResolveListener listener) {
resolveService(serviceInfo, Runnable::run, listener);
}
/**
* 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.
* @param serviceInfo service to be resolved
* @param executor Executor to run listener callbacks with
* @param listener to receive callback upon success or failure.
*
* @deprecated 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
* {@link #registerServiceInfoCallback}, which will keep the application up-to-date with the
* state of the service.
*/
@Deprecated
public void resolveService(@NonNull NsdServiceInfo serviceInfo,
@NonNull Executor executor, @NonNull ResolveListener listener) {
checkServiceInfoForResolution(serviceInfo);
int key = putListener(listener, executor, serviceInfo);
try {
mService.resolveService(key, serviceInfo);
} catch (RemoteException e) {
e.rethrowFromSystemServer();
}
}
/**
* Stop service resolution initiated with {@link #resolveService}.
*
* A successful stop is notified with a call to {@link ResolveListener#onResolutionStopped}.
*
* Upon failure to stop service resolution for example if resolution is done or the
* requester stops resolution repeatedly, the application is notified
* {@link ResolveListener#onStopResolutionFailed} with {@link #FAILURE_OPERATION_NOT_RUNNING}
*
* @param listener This should be a listener object that was passed to {@link #resolveService}.
* It identifies the resolution that should be stopped and notifies of a
* successful or unsuccessful stop. Throws {@code IllegalArgumentException} if
* the listener was not passed to resolveService before.
*/
public void stopServiceResolution(@NonNull ResolveListener listener) {
int id = getListenerKey(listener);
try {
mService.stopResolution(id);
} catch (RemoteException e) {
e.rethrowFromSystemServer();
}
}
/**
* 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 {@link ServiceInfoCallback#onServiceUpdated}.
*
* This is different from {@link #resolveService} 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
* {@link ServiceInfoCallback#onServiceInfoCallbackRegistrationFailed} with
* {@link #FAILURE_BAD_PARAMETERS}.
*
* @param serviceInfo the service to receive updates for
* @param executor Executor to run callbacks with
* @param listener to receive callback upon service update
*/
// TODO: use {@link DiscoveryRequest} to specify the service to be subscribed
public void registerServiceInfoCallback(@NonNull NsdServiceInfo serviceInfo,
@NonNull Executor executor, @NonNull ServiceInfoCallback listener) {
checkServiceInfoForResolution(serviceInfo);
int key = putListener(listener, executor, serviceInfo);
try {
mService.registerServiceInfoCallback(key, serviceInfo);
} catch (RemoteException e) {
e.rethrowFromSystemServer();
}
}
/**
* Unregister a callback registered with {@link #registerServiceInfoCallback}.
*
* A successful unregistration is notified with a call to
* {@link ServiceInfoCallback#onServiceInfoCallbackUnregistered}. The same callback can only be
* reused after this is called.
*
* If the callback is not already registered, this will throw with
* {@link IllegalArgumentException}.
*
* @param listener This should be a listener object that was passed to
* {@link #registerServiceInfoCallback}. It identifies the registration that
* should be unregistered and notifies of a successful or unsuccessful stop.
* Throws {@code IllegalArgumentException} if the listener was not passed to
* {@link #registerServiceInfoCallback} before.
*/
public void unregisterServiceInfoCallback(@NonNull ServiceInfoCallback listener) {
// Will throw IllegalArgumentException if the listener is not known
int id = getListenerKey(listener);
try {
mService.unregisterServiceInfoCallback(id);
} catch (RemoteException e) {
e.rethrowFromSystemServer();
}
}
private static void checkListener(Object listener) {
Objects.requireNonNull(listener, "listener cannot be null");
}
static void checkProtocol(int protocolType) {
if (protocolType != PROTOCOL_DNS_SD) {
throw new IllegalArgumentException("Unsupported protocol");
}
}
private static void checkServiceInfoForResolution(NsdServiceInfo serviceInfo) {
Objects.requireNonNull(serviceInfo, "NsdServiceInfo cannot be null");
if (TextUtils.isEmpty(serviceInfo.getServiceName())) {
throw new IllegalArgumentException("Service name cannot be empty");
}
if (TextUtils.isEmpty(serviceInfo.getServiceType())) {
throw new IllegalArgumentException("Service type cannot be empty");
}
}
private enum ServiceValidationType {
NO_SERVICE,
HAS_SERVICE, // A service with a positive port
HAS_SERVICE_ZERO_PORT, // A service with a zero port
}
private enum HostValidationType {
DEFAULT_HOST, // No host is specified so the default host will be used
CUSTOM_HOST, // A custom host with addresses is specified
CUSTOM_HOST_NO_ADDRESS, // A custom host without address is specified
}
private enum PublicKeyValidationType {
NO_KEY,
HAS_KEY,
}
/**
* Check if the service is valid for registration and classify it as one of {@link
* ServiceValidationType}.
*/
private static ServiceValidationType validateService(NsdServiceInfo serviceInfo) {
final boolean hasServiceName = !TextUtils.isEmpty(serviceInfo.getServiceName());
final boolean hasServiceType = !TextUtils.isEmpty(serviceInfo.getServiceType());
if (!hasServiceName && !hasServiceType && serviceInfo.getPort() == 0) {
return ServiceValidationType.NO_SERVICE;
}
if (!hasServiceName || !hasServiceType) {
throw new IllegalArgumentException("The service name or the service type is missing");
}
if (serviceInfo.getPort() < 0) {
throw new IllegalArgumentException("Invalid port");
}
if (serviceInfo.getPort() == 0) {
return ServiceValidationType.HAS_SERVICE_ZERO_PORT;
}
return ServiceValidationType.HAS_SERVICE;
}
/**
* Check if the host is valid for registration and classify it as one of {@link
* HostValidationType}.
*/
private static HostValidationType validateHost(NsdServiceInfo serviceInfo) {
final boolean hasHostname = !TextUtils.isEmpty(serviceInfo.getHostname());
final boolean hasHostAddresses = !CollectionUtils.isEmpty(serviceInfo.getHostAddresses());
if (!hasHostname) {
// Keep compatible with the legacy behavior: It's allowed to set host
// addresses for a service registration although the host addresses
// won't be registered. To register the addresses for a host, the
// hostname must be specified.
return HostValidationType.DEFAULT_HOST;
}
if (!hasHostAddresses) {
return HostValidationType.CUSTOM_HOST_NO_ADDRESS;
}
return HostValidationType.CUSTOM_HOST;
}
/**
* Check if the public key is valid for registration and classify it as one of {@link
* PublicKeyValidationType}.
*
* For simplicity, it only checks if the protocol is DNSSEC and the RDATA is not fewer than 4
* bytes. See RFC 3445 Section 3.
*/
private static PublicKeyValidationType validatePublicKey(NsdServiceInfo serviceInfo) {
byte[] publicKey = serviceInfo.getPublicKey();
if (publicKey == null) {
return PublicKeyValidationType.NO_KEY;
}
if (publicKey.length < 4) {
throw new IllegalArgumentException("The public key should be at least 4 bytes long");
}
int protocol = publicKey[2];
if (protocol == DNSSEC_PROTOCOL) {
return PublicKeyValidationType.HAS_KEY;
}
throw new IllegalArgumentException(
"The public key's protocol ("
+ protocol
+ ") is invalid. It should be DNSSEC_PROTOCOL (3)");
}
/**
* Check if the {@link NsdServiceInfo} is valid for registration.
*
* Firstly, check if service, host and public key are all valid respectively. Then check if
* the combination of service, host and public key is valid.
*
* If the {@code serviceInfo} is invalid, throw an {@link IllegalArgumentException}
* describing the reason.
*
* There are the invalid combinations of service, host and public key:
*
* Keys are used to reserve hostnames or service names while the service/host is temporarily
* inactive, so registrations with a key and just a hostname or a service name are acceptable.
*
* @hide
*/
public static void checkServiceInfoForRegistration(NsdServiceInfo serviceInfo) {
Objects.requireNonNull(serviceInfo, "NsdServiceInfo cannot be null");
final ServiceValidationType serviceValidation = validateService(serviceInfo);
final HostValidationType hostValidation = validateHost(serviceInfo);
final PublicKeyValidationType publicKeyValidation = validatePublicKey(serviceInfo);
if (serviceValidation == ServiceValidationType.NO_SERVICE
&& hostValidation == HostValidationType.DEFAULT_HOST) {
throw new IllegalArgumentException("Nothing to register");
}
if (publicKeyValidation == PublicKeyValidationType.NO_KEY) {
if (serviceValidation == ServiceValidationType.HAS_SERVICE_ZERO_PORT) {
throw new IllegalArgumentException("The port is missing");
}
if (serviceValidation == ServiceValidationType.NO_SERVICE
&& hostValidation == HostValidationType.CUSTOM_HOST_NO_ADDRESS) {
throw new IllegalArgumentException(
"The host addresses must be specified unless there is a service");
}
}
}
}
*
*
*