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