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