NSNetService Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 2.0 and later. |
| Declared in | NSNetServices.h |
| Companion guides | |
Overview
The NSNetService class represents a network service that your application publishes or uses as a client. This class and the NSNetServiceBrowser class use multicast DNS to convey information about network services to and from your application. The API of NSNetService provides a convenient way to publish the services offered by your application and to resolve the socket address for a service.
The types of services you access using NSNetService are the same types that you access directly using BSD sockets. HTTP and FTP are two services commonly provided by systems. (For a list of common services and the ports used by those services, see the file /etc/services.) Applications can also define their own custom services to provide specific data to clients.
You can use the NSNetService class as either a publisher of a service or as a client of a service. If your application publishes a service, your code must acquire a port and prepare a socket to communicate with clients. Once your socket is ready, you use the NSNetService class to notify clients that your service is ready. If your application is the client of a network service, you can either create an NSNetService object directly (if you know the exact host and port information) or you can use an NSNetServiceBrowser object to browse for services.
To publish a service, you must initialize your NSNetService object with the service name, domain, type, and port information. All of this information must be valid for the socket created by your application. Once initialized, you call the publish method to broadcast your service information out to the network.
When connecting to a service, you would normally use the NSNetServiceBrowser class to locate the service on the network and obtain the corresponding NSNetService object. Once you have the object, you proceed to call the resolveWithTimeout: method to verify that the service is available and ready for your application. If it is, the addresses method returns the socket information you can use to connect to the service.
The methods of NSNetService operate asynchronously so that your application is not impacted by the speed of the network. All information about a service is returned to your application through the NSNetService object’s delegate. You must provide a delegate object to respond to messages and to handle errors appropriately.
Tasks
Creating Network Services
Configuring Network Services
-
+ dataFromTXTRecordDictionary: -
+ dictionaryFromTXTRecordData: -
– addresses -
– domain -
– getInputStream:outputStream: -
– hostName -
– name -
– type -
– TXTRecordData -
– setTXTRecordData: -
– delegate -
– setDelegate:
Managing Run Loops
Using Network Services
-
– publish -
– publishWithOptions: -
– resolveWithTimeout: -
– port -
– startMonitoring -
– stop -
– stopMonitoring -
– resolveDeprecated in iOS 2.0
Class Methods
dataFromTXTRecordDictionary:
Returns an NSData object representing a TXT record formed from a given dictionary.
Parameters
- txtDictionary
A dictionary containing a TXT record.
Return Value
An NSData object representing TXT data formed from txtDictionary. Fails an assertion if txtDictionary cannot be represented as an NSData object.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hdictionaryFromTXTRecordData:
Returns a dictionary representing a TXT record given as an NSData object.
Parameters
- txtData
A data object encoding a TXT record.
Return Value
A dictionary representing txtData. The dictionary’s keys are NSString objects using UTF8 encoding. The values associated with all the dictionary’s keys are NSData objects that encapsulate strings or data.
Fails an assertion if txtData cannot be represented as an NSDictionary object.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hInstance Methods
addresses
Returns an array containing NSData objects, each of which contains a socket address for the service.
Return Value
An array containing NSData objects, each of which contains a socket address for the service. Each NSData object in the returned array contains an appropriate sockaddr structure that you can use to connect to the socket. The exact type of this structure depends on the service to which you are connecting. If no addresses were resolved for the service, the returned array contains zero elements.
Discussion
It is possible for a single service to resolve to more than one address or not resolve to any addresses. A service might resolve to multiple addresses if the computer publishing the service is currently multihoming.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hdelegate
Returns the delegate for the receiver.
Return Value
The delegate for the receiver.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hdomain
Returns the domain name of the service.
Return Value
The domain name of the service.
This can be an explicit domain name or it can contain the generic local domain name, @"local." (note the trailing period, which indicates an absolute name).
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hgetInputStream:outputStream:
Retrieves by reference the input and output streams for the receiver and returns a Boolean value that indicates whether they were retrieved successfully.
Parameters
- inputStream
Upon return, the input stream for the receiver.
- outputStream
Upon return, the output stream for the receiver.
Discussion
After this method is called, no delegate callbacks are called by the receiver.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hhostName
Returns the host name of the computer providing the service.
Return Value
The host name of the computer providing the service. Returns nil if a successful resolve has not occurred.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hinitWithDomain:type:name:
Returns the receiver, initialized as a network service of a given type and sets the initial host information.
Parameters
- domain
The domain for the service. For the local domain, use
@"local."not@"".- type
The network service type.
type must contain both the service type and transport layer information. To ensure that the mDNS responder searches for services, as opposed to hosts, 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 of the string, which indicates that the domain name is an absolute name, is required.- name
The name of the service to resolve.
Return Value
The receiver, initialized as a network service named name of type type in the domain domain.
Discussion
This method is the appropriate initializer to use to resolve a service—to publish a service, use initWithDomain:type:name:port:.
If you know the values for domain, type, and name of the service you wish to connect to, you can create an NSNetService object using this initializer and call resolveWithTimeout: on the result.
You cannot use this initializer to publish a service. This initializer passes an invalid port number to the designated initializer, which prevents the service from being registered. Calling publish on an NSNetService object initialized with this method generates a call to your delegate’s netService:didNotPublish: method with an NSNetServicesBadArgumentError error.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hinitWithDomain:type:name:port:
Initializes the receiver as a network service of type type at the socket location specified by domain, name, and port.
Parameters
- domain
The domain for the service. For the local domain, use
@"local."not@"".It is generally preferred to use a
NSNetServiceBrowserobject to obtain the local registration domain in which to publish your service. To use this default domain, simply pass in an empty string (@"").- type
The network service type.
type must contain both the service type and transport layer information. To ensure that the mDNS responder searches for services, as opposed to hosts, 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 of the string, which indicates that the domain name is an absolute name, is required.- name
The name by which the service is identified to the network. The name must be unique. If you pass the empty string (
@""), the system automatically advertises your service using the computer name as the service name.- port
The port on which the service is published.
port must be a port number acquired by your application for the service.
Discussion
You use this method to create a service that you wish to publish on the network. Although you can also use this method to create a service you wish to resolve on the network, it is generally more appropriate to use the initWithDomain:type:name: method instead.
When publishing a service, you must provide valid arguments in order to advertise your service correctly. If the host computer has access to multiple registration domains, you must create separate NSNetService objects for each domain. If you attempt to publish in a domain for which you do not have registration authority, your request may be denied.
It is acceptable to use an empty string for the domain argument when publishing or browsing a service, but do not rely on this for resolution.
This method is the designated initializer.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hname
Returns the name of the service.
Return Value
The name of the service.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hport
Provides the port of the receiver.
Return Value
The receiver’s port. -1 when it has not been resolved.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hpublish
Attempts to advertise the receiver’s on the network.
Discussion
This method returns immediately, with success or failure indicated by the callbacks to the delegate.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hpublishWithOptions:
Attempts to advertise the receiver on the network, with the given options.
Parameters
- serviceOptions
Options for the receiver.
Discussion
This method returns immediately, with success or failure indicated by the callbacks to the delegate.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hremoveFromRunLoop:forMode:
Removes the service from the given run loop for a given mode.
Parameters
- aRunLoop
The run loop from which to remove the receiver.
- mode
The run loop mode from which to remove the receiver. Possible values for mode are discussed in the "Constants" section of
NSRunLoop.
Discussion
You can use this method in conjunction with scheduleInRunLoop:forMode: to transfer the service to a different run loop. Although it is possible to remove an NSNetService object completely from any run loop and then attempt actions on it, it is an error to do so.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hresolveWithTimeout:
Starts a resolve process of a finite duration for the receiver.
Parameters
- timeout
The maximum number of seconds to attempt a resolve. A value of 0.0 indicates no timeout and a resolve process of indefinite duration.
Discussion
If the resolve succeeds before the timeout period lapses, the receiver sends netServiceDidResolveAddress: to the delegate. Otherwise, the receiver sends netService:didNotResolve: to the delegate.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hscheduleInRunLoop:forMode:
Adds the service to the specified run loop.
Parameters
- aRunLoop
The run loop to which to add the receiver.
- mode
The run loop mode to which to add the receiver. Possible values for mode are discussed in the "Constants" section of
NSRunLoop.
Discussion
You can use this method in conjunction with removeFromRunLoop:forMode: to transfer a service to a different run loop. You should not attempt to run a service on multiple run loops.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hsetDelegate:
Sets the delegate for the receiver.
Parameters
- delegate
The delegate for the receiver. The delegate must conform to the
NSNetServiceDelegate Protocolprotocol.
Discussion
The delegate is not retained.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hsetTXTRecordData:
Sets the TXT record for the receiver, and returns a Boolean value that indicates whether the operation was successful.
Parameters
- recordData
The TXT record for the receiver.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hstartMonitoring
Starts the monitoring of TXT-record updates for the receiver.
Discussion
The delegate must implement netService:didUpdateTXTRecordData:, which is called when the TXT record for the receiver is updated.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hstop
Halts a currently running attempt to publish or resolve a service.
Discussion
This method results in the sending of a netServiceDidStop: message to the delegate.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hstopMonitoring
Stops the monitoring of TXT-record updates for the receiver.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSNetServices.hTXTRecordData
Returns the TXT record for the receiver.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.htype
Returns the type of the service.
Return Value
The type of the service.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.hConstants
NSNetServices Errors
If an error occurs, the delegate error-handling methods return a dictionary with the following keys.
extern NSString *NSNetServicesErrorCode; extern NSString *NSNetServicesErrorDomain;
Constants
NSNetServicesErrorCodeThis key identifies the error that occurred during the most recent operation.
Available in iOS 2.0 and later.
Declared in
NSNetServices.h.NSNetServicesErrorDomainThis key identifies the originator of the error, which is either the
NSNetServiceobject or the mach network layer. For most errors, you should not need the value provided by this key.Available in iOS 2.0 and later.
Declared in
NSNetServices.h.
Declared In
NSNetServices.hNSNetServicesError
These constants identify errors that can occur when accessing net services.
typedef enum {
NSNetServicesUnknownError = -72000,
NSNetServicesCollisionError = -72001,
NSNetServicesNotFoundError = -72002,
NSNetServicesActivityInProgress = -72003,
NSNetServicesBadArgumentError = -72004,
NSNetServicesCancelledError = -72005,
NSNetServicesInvalidError = -72006,
NSNetServicesTimeoutError = -72007,
} NSNetServicesError;
Constants
NSNetServicesUnknownErrorAn unknown error occurred.
Available in iOS 2.0 and later.
Declared in
NSNetServices.h.NSNetServicesCollisionErrorThe service could not be published because the name is already in use. The name could be in use locally or on another system.
Available in iOS 2.0 and later.
Declared in
NSNetServices.h.NSNetServicesNotFoundErrorThe service could not be found on the network.
Available in iOS 2.0 and later.
Declared in
NSNetServices.h.NSNetServicesActivityInProgressThe net service cannot process the request at this time. No additional information about the network state is known.
Available in iOS 2.0 and later.
Declared in
NSNetServices.h.NSNetServicesBadArgumentErrorAn invalid argument was used when creating the
NSNetServiceobject.Available in iOS 2.0 and later.
Declared in
NSNetServices.h.NSNetServicesCancelledErrorThe client canceled the action.
Available in iOS 2.0 and later.
Declared in
NSNetServices.h.NSNetServicesInvalidErrorThe net service was improperly configured.
Available in iOS 2.0 and later.
Declared in
NSNetServices.h.NSNetServicesTimeoutErrorThe net service has timed out.
Available in iOS 2.0 and later.
Declared in
NSNetServices.h.
Declared In
NSNetServices.hNSNetServiceOptions
These constants specify options for a network service.
enum {
NSNetServiceNoAutoRename = 1 << 0
};
typedef NSUInteger NSNetServiceOptions;
Constants
NSNetServiceNoAutoRenameSpecifies that the network service not rename itself in the event of a name collision.
Available in iOS 2.0 and later.
Declared in
NSNetServices.h.
Availability
- Available in iOS 2.0 and later.
Declared In
NSNetServices.h© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-01-04)