Registering and Terminating a Service

When your service starts up, you need to register with the mDNSResponder daemon so that applications can discover your service. This section provides a general overview of the process, followed by a set of step-by-step instructions.

Registering a Service

To register your service, call DNSServiceRegister. The parameters for making this call consist of the following:

Services that require TXT records also pass the raw data of the TXT record and the length of the raw data as parameters. Most services don’t need TXT records and therefore pass NULL and 0, respectively, for these parameters.

Instead of providing a callback function, you may pass NULL, in which case, you will not be notified of default values that may be chosen on your behalf and you will not be notified of any asynchronous errors that may prevent the registration of your service. If you pass NULL for this parameter, you cannot pass kDNSServiceFlagsNoAutoRename as the flag parameter. You can de-register a service that is registered without a callback function in the normal way, by calling DNSServiceRefDeallocate.

If the registration can be started, DNSServiceRegister initializes the service discovery reference and creates a socket that is used to communicate with the mDNSResponder daemon. Use the service discovery reference to call DNSServiceRefSockFD and get the socket descriptor for the service reference.

Set up a run or select loop using the socket descriptor. When the loop indicates that the mDNSResponder daemon’s reply is available, call DNSServiceProcessResult and pass to it the service discovery reference initialized by DNSServiceRegister. DNSServiceProcessResult will call the callback function associated with the service discovery reference.

Instead of setting up a run loop or a select loop, you can call DNSServiceRegister and immediately call DNSServiceProcessResult. The DNSServiceProcessResult function will block until the mDNSResponder daemon has a response, at which time the callback specified when DNSServiceRegister was called (if any) will be invoked.

In addition to the service discovery reference and flags that are not currently used, your callback will be called with the following parameters:

If the combination of service name, registration type, and domain name resulted in a full domain name that is already in local use and you specified kDNSServiceFlagsNoAutoRename, you’ll need to deallocate the service discovery reference, choose another service name and try again, until a locally unique name can be registered.

Upon successful registration, your service is announced to the local network and its access information (IP address, port, and so on) can be found using multicast DNS, either by name or by browsing for services. Using the initialized service discovery reference, you can communicate with the mDNSResponder daemon to add a record to the registration information for your service, update an added record, or remove an added record while your service is running. However, you will probably never need to make changes to your registration information because Bonjour handles the common cases, such as waking, sleeping, shutting down, and changing IP addresses.

A rare exception would be the need to update the text record associated with a service. If a text field contains a queue name, for example, and the queue name changes, you would need to update the text record for the service.

You must keep the socket descriptor on the run loop or the select loop as long as you expect your callback function to be called.

Terminating a Service's Registration

To terminate your service's registration, remove the socket descriptor from the run loop or the select loop and call DNSServiceRefDeallocate, passing to it the service discovery reference that was initialized when your service was registered. In addition to invalidating the service discovery reference and deallocating the memory associated with it, any resource records that have been added are de-registered and their references are invalidated. The socket that underlies the connection with the mDNSResponder daemon is closed, thereby terminating your application’s connection with the daemon.