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