bindings/cxx/include/libsigrok/libsigrok.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 sigrok++ API provides an object-oriented C++ interface to the functionality
  28 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 sigrok++ objects and their underlying libsigrok
  49 resources can be treated as fully automatic. As long as all shared pointers to
  50 objects are deleted or reassigned when no longer in use, all underlying
  51 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 LIBSIGROK_HPP
  71 #define LIBSIGROK_HPP
  72
  73 #include "libsigrok/libsigrok.h"
  74 #include <glibmm-2.4/glibmm.h>
  75
  76 #include <stdexcept>
  77 #include <memory>
  78 #include <vector>
  79 #include <map>
  80
  81 namespace sigrok
  82 {
  83
  84 using namespace std;
  85
  86 /* Forward declarations */
  87 class SR_API Error;
  88 class SR_API Context;
  89 class SR_API Driver;
  90 class SR_API Device;
  91 class SR_API HardwareDevice;
  92 class SR_API Channel;
  93 class SR_API EventSource;
  94 class SR_API Session;
  95 class SR_API ConfigKey;
  96 class SR_API InputFormat;
  97 class SR_API OutputFormat;
  98 class SR_API LogLevel;
  99 class SR_API ChannelGroup;
 100 class SR_API Trigger;
 101 class SR_API TriggerStage;
 102 class SR_API TriggerMatch;
 103 class SR_API TriggerMatchType;
 104 class SR_API ChannelType;
 105 class SR_API Packet;
 106 class SR_API PacketPayload;
 107 class SR_API PacketType;
 108 class SR_API Quantity;
 109 class SR_API Unit;
 110 class SR_API QuantityFlag;
 111 class SR_API Input;
 112 class SR_API InputDevice;
 113 class SR_API Output;
 114 class SR_API DataType;
 115 class SR_API Option;
 116
 117 /** Exception thrown when an error code is returned by any libsigrok call. */
 118 class SR_API Error: public exception
 119 {
 120 public:
 121         Error(int result);
 122         ~Error() throw();
 123         const int result;
 124         const char *what() const throw();
 125 };
 126
 127 /* Base template for classes whose resources are owned by a parent object. */
 128 template <class Class, class Parent, typename Struct>
 129 class SR_API ParentOwned
 130 {
 131 protected:
 132         /*  Parent object which owns this child object's underlying structure.
 133
 134                 This shared pointer will be null when this child is unused, but
 135                 will be assigned to point to the parent before any shared pointer
 136                 to this child is handed out to the user.
 137
 138                 When the reference count of this child falls to zero, this shared
 139                 pointer to its parent is reset by a custom deleter on the child's
 140                 shared pointer.
 141
 142                 This strategy ensures that the destructors for both the child and
 143                 the parent are called at the correct time, i.e. only when all
 144                 references to both the parent and all its children are gone. */
 145         shared_ptr<Parent> parent;
 146
 147         /* Weak pointer for shared_from_this() implementation. */
 148         weak_ptr<Class> weak_this;
 149
 150 public:
 151         /* Note, this implementation will create a new smart_ptr if none exists. */
 152         shared_ptr<Class> shared_from_this()
 153         {
 154                 shared_ptr<Class> shared;
 155
 156                 if (!(shared = weak_this.lock()))
 157                 {
 158                         shared = shared_ptr<Class>((Class *) this, reset_parent);
 159                         weak_this = shared;
 160                 }
 161
 162                 return shared;
 163         }
 164
 165         shared_ptr<Class> get_shared_pointer(shared_ptr<Parent> parent)
 166         {
 167                 if (!parent)
 168                         throw Error(SR_ERR_BUG);
 169                 this->parent = parent;
 170                 return shared_from_this();
 171         }
 172
 173         shared_ptr<Class> get_shared_pointer(Parent *parent)
 174         {
 175                 if (!parent)
 176                         throw Error(SR_ERR_BUG);
 177                 return get_shared_pointer(parent->shared_from_this());
 178         }
 179 protected:
 180         static void reset_parent(Class *object)
 181         {
 182                 if (!object->parent)
 183                         throw Error(SR_ERR_BUG);
 184                 object->parent.reset();
 185         }
 186
 187         Struct *structure;
 188
 189         ParentOwned<Class, Parent, Struct>(Struct *structure) :
 190                 structure(structure)
 191         {
 192         }
 193 };
 194
 195 /* Base template for classes whose resources are owned by the user. */
 196 template <class Class, typename Struct>
 197 class SR_API UserOwned : public enable_shared_from_this<Class>
 198 {
 199 public:
 200         shared_ptr<Class> shared_from_this()
 201         {
 202                 auto shared = enable_shared_from_this<Class>::shared_from_this();
 203                 if (!shared)
 204                         throw Error(SR_ERR_BUG);
 205                 return shared;
 206         }
 207 protected:
 208         Struct *structure;
 209
 210         UserOwned<Class, Struct>(Struct *structure) :
 211                 structure(structure)
 212         {
 213         }
 214 };
 215
 216 /** Type of log callback */
 217 typedef function<void(const LogLevel *, string message)> LogCallbackFunction;
 218
 219 /** The global libsigrok context */
 220 class SR_API Context : public UserOwned<Context, struct sr_context>
 221 {
 222 public:
 223         /** Create new context */
 224         static shared_ptr<Context> create();
 225         /** libsigrok package version. */
 226         string get_package_version();
 227         /** libsigrok library version. */
 228         string get_lib_version();
 229         /** Available hardware drivers, indexed by name. */
 230         map<string, shared_ptr<Driver> > get_drivers();
 231         /** Available input formats, indexed by name. */
 232         map<string, shared_ptr<InputFormat> > get_input_formats();
 233         /** Available output formats, indexed by name. */
 234         map<string, shared_ptr<OutputFormat> > get_output_formats();
 235         /** Current log level. */
 236         const LogLevel *get_log_level();
 237         /** Set the log level.
 238          * @param level LogLevel to use. */
 239         void set_log_level(const LogLevel *level);
 240         /** Current log domain. */
 241         string get_log_domain();
 242         /** Set the log domain.
 243          * @param value Log domain prefix string. */
 244         void set_log_domain(string value);
 245         /** Set the log callback.
 246          * @param callback Callback of the form callback(LogLevel, string). */
 247         void set_log_callback(LogCallbackFunction callback);
 248         /** Set the log callback to the default handler. */
 249         void set_log_callback_default();
 250         /** Create a new session. */
 251         shared_ptr<Session> create_session();
 252         /** Load a saved session.
 253          * @param filename File name string. */
 254         shared_ptr<Session> load_session(string filename);
 255         /** Create a new trigger.
 256          * @param name Name string for new trigger. */
 257         shared_ptr<Trigger> create_trigger(string name);
 258         /** Open an input file.
 259          * @param filename File name string. */
 260         shared_ptr<Input> open_file(string filename);
 261         /** Open an input stream based on header data.
 262          * @param header Initial data from stream. */
 263         shared_ptr<Input> open_stream(string header);
 264 protected:
 265         map<string, Driver *> drivers;
 266         map<string, InputFormat *> input_formats;
 267         map<string, OutputFormat *> output_formats;
 268         Session *session;
 269         LogCallbackFunction log_callback;
 270         Context();
 271         ~Context();
 272         /** Deleter needed to allow shared_ptr use with protected destructor. */
 273         class Deleter
 274         {
 275         public:
 276                 void operator()(Context *context) { delete context; }
 277         };
 278         friend class Deleter;
 279         friend class Session;
 280         friend class Driver;
 281 };
 282
 283 /** A hardware driver provided by the library */
 284 class SR_API Driver :
 285         public ParentOwned<Driver, Context, struct sr_dev_driver>
 286 {
 287 public:
 288         /** Name of this driver. */
 289         string get_name();
 290         /** Long name for this driver. */
 291         string get_long_name();
 292         /** Scan for devices and return a list of devices found.
 293          * @param options Mapping of (ConfigKey, value) pairs. */
 294         vector<shared_ptr<HardwareDevice> > scan(
 295                 map<const ConfigKey *, Glib::VariantBase> options = {});
 296 protected:
 297         bool initialized;
 298         vector<HardwareDevice *> devices;
 299         Driver(struct sr_dev_driver *structure);
 300         ~Driver();
 301         friend class Context;
 302         friend class HardwareDevice;
 303         friend class ChannelGroup;
 304 };
 305
 306 /** An object that can be configured. */
 307 class SR_API Configurable
 308 {
 309 public:
 310         /** Read configuration for the given key.
 311          * @param key ConfigKey to read. */
 312         Glib::VariantBase config_get(const ConfigKey *key);
 313         /** Set configuration for the given key to a specified value.
 314          * @param key ConfigKey to set.
 315          * @param value Value to set. */
 316         void config_set(const ConfigKey *key, Glib::VariantBase value);
 317         /** Enumerate available values for the given configuration key.
 318          * @param key ConfigKey to enumerate values for. */
 319         Glib::VariantContainerBase config_list(const ConfigKey *key);
 320 protected:
 321         Configurable(
 322                 struct sr_dev_driver *driver,
 323                 struct sr_dev_inst *sdi,
 324                 struct sr_channel_group *channel_group);
 325         virtual ~Configurable();
 326         struct sr_dev_driver *config_driver;
 327         struct sr_dev_inst *config_sdi;
 328         struct sr_channel_group *config_channel_group;
 329 };
 330
 331 /** A generic device, either hardware or virtual */
 332 class SR_API Device : public Configurable
 333 {
 334 public:
 335         /** Description identifying this device. */
 336         string get_description();
 337         /** Vendor name for this device. */
 338         string get_vendor();
 339         /** Model name for this device. */
 340         string get_model();
 341         /** Version string for this device. */
 342         string get_version();
 343         /** List of the channels available on this device. */
 344         vector<shared_ptr<Channel> > get_channels();
 345         /** Channel groups available on this device, indexed by name. */
 346         map<string, shared_ptr<ChannelGroup> > get_channel_groups();
 347         /** Open device. */
 348         void open();
 349         /** Close device. */
 350         void close();
 351 protected:
 352         Device(struct sr_dev_inst *structure);
 353         ~Device();
 354         virtual shared_ptr<Device> get_shared_from_this() = 0;
 355         shared_ptr<Channel> get_channel(struct sr_channel *ptr);
 356         struct sr_dev_inst *structure;
 357         map<struct sr_channel *, Channel *> channels;
 358         map<string, ChannelGroup *> channel_groups;
 359         /** Deleter needed to allow shared_ptr use with protected destructor. */
 360         class Deleter
 361         {
 362         public:
 363                 void operator()(Device *device) { delete device; }
 364         };
 365         friend class Deleter;
 366         friend class Session;
 367         friend class Channel;
 368         friend class ChannelGroup;
 369         friend class Output;
 370         friend class Analog;
 371 };
 372
 373 /** A real hardware device, connected via a driver */
 374 class SR_API HardwareDevice :
 375         public ParentOwned<HardwareDevice, Context, struct sr_dev_inst>,
 376         public Device
 377 {
 378 public:
 379         /** Driver providing this device. */
 380         shared_ptr<Driver> get_driver();
 381 protected:
 382         HardwareDevice(Driver *driver, struct sr_dev_inst *structure);
 383         ~HardwareDevice();
 384         shared_ptr<Device> get_shared_from_this();
 385         Driver *driver;
 386         friend class Driver;
 387         friend class ChannelGroup;
 388 };
 389
 390 /** A channel on a device */
 391 class SR_API Channel :
 392         public ParentOwned<Channel, Device, struct sr_channel>
 393 {
 394 public:
 395         /** Current name of this channel. */
 396         string get_name();
 397         /** Set the name of this channel. *
 398          * @param name Name string to set. */
 399         void set_name(string name);
 400         /** Type of this channel. */
 401         const ChannelType *get_type();
 402         /** Enabled status of this channel. */
 403         bool get_enabled();
 404         /** Set the enabled status of this channel.
 405          * @param value Boolean value to set. */
 406         void set_enabled(bool value);
 407         /** Get the index number of this channel. */
 408         unsigned int get_index();
 409 protected:
 410         Channel(struct sr_channel *structure);
 411         ~Channel();
 412         const ChannelType * const type;
 413         friend class Device;
 414         friend class ChannelGroup;
 415         friend class Session;
 416         friend class TriggerStage;
 417 };
 418
 419 /** A group of channels on a device, which share some configuration */
 420 class SR_API ChannelGroup :
 421         public ParentOwned<ChannelGroup, Device, struct sr_channel_group>,
 422         public Configurable
 423 {
 424 public:
 425         /** Name of this channel group. */
 426         string get_name();
 427         /** List of the channels in this group. */
 428         vector<shared_ptr<Channel> > get_channels();
 429 protected:
 430         ChannelGroup(Device *device, struct sr_channel_group *structure);
 431         ~ChannelGroup();
 432         vector<Channel *> channels;
 433         friend class Device;
 434 };
 435
 436 /** A trigger configuration */
 437 class SR_API Trigger : public UserOwned<Trigger, struct sr_trigger>
 438 {
 439 public:
 440         /** Name of this trigger configuration. */
 441         string get_name();
 442         /** List of the stages in this trigger. */
 443         vector<shared_ptr<TriggerStage> > get_stages();
 444         /** Add a new stage to this trigger. */
 445         shared_ptr<TriggerStage> add_stage();
 446 protected:
 447         Trigger(shared_ptr<Context> context, string name);
 448         ~Trigger();
 449         shared_ptr<Context> context;
 450         vector<TriggerStage *> stages;
 451         /** Deleter needed to allow shared_ptr use with protected destructor. */
 452         class Deleter
 453         {
 454         public:
 455                 void operator()(Trigger *trigger) { delete trigger; }
 456         };
 457         friend class Context;
 458         friend class Session;
 459 };
 460
 461 /** A stage in a trigger configuration */
 462 class SR_API TriggerStage :
 463         public ParentOwned<TriggerStage, Trigger, struct sr_trigger_stage>
 464 {
 465 public:
 466         /** Index number of this stage. */
 467         int get_number();
 468         /** List of match conditions on this stage. */
 469         vector<shared_ptr<TriggerMatch> > get_matches();
 470         /** Add a new match condition to this stage.
 471          * @param channel Channel to match on.
 472          * @param type TriggerMatchType to apply. */
 473         void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type);
 474         /** Add a new match condition to this stage.
 475          * @param channel Channel to match on.
 476          * @param type TriggerMatchType to apply.
 477          * @param value Threshold value. */
 478         void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type, float value);
 479 protected:
 480         vector<TriggerMatch *> matches;
 481         TriggerStage(struct sr_trigger_stage *structure);
 482         ~TriggerStage();
 483         friend class Trigger;
 484 };
 485
 486 /** A match condition in a trigger configuration  */
 487 class SR_API TriggerMatch :
 488         public ParentOwned<TriggerMatch, TriggerStage, struct sr_trigger_match>
 489 {
 490 public:
 491         /** Channel this condition matches on. */
 492         shared_ptr<Channel> get_channel();
 493         /** Type of match. */
 494         const TriggerMatchType *get_type();
 495         /** Threshold value. */
 496         float get_value();
 497 protected:
 498         TriggerMatch(struct sr_trigger_match *structure, shared_ptr<Channel> channel);
 499         ~TriggerMatch();
 500         shared_ptr<Channel> channel;
 501         friend class TriggerStage;
 502 };
 503
 504 /** Type of datafeed callback */
 505 typedef function<void(shared_ptr<Device>, shared_ptr<Packet>)>
 506         DatafeedCallbackFunction;
 507
 508 /* Data required for C callback function to call a C++ datafeed callback */
 509 class SR_PRIV DatafeedCallbackData
 510 {
 511 public:
 512         void run(const struct sr_dev_inst *sdi,
 513                 const struct sr_datafeed_packet *pkt);
 514 protected:
 515         DatafeedCallbackFunction callback;
 516         DatafeedCallbackData(Session *session,
 517                 DatafeedCallbackFunction callback);
 518         Session *session;
 519         friend class Session;
 520 };
 521
 522 /** Type of source callback */
 523 typedef function<bool(Glib::IOCondition)>
 524         SourceCallbackFunction;
 525
 526 /* Data required for C callback function to call a C++ source callback */
 527 class SR_PRIV SourceCallbackData
 528 {
 529 public:
 530         bool run(int revents);
 531 protected:
 532         SourceCallbackData(shared_ptr<EventSource> source);
 533         shared_ptr<EventSource> source;
 534         friend class Session;
 535 };
 536
 537 /** An I/O event source */
 538 class SR_API EventSource
 539 {
 540 public:
 541         /** Create an event source from a file descriptor.
 542          * @param fd File descriptor.
 543          * @param events GLib IOCondition event mask.
 544          * @param timeout Timeout in milliseconds.
 545          * @param callback Callback of the form callback(events) */
 546         static shared_ptr<EventSource> create(int fd, Glib::IOCondition events,
 547                 int timeout, SourceCallbackFunction callback);
 548         /** Create an event source from a GLib PollFD
 549          * @param pollfd GLib PollFD
 550          * @param timeout Timeout in milliseconds.
 551          * @param callback Callback of the form callback(events) */
 552         static shared_ptr<EventSource> create(Glib::PollFD pollfd, int timeout,
 553                 SourceCallbackFunction callback);
 554         /** Create an event source from a GLib IOChannel
 555          * @param channel GLib IOChannel.
 556          * @param events GLib IOCondition event mask.
 557          * @param timeout Timeout in milliseconds.
 558          * @param callback Callback of the form callback(events) */
 559         static shared_ptr<EventSource> create(
 560                 Glib::RefPtr<Glib::IOChannel> channel, Glib::IOCondition events,
 561                 int timeout, SourceCallbackFunction callback);
 562 protected:
 563         EventSource(int timeout, SourceCallbackFunction callback);
 564         ~EventSource();
 565         enum source_type {
 566                 SOURCE_FD,
 567                 SOURCE_POLLFD,
 568                 SOURCE_IOCHANNEL
 569         } type;
 570         int fd;
 571         Glib::PollFD pollfd;
 572         Glib::RefPtr<Glib::IOChannel> channel;
 573         Glib::IOCondition events;
 574         int timeout;
 575         SourceCallbackFunction callback;
 576         /** Deleter needed to allow shared_ptr use with protected destructor. */
 577         class Deleter
 578         {
 579         public:
 580                 void operator()(EventSource *source) { delete source; }
 581         };
 582         friend class Deleter;
 583         friend class Session;
 584         friend class SourceCallbackData;
 585 };
 586
 587 /** A sigrok session */
 588 class SR_API Session : public UserOwned<Session, struct sr_session>
 589 {
 590 public:
 591         /** Add a device to this session.
 592          * @param device Device to add. */
 593         void add_device(shared_ptr<Device> device);
 594         /** List devices attached to this session. */
 595         vector<shared_ptr<Device> > get_devices();
 596         /** Remove all devices from this session. */
 597         void remove_devices();
 598         /** Add a datafeed callback to this session.
 599          * @param callback Callback of the form callback(Device, Packet). */
 600         void add_datafeed_callback(DatafeedCallbackFunction callback);
 601         /** Remove all datafeed callbacks from this session. */
 602         void remove_datafeed_callbacks();
 603         /** Add an I/O event source.
 604          * @param source EventSource to add. */
 605         void add_source(shared_ptr<EventSource> source);
 606         /** Remove an event source.
 607          * @param source EventSource to remove. */
 608         void remove_source(shared_ptr<EventSource> source);
 609         /** Start the session. */
 610         void start();
 611         /** Run the session event loop. */
 612         void run();
 613         /** Stop the session. */
 614         void stop();
 615         /** Begin saving session to a file.
 616          * @param filename File name string. */
 617         void begin_save(string filename);
 618         /** Append a packet to the session file being saved.
 619          * @param packet Packet to append. */
 620         void append(shared_ptr<Packet> packet);
 621         /** Append raw logic data to the session file being saved. */
 622         void append(void *data, size_t length, unsigned int unit_size);
 623         /** Get current trigger setting. */
 624         shared_ptr<Trigger> get_trigger();
 625         /** Set trigger setting.
 626          * @param trigger Trigger object to use. */
 627         void set_trigger(shared_ptr<Trigger> trigger);
 628 protected:
 629         Session(shared_ptr<Context> context);
 630         Session(shared_ptr<Context> context, string filename);
 631         ~Session();
 632         const shared_ptr<Context> context;
 633         map<const struct sr_dev_inst *, shared_ptr<Device> > devices;
 634         vector<DatafeedCallbackData *> datafeed_callbacks;
 635         map<shared_ptr<EventSource>, SourceCallbackData *> source_callbacks;
 636         bool saving;
 637         bool save_initialized;
 638         string save_filename;
 639         uint64_t save_samplerate;
 640         shared_ptr<Trigger> trigger;
 641         /** Deleter needed to allow shared_ptr use with protected destructor. */
 642         class Deleter
 643         {
 644         public:
 645                 void operator()(Session *session) { delete session; }
 646         };
 647         friend class Deleter;
 648         friend class Context;
 649         friend class DatafeedCallbackData;
 650 };
 651
 652 /** A packet on the session datafeed */
 653 class SR_API Packet : public UserOwned<Packet, const struct sr_datafeed_packet>
 654 {
 655 public:
 656         /** Type of this packet. */
 657         const PacketType *get_type();
 658         /** Payload of this packet. */
 659         shared_ptr<PacketPayload> get_payload();
 660 protected:
 661         Packet(shared_ptr<Device> device,
 662                 const struct sr_datafeed_packet *structure);
 663         ~Packet();
 664         shared_ptr<Device> device;
 665         PacketPayload *payload;
 666         /** Deleter needed to allow shared_ptr use with protected destructor. */
 667         class Deleter
 668         {
 669         public:
 670                 void operator()(Packet *packet) { delete packet; }
 671         };
 672         friend class Deleter;
 673         friend class Session;
 674         friend class Output;
 675         friend class DatafeedCallbackData;
 676         friend class Header;
 677         friend class Meta;
 678         friend class Logic;
 679         friend class Analog;
 680 };
 681
 682 /** Abstract base class for datafeed packet payloads */
 683 class SR_API PacketPayload
 684 {
 685 protected:
 686         PacketPayload();
 687         virtual ~PacketPayload() = 0;
 688         virtual shared_ptr<PacketPayload> get_shared_pointer(Packet *parent) = 0;
 689         /** Deleter needed to allow shared_ptr use with protected destructor. */
 690         class Deleter
 691         {
 692         public:
 693                 void operator()(PacketPayload *payload) { delete payload; }
 694         };
 695         friend class Deleter;
 696         friend class Packet;
 697         friend class Output;
 698 };
 699
 700 /** Payload of a datafeed header packet */
 701 class SR_API Header :
 702         public ParentOwned<Header, Packet, const struct sr_datafeed_header>,
 703         public PacketPayload
 704 {
 705 public:
 706         /* Feed version number. */
 707         int get_feed_version();
 708         /* Start time of this session. */
 709         Glib::TimeVal get_start_time();
 710 protected:
 711         Header(const struct sr_datafeed_header *structure);
 712         ~Header();
 713         shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
 714         friend class Packet;
 715 };
 716
 717 /** Payload of a datafeed metadata packet */
 718 class SR_API Meta :
 719         public ParentOwned<Meta, Packet, const struct sr_datafeed_meta>,
 720         public PacketPayload
 721 {
 722 public:
 723         /* Mapping of (ConfigKey, value) pairs. */
 724         map<const ConfigKey *, Glib::VariantBase> get_config();
 725 protected:
 726         Meta(const struct sr_datafeed_meta *structure);
 727         ~Meta();
 728         shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
 729         map<const ConfigKey *, Glib::VariantBase> config;
 730         friend class Packet;
 731 };
 732
 733 /** Payload of a datafeed packet with logic data */
 734 class SR_API Logic :
 735         public ParentOwned<Logic, Packet, const struct sr_datafeed_logic>,
 736         public PacketPayload
 737 {
 738 public:
 739         /* Pointer to data. */
 740         void *get_data_pointer();
 741         /* Data length in bytes. */
 742         size_t get_data_length();
 743         /* Size of each sample in bytes. */
 744         unsigned int get_unit_size();
 745 protected:
 746         Logic(const struct sr_datafeed_logic *structure);
 747         ~Logic();
 748         shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
 749         friend class Packet;
 750 };
 751
 752 /** Payload of a datafeed packet with analog data */
 753 class SR_API Analog :
 754         public ParentOwned<Analog, Packet, const struct sr_datafeed_analog>,
 755         public PacketPayload
 756 {
 757 public:
 758         /** Pointer to data. */
 759         float *get_data_pointer();
 760         /** Number of samples in this packet. */
 761         unsigned int get_num_samples();
 762         /** Channels for which this packet contains data. */
 763         vector<shared_ptr<Channel> > get_channels();
 764         /** Measured quantity of the samples in this packet. */
 765         const Quantity *get_mq();
 766         /** Unit of the samples in this packet. */
 767         const Unit *get_unit();
 768         /** Measurement flags associated with the samples in this packet. */
 769         vector<const QuantityFlag *> get_mq_flags();
 770 protected:
 771         Analog(const struct sr_datafeed_analog *structure);
 772         ~Analog();
 773         shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
 774         friend class Packet;
 775 };
 776
 777 /** An input format supported by the library */
 778 class SR_API InputFormat :
 779         public ParentOwned<InputFormat, Context, const struct sr_input_module>
 780 {
 781 public:
 782         /** Name of this input format. */
 783         string get_name();
 784         /** Description of this input format. */
 785         string get_description();
 786         /** Options supported by this input format. */
 787         map<string, shared_ptr<Option> > get_options();
 788         /** Create an input using this input format.
 789          * @param options Mapping of (option name, value) pairs. */
 790         shared_ptr<Input> create_input(map<string, Glib::VariantBase> options = {});
 791 protected:
 792         InputFormat(const struct sr_input_module *structure);
 793         ~InputFormat();
 794         friend class Context;
 795         friend class InputDevice;
 796 };
 797
 798 /** An input instance (an input format applied to a file or stream) */
 799 class SR_API Input : public UserOwned<Input, const struct sr_input>
 800 {
 801 public:
 802         /** Virtual device associated with this input. */
 803         shared_ptr<InputDevice> get_device();
 804         /** Send next stream data.
 805          * @param data Next stream data. */
 806         void send(string data);
 807 protected:
 808         Input(shared_ptr<Context> context, const struct sr_input *structure);
 809         ~Input();
 810         shared_ptr<Context> context;
 811         InputDevice *device;
 812         /** Deleter needed to allow shared_ptr use with protected destructor. */
 813         class Deleter
 814         {
 815         public:
 816                 void operator()(Input *input) { delete input; }
 817         };
 818         friend class Deleter;
 819         friend class Context;
 820         friend class InputFormat;
 821 };
 822
 823 /** A virtual device associated with an input */
 824 class SR_API InputDevice :
 825         public ParentOwned<InputDevice, Input, struct sr_dev_inst>,
 826         public Device
 827 {
 828 protected:
 829         InputDevice(shared_ptr<Input> input, struct sr_dev_inst *sdi);
 830         ~InputDevice();
 831         shared_ptr<Device> get_shared_from_this();
 832         shared_ptr<Input> input;
 833         /** Deleter needed to allow shared_ptr use with protected destructor. */
 834         class Deleter
 835         {
 836         public:
 837                 void operator()(InputDevice *device) { delete device; }
 838         };
 839         friend class Deleter;
 840         friend class Input;
 841 };
 842
 843 /** An option used by an output format */
 844 class SR_API Option : public UserOwned<Option, const struct sr_option>
 845 {
 846 public:
 847         /** Short name of this option suitable for command line usage. */
 848         string get_id();
 849         /** Short name of this option suitable for GUI usage. */
 850         string get_name();
 851         /** Description of this option in a sentence. */
 852         string get_description();
 853         /** Default value for this option. */
 854         Glib::VariantBase get_default_value();
 855         /** Possible values for this option, if a limited set. */
 856         vector<Glib::VariantBase> get_values();
 857 protected:
 858         Option(const struct sr_option *structure,
 859                 shared_ptr<const struct sr_option *> structure_array);
 860         ~Option();
 861         shared_ptr<const struct sr_option *> structure_array;
 862         /** Deleter needed to allow shared_ptr use with protected destructor. */
 863         class Deleter
 864         {
 865         public:
 866                 void operator()(Option *option) { delete option; }
 867         };
 868         friend class Deleter;
 869         friend class InputFormat;
 870         friend class OutputFormat;
 871 };
 872
 873 /** An output format supported by the library */
 874 class SR_API OutputFormat :
 875         public ParentOwned<OutputFormat, Context, const struct sr_output_module>
 876 {
 877 public:
 878         /** Name of this output format. */
 879         string get_name();
 880         /** Description of this output format. */
 881         string get_description();
 882         /** Options supported by this output format. */
 883         map<string, shared_ptr<Option> > get_options();
 884         /** Create an output using this format.
 885          * @param device Device to output for.
 886          * @param options Mapping of (option name, value) pairs. */
 887         shared_ptr<Output> create_output(shared_ptr<Device> device,
 888                 map<string, Glib::VariantBase> options = {});
 889 protected:
 890         OutputFormat(const struct sr_output_module *structure);
 891         ~OutputFormat();
 892         friend class Context;
 893         friend class Output;
 894 };
 895
 896 /** An output instance (an output format applied to a device) */
 897 class SR_API Output : public UserOwned<Output, const struct sr_output>
 898 {
 899 public:
 900         /** Update output with data from the given packet.
 901          * @param packet Packet to handle. */
 902         string receive(shared_ptr<Packet> packet);
 903 protected:
 904         Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
 905         Output(shared_ptr<OutputFormat> format,
 906                 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
 907         ~Output();
 908         const shared_ptr<OutputFormat> format;
 909         const shared_ptr<Device> device;
 910         const map<string, Glib::VariantBase> options;
 911         /** Deleter needed to allow shared_ptr use with protected destructor. */
 912         class Deleter
 913         {
 914         public:
 915                 void operator()(Output *output) { delete output; }
 916         };
 917         friend class Deleter;
 918         friend class OutputFormat;
 919 };
 920
 921 /** Base class for objects which wrap an enumeration value from libsigrok */
 922 template <typename T> class SR_API EnumValue
 923 {
 924 public:
 925         /** The enum constant associated with this value. */
 926         T get_id() const { return id; }
 927         /** The name associated with this value. */
 928         string get_name() const { return name; }
 929 protected:
 930         EnumValue(T id, const char name[]) : id(id), name(name) {}
 931         ~EnumValue() {}
 932         const T id;
 933         const string name;
 934 };
 935
 936 #include "enums.hpp"
 937
 938 }
 939
 940 #endif // LIBSIGROK_HPP