---

NSNetServiceBrowser Class Reference

Overview

The NSNetServiceBrowser class defines an interface for finding published services on a network using multicast DNS. An instance of NSNetServiceBrowser is known as a network service browser.

Services can range from standard services, such as HTTP and FTP, to custom services defined by other applications. You can use a network service browser in your code to obtain the list of accessible domains and then to obtain an NSNetService object for each discovered service. Each network service browser performs one search at a time, so if you want to perform multiple simultaneous searches, use multiple network service browsers.

A network service browser performs all searches asynchronously using the current run loop to execute the search in the background. Results from a search are returned through the associated delegate object, which your client application must provide. Searching proceeds in the background until the object receives a stop message.

To use an NSNetServiceBrowser object to search for services, allocate it, initialize it, and assign a delegate. (If you wish, you can also use the scheduleInRunLoop:forMode: and removeFromRunLoop:forMode: methods to execute searches on a run loop other than the current one.) Once your object is ready, you begin by gathering the list of accessible domains using either the searchForRegistrationDomains or searchForBrowsableDomains methods. From the list of returned domains, you can pick one and use the searchForServicesOfType:inDomain: method to search for services in that domain.

The NSNetServiceBrowser class provides two ways to search for domains. In most cases, your client should use the searchForRegistrationDomains method to search only for local domains to which the host machine has registration authority. This is the preferred method for accessing domains as it guarantees that the host machine can connect to services in the returned domains. Access to domains outside this list may be more limited.

Tasks

Creating Network Service Browsers

• – init

Configuring Network Service Browsers

• – delegate
• – setDelegate:

Using Network Service Browsers

• – searchForBrowsableDomains
• – searchForRegistrationDomains
• – netServiceBrowser:didFindDomain:moreComing:  delegate method
• – netServiceBrowser:didRemoveDomain:moreComing:  delegate method
• – searchForServicesOfType:inDomain:
• – netServiceBrowser:didFindService:moreComing:  delegate method
• – netServiceBrowser:didRemoveService:moreComing:  delegate method
• – netServiceBrowserWillSearch:  delegate method
• – netServiceBrowser:didNotSearch:  delegate method
• – stop
• – netServiceBrowserDidStopSearch:  delegate method
• – searchForAllDomains Deprecated in Mac OS X v10.4

Managing Run Loops

• – scheduleInRunLoop:forMode:
• – removeFromRunLoop:forMode:

Instance Methods

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

Delegate for the receiver.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – setDelegate:

Declared In

NSNetServices.h

init

Initializes an allocated NSNetServiceBrowser object.

- (id)init

Return Value

Initialized NSNetServiceBrowser object.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSNetServices.h

removeFromRunLoop:forMode:

Removes the receiver from the specified run loop.

- (void)removeFromRunLoop:(NSRunLoop *)runLoop forMode:(NSString *)runLoopMode

Parameters

runLoop

Run loop from which to remove the receiver.

runLoopMode

Run loop mode in which to perform this operation, such as NSDefaultRunLoopMode. See the “Constants” section of the NSRunLoop class for other run loop mode values.

Discussion

You can use this method in conjunction with scheduleInRunLoop:forMode: to transfer the receiver to a run loop other than the default one. Although it is possible to remove an NSNetService object completely from any run loop and then attempt actions on it, you must not do it.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – scheduleInRunLoop:forMode:

Declared In

NSNetServices.h

scheduleInRunLoop:forMode:

Adds the receiver to the specified run loop.

- (void)scheduleInRunLoop:(NSRunLoop *)runLoop forMode:(NSString *)runLoopMode

Parameters

runLoop

Run loop from which to remove the receiver.

runLoopMode

Run loop mode in which to perform this operation, such as NSDefaultRunLoopMode. See the “Constants” section of the NSRunLoop class for other run loop mode values.

Discussion

You can use this method in conjunction with removeFromRunLoop:forMode: to transfer the receiver to a run loop other than the default one. You should not attempt to run the receiver on multiple run loops.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – removeFromRunLoop:forMode:

Declared In

NSNetServices.h

searchForBrowsableDomains

Initiates a search for domains visible to the host. This method returns immediately.

- (void)searchForBrowsableDomains

Discussion

The delegate receives a netServiceBrowser:didFindDomain:moreComing: message for each domain discovered.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – searchForRegistrationDomains

Declared In

NSNetServices.h

searchForRegistrationDomains

Initiates a search for domains in which the host may register services.

- (void)searchForRegistrationDomains

Discussion

This method returns immediately, sending a netServiceBrowserWillSearch: message to the delegate if the network was ready to initiate the search. The delegate receives a subsequent netServiceBrowser:didFindDomain:moreComing: message for each domain discovered.

Most network service browser clients do not have to use this method—it is sufficient to publish a service with the empty string, which registers it in any available registration domains automatically.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – searchForBrowsableDomains
• – searchForServicesOfType:inDomain:
• – netServiceBrowser:didFindDomain:moreComing:
• – netServiceBrowserWillSearch:

Declared In

NSNetServices.h

searchForServicesOfType:inDomain:

Starts a search for services of a particular type within a specific domain.

- (void)searchForServicesOfType:(NSString *)serviceType inDomain:(NSString *)domainName

Parameters

serviceType

Type of the service to search for.

domainName

Domain name in which to perform the search.

Discussion

This method returns immediately, sending a netServiceBrowserWillSearch: message to the delegate if the network was ready to initiate the search.The delegate receives subsequent netServiceBrowser:didFindService:moreComing: messages for each service discovered.

