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