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