In a previous post I showed you how we use DNS Service Discovery in a product I work on for Cisco Systems. That project uses the Avahi browser, which does not have a Windows port. In this article, I’ll show you how to perform service discovery on Windows using Apple’s Bonjour SDK for Windows.

DNS-SD On Windows

Microsoft has been pushing us to use UPnP as our network discovery protocol, to the exclusion of all others. As a result, Windows ships with no support for DNS-SD - zip. And that might be the end of it, if it weren’t for Apple’s vested interest in having iTunes installed on every Windows machine in the world.

iTunes uses DNS-SD to share music catalogs across Local Area Networks - a natural choice with the native support in OS X for Zeroconf. Rather than isolate Windows users in an pocket UPnP universe, Apple chose to instead port the service discovery components of Bonjour to Windows, and install it with every copy of Windows. Thus, Windows and OS X users can happily share their iTunes libraries with none of the unusual calisthenics required.

To sweeten the deal, Apple has released a Bonjour SDK for Windows, which is currently shipping version 3.0 from their developer support site. In Apple’s words:

The Bonjour SDK for Windows includes the latest version of Bonjour as well as header files, libraries, and sample code to assist developers in creating Bonjour enabled applications on Windows. The SDK has been updated with the Bonjour core that is bundled with iTunes 10.3.1. This release will bring all existing Bonjour functionality released in Mac OS X 10.7 into the Bonjour for Windows product.

It sounds pretty good, doesn’t it?

An Emphasis on Kit

Installing the SDK is a decision-free breeze:

The splash graphic that pops up when you are installing the Bonjour SDK
Installing the SDK

The installation may be easy, but the real dirty truth about the Bonjour SDK is that it is not much of an SDK at all. The developer interface to Bonjour services are packaged in a single DLL, and the SDK provides programmers with sample code that illustrates how to use some of the bindings in C, C#, Java, and VB. There is no documentation on the interfaces, no source for the Bonjour components, and the few samples don’t begin to provide comprehensive coverage of the interface.

In other words, this is pretty much a code dump.

An Overview

For the most part, the Bonjour SDK interfaces follow a single pattern. Each request made to the API returns immediately, and gives you a reference that you can use to track the progress of your request. That reference can be converted to a file handle, and you can use the file handle to see when your request has some data to produce.

When your request has generated some data, and the Bonjour components are ready to deliver it to you, they do so by a callback mechanism - the Bonjour components make calls into your C or C++ program and provide the data you requested.

Most of the callbacks include a flag parameter. You can check the flag to see if there is any more data expected. If there isn’t, you can delete the reference and you are then done with that particular call. Otherwise, you will have to wait for the request to be responded to when the Bonjour components get around to it.

An Example - Discover Service Types

I’ve written a demo program that browses the network for details on every service instance it can find, and presents the results in a tree format. The figure below shows the program running on my home network, where I have drilled down to get information about an instance of a print service.

A dialog box that contains a tree listing the devices discovered on my home network. Seeing a device requires drilling down through a service type and instance name.
The ServiceBrowser Sample Program

This program has to start by doing a top-level iteration of all the service types currently seen on my network. From my previous article, you might remember that I can use a special browse command to accomplish this. If you’ve installed the Bonjour SDK, you can run the dns-sd program and browse for service type _services._dns-sd._udp, which should give results something like this:

C:\Users\Mark>dns-sd -B _services._dns-sd._udp
Browsing for _services._dns-sd._udp
Timestamp     A/R Flags if Domain  Service Type  Instance Name
17:38:09.407  Add     3 13 .       _tcp.local.     _smb
17:38:09.407  Add     3 13 .       _tcp.local.     _printer
17:38:09.408  Add     3 13 .       _tcp.local.     _pdl-datastream
17:38:09.408  Add     3 13 .       _tcp.local.     _http
17:38:09.408  Add     3 13 .       _tcp.local.     _tivo-videos
17:38:09.409  Add     2 13 .       _tcp.local.     _csco-sb

Looking to do the same thing in my demo program, I turn to the header file dns_sd.h. This file ships with the Bonjour SDK and contains not only the API definition, but what passes for documentation. In that header file I see that there is a function called DNSServiceBrowse, and it looks like it does exactly what I want. In my sample program, my call to this routine is shown below:

DNSServiceRef client = NULL;
DNSServiceErrorType err;
err = DNSServiceBrowse( &client, 
                        0, 
                        0, 
                        "_services._dns-sd._udp", 
                        "", 
                        IterateServiceTypes, 
                        this );

You can get some exposition on each of the arguments I pass to the function from the header file, my brief comments on each are given below:

sdRef Every call to the Bonjour API creates a new DNSServiceRef handle. It is initialized by the function call, and used later to retrieve the results.
flags This parameter is not used in this version of the SDK.
interfaceIndex This argument is used to select a specific network interface. For this particular function I want to browse on all available interfaces, so a value of 0 is used.
regType The type of service being browsed for. Normally when you call DNSServiceBrowse you will use this parameter to specify a specific service type that you are interested in, such as _http._tcp. I'm using the special type of _services._dns-sd._udp in order to get a list of all published service types, not specific instances.
domain By passing an empty string I tell the service that I want to see advertisements from all domains.
callback The pointer to a callback function that will receive the responses to this request. The argument I pass in, IterateServiceTypes, is a static member of my MCF Dialog class.
context The context variable is an opaque pointer type that is passed in to the Bonjour service. When it performs a callback, it will include a copy of the context pointer for the use of the callback function. I always pass in a pointer to my MFC Dialog class, so my callback functions have full access to the class members.

The important thing to note here is that the call to the API function doesn’t return any important data. All I get back is an error code indicating that the request is being processed, and a DNSServiceRef handle that I use to track that progress.

The real action comes when my callback function is invoked. IterateServiceTypes is a static member of my Dialog class. Apple kept things simple by having one callback type for C and C++, which means no member functions. You could easily build shims to make it appear as though the DLL was calling member functions - it would just take a small modification to the code I’ll show you here.

The function definition has to follow exactly the declaration given in dns_sd.h. My implementation starts like this:

void DNSSD_API CServiceBrowserDlg::IterateServiceTypes( DNSServiceRef sdRef,
                                                        DNSServiceFlags flags,
                                                        uint32_t interfaceIndex,
                                                        DNSServiceErrorType errorCode,
                                                        const char *serviceName,
                                                        const char *regtype,
                                                        const char *domain,
                                                        void *context )
{
	CServiceBrowserDlg *p = (CServiceBrowserDlg *) context;

It’s worth walking through a look at each of the parameters in the callback:

sdRef This is the same DNSServiceRef value that was created when the call was made to DNSServiceBrowse. You don't need to make any use of it in the callback, but it does provide a good way to correlate results with function calls, particularly if you are using a single callback function to process many different results.
flags There are two important flag bits to check in this value. The first value, kDNSServiceFlagsMoreComing is used to indicate that there are definitely more callbacks coming. If that bit is cleared, there is no more pending data. The second flag bit, kDNSServiceFlagsAdd is used to indicate whether this service is being added or deleted. When you first start browsing, all the callbacks will be for services added. As services are added and removed from the system, additional callbacks will be generated with this bit both set and cleared.
interfaceIndex In the callback, this index will be set to the index of the network interface where the advertisement was found. When it comes time to resolve this service, you need to pass in the correct index.
errorCode If this value is not zero, the callback is indicating an error. As long as it is zero your code can process the input safely.
serviceName This value contains the name of a discovered service - it is the whole point of the callback. Normally this will contain the name of an instance of a service. However, when browsing for the special name _services._dns-sd._udp, the instance name is actually a service type.
regtype The type of the service - you may already know this information by the time you reach the callback, but if the callback is handling the results from multiple queries, it can be helfpul.
domain The domain of the discovered service. Like the interface index, you need use the domain when you are attempting to resolve the service
context A copy of the context variable passed in when the browse call was made.

If you look at the first line of code above, the first thing I do is cast the context pointer to its correct type, a pointer to my MFC Dialog class. Now I can make full use of all the members of the class, albeit via a call through a pointer instead of directly.

So what do I do with these services once I receive them? Well, for each service type that I find, I kick off a new browse process, looking for specific instances of the service. Just as an example, in my callback IterateServiceTypes, one of the callbacks returns a service type of _printer._tcp. In order to find all instances of this service, I have to call DNSServiceBrowse again, with that service name and the correct interface and domain. After inserting the service type into the tree, I make that call so I can start adding those instances:

HTREEITEM item = p->m_Tree.InsertItem( CA2T(service_type.c_str()), TVI_ROOT, TVI_SORT );
DNSServiceRef client = NULL;
DNSServiceErrorType err;
err = DNSServiceBrowse( &client, 
                        0, 
                        0, 
                        service_type.c_str(), 
                        "", 
                        IterateServiceInstances, 
                        context );

The key point to note about this call is that the callback function, IterateServiceInstances, is a different member function - one that expects to get the results of my browsing for instances of a specific service.

Driving the Callbacks

One thing I’ve skipped over so far - how do these callbacks actually get generated? Does the DLL asynchronously make calls into my code whenever events occur?

The Bonjour SDK lets your program control when callbacks occur by giving you the handle to the message pump. When you call DNSServiceProcessResult() with a single argument of a DNSServiceRef, you will generate a single callback message for the given reference. The callback will occur within the context of the call to DNSServiceProcessResult().

When you call DNSServiceProcessResult(), the Bonjour DLL will block if there are no messages ready to process. So how do you know when there are messages ready?

The indicator that messages are ready is given by a file descriptor associated with the DNSServiceRef. You can get a copy of the file descriptor by calling DNSServiceRefSockFD(), passing in a copy of the reference. When the file descriptor has data ready to read, you have callbacks pending. The easiest way to check this condition is to use the select() function, which can check multiple references in one fell swoop.

In my implementation of the callback message pump, I rely on an unordered_map called m_ClientToFdMap that contains a copy of all the DNSServiceRef references currently waiting for responses. I create the necessary data structure used by select(), then call it to get a list of all references that have callbacks pending. The core of this code looks like this:

int result = select(0, &readfds, (fd_set*)NULL, (fd_set*)NULL, &tv);
if ( result > 0 ) {
//
// While iterating through the loop, the callback functions might delete
// the client pointed to by the current iterator, so I have to increment
// it BEFORE calling DNSServiceProcessResult
//
    for ( auto ii = m_ClientToFdMap.cbegin() ; ii != m_ClientToFdMap.cend() ; ) {
        auto jj = ii++;
        if (FD_ISSET(jj->second, &readfds) ) 
            DNSServiceErrorType err = DNSServiceProcessResult(jj->first);
    }
}

This generates my callbacks efficiently, and because they are in the context of my main program’s UI thread, I avoid a lot of unpleasant issues.

Threading Issues

My program manages the Bonjour callbacks in a fairly ugly fashion. When my browsing activity starts, I create a timer that fires once every 250 milliseconds. I process up to 10 callbacks in that timer call, then exit. This continues until there are no pending browser or resolution requests, at which time I kill the timer.

Depending on your use of DNS-SD, you may find that this is not as efficient as you like. If this is the case, you might find it useful to move your message pump code to a separate thread.

Once you do that, you can wait on all your callbacks by calling select with a long or infinite timeout. This has the effect of blocking your callback thread until it has actual work to do - resulting in a better use of CPU time.

There are some obvious downsides to this approach. Clearly you have to use some sort of locking mechanism on the data structures that are shared between your callback thread and the rest of your program. And the use of the select() statement with an infinite timeout is complicated by the possibility that you may be making or canceling browsing or resolution calls while your program runs.

A good way to deal with both of these problems is to invoke a socket-based message passing protocol between the callback thread and the other components of your program. If you restrict your interface to messages, you don’t have to worry about locking access to shared data. And because you are using a socket for communications, your select() statement will be used to activate the thread when new messages arrive.

Character Sets

The days when DNS was limited to seven-bit ASCII characters are long gone. Service instances are encoded as UTF-8, and can use whatever Unicode characters they like. In the figure shown below, you can see the effects of that when I browse for instances of iTunes:

An MS-DOS CMD.EXE window that shows some trouble when listing Instance Names with non-ASCII characters. A second view shows that the characters render properly after switching to code page 65001.
Character set problems in service instance names

You can see that OS X users have so-called curly quotes in their library instance names, and curly quotes are definitely outside the range of seven-bit ASCII. DNS-SD collects the names as UTF-8 encoded strings, and sends them to the console in that format.

By default, the Windows cmd.exe window doesn’t render UTF-8 properly, but changing the code page to 65001 results in the correct rendering.

In my sample program, I deal with this with a two step approach. First, my program is built using the Unicode libraries, ensuring that I am able to render Unicode output properly. To conform with Microsoft’s C++ paradigms, I use CString for all my Unicode strings, and wrap all my string literals in the _T() wrapper.

This works fine for my UI, but I can’t use strings built of wchar_t to communicate with the Bonjour SDK - it expects eight bit characters with UTF-8 encoding. In my program I use the C++ std::string class everywhere where I am working with 8-bit characters that might be encoded in UTF-8. When it comes time to render one of those strings in my Unicode context, all I have to do is use the handy CA2T macro with the CP_UTF8 parameter, and things work properly.

Library Issues

The design of the Bonjour SDK imposes some uncomfortable restrictions on you when it comes to building your C or C++ program. Because you are linking directly to code found in the library dnssd.lib, you have to ensure that your program and that library link against the same version of the C run time library. And for the Bonjour SDK under Windows, this means you must link with the static, multithreaded, release version of the library.

You’ll see the problem in this right away when you create an MFC project and try to build with dnssd.lib. By default, the project generator will probably have you using MFC in a shared DLL, and using the Multithreaded Debug DLL version of the C libraries. When you try to build like this, you will get some unpleasant error messages:

1>LINK : warning LNK4098: 
         defaultlib 'msvcrtd.lib' conflicts with use of other libs; 
         use /NODEFAULTLIB:library
1>LINK : warning LNK4098: 
         defaultlib 'LIBCMT' conflicts with use of other libs; 
         use /NODEFAULTLIB:library

A full featured SDK would provide libraries built for multiple scenarios, and you would pick the one of your choice depending on your build parameters. But with the Bonjour SDK, you don’t get this choice, so you need to ensure that your project follows a few guidelines:

  • Under Configuration Properties/General, field Use of MFC needs to be set to Use MFC in a Static Library for both debug and release builds.
  • Under Configuration Properties/C++/Code Generation, field Runtime Library needs to be set to Multi-threaded (/MT) for both debug and release builds.
  • Under Configuration Properties/C++/Preprocessor, field Preprocessor Definitions the constant _DEBUG needs to be changed to NDEBUG for Debug configurations.

To build a project that uses the SDK, you will also need to add dns_sd.lib to your list of linker inputs, add dns_sd.h to your header files, and add the appropriate directories in the configuration under Configuration Properties/C++/General/ in field Additional Include Directories, and under Configuration Properties/Linker/General/ in field Additional Include Directories.

Overview Of the Demo Program

I’ve included the full source for a project that will build with Visual Studio 10, as long as you have the Bonjour SDK installed. It browses all available services on the network and displays the information about them in a tree form.

The program starts by kicking off a browser for _services._dns-sd._udp. The results are processed in member function IterateServiceTypes(). As each new service type is discovered, it is added to the tree, and a call to DNSServiceBrowse()is made to discover all instances of that service type. The callback for that browse call is member function IterateServiceInstances().

In IterateServiceInstances() I add the instance to the tree, then call DNSServiceResolve(). This function operates much like the browse function, but it actually gets the DNS record for the service. This record contains the host name, service port and a list of name/value pairs that a service can advertise as part of its record. You can see those values put to good work with service types like _ipp._tcp, in which printer parameters are exposed as part of service discovery.

ResolveInstance() is the callback routine that receives the information about the service instance. The host name, port, and name/value pairs are added to the tree, and then one final call is made to a Bonjour SDK entry called DNSServiceGetAddrInfo(). This function resolves the IP address for the given host name. The address is stuffed into the tree in callback function GetAddress().

Conclusion

DNS service discover is powerful tool, but Windows programmers might be put off by the lack of a nicely packaged SDK. Using this simple example program might be a good way to get comfortable with an SDK that gives you a powerful tool that provides a good multi-platform alternative to UPnP.

Sample program source: ServiceBrowser.zip
Sample program executable: ServiceBrowserExe.zip