Connecting with Streams

If you are connecting using Foundation’s raw TCP stream API (as opposed to a higher-level API, such as NSURLConnection), the most straightforward way to connect to a service is with a connect-to-service API, such as getInputStream:outputStream:.

This method provides a reference to an input stream (NSInputStream) and an output stream (NSOutputStream), both of which you may access synchronously or asynchronously. To interact asynchronously, you must schedule the streams in the current run loop and assign them a delegate object. These streams provide a general-purpose means of communicating with TCP-based network services that is not tied to any specific protocol (such as HTTP).

Listing 4-1 demonstrates how to connect to a network service (NSNetService) using streams. Note that if you require only one of the two streams, you should pass NULL for the other parameter so that you do not get the other stream back. For a complete example of service resolution using NSStream objects, see the PictureSharing sample code project in the Mac Developer Library.

Listing 4-1  Connecting to a resolved Bonjour network service

#import <sys/socket.h>

#import <netinet/in.h>

// ...

NSNetService *service;  // Assume this exists. For instance, you may

                        // have received it from an NSNetServiceBrowser

                        // delegate callback.

NSInputStream *istream = nil;

NSOutputStream *ostream = nil;

[service getInputStream:&istream outputStream:&ostream];

if (istream && ostream)

{

    // Use the streams as you like for reading and writing.

}

else

{

    NSLog(@"Failed to acquire valid streams");

}

Connecting by Name

If you are connecting to a Bonjour service using a higher-level API such as NSURLConnection, you should connect using the service’s hostname.

You can obtain the hostname for a Bonjour service by resolving the service and then calling the hostName method on the NSNetService object. Then, pass that hostname and port to the appropriate API, just as you would any other hostname.

id delegateObject = [[NetServiceResolutionDelegate alloc] init]; // Defined below

NSString *serviceName = ...;

NSNetService *service;

service = [[NSNetService alloc] initWithDomain:@"local." type:@"_music._tcp"

                                name:serviceName];

[service setDelegate:delegateObject];

[service resolveWithTimeout:5.0];

#import <Foundation/Foundation.h>

@interface NetServiceResolutionDelegate : NSObject <NSNetServiceDelegate>

{

    // Keeps track of services handled by this delegate

    NSMutableArray *services;

}

// Other methods

- (BOOL)addressesComplete:(NSArray *)addresses

        forServiceType:(NSString *)serviceType;

- (void)handleError:(NSNumber *)error withService:(NSNetService *)service;

@end

#import "NetServiceResolutionDelegate.h"

@implementation NetServiceResolutionDelegate

- (id)init

{

    self = [super init];

    if (self) {

        services = [[NSMutableArray alloc] init];

    }

    return self;

}

// Sent when addresses are resolved

- (void)netServiceDidResolveAddress:(NSNetService *)netService

{

    // Make sure [netService addresses] contains the

    // necessary connection information

    if ([self addressesComplete:[netService addresses]

            forServiceType:[netService type]]) {

        [services addObject:netService];

    }

}

// Sent if resolution fails

- (void)netService:(NSNetService *)netService

        didNotResolve:(NSDictionary *)errorDict

{

    [self handleError:[errorDict objectForKey:NSNetServicesErrorCode] withService:netService];

    [services removeObject:netService];

}

// Verifies [netService addresses]

- (BOOL)addressesComplete:(NSArray *)addresses

        forServiceType:(NSString *)serviceType

{

    // Perform appropriate logic to ensure that [netService addresses]

    // contains the appropriate information to connect to the service

    return YES;

}

// Error handling code

- (void)handleError:(NSNumber *)error withService:(NSNetService *)service

{

    NSLog(@"An error occurred with service %@.%@.%@, error code = %d",

        [service name], [service type], [service domain], [error intValue]);

    // Handle error here

}

