bindings/cxx/include/libsigrokcxx/libsigrokcxx.hpp

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2013-2014 Martin Ling <martin-sigrok@earth.li>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 /**
  21
  22 @mainpage API Reference
  23
  24 Introduction
  25 ------------
  26
  27 The libsigrokcxx API provides an object-oriented C++ interface to the
  28 functionality in libsigrok, including automatic memory and resource management.
  29
  30 It is built on top of the public libsigrok C API, and is designed to be used as
  31 a standalone alternative API. Programs should not mix usage of the C and C++
  32 APIs; the C++ interface code needs to have full control of all C API calls for
  33 resources to be managed correctly.
  34
  35 Memory management
  36 -----------------
  37
  38 All runtime objects created through the C++ API are passed and accessed via
  39 shared pointers, using the C++11 std::shared_ptr implementation. This means
  40 that a reference count is kept for each object.
  41
  42 Shared pointers can be copied and assigned in a user's program, automatically
  43 updating their reference count and deleting objects when they are no longer in
  44 use. The C++ interface code also keeps track of internal dependencies between
  45 libsigrok resources, and ensures that objects are not prematurely deleted when
  46 their resources are in use by other objects.
  47
  48 This means that management of libsigrokcxx objects and their underlying
  49 libsigrok resources can be treated as fully automatic. As long as all shared
  50 pointers to objects are deleted or reassigned when no longer in use, all
  51 underlying resources will be released at the right time.
  52
  53 Getting started
  54 ---------------
  55
  56 Usage of the C++ API needs to begin with a call to sigrok::Context::create().
  57 This will create the global libsigrok context and returns a shared pointer to
  58 the sigrok::Context object. Methods on this object provide access to the
  59 hardware drivers, input and output formats supported by the library, as well
  60 as means of creating other objects such as sessions and triggers.
  61
  62 Error handling
  63 --------------
  64
  65 When any libsigrok C API call returns an error, a sigrok::Error exception is
  66 raised, which provides access to the error code and description.
  67
  68 */
  69
  70 #ifndef LIBSIGROKCXX_HPP
  71 #define LIBSIGROKCXX_HPP
  72
  73 #include <libsigrok/libsigrok.h>
  74
  75 /* Suppress warnings due to glibmm's use of std::auto_ptr<> in a public
  76  * header file. To be removed once glibmm is fixed. */
  77 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  78 #include <glibmm.h>
  79 G_GNUC_END_IGNORE_DEPRECATIONS
  80
  81 #include <stdexcept>
  82 #include <memory>
  83 #include <vector>
  84 #include <map>
  85 #include <set>
  86
  87 namespace sigrok
  88 {
  89
  90 /* Forward declarations */
  91 class SR_API Error;
  92 class SR_API Context;
  93 class SR_API Driver;
  94 class SR_API Device;
  95 class SR_API HardwareDevice;
  96 class SR_API Channel;
  97 class SR_API Session;
  98 class SR_API ConfigKey;
  99 class SR_API Capability;
 100 class SR_API InputFormat;
 101 class SR_API OutputFormat;
 102 class SR_API OutputFlag;
 103 class SR_API LogLevel;
 104 class SR_API ChannelGroup;
 105 class SR_API Trigger;
 106 class SR_API TriggerStage;
 107 class SR_API TriggerMatch;
 108 class SR_API TriggerMatchType;
 109 class SR_API ChannelType;
 110 class SR_API Packet;
 111 class SR_API PacketPayload;
 112 class SR_API PacketType;
 113 class SR_API Quantity;
 114 class SR_API Unit;
 115 class SR_API QuantityFlag;
 116 class SR_API Rational;
 117 class SR_API Input;
 118 class SR_API InputDevice;
 119 class SR_API Output;
 120 class SR_API DataType;
 121 class SR_API Option;
 122 class SR_API UserDevice;
 123
 124 /** Exception thrown when an error code is returned by any libsigrok call. */
 125 class SR_API Error: public std::exception
 126 {
 127 public:
 128         explicit Error(int result);
 129         ~Error() noexcept;
 130         const int result;
 131         const char *what() const noexcept;
 132 };
 133
 134 /* Base template for classes whose resources are owned by a parent object. */
 135 template <class Class, class Parent>
 136 class SR_API ParentOwned
 137 {
 138 private:
 139         /* Weak pointer for shared_from_this() implementation. */
 140         std::weak_ptr<Class> _weak_this;
 141
 142         static void reset_parent(Class *object)
 143         {
 144                 if (!object->_parent)
 145                         throw Error(SR_ERR_BUG);
 146                 object->_parent.reset();
 147         }
 148
 149 protected:
 150         /*  Parent object which owns this child object's underlying structure.
 151
 152                 This shared pointer will be null when this child is unused, but
 153                 will be assigned to point to the parent before any shared pointer
 154                 to this child is handed out to the user.
 155
 156                 When the reference count of this child falls to zero, this shared
 157                 pointer to its parent is reset by a custom deleter on the child's
 158                 shared pointer.
 159
 160                 This strategy ensures that the destructors for both the child and
 161                 the parent are called at the correct time, i.e. only when all
 162                 references to both the parent and all its children are gone. */
 163         std::shared_ptr<Parent> _parent;
 164
 165         ParentOwned() {}
 166
 167         /* Note, this implementation will create a new smart_ptr if none exists. */
 168         std::shared_ptr<Class> shared_from_this()
 169         {
 170                 std::shared_ptr<Class> shared = _weak_this.lock();
 171
 172                 if (!shared)
 173                 {
 174                         shared.reset(static_cast<Class *>(this), &reset_parent);
 175                         _weak_this = shared;
 176                 }
 177
 178                 return shared;
 179         }
 180
 181         std::shared_ptr<Class> share_owned_by(std::shared_ptr<Parent> parent)
 182         {
 183                 if (!parent)
 184                         throw Error(SR_ERR_BUG);
 185                 this->_parent = parent;
 186                 return shared_from_this();
 187         }
 188
 189 public:
 190         /* Get parent object that owns this object. */
 191         std::shared_ptr<Parent> parent()
 192         {
 193                 return _parent;
 194         }
 195 };
 196
 197 /* Base template for classes whose resources are owned by the user. */
 198 template <class Class>
 199 class SR_API UserOwned : public std::enable_shared_from_this<Class>
 200 {
 201 protected:
 202         UserOwned() {}
 203
 204         std::shared_ptr<Class> shared_from_this()
 205         {
 206                 auto shared = std::enable_shared_from_this<Class>::shared_from_this();
 207                 if (!shared)
 208                         throw Error(SR_ERR_BUG);
 209                 return shared;
 210         }
 211 };
 212
 213 /** Type of log callback */
 214 typedef std::function<void(const LogLevel *, std::string message)> LogCallbackFunction;
 215
 216 /** Resource reader delegate. */
 217 class SR_API ResourceReader
 218 {
 219 public:
 220         ResourceReader() {}
 221         virtual ~ResourceReader();
 222 private:
 223         /** Resource open hook. */
 224         virtual void open(struct sr_resource *res, std::string name) = 0;
 225         /** Resource close hook. */
 226         virtual void close(struct sr_resource *res) = 0;
 227         /** Resource read hook. */
 228         virtual size_t read(const struct sr_resource *res, void *buf, size_t count) = 0;
 229
 230         static SR_PRIV int open_callback(struct sr_resource *res,
 231                         const char *name, void *cb_data) noexcept;
 232         static SR_PRIV int close_callback(struct sr_resource *res,
 233                         void *cb_data) noexcept;
 234         static SR_PRIV gssize read_callback(const struct sr_resource *res,
 235                         void *buf, size_t count, void *cb_data) noexcept;
 236         friend class Context;
 237 };
 238
 239 /** The global libsigrok context */
 240 class SR_API Context : public UserOwned<Context>
 241 {
 242 public:
 243         /** Create new context */
 244         static std::shared_ptr<Context> create();
 245         /** libsigrok package version. */
 246         static std::string package_version();
 247         /** libsigrok library version. */
 248         static std::string lib_version();
 249         /** Available hardware drivers, indexed by name. */
 250         std::map<std::string, std::shared_ptr<Driver> > drivers();
 251         /** Available input formats, indexed by name. */
 252         std::map<std::string, std::shared_ptr<InputFormat> > input_formats();
 253         /** Lookup the responsible input module for an input file. */
 254         std::shared_ptr<InputFormat> input_format_match(std::string filename);
 255         /** Available output formats, indexed by name. */
 256         std::map<std::string, std::shared_ptr<OutputFormat> > output_formats();
 257         /** Current log level. */
 258         const LogLevel *log_level() const;
 259         /** Set the log level.
 260          * @param level LogLevel to use. */
 261         void set_log_level(const LogLevel *level);
 262         /** Set the log callback.
 263          * @param callback Callback of the form callback(LogLevel, string). */
 264         void set_log_callback(LogCallbackFunction callback);
 265         /** Set the log callback to the default handler. */
 266         void set_log_callback_default();
 267         /** Install a delegate for reading resource files.
 268          * @param reader The resource reader delegate, or nullptr to unset. */
 269         void set_resource_reader(ResourceReader *reader);
 270         /** Create a new session. */
 271         std::shared_ptr<Session> create_session();
 272         /** Create a new user device. */
 273         std::shared_ptr<UserDevice> create_user_device(
 274                 std::string vendor, std::string model, std::string version);
 275         /** Create a header packet. */
 276         std::shared_ptr<Packet> create_header_packet(Glib::TimeVal start_time);
 277         /** Create a meta packet. */
 278         std::shared_ptr<Packet> create_meta_packet(
 279                 std::map<const ConfigKey *, Glib::VariantBase> config);
 280         /** Create a logic packet. */
 281         std::shared_ptr<Packet> create_logic_packet(
 282                 void *data_pointer, size_t data_length, unsigned int unit_size);
 283         /** Create an analog packet. */
 284         std::shared_ptr<Packet> create_analog_packet(
 285                 std::vector<std::shared_ptr<Channel> > channels,
 286                 const float *data_pointer, unsigned int num_samples, const Quantity *mq,
 287                 const Unit *unit, std::vector<const QuantityFlag *> mqflags);
 288         /** Create an end packet. */
 289         std::shared_ptr<Packet> create_end_packet();
 290         /** Load a saved session.
 291          * @param filename File name string. */
 292         std::shared_ptr<Session> load_session(std::string filename);
 293         /** Create a new trigger.
 294          * @param name Name string for new trigger. */
 295         std::shared_ptr<Trigger> create_trigger(std::string name);
 296         /** Open an input file.
 297          * @param filename File name string. */
 298         std::shared_ptr<Input> open_file(std::string filename);
 299         /** Open an input stream based on header data.
 300          * @param header Initial data from stream. */
 301         std::shared_ptr<Input> open_stream(std::string header);
 302         std::map<std::string, std::string> serials(std::shared_ptr<Driver> driver) const;
 303 private:
 304         struct sr_context *_structure;
 305         std::map<std::string, std::unique_ptr<Driver> > _drivers;
 306         std::map<std::string, std::unique_ptr<InputFormat> > _input_formats;
 307         std::map<std::string, std::unique_ptr<OutputFormat> > _output_formats;
 308         Session *_session;
 309         LogCallbackFunction _log_callback;
 310         Context();
 311         ~Context();
 312         friend class Session;
 313         friend class Driver;
 314         friend struct std::default_delete<Context>;
 315 };
 316
 317 /** An object that can be configured. */
 318 class SR_API Configurable
 319 {
 320 public:
 321         /** Supported configuration keys. */
 322         std::set<const ConfigKey *> config_keys() const;
 323         /** Read configuration for the given key.
 324          * @param key ConfigKey to read. */
 325         Glib::VariantBase config_get(const ConfigKey *key) const;
 326         /** Set configuration for the given key to a specified value.
 327          * @param key ConfigKey to set.
 328          * @param value Value to set. */
 329         void config_set(const ConfigKey *key, const Glib::VariantBase &value);
 330         /** Enumerate available values for the given configuration key.
 331          * @param key ConfigKey to enumerate values for. */
 332         Glib::VariantContainerBase config_list(const ConfigKey *key) const;
 333         /** Enumerate configuration capabilities for the given configuration key.
 334          * @param key ConfigKey to enumerate capabilities for. */
 335         std::set<const Capability *> config_capabilities(const ConfigKey *key) const;
 336         /** Check whether a configuration capability is supported for a given key.
 337          * @param key ConfigKey to check.
 338          * @param capability Capability to check for. */
 339         bool config_check(const ConfigKey *key, const Capability *capability) const;
 340 protected:
 341         Configurable(
 342                 struct sr_dev_driver *driver,
 343                 struct sr_dev_inst *sdi,
 344                 struct sr_channel_group *channel_group);
 345         virtual ~Configurable();
 346         struct sr_dev_driver *config_driver;
 347         struct sr_dev_inst *config_sdi;
 348         struct sr_channel_group *config_channel_group;
 349 };
 350
 351 /** A hardware driver provided by the library */
 352 class SR_API Driver : public ParentOwned<Driver, Context>, public Configurable
 353 {
 354 public:
 355         /** Name of this driver. */
 356         std::string name() const;
 357         /** Long name for this driver. */
 358         std::string long_name() const;
 359         /** Scan options supported by this driver. */
 360         std::set<const ConfigKey *> scan_options() const;
 361         /** Scan for devices and return a list of devices found.
 362          * @param options Mapping of (ConfigKey, value) pairs. */
 363         std::vector<std::shared_ptr<HardwareDevice> > scan(std::map<const ConfigKey *, Glib::VariantBase>
 364                         options = std::map<const ConfigKey *, Glib::VariantBase>());
 365 private:
 366         struct sr_dev_driver *_structure;
 367         bool _initialized;
 368         std::vector<HardwareDevice *> _devices;
 369         explicit Driver(struct sr_dev_driver *structure);
 370         ~Driver();
 371         friend class Context;
 372         friend class HardwareDevice;
 373         friend class ChannelGroup;
 374         friend struct std::default_delete<Driver>;
 375 };
 376
 377 /** A generic device, either hardware or virtual */
 378 class SR_API Device : public Configurable
 379 {
 380 public:
 381         /** Vendor name for this device. */
 382         std::string vendor() const;
 383         /** Model name for this device. */
 384         std::string model() const;
 385         /** Version string for this device. */
 386         std::string version() const;
 387         /** Serial number for this device. */
 388         std::string serial_number() const;
 389         /** Connection ID for this device. */
 390         std::string connection_id() const;
 391         /** List of the channels available on this device. */
 392         std::vector<std::shared_ptr<Channel> > channels();
 393         /** Channel groups available on this device, indexed by name. */
 394         std::map<std::string, std::shared_ptr<ChannelGroup> > channel_groups();
 395         /** Open device. */
 396         void open();
 397         /** Close device. */
 398         void close();
 399 protected:
 400         explicit Device(struct sr_dev_inst *structure);
 401         ~Device();
 402         virtual std::shared_ptr<Device> get_shared_from_this() = 0;
 403         std::shared_ptr<Channel> get_channel(struct sr_channel *ptr);
 404
 405         struct sr_dev_inst *_structure;
 406         std::map<struct sr_channel *, std::unique_ptr<Channel> > _channels;
 407 private:
 408         std::map<std::string, std::unique_ptr<ChannelGroup> > _channel_groups;
 409
 410         friend class Session;
 411         friend class Channel;
 412         friend class ChannelGroup;
 413         friend class Output;
 414         friend class Analog;
 415         friend struct std::default_delete<Device>;
 416 };
 417
 418 /** A real hardware device, connected via a driver */
 419 class SR_API HardwareDevice :
 420         public UserOwned<HardwareDevice>,
 421         public Device
 422 {
 423 public:
 424         /** Driver providing this device. */
 425         std::shared_ptr<Driver> driver();
 426 private:
 427         HardwareDevice(std::shared_ptr<Driver> driver, struct sr_dev_inst *structure);
 428         ~HardwareDevice();
 429         std::shared_ptr<Device> get_shared_from_this();
 430         std::shared_ptr<Driver> _driver;
 431
 432         friend class Driver;
 433         friend class ChannelGroup;
 434         friend struct std::default_delete<HardwareDevice>;
 435 };
 436
 437 /** A virtual device, created by the user */
 438 class SR_API UserDevice :
 439         public UserOwned<UserDevice>,
 440         public Device
 441 {
 442 public:
 443         /** Add a new channel to this device. */
 444         std::shared_ptr<Channel> add_channel(unsigned int index, const ChannelType *type, std::string name);
 445 private:
 446         UserDevice(std::string vendor, std::string model, std::string version);
 447         ~UserDevice();
 448         std::shared_ptr<Device> get_shared_from_this();
 449
 450         friend class Context;
 451         friend struct std::default_delete<UserDevice>;
 452 };
 453
 454 /** A channel on a device */
 455 class SR_API Channel :
 456         public ParentOwned<Channel, Device>
 457 {
 458 public:
 459         /** Current name of this channel. */
 460         std::string name() const;
 461         /** Set the name of this channel. *
 462          * @param name Name string to set. */
 463         void set_name(std::string name);
 464         /** Type of this channel. */
 465         const ChannelType *type() const;
 466         /** Enabled status of this channel. */
 467         bool enabled() const;
 468         /** Set the enabled status of this channel.
 469          * @param value Boolean value to set. */
 470         void set_enabled(bool value);
 471         /** Get the index number of this channel. */
 472         unsigned int index() const;
 473 private:
 474         explicit Channel(struct sr_channel *structure);
 475         ~Channel();
 476         struct sr_channel *_structure;
 477         const ChannelType * const _type;
 478         friend class Device;
 479         friend class UserDevice;
 480         friend class ChannelGroup;
 481         friend class Session;
 482         friend class TriggerStage;
 483         friend class Context;
 484         friend struct std::default_delete<Channel>;
 485 };
 486
 487 /** A group of channels on a device, which share some configuration */
 488 class SR_API ChannelGroup :
 489         public ParentOwned<ChannelGroup, Device>,
 490         public Configurable
 491 {
 492 public:
 493         /** Name of this channel group. */
 494         std::string name() const;
 495         /** List of the channels in this group. */
 496         std::vector<std::shared_ptr<Channel> > channels();
 497 private:
 498         ChannelGroup(const Device *device, struct sr_channel_group *structure);
 499         ~ChannelGroup();
 500         std::vector<Channel *> _channels;
 501         friend class Device;
 502         friend struct std::default_delete<ChannelGroup>;
 503 };
 504
 505 /** A trigger configuration */
 506 class SR_API Trigger : public UserOwned<Trigger>
 507 {
 508 public:
 509         /** Name of this trigger configuration. */
 510         std::string name() const;
 511         /** List of the stages in this trigger. */
 512         std::vector<std::shared_ptr<TriggerStage> > stages();
 513         /** Add a new stage to this trigger. */
 514         std::shared_ptr<TriggerStage> add_stage();
 515 private:
 516         Trigger(std::shared_ptr<Context> context, std::string name);
 517         ~Trigger();
 518         struct sr_trigger *_structure;
 519         std::shared_ptr<Context> _context;
 520         std::vector<std::unique_ptr<TriggerStage> > _stages;
 521         friend class Context;
 522         friend class Session;
 523         friend struct std::default_delete<Trigger>;
 524 };
 525
 526 /** A stage in a trigger configuration */
 527 class SR_API TriggerStage :
 528         public ParentOwned<TriggerStage, Trigger>
 529 {
 530 public:
 531         /** Index number of this stage. */
 532         int number() const;
 533         /** List of match conditions on this stage. */
 534         std::vector<std::shared_ptr<TriggerMatch> > matches();
 535         /** Add a new match condition to this stage.
 536          * @param channel Channel to match on.
 537          * @param type TriggerMatchType to apply. */
 538         void add_match(std::shared_ptr<Channel> channel, const TriggerMatchType *type);
 539         /** Add a new match condition to this stage.
 540          * @param channel Channel to match on.
 541          * @param type TriggerMatchType to apply.
 542          * @param value Threshold value. */
 543         void add_match(std::shared_ptr<Channel> channel, const TriggerMatchType *type, float value);
 544 private:
 545         struct sr_trigger_stage *_structure;
 546         std::vector<std::unique_ptr<TriggerMatch> > _matches;
 547         explicit TriggerStage(struct sr_trigger_stage *structure);
 548         ~TriggerStage();
 549         friend class Trigger;
 550         friend struct std::default_delete<TriggerStage>;
 551 };
 552
 553 /** A match condition in a trigger configuration  */
 554 class SR_API TriggerMatch :
 555         public ParentOwned<TriggerMatch, TriggerStage>
 556 {
 557 public:
 558         /** Channel this condition matches on. */
 559         std::shared_ptr<Channel> channel();
 560         /** Type of match. */
 561         const TriggerMatchType *type() const;
 562         /** Threshold value. */
 563         float value() const;
 564 private:
 565         TriggerMatch(struct sr_trigger_match *structure, std::shared_ptr<Channel> channel);
 566         ~TriggerMatch();
 567         struct sr_trigger_match *_structure;
 568         std::shared_ptr<Channel> _channel;
 569         friend class TriggerStage;
 570         friend struct std::default_delete<TriggerMatch>;
 571 };
 572
 573 /** Type of session stopped callback */
 574 typedef std::function<void()> SessionStoppedCallback;
 575
 576 /** Type of datafeed callback */
 577 typedef std::function<void(std::shared_ptr<Device>, std::shared_ptr<Packet>)>
 578         DatafeedCallbackFunction;
 579
 580 /* Data required for C callback function to call a C++ datafeed callback */
 581 class SR_PRIV DatafeedCallbackData
 582 {
 583 public:
 584         void run(const struct sr_dev_inst *sdi,
 585                 const struct sr_datafeed_packet *pkt);
 586 private:
 587         DatafeedCallbackFunction _callback;
 588         DatafeedCallbackData(Session *session,
 589                 DatafeedCallbackFunction callback);
 590         Session *_session;
 591         friend class Session;
 592 };
 593
 594 /** A virtual device associated with a stored session */
 595 class SR_API SessionDevice :
 596         public ParentOwned<SessionDevice, Session>,
 597         public Device
 598 {
 599 private:
 600         explicit SessionDevice(struct sr_dev_inst *sdi);
 601         ~SessionDevice();
 602         std::shared_ptr<Device> get_shared_from_this();
 603
 604         friend class Session;
 605         friend struct std::default_delete<SessionDevice>;
 606 };
 607
 608 /** A sigrok session */
 609 class SR_API Session : public UserOwned<Session>
 610 {
 611 public:
 612         /** Add a device to this session.
 613          * @param device Device to add. */
 614         void add_device(std::shared_ptr<Device> device);
 615         /** List devices attached to this session. */
 616         std::vector<std::shared_ptr<Device> > devices();
 617         /** Remove all devices from this session. */
 618         void remove_devices();
 619         /** Add a datafeed callback to this session.
 620          * @param callback Callback of the form callback(Device, Packet). */
 621         void add_datafeed_callback(DatafeedCallbackFunction callback);
 622         /** Remove all datafeed callbacks from this session. */
 623         void remove_datafeed_callbacks();
 624         /** Start the session. */
 625         void start();
 626         /** Run the session event loop. */
 627         void run();
 628         /** Stop the session. */
 629         void stop();
 630         /** Return whether the session is running. */
 631         bool is_running() const;
 632         /** Set callback to be invoked on session stop. */
 633         void set_stopped_callback(SessionStoppedCallback callback);
 634         /** Get current trigger setting. */
 635         std::shared_ptr<Trigger> trigger();
 636         /** Get the context. */
 637         std::shared_ptr<Context> context();
 638         /** Set trigger setting.
 639          * @param trigger Trigger object to use. */
 640         void set_trigger(std::shared_ptr<Trigger> trigger);
 641         /** Get filename this session was loaded from. */
 642         std::string filename() const;
 643 private:
 644         explicit Session(std::shared_ptr<Context> context);
 645         Session(std::shared_ptr<Context> context, std::string filename);
 646         ~Session();
 647         std::shared_ptr<Device> get_device(const struct sr_dev_inst *sdi);
 648         struct sr_session *_structure;
 649         const std::shared_ptr<Context> _context;
 650         std::map<const struct sr_dev_inst *, std::unique_ptr<SessionDevice> > _owned_devices;
 651         std::map<const struct sr_dev_inst *, std::shared_ptr<Device> > _other_devices;
 652         std::vector<std::unique_ptr<DatafeedCallbackData> > _datafeed_callbacks;
 653         SessionStoppedCallback _stopped_callback;
 654         std::string _filename;
 655         std::shared_ptr<Trigger> _trigger;
 656
 657         friend class Context;
 658         friend class DatafeedCallbackData;
 659         friend class SessionDevice;
 660         friend struct std::default_delete<Session>;
 661 };
 662
 663 /** A packet on the session datafeed */
 664 class SR_API Packet : public UserOwned<Packet>
 665 {
 666 public:
 667         /** Type of this packet. */
 668         const PacketType *type() const;
 669         /** Payload of this packet. */
 670         std::shared_ptr<PacketPayload> payload();
 671 private:
 672         Packet(std::shared_ptr<Device> device,
 673                 const struct sr_datafeed_packet *structure);
 674         ~Packet();
 675         const struct sr_datafeed_packet *_structure;
 676         std::shared_ptr<Device> _device;
 677         std::unique_ptr<PacketPayload> _payload;
 678
 679         friend class Session;
 680         friend class Output;
 681         friend class DatafeedCallbackData;
 682         friend class Header;
 683         friend class Meta;
 684         friend class Logic;
 685         friend class Analog;
 686         friend class Context;
 687         friend struct std::default_delete<Packet>;
 688 };
 689
 690 /** Abstract base class for datafeed packet payloads */
 691 class SR_API PacketPayload
 692 {
 693 protected:
 694         PacketPayload();
 695         virtual ~PacketPayload() = 0;
 696 private:
 697         virtual std::shared_ptr<PacketPayload> share_owned_by(std::shared_ptr<Packet> parent) = 0;
 698
 699         friend class Packet;
 700         friend class Output;
 701         friend struct std::default_delete<PacketPayload>;
 702 };
 703
 704 /** Payload of a datafeed header packet */
 705 class SR_API Header :
 706         public ParentOwned<Header, Packet>,
 707         public PacketPayload
 708 {
 709 public:
 710         /* Feed version number. */
 711         int feed_version() const;
 712         /* Start time of this session. */
 713         Glib::TimeVal start_time() const;
 714 private:
 715         explicit Header(const struct sr_datafeed_header *structure);
 716         ~Header();
 717         std::shared_ptr<PacketPayload> share_owned_by(std::shared_ptr<Packet> parent);
 718
 719         const struct sr_datafeed_header *_structure;
 720
 721         friend class Packet;
 722 };
 723
 724 /** Payload of a datafeed metadata packet */
 725 class SR_API Meta :
 726         public ParentOwned<Meta, Packet>,
 727         public PacketPayload
 728 {
 729 public:
 730         /* Mapping of (ConfigKey, value) pairs. */
 731         std::map<const ConfigKey *, Glib::VariantBase> config() const;
 732 private:
 733         explicit Meta(const struct sr_datafeed_meta *structure);
 734         ~Meta();
 735         std::shared_ptr<PacketPayload> share_owned_by(std::shared_ptr<Packet> parent);
 736
 737         const struct sr_datafeed_meta *_structure;
 738         std::map<const ConfigKey *, Glib::VariantBase> _config;
 739
 740         friend class Packet;
 741 };
 742
 743 /** Payload of a datafeed packet with logic data */
 744 class SR_API Logic :
 745         public ParentOwned<Logic, Packet>,
 746         public PacketPayload
 747 {
 748 public:
 749         /* Pointer to data. */
 750         void *data_pointer();
 751         /* Data length in bytes. */
 752         size_t data_length() const;
 753         /* Size of each sample in bytes. */
 754         unsigned int unit_size() const;
 755 private:
 756         explicit Logic(const struct sr_datafeed_logic *structure);
 757         ~Logic();
 758         std::shared_ptr<PacketPayload> share_owned_by(std::shared_ptr<Packet> parent);
 759
 760         const struct sr_datafeed_logic *_structure;
 761
 762         friend class Packet;
 763         friend class Analog;
 764         friend struct std::default_delete<Logic>;
 765 };
 766
 767 /** Payload of a datafeed packet with analog data */
 768 class SR_API Analog :
 769         public ParentOwned<Analog, Packet>,
 770         public PacketPayload
 771 {
 772 public:
 773         /** Pointer to data. */
 774         void *data_pointer();
 775         /**
 776          * Fills dest pointer with the analog data converted to float.
 777          * The pointer must have space for num_samples() floats.
 778          */
 779         void get_data_as_float(float *dest);
 780         /** Number of samples in this packet. */
 781         unsigned int num_samples() const;
 782         /** Channels for which this packet contains data. */
 783         std::vector<std::shared_ptr<Channel> > channels();
 784         /** Size of a single sample in bytes. */
 785         unsigned int unitsize() const;
 786         /** Samples use a signed data type. */
 787         bool is_signed() const;
 788         /** Samples use float. */
 789         bool is_float() const;
 790         /** Samples are stored in big-endian order. */
 791         bool is_bigendian() const;
 792         /**
 793          * Number of significant digits after the decimal point if positive,
 794          * or number of non-significant digits before the decimal point if negative
 795          * (refers to the value we actually read on the wire).
 796          */
 797         int digits() const;
 798         /** TBD */
 799         bool is_digits_decimal() const;
 800         /** TBD */
 801         std::shared_ptr<Rational> scale();
 802         /** TBD */
 803         std::shared_ptr<Rational> offset();
 804         /** Measured quantity of the samples in this packet. */
 805         const Quantity *mq() const;
 806         /** Unit of the samples in this packet. */
 807         const Unit *unit() const;
 808         /** Measurement flags associated with the samples in this packet. */
 809         std::vector<const QuantityFlag *> mq_flags() const;
 810         /**
 811          * Provides a Logic packet that contains a conversion of the analog
 812          * data using a simple threshold.
 813          *
 814          * @param threshold Threshold to use.
 815          * @param data_ptr Pointer to num_samples() bytes where the logic
 816          *                 samples are stored. When nullptr, memory for
 817          *                 logic->data_pointer() will be allocated and must
 818          *                 be freed by the caller.
 819          */
 820         std::shared_ptr<Logic> get_logic_via_threshold(float threshold,
 821                 uint8_t *data_ptr=nullptr) const;
 822         /**
 823          * Provides a Logic packet that contains a conversion of the analog
 824          * data using a Schmitt-Trigger.
 825          *
 826          * @param lo_thr Low threshold to use (anything below this is low).
 827          * @param hi_thr High threshold to use (anything above this is high).
 828          * @param state Points to a byte that contains the current state of the
 829          *              converter. For best results, set to value of logic
 830          *              sample n-1.
 831          * @param data_ptr Pointer to num_samples() bytes where the logic
 832          *                 samples are stored. When nullptr, memory for
 833          *                 logic->data_pointer() will be allocated and must be
 834          *                 freed by the caller.
 835          */
 836         std::shared_ptr<Logic> get_logic_via_schmitt_trigger(float lo_thr,
 837                 float hi_thr, uint8_t *state, uint8_t *data_ptr=nullptr) const;
 838 private:
 839         explicit Analog(const struct sr_datafeed_analog *structure);
 840         ~Analog();
 841         std::shared_ptr<PacketPayload> share_owned_by(std::shared_ptr<Packet> parent);
 842
 843         const struct sr_datafeed_analog *_structure;
 844
 845         friend class Packet;
 846 };
 847
 848 /** Number represented by a numerator/denominator integer pair */
 849 class SR_API Rational :
 850         public ParentOwned<Rational, Analog>
 851 {
 852 public:
 853         /** Numerator, i.e. the dividend. */
 854         int64_t numerator() const;
 855         /** Denominator, i.e. the divider. */
 856         uint64_t denominator() const;
 857         /** Actual (lossy) value. */
 858         float value() const;
 859 private:
 860         explicit Rational(const struct sr_rational *structure);
 861         ~Rational();
 862         std::shared_ptr<Rational> share_owned_by(std::shared_ptr<Analog> parent);
 863
 864         const struct sr_rational *_structure;
 865
 866         friend class Analog;
 867         friend struct std::default_delete<Rational>;
 868 };
 869
 870 /** An input format supported by the library */
 871 class SR_API InputFormat :
 872         public ParentOwned<InputFormat, Context>
 873 {
 874 public:
 875         /** Name of this input format. */
 876         std::string name() const;
 877         /** Description of this input format. */
 878         std::string description() const;
 879         /** A list of preferred file name extensions for this file format.
 880          * @note This list is a recommendation only. */
 881         std::vector<std::string> extensions() const;
 882         /** Options supported by this input format. */
 883         std::map<std::string, std::shared_ptr<Option> > options();
 884         /** Create an input using this input format.
 885          * @param options Mapping of (option name, value) pairs. */
 886         std::shared_ptr<Input> create_input(std::map<std::string, Glib::VariantBase>
 887                         options = std::map<std::string, Glib::VariantBase>());
 888 private:
 889         explicit InputFormat(const struct sr_input_module *structure);
 890         ~InputFormat();
 891
 892         const struct sr_input_module *_structure;
 893
 894         friend class Context;
 895         friend class InputDevice;
 896         friend struct std::default_delete<InputFormat>;
 897 };
 898
 899 /** An input instance (an input format applied to a file or stream) */
 900 class SR_API Input : public UserOwned<Input>
 901 {
 902 public:
 903         /** Virtual device associated with this input. */
 904         std::shared_ptr<InputDevice> device();
 905         /** Send next stream data.
 906          * @param data Next stream data.
 907          * @param length Length of data. */
 908         void send(void *data, size_t length);
 909         /** Signal end of input data. */
 910         void end();
 911         void reset();
 912 private:
 913         Input(std::shared_ptr<Context> context, const struct sr_input *structure);
 914         ~Input();
 915         const struct sr_input *_structure;
 916         std::shared_ptr<Context> _context;
 917         std::unique_ptr<InputDevice> _device;
 918
 919         friend class Context;
 920         friend class InputFormat;
 921         friend struct std::default_delete<Input>;
 922 };
 923
 924 /** A virtual device associated with an input */
 925 class SR_API InputDevice :
 926         public ParentOwned<InputDevice, Input>,
 927         public Device
 928 {
 929 private:
 930         InputDevice(std::shared_ptr<Input> input, struct sr_dev_inst *sdi);
 931         ~InputDevice();
 932         std::shared_ptr<Device> get_shared_from_this();
 933         std::shared_ptr<Input> _input;
 934         friend class Input;
 935         friend struct std::default_delete<InputDevice>;
 936 };
 937
 938 /** An option used by an output format */
 939 class SR_API Option : public UserOwned<Option>
 940 {
 941 public:
 942         /** Short name of this option suitable for command line usage. */
 943         std::string id() const;
 944         /** Short name of this option suitable for GUI usage. */
 945         std::string name() const;
 946         /** Description of this option in a sentence. */
 947         std::string description() const;
 948         /** Default value for this option. */
 949         Glib::VariantBase default_value() const;
 950         /** Possible values for this option, if a limited set. */
 951         std::vector<Glib::VariantBase> values() const;
 952         /** Parse a string argument into the appropriate type for this option. */
 953         Glib::VariantBase parse_string(std::string value);
 954 private:
 955         Option(const struct sr_option *structure,
 956                 std::shared_ptr<const struct sr_option *> structure_array);
 957         ~Option();
 958         const struct sr_option *_structure;
 959         std::shared_ptr<const struct sr_option *> _structure_array;
 960
 961         friend class InputFormat;
 962         friend class OutputFormat;
 963         friend struct std::default_delete<Option>;
 964 };
 965
 966 /** An output format supported by the library */
 967 class SR_API OutputFormat :
 968         public ParentOwned<OutputFormat, Context>
 969 {
 970 public:
 971         /** Name of this output format. */
 972         std::string name() const;
 973         /** Description of this output format. */
 974         std::string description() const;
 975         /** A list of preferred file name extensions for this file format.
 976          * @note This list is a recommendation only. */
 977         std::vector<std::string> extensions() const;
 978         /** Options supported by this output format. */
 979         std::map<std::string, std::shared_ptr<Option> > options();
 980         /** Create an output using this format.
 981          * @param device Device to output for.
 982          * @param options Mapping of (option name, value) pairs. */
 983         std::shared_ptr<Output> create_output(std::shared_ptr<Device> device,
 984                 std::map<std::string, Glib::VariantBase> options = std::map<std::string, Glib::VariantBase>());
 985         /** Create an output using this format.
 986          * @param filename Name of destination file.
 987          * @param device Device to output for.
 988          * @param options Mapping of (option name, value) pairs. */
 989         std::shared_ptr<Output> create_output(std::string filename,
 990                 std::shared_ptr<Device> device,
 991                 std::map<std::string, Glib::VariantBase> options = std::map<std::string, Glib::VariantBase>());
 992         /**
 993          * Checks whether a given flag is set.
 994          * @param flag Flag to check
 995          * @return true if flag is set for this module
 996          * @see sr_output_flags
 997          */
 998         bool test_flag(const OutputFlag *flag) const;
 999 private:
1000         explicit OutputFormat(const struct sr_output_module *structure);
1001         ~OutputFormat();
1002
1003         const struct sr_output_module *_structure;
1004
1005         friend class Context;
1006         friend class Output;
1007         friend struct std::default_delete<OutputFormat>;
1008 };
1009
1010 /** An output instance (an output format applied to a device) */
1011 class SR_API Output : public UserOwned<Output>
1012 {
1013 public:
1014         /** Update output with data from the given packet.
1015          * @param packet Packet to handle. */
1016         std::string receive(std::shared_ptr<Packet> packet);
1017         /** Output format in use for this output */
1018         std::shared_ptr<OutputFormat> format();
1019 private:
1020         Output(std::shared_ptr<OutputFormat> format, std::shared_ptr<Device> device);
1021         Output(std::shared_ptr<OutputFormat> format,
1022                 std::shared_ptr<Device> device, std::map<std::string, Glib::VariantBase> options);
1023         Output(std::string filename, std::shared_ptr<OutputFormat> format,
1024                 std::shared_ptr<Device> device, std::map<std::string, Glib::VariantBase> options);
1025         ~Output();
1026
1027         const struct sr_output *_structure;
1028         const std::shared_ptr<OutputFormat> _format;
1029         const std::shared_ptr<Device> _device;
1030         const std::map<std::string, Glib::VariantBase> _options;
1031
1032         friend class OutputFormat;
1033         friend struct std::default_delete<Output>;
1034 };
1035
1036 /** Base class for objects which wrap an enumeration value from libsigrok */
1037 template <class Class, typename Enum> class SR_API EnumValue
1038 {
1039 public:
1040         /** The integer constant associated with this value. */
1041         int id() const
1042         {
1043                 return static_cast<int>(_id);
1044         }
1045         /** The name associated with this value. */
1046         std::string name() const
1047         {
1048                 return _name;
1049         }
1050         /** Get value associated with a given integer constant. */
1051         static const Class *get(int id)
1052         {
1053                 const auto pos = _values.find(static_cast<Enum>(id));
1054                 if (pos == _values.end())
1055                         throw Error(SR_ERR_ARG);
1056                 return pos->second;
1057         }
1058         /** Get possible values. */
1059         static std::vector<const Class *> values()
1060         {
1061                 std::vector<const Class *> result;
1062                 for (auto entry : _values)
1063                         result.push_back(entry.second);
1064                 return result;
1065         }
1066 protected:
1067         EnumValue(Enum id, const char name[]) : _id(id), _name(name)
1068         {
1069         }
1070         ~EnumValue()
1071         {
1072         }
1073 private:
1074         static const std::map<const Enum, const Class * const> _values;
1075         const Enum _id;
1076         const std::string _name;
1077 };
1078
1079 }
1080
1081 #include <libsigrokcxx/enums.hpp>
1082
1083 #endif