The serviceType argument must contain both the service type and transport layer information. To ensure that the mDNS responder searches for services, rather than hosts, make sure to prefix both the service name and transport layer name with an underscore character (“_”). For example, to search for an HTTP service on TCP, you would use the type string “_http._tcp.“. Note that the period character at the end is required.

The domainName argument can be an explicit domain name, the generic local domain @"local." (note trailing period, which indicates an absolute name), or the empty string (@""), which indicates the default registration domains. Usually, you pass in an empty string. Note that it is acceptable to use an empty string for the domainName argument when publishing or browsing a service, but do not rely on this for resolution.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – netServiceBrowser:didFindService:moreComing:
• – netServiceBrowserWillSearch:

Declared In

NSNetServices.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)delegate

Parameters

delegate

Object to serve as the receiver’s delegate. Must not be nil.

Discussion

The delegate is not retained. The receiver calls the methods of your delegate to receive information about discovered domains and services.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – delegate

Declared In

NSNetServices.h

stop

Halts a currently running search or resolution.

- (void)stop

Discussion

This method sends a netServiceBrowserDidStopSearch: message to the delegate and causes the browser to discard any pending search results.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – netServiceBrowserDidStopSearch:

Declared In

NSNetServices.h

Delegate Methods

netServiceBrowser:didFindDomain:moreComing:

Tells the delegate the sender found a domain.

- (void)netServiceBrowser:(NSNetServiceBrowser *)netServiceBrowser didFindDomain:(NSString *)domainName moreComing:(BOOL)moreDomainsComing

Parameters

netServiceBrowser

Sender of this delegate message.

domainName

Name of the domain found by netServiceBrowser.

moreDomainsComing

YES when netServiceBrowser is waiting for additional domains. NO when there are no additional domains.

Discussion

The delegate uses this message to compile a list of available domains. It should wait until moreDomainsComing is NO to do a bulk update of user interface elements.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – searchForBrowsableDomains
• – searchForRegistrationDomains

Declared In

NSNetServices.h

netServiceBrowser:didFindService:moreComing:

Tells the delegate the sender found a service.

- (void)netServiceBrowser:(NSNetServiceBrowser *)netServiceBrowser didFindService:(NSNetService *)netService moreComing:(BOOL)moreServicesComing

Parameters

netServiceBrowser

Sender of this delegate message.

netService

Network service found by netServiceBrowser. The delegate can use this object to connect to and use the service.

moreServicesComing

YES when netServiceBrowser is waiting for additional services. NO when there are no additional services.

Discussion

The delegate uses this message to compile a list of available services. It should wait until moreServicesComing is NO to do a bulk update of user interface elements.

Special Considerations

If the delegate chooses to resolve netService, it should retain netService and set itself as that service’s delegate. The delegate should, therefore, release that service when it receives the netServiceDidResolveAddress: or netService:didNotResolve: delegate messages of the NSNetService class.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – searchForServicesOfType:inDomain:

Declared In

NSNetServices.h

netServiceBrowser:didNotSearch:

Tells the delegate that a search was not successful.

- (void)netServiceBrowser:(NSNetServiceBrowser *)netServiceBrowser didNotSearch:(NSDictionary *)errorInfo

Parameters

netServiceBrowser

Sender of this delegate message.

errorInfo

Dictionary with the reasons the search was unsuccessful. Use the dictionary keys NSNetServicesErrorCode and NSNetServicesErrorDomain to retrieve the error information from the dictionary.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – netServiceBrowserWillSearch:

Declared In

NSNetServices.h

netServiceBrowser:didRemoveDomain:moreComing:

Tells the delegate the a domain has disappeared or has become unavailable.

- (void)netServiceBrowser:(NSNetServiceBrowser *)netServiceBrowser didRemoveDomain:(NSString *)domainName moreComing:(BOOL)moreDomainsComing

Parameters

netServiceBrowser

Sender of this delegate message.

domainName

Name of the domain that became unavailable.

moreDomainsComing

YES when netServiceBrowser is waiting for additional domains. NO when there are no additional domains.

Discussion

The delegate uses this message to compile a list of unavailable domains. It should wait until moreDomainsComing is NO to do a bulk update of user interface elements.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSNetServices.h

netServiceBrowser:didRemoveService:moreComing:

Tells the delegate a service has disappeared or has become unavailable.

- (void)netServiceBrowser:(NSNetServiceBrowser *)netServiceBrowser didRemoveService:(NSNetService *)netService moreComing:(BOOL)moreServicesComing

Parameters

netServiceBrowser

Sender of this delegate message.

netService

Network service that has become unavailable.

moreServicesComing

YES when netServiceBrowser is waiting for additional services. NO when there are no additional services.

Discussion

The delegate uses this message to compile a list of unavailable services. It should wait until moreServicesComing is NO to do a bulk update of user interface elements.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSNetServices.h

netServiceBrowserDidStopSearch:

Tells the delegate that a search was stopped.

- (void)netServiceBrowserDidStopSearch:(NSNetServiceBrowser *)netServiceBrowser

Parameters

netServiceBrowser

Sender of this delegate message.

Discussion

When netServiceBrowser receives a stop message from its client, netServiceBrowser sends a netServiceBrowserDidStopSearch: message to its delegate. The delegate then performs any necessary cleanup.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – stop

Declared In

NSNetServices.h

netServiceBrowserWillSearch:

Tells the delegate that a serch is commencing.

- (void)netServiceBrowserWillSearch:(NSNetServiceBrowser *)netServiceBrowser

Parameters

netServiceBrowser

Sender of this delegate message.

Discussion

This message is sent to the delegate only if the underlying network layer is ready to begin a search. The delegate can use this notification to prepare its data structures to receive data.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – netServiceBrowser:didNotSearch:

Declared In

NSNetServices.h

---