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                 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 };
 762
 763 /** Payload of a datafeed packet with analog data */
 764 class SR_API Analog :
 765         public ParentOwned<Analog, Packet>,
 766         public PacketPayload
 767 {
 768 public:
 769         /** Pointer to data. */
 770         void *data_pointer();
 771         /**
 772          * Fills dest pointer with the analog data converted to float.
 773          * The pointer must have space for num_samples() floats.
 774          */
 775         void get_data_as_float(float *dest);
 776         /** Number of samples in this packet. */
 777         unsigned int num_samples() const;
 778         /** Channels for which this packet contains data. */
 779         vector<shared_ptr<Channel> > channels();
 780         /** Size of a single sample in bytes. */
 781         unsigned int unitsize() const;
 782         /** Samples use a signed data type. */
 783         bool is_signed() const;
 784         /** Samples use float. */
 785         bool is_float() const;
 786         /** Samples are stored in big-endian order. */
 787         bool is_bigendian() const;
 788         /**
 789          * Number of significant digits after the decimal point if positive,
 790          * or number of non-significant digits before the decimal point if negative
 791          * (refers to the value we actually read on the wire).
 792          */
 793         int digits() const;
 794         /** TBD */
 795         bool is_digits_decimal() const;
 796         /** TBD */
 797         shared_ptr<Rational> scale();
 798         /** TBD */
 799         shared_ptr<Rational> offset();
 800         /** Measured quantity of the samples in this packet. */
 801         const Quantity *mq() const;
 802         /** Unit of the samples in this packet. */
 803         const Unit *unit() const;
 804         /** Measurement flags associated with the samples in this packet. */
 805         vector<const QuantityFlag *> mq_flags() const;
 806 private:
 807         explicit Analog(const struct sr_datafeed_analog *structure);
 808         ~Analog();
 809         shared_ptr<PacketPayload> share_owned_by(shared_ptr<Packet> parent);
 810
 811         const struct sr_datafeed_analog *_structure;
 812
 813         friend class Packet;
 814 };
 815
 816 /** Number represented by a numerator/denominator integer pair */
 817 class SR_API Rational :
 818         public ParentOwned<Rational, Analog>
 819 {
 820 public:
 821         /** Numerator, i.e. the dividend. */
 822         int64_t numerator() const;
 823         /** Denominator, i.e. the divider. */
 824         uint64_t denominator() const;
 825         /** Actual (lossy) value. */
 826         float value() const;
 827 private:
 828         explicit Rational(const struct sr_rational *structure);
 829         ~Rational();
 830         shared_ptr<Rational> share_owned_by(shared_ptr<Analog> parent);
 831
 832         const struct sr_rational *_structure;
 833
 834         friend class Analog;
 835         friend struct std::default_delete<Rational>;
 836 };
 837
 838 /** An input format supported by the library */
 839 class SR_API InputFormat :
 840         public ParentOwned<InputFormat, Context>
 841 {
 842 public:
 843         /** Name of this input format. */
 844         string name() const;
 845         /** Description of this input format. */
 846         string description() const;
 847         /** A list of preferred file name extensions for this file format.
 848          * @note This list is a recommendation only. */
 849         vector<string> extensions() const;
 850         /** Options supported by this input format. */
 851         map<string, shared_ptr<Option> > options();
 852         /** Create an input using this input format.
 853          * @param options Mapping of (option name, value) pairs. */
 854         shared_ptr<Input> create_input(map<string, Glib::VariantBase>
 855                         options = map<string, Glib::VariantBase>());
 856 private:
 857         explicit InputFormat(const struct sr_input_module *structure);
 858         ~InputFormat();
 859
 860         const struct sr_input_module *_structure;
 861
 862         friend class Context;
 863         friend class InputDevice;
 864         friend struct std::default_delete<InputFormat>;
 865 };
 866
 867 /** An input instance (an input format applied to a file or stream) */
 868 class SR_API Input : public UserOwned<Input>
 869 {
 870 public:
 871         /** Virtual device associated with this input. */
 872         shared_ptr<InputDevice> device();
 873         /** Send next stream data.
 874          * @param data Next stream data.
 875          * @param length Length of data. */
 876         void send(void *data, size_t length);
 877         /** Signal end of input data. */
 878         void end();
 879         void reset();
 880 private:
 881         Input(shared_ptr<Context> context, const struct sr_input *structure);
 882         ~Input();
 883         const struct sr_input *_structure;
 884         shared_ptr<Context> _context;
 885         unique_ptr<InputDevice> _device;
 886
 887         friend class Context;
 888         friend class InputFormat;
 889         friend struct std::default_delete<Input>;
 890 };
 891
 892 /** A virtual device associated with an input */
 893 class SR_API InputDevice :
 894         public ParentOwned<InputDevice, Input>,
 895         public Device
 896 {
 897 private:
 898         InputDevice(shared_ptr<Input> input, struct sr_dev_inst *sdi);
 899         ~InputDevice();
 900         shared_ptr<Device> get_shared_from_this();
 901         shared_ptr<Input> _input;
 902         friend class Input;
 903         friend struct std::default_delete<InputDevice>;
 904 };
 905
 906 /** An option used by an output format */
 907 class SR_API Option : public UserOwned<Option>
 908 {
 909 public:
 910         /** Short name of this option suitable for command line usage. */
 911         string id() const;
 912         /** Short name of this option suitable for GUI usage. */
 913         string name() const;
 914         /** Description of this option in a sentence. */
 915         string description() const;
 916         /** Default value for this option. */
 917         Glib::VariantBase default_value() const;
 918         /** Possible values for this option, if a limited set. */
 919         vector<Glib::VariantBase> values() const;
 920 private:
 921         Option(const struct sr_option *structure,
 922                 shared_ptr<const struct sr_option *> structure_array);
 923         ~Option();
 924         const struct sr_option *_structure;
 925         shared_ptr<const struct sr_option *> _structure_array;
 926
 927         friend class InputFormat;
 928         friend class OutputFormat;
 929         friend struct std::default_delete<Option>;
 930 };
 931
 932 /** An output format supported by the library */
 933 class SR_API OutputFormat :
 934         public ParentOwned<OutputFormat, Context>
 935 {
 936 public:
 937         /** Name of this output format. */
 938         string name() const;
 939         /** Description of this output format. */
 940         string description() const;
 941         /** A list of preferred file name extensions for this file format.
 942          * @note This list is a recommendation only. */
 943         vector<string> extensions() const;
 944         /** Options supported by this output format. */
 945         map<string, shared_ptr<Option> > options();
 946         /** Create an output using this format.
 947          * @param device Device to output for.
 948          * @param options Mapping of (option name, value) pairs. */
 949         shared_ptr<Output> create_output(shared_ptr<Device> device,
 950                 map<string, Glib::VariantBase> options = map<string, Glib::VariantBase>());
 951         /** Create an output using this format.
 952          * @param filename Name of destination file.
 953          * @param device Device to output for.
 954          * @param options Mapping of (option name, value) pairs. */
 955         shared_ptr<Output> create_output(string filename,
 956                 shared_ptr<Device> device,
 957                 map<string, Glib::VariantBase> options = map<string, Glib::VariantBase>());
 958         /**
 959          * Checks whether a given flag is set.
 960          * @param flag Flag to check
 961          * @return true if flag is set for this module
 962          * @see sr_output_flags
 963          */
 964         bool test_flag(const OutputFlag *flag) const;
 965 private:
 966         explicit OutputFormat(const struct sr_output_module *structure);
 967         ~OutputFormat();
 968
 969         const struct sr_output_module *_structure;
 970
 971         friend class Context;
 972         friend class Output;
 973         friend struct std::default_delete<OutputFormat>;
 974 };
 975
 976 /** An output instance (an output format applied to a device) */
 977 class SR_API Output : public UserOwned<Output>
 978 {
 979 public:
 980         /** Update output with data from the given packet.
 981          * @param packet Packet to handle. */
 982         string receive(shared_ptr<Packet> packet);
 983 private:
 984         Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
 985         Output(shared_ptr<OutputFormat> format,
 986                 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
 987         Output(string filename, shared_ptr<OutputFormat> format,
 988                 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
 989         ~Output();
 990
 991         const struct sr_output *_structure;
 992         const shared_ptr<OutputFormat> _format;
 993         const shared_ptr<Device> _device;
 994         const map<string, Glib::VariantBase> _options;
 995
 996         friend class OutputFormat;
 997         friend struct std::default_delete<Output>;
 998 };
 999
1000 /** Base class for objects which wrap an enumeration value from libsigrok */
1001 template <class Class, typename Enum> class SR_API EnumValue
1002 {
1003 public:
1004         /** The integer constant associated with this value. */
1005         int id() const
1006         {
1007                 return static_cast<int>(_id);
1008         }
1009         /** The name associated with this value. */
1010         string name() const
1011         {
1012                 return _name;
1013         }
1014         /** Get value associated with a given integer constant. */
1015         static const Class *get(int id)
1016         {
1017                 const auto pos = _values.find(static_cast<Enum>(id));
1018                 if (pos == _values.end())
1019                         throw Error(SR_ERR_ARG);
1020                 return pos->second;
1021         }
1022         /** Get possible values. */
1023         static std::vector<const Class *> values()
1024         {
1025                 std::vector<const Class *> result;
1026                 for (auto entry : _values)
1027                         result.push_back(entry.second);
1028                 return result;
1029         }
1030 protected:
1031         EnumValue(Enum id, const char name[]) : _id(id), _name(name)
1032         {
1033         }
1034         ~EnumValue()
1035         {
1036         }
1037 private:
1038         static const std::map<const Enum, const Class * const> _values;
1039         const Enum _id;
1040         const string _name;
1041 };
1042
1043 }
1044
1045 #include <libsigrokcxx/enums.hpp>
1046
1047 #endif