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