introduce device discovery api

This API allows to acquire a list of devices connected to the host and
creates an argument string ready to be passed to a source object for
cunstruction.

Each device_t entry contains a "label" entry, which holds the generic
device name which may be shown to the user for device selection.

For certain radio hardware extended entries ("name", "serial", "type")
may be available to make bijective device addressing possible.

The argument string for target types "rtl_tcp" and "file" might be
constructed using the osmosdr::device_t class facilities.

Example:

 #include <osmosdr_device.h>
 #include <osmosdr_source_c.h>

osmosdr::devices_t devs = osmosdr::device::find();

BOOST_FOREACH(osmosdr::device_t &dev, devs) // try to create each dev
  osmosdr_source_c_sptr src = osmosdr_make_source_c(dev.to_string());

2 files changed, 113 insertions, 0 deletions

diff --git a/include/osmosdr/CMakeLists.txt b/include/osmosdr/CMakeLists.txt
index 65f10f1..c59bd01 100644
--- a/include/osmosdr/CMakeLists.txt
+++ b/include/osmosdr/CMakeLists.txt
@@ -24,6 +24,7 @@ install(FILES
     osmosdr_api.h
     osmosdr_pimpl.h
     osmosdr_ranges.h
+    osmosdr_device.h
     osmosdr_source_c.h
 #    osmosdr_sink_c.h
     DESTINATION include/osmosdr
diff --git a/include/osmosdr/osmosdr_device.h b/include/osmosdr/osmosdr_device.h
new file mode 100644
index 0000000..330d0df
--- /dev/null
+++ b/include/osmosdr/osmosdr_device.h
@@ -0,0 +1,112 @@
+/* -*- c++ -*- */
+/*
+ * Copyright 2012 Dimitri Stolnikov <horiz0n@gmx.net>
+ *
+ * GNU Radio is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3, or (at your option)
+ * any later version.
+ *
+ * GNU Radio is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with GNU Radio; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#ifndef INCLUDED_OSMOSDR_DEVICE_H
+#define INCLUDED_OSMOSDR_DEVICE_H
+
+#include <osmosdr_api.h>
+#include <osmosdr_pimpl.h>
+#include <boost/noncopyable.hpp>
+#include <boost/lexical_cast.hpp>
+#include <stdexcept>
+#include <string>
+#include <vector>
+#include <map>
+
+typedef std::map<std::string, std::string> string_string_dict_t;
+
+namespace osmosdr {
+
+  /*!
+   * Mapping of key/value pairs for locating devices on the system.
+   * When left empty, the device discovery routines will search
+   * all available transports on the system (ethernet, usb...).
+   *
+   * The logical device can also be used to pass arguments into
+   * the transport layer control to set (for example) buffer sizes.
+   *
+   * An arguments string, is a way to represent a device address
+   * using a single string with delimiter characters.
+   */
+  class OSMOSDR_API device_t : public string_string_dict_t
+  {
+  public:
+    /*!
+     * Create a logical device from an args string.
+     * \param args the arguments string
+     */
+    device_t(const std::string &args = "");
+
+    /*!
+     * Convert a logical device into a pretty print string.
+     * \return a printable string representing the device
+     */
+    std::string to_pp_string(void) const;
+
+    /*!
+     * Convert the logical device into an args string.
+     * The args string contains delimiter symbols.
+     * \return a string with delimiter markup
+     */
+    std::string to_string(void) const;
+
+    /*!
+     * Lexically cast a parameter to the specified type,
+     * or use the default value if the key is not found.
+     * \param key the key as one of the parameters
+     * \param def the value to use when key is not present
+     * \return the casted value as type T or the default
+     * \throw error when the parameter cannot be casted
+     */
+    template <typename T> T cast(const std::string &key, const T &def) const
+    {
+      if (!this->count(key)) return def;
+      try { return boost::lexical_cast<T>((*this)[key]); }
+      catch(const boost::bad_lexical_cast &) {
+        throw std::runtime_error("cannot cast " + key + " = " + (*this)[key]);
+      }
+    }
+  };
+
+  //! A typedef for a vector of logical devices
+  typedef std::vector<device_t> devices_t;
+
+  /*!
+   * The device interface represents the underyling hardware.
+   * The api allows for discovery, configuration, and streaming.
+   */
+  class OSMOSDR_API device : boost::noncopyable
+  {
+  public:
+    /*!
+     * \brief Find logical radio devices attached to the host.
+     *
+     * The device hint should be used to narrow down the search
+     * to particular transport types and/or transport arguments.
+     *
+     * \param hint a partially (or fully) filled in logical device
+     * \return a vector of logical devices for all radios on the system
+     */
+    static devices_t find(const device_t &hint = osmosdr::device_t());
+  };
+
+} //namespace osmosdr
+
+#endif /* INCLUDED_OSMOSDR_DEVICE_H */