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