@end

            // serviceName should be in the form

            // "name.service.protocol.domain.".  For example:

            // "MyLaptop._ftp._tcp.local."

            NSString *serviceName = ...;

            NSString *              serviceName;

            NSArray *               serviceNameComponents;

            NSUInteger              serviceNameComponentsCount;

            serviceNameComponents = [serviceName componentsSeparatedByString:@"."];

            serviceNameComponentsCount = [serviceNameComponents count];

            if ( (serviceNameComponentsCount >= 5) && ([serviceNameComponents[serviceNameComponentsCount - 1] length] == 0) ) {

                protocol = [serviceNameComponents[2] lowercaseString];

                if ( [protocol isEqual:@"_tcp"] || [protocol isEqual:@"_udp"] ) {

                    fullname = [[serviceNameComponents subarrayWithRange:NSMakeRange(1, serviceNameComponentsCount - 1)] componentsJoinedByString:@"."];

                    retVal = EXIT_SUCCESS;

                    NSMutableData *     recordData;

                    recordData = [[NSMutableData alloc] init];

                    for (NSString * label in serviceNameComponents) {

                        const char *    labelStr;

                        uint8_t         labelStrLen;

                        labelStr = [label UTF8String];

                        if (strlen(labelStr) >= 64) {

                            fprintf(stderr, "%s: label too long: %s\n", getprogname(), labelStr);

                            retVal = EXIT_FAILURE;

                            break;

                        } else {

                            // cast is safe because of length check

                            labelStrLen = (uint8_t) strlen(labelStr);

                            [recordData appendBytes:&labelStrLen length:sizeof(labelStrLen)];

                            [recordData appendBytes:labelStr length:labelStrLen];

                        }

                    }

                    if ( (retVal == EXIT_SUCCESS) && ([recordData length] >= 256) ) {

                        fprintf(stderr, "%s: record data too long\n", getprogname());

                        retVal = EXIT_FAILURE;

                    }

                    if (retVal == EXIT_SUCCESS) {

                        err = DNSServiceReconfirmRecord(

                            0,

                            interfaceIndex,

                            [fullname UTF8String],

                            kDNSServiceType_PTR,

                            kDNSServiceClass_IN,

                            // cast is safe because of recordData length check above

                            (uint16_t) [recordData length],

                            [recordData bytes]

                        );

                        if (err != kDNSServiceErr_NoError) {

                            fprintf(stderr, "%s: reconfirm record error: %d\n", getprogname(), (int) err);

                            retVal = EXIT_FAILURE;

                        }

                    }

                }

            }

Connecting to a Bonjour Service by IP Address

As a rule, you should not resolve a service to an IP address and port number unless you are doing something very unusual. In the dynamic world of modern networking, IP addresses can change at any time. Further, a given Bonjour service can have more than one IP address, and not all of them may be reachable. By connecting using hostnames, you avoid these problems. For more information, read Avoid Resolving DNS Names Before Connecting to a Host in Networking Overview.

In the rare instances when connecting by IP address is required, you can do so by following the steps for resolving a Bonjour service in Connecting by Name and then using the IP addresses instead of the hostname. There are a few caveats, however:

• If you are working with IP addresses directly, be sure to perform resolution every time you use a service, because although the service name is a persistent property, the socket information (IP addresses and port number) can change from session to session.

  In particular, never store the IP address information long-term. If a user browses for a service and saves that service, such as in a printer chooser, store only the service name, type, and domain. When it is time to connect, these values can be resolved into the relevant IP address and port number. See Persisting a Bonjour Service for more information.

• The netServiceDidResolveAddress: method tells the delegate that the NSNetService object has added an address to its list of addresses for the service. However, more addresses may be added. For example, in systems that support both IPv4 and IPv6, netServiceDidResolveAddress: may be called two or more times—once for the IPv4 address and again for the IPv6 address.

  In this delegate method, be sure that all the required connection information is present before attempting to connect to the service. If some of the information is missing, netServiceDidResolveAddress: will be called later. If multiple addresses are returned from resolving a service, try to connect to each one before giving up.

Persisting a Bonjour Service

If your app needs to persistently store a reference to a Bonjour service, such as in a printer chooser, store only the service name, type, and domain. By persisting only the domain, type, and name information, you ensure that your app can find the relevant service even if its IP addresses or port number has changed.

When you connect to the service later, initialize an NSNetService object with this information by calling its initWithDomain:type:name: method.

After you have initialized the service object, connect to the service by calling the getInputStream:outputStream: method or by passing the result of a hostName call to a connect-by-name function or method, as described earlier in this chapter. When you do this, Bonjour automatically resolves the hostname or domain, type, and name values into the current IP addresses and port number for the service.

Monitoring a Bonjour Service

In some situations, an app may need to know certain information about a Bonjour service without needing to maintain a connection to that service. For example, a chat program might let the user specify a status (idle, away, and so on). Other users on the network should be able to learn this new information quickly, without each machine needing to constantly poll every other machine.

To support the dissemination of such information, Bonjour lets each service provide an arbitrary DNS TXT record with additional information. If you want to use this functionality in your app, you must do the following:

When publishing a service, call the setTXTRecordData: method to set or update the data associated with the service. This data must be encoded according to section 3.3.14 of RFC 1035.

The most straightforward way to generate compliant data is by calling dataFromTXTRecordDictionary: with an NSDictionary object. In that dictionary, store only the key-value pairs that you want to make available to any app that is browsing for your service.

When browsing for services, do the following:

• Call the startMonitoring method to start monitoring the TXT record associated with a given service.

• Implement the netService:didUpdateTXTRecordData: method to receive notification whenever a service’s TXT record changes.

  You can either process the resulting data yourself or call dictionaryFromTXTRecordData: to obtain an NSDictionary object containing the provided key-value pairs (often from a previous call to dataFromTXTRecordDictionary:).

• Call the stopMonitoring method when you no longer want to receive notifications about changes to a particular service.

For more details, see the documentation for the methods mentioned above.