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