RadioDNS client library
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
buildtools @ 1d704e5
doc
.gitignore
.gitmodules
Doxyfile
LICENSE
Makefile.am
NOTICE
README
README.GIT
cli.c
configure.ac
context.c
libradiodns-uninstalled.pc.in
libradiodns.pc.in
p_radiodns.h
radiodns.h
resolver.c

README

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).