RadioDNS client library
=======================

This is a simple client library for RadioDNS.

The public interface is in libradiodns.h. Much of it should be fairly
self-explanatory: you create a context using one of the radiodns_create()
family of functions, which either uses the specified domain name (in
the case of radiodns_create() itself) or constructs one based on
supplied parameters (in the case of the other functions in the family).

One a context has been created, you can use radiodns_resolve_target() to
find the target domain name beneath which SRV records will be looked for.

At any point you can call radiodns_domain() or radiodns_target() to query
the current (initial) domain name or target domain name. If
radiodns_resolve_target() has yet to be called or failed catastrophically,
radiodns_target() will return NULL.

Note that everything is synchronous: anything with 'resolve' in the name
will perform one or more DNS queries and block until complete. Usual
cautions regarding UI threads and networking apply.

Once you're finished with a context, you should use radiodns_destroy()
to free up the resources associated with it.

Accompanying the library is a command-line utility, currently named
'radiodns' which allows testing. Run the utility without any parameters
for a usage summary. Any numerical values used as parameters can be
specified in decimal as-is, in hexadecimal with a '0x' prefix, or octal
with a '0' prefix.

For example, Capital FM in London:

$ ./radiodns fm 9580 0xc586 0xce1
Domain: 09580.c586.ce1.fm.radiodns.org
Target: rnds.musicradio.com

Or BBC One in Bristol:

$ ./radiodns dvb 0x233a 0x1041 0x10bf 0x3098
Domain: 3098.10bf.1041.233a.dvb.tvdns.net
Target: west.bbc.srv.tvdns.net

If you just want to find out what the application-discovery target of a given
FQDN is, you can do:

$ ./radiodns -target dns 09580.c586.ce1.fm.radiodns.org
rnds.musicradio.com

If no options such as -target or -domain are specified on the command-line,
the utility behaves as though '-domain -target' were supplied, and defaults
to being verbose unless '-quiet' is specified.

To perform service discovery, you will need to specify the '-app' parameter,
along with the name of the service you're attempting to locate. At the moment,
only _tcp services are supported.

For example:

$ ./radiodns -app radiovis fm 9580 0xc586 0xce1
Instance (no name):
  1 service record:
    IN SRV 0 100 61613 vis.musicradio.com.
  No parameters.

This does, of course, work on ordinary DNS domains which advertise SRV
records in the usual fashion. For example:

$ ./radiodns -app xmpp-server dns google.com
Instance (no name):
  5 service records:
    IN SRV 20 0 5269 xmpp-server4.l.google.com.
    IN SRV 5 0 5269 xmpp-server.l.google.com.
    IN SRV 20 0 5269 xmpp-server1.l.google.com.
    IN SRV 20 0 5269 xmpp-server2.l.google.com.
    IN SRV 20 0 5269 xmpp-server3.l.google.com.
  No parameters.

In a minor divergance from the RadioDNS specification, libradiodns supports
multiple service instances, using PTR records (as per DNS-SD):

$ ./radiodns -app http dns dns-sd.org
Instance (no name):
  1 service record:
    IN SRV 0 100 80 www.dns-sd.org.
  No parameters.
Instance " * Zeroconf":
  1 service record:
    IN SRV 0 0 80 zeroconf.org.
  1 parameter:
    path = /
Instance " * Wired, Technology, Culture, Business, Politics":
  1 service record:
    IN SRV 0 0 80 wired.com.
  1 parameter:
    path = /
Instance " * SlashDot, News for Nerds, Stuff that Matters":
  1 service record:
    IN SRV 0 0 80 slashdot.org.
  1 parameter:
    path = /
Instance " * Yahoo, maps, weather, and stock quotes":
  1 service record:
    IN SRV 0 0 80 www.yahoo.com.
  1 parameter:
    path = /
Instance " * Amazon.com, on-line shopping":
  1 service record:
    IN SRV 0 0 80 www.amazon.com.
  1 parameter:
    path = /
Instance " * Google, searching the Web":
  1 service record:
    IN SRV 0 0 80 www.google.com.
  1 parameter:
    path = /
Instance " * Apple, makers of the iPod":
  1 service record:
    IN SRV 0 0 80 www.apple.com.
  1 parameter:
    path = /
Instance " * eBay, online auctions":
  1 service record:
    IN SRV 0 0 80 www.ebay.com.
  1 parameter:
    path = /
Instance " * DNS Service Discovery":
  1 service record:
    IN SRV 0 0 80 dns-sd.org.
  1 parameter:
    path = /
Instance "Stuart's Printer":
  1 service record:
    IN SRV 0 0 80 exampleprinter.dns-sd.org.
  1 parameter:
    path = /
Instance " * CNN, World news":
  1 service record:
    IN SRV 0 0 80 www.cnn.com.
  1 parameter:
    path = /
Instance " * BBC, World news":
  1 service record:
    IN SRV 0 0 80 news.bbc.co.uk.
  1 parameter:
    path = /
Instance " * Multicast DNS":
  1 service record:
    IN SRV 0 0 80 multicastdns.org.
  1 parameter:
    path = /


In this example, dns-sd.org has a SRV record on _http._tcp.dns-sd.org, but it
*also* has thirteen PTR records, consituting named service instances. In the
context of RadioTAG, RadioVIS and RadioEPG this isn't especially useful, but
future RadioDNS-based services may benefit from the ability to advertise
multiple distinct instances of an application (as distinct from multiple
SRV records relating to a single instance).