bindings/cxx/include/libsigrokcxx/libsigrokcxx.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 libsigrokcxx API provides an object-oriented C++ interface to the
  28 functionality 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 libsigrokcxx objects and their underlying
  49 libsigrok resources can be treated as fully automatic. As long as all shared
  50 pointers to objects are deleted or reassigned when no longer in use, all
  51 underlying 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 LIBSIGROKCXX_HPP
  71 #define LIBSIGROKCXX_HPP
  72
  73 #include "libsigrok/libsigrok.h"
  74 #include <glibmm.h>
  75
  76 #include <stdexcept>
  77 #include <memory>
  78 #include <vector>
  79 #include <map>
  80 #include <set>
  81
  82 namespace sigrok
  83 {
  84
  85 using namespace std;
  86
  87 /* Forward declarations */
  88 class SR_API Error;
  89 class SR_API Context;
  90 class SR_API Driver;
  91 class SR_API Device;
  92 class SR_API HardwareDevice;
  93 class SR_API Channel;
  94 class SR_API EventSource;
  95 class SR_API Session;
  96 class SR_API ConfigKey;
  97 class SR_API InputFormat;
  98 class SR_API OutputFormat;
  99 class SR_API OutputFlag;
 100 class SR_API LogLevel;
 101 class SR_API ChannelGroup;
 102 class SR_API Trigger;
 103 class SR_API TriggerStage;
 104 class SR_API TriggerMatch;
 105 class SR_API TriggerMatchType;
 106 class SR_API ChannelType;
 107 class SR_API Packet;
 108 class SR_API PacketPayload;
 109 class SR_API PacketType;
 110 class SR_API Quantity;
 111 class SR_API Unit;
 112 class SR_API QuantityFlag;
 113 class SR_API Input;
 114 class SR_API InputDevice;
 115 class SR_API Output;
 116 class SR_API DataType;
 117 class SR_API Option;
 118 class SR_API UserDevice;
 119
 120 /** Exception thrown when an error code is returned by any libsigrok call. */
 121 class SR_API Error: public exception
 122 {
 123 public:
 124         Error(int result);
 125         ~Error() throw();
 126         const int result;
 127         const char *what() const throw();
 128 };
 129
 130 /* Base template for classes whose resources are owned by a parent object. */
 131 template <class Class, class Parent, typename Struct>
 132 class SR_API ParentOwned
 133 {
 134 protected:
 135         /*  Parent object which owns this child object's underlying structure.
 136
 137                 This shared pointer will be null when this child is unused, but
 138                 will be assigned to point to the parent before any shared pointer
 139                 to this child is handed out to the user.
 140
 141                 When the reference count of this child falls to zero, this shared
 142                 pointer to its parent is reset by a custom deleter on the child's
 143                 shared pointer.
 144
 145                 This strategy ensures that the destructors for both the child and
 146                 the parent are called at the correct time, i.e. only when all
 147                 references to both the parent and all its children are gone. */
 148         shared_ptr<Parent> _parent;
 149
 150         /* Weak pointer for shared_from_this() implementation. */
 151         weak_ptr<Class> _weak_this;
 152
 153 public:
 154         /* Get parent object that owns this object. */
 155         shared_ptr<Parent> parent()
 156         {
 157                 return _parent;
 158         }
 159
 160         /* Note, this implementation will create a new smart_ptr if none exists. */
 161         shared_ptr<Class> shared_from_this()
 162         {
 163                 shared_ptr<Class> shared;
 164
 165                 if (!(shared = _weak_this.lock()))
 166                 {
 167                         shared = shared_ptr<Class>((Class *) this, reset_parent);
 168                         _weak_this = shared;
 169                 }
 170
 171                 return shared;
 172         }
 173
 174         shared_ptr<Class> get_shared_pointer(shared_ptr<Parent> parent)
 175         {
 176                 if (!parent)
 177                         throw Error(SR_ERR_BUG);
 178                 this->_parent = parent;
 179                 return shared_from_this();
 180         }
 181
 182         shared_ptr<Class> get_shared_pointer(Parent *parent)
 183         {
 184                 if (!parent)
 185                         throw Error(SR_ERR_BUG);
 186                 return get_shared_pointer(parent->shared_from_this());
 187         }
 188 protected:
 189         static void reset_parent(Class *object)
 190         {
 191                 if (!object->_parent)
 192                         throw Error(SR_ERR_BUG);
 193                 object->_parent.reset();
 194         }
 195
 196         Struct *_structure;
 197
 198         ParentOwned<Class, Parent, Struct>(Struct *structure) :
 199                 _structure(structure)
 200         {
 201         }
 202 };
 203
 204 /* Base template for classes whose resources are owned by the user. */
 205 template <class Class, typename Struct>
 206 class SR_API UserOwned : public enable_shared_from_this<Class>
 207 {
 208 public:
 209         shared_ptr<Class> shared_from_this()
 210         {
 211                 auto shared = enable_shared_from_this<Class>::shared_from_this();
 212                 if (!shared)
 213                         throw Error(SR_ERR_BUG);
 214                 return shared;
 215         }
 216 protected:
 217         Struct *_structure;
 218
 219         UserOwned<Class, Struct>(Struct *structure) :
 220                 _structure(structure)
 221         {
 222         }
 223
 224         /* Deleter needed to allow shared_ptr use with protected destructor. */
 225         class Deleter
 226         {
 227         public:
 228                 void operator()(Class *object) { delete object; }
 229         };
 230 };
 231
 232 /** Type of log callback */
 233 typedef function<void(const LogLevel *, string message)> LogCallbackFunction;
 234
 235 /** The global libsigrok context */
 236 class SR_API Context : public UserOwned<Context, struct sr_context>
 237 {
 238 public:
 239         /** Create new context */
 240         static shared_ptr<Context> create();
 241         /** libsigrok package version. */
 242         string package_version();
 243         /** libsigrok library version. */
 244         string lib_version();
 245         /** Available hardware drivers, indexed by name. */
 246         map<string, shared_ptr<Driver> > drivers();
 247         /** Available input formats, indexed by name. */
 248         map<string, shared_ptr<InputFormat> > input_formats();
 249         /** Available output formats, indexed by name. */
 250         map<string, shared_ptr<OutputFormat> > output_formats();
 251         /** Current log level. */
 252         const LogLevel *log_level();
 253         /** Set the log level.
 254          * @param level LogLevel to use. */
 255         void set_log_level(const LogLevel *level);
 256         /** Current log domain. */
 257         string log_domain();
 258         /** Set the log domain.
 259          * @param value Log domain prefix string. */
 260         void set_log_domain(string value);
 261         /** Set the log callback.
 262          * @param callback Callback of the form callback(LogLevel, string). */
 263         void set_log_callback(LogCallbackFunction callback);
 264         /** Set the log callback to the default handler. */
 265         void set_log_callback_default();
 266         /** Create a new session. */
 267         shared_ptr<Session> create_session();
 268         /** Create a new user device. */
 269         shared_ptr<UserDevice> create_user_device(
 270                 string vendor, string model, string version);
 271         /** Create a header packet. */
 272         shared_ptr<Packet> create_header_packet(Glib::TimeVal start_time);
 273         /** Create a meta packet. */
 274         shared_ptr<Packet> create_meta_packet(
 275                 map<const ConfigKey *, Glib::VariantBase> config);
 276         /** Create a logic packet. */
 277         shared_ptr<Packet> create_logic_packet(
 278                 void *data_pointer, size_t data_length, unsigned int unit_size);
 279         /** Create an analog packet. */
 280         shared_ptr<Packet> create_analog_packet(
 281                 vector<shared_ptr<Channel> > channels,
 282                 float *data_pointer, unsigned int num_samples, const Quantity *mq,
 283                 const Unit *unit, vector<const QuantityFlag *> mqflags);
 284         /** Load a saved session.
 285          * @param filename File name string. */
 286         shared_ptr<Session> load_session(string filename);
 287         /** Create a new trigger.
 288          * @param name Name string for new trigger. */
 289         shared_ptr<Trigger> create_trigger(string name);
 290         /** Open an input file.
 291          * @param filename File name string. */
 292         shared_ptr<Input> open_file(string filename);
 293         /** Open an input stream based on header data.
 294          * @param header Initial data from stream. */
 295         shared_ptr<Input> open_stream(string header);
 296         map<string, string> serials(shared_ptr<Driver> driver);
 297 protected:
 298         map<string, Driver *> _drivers;
 299         map<string, InputFormat *> _input_formats;
 300         map<string, OutputFormat *> _output_formats;
 301         Session *_session;
 302         LogCallbackFunction _log_callback;
 303         Context();
 304         ~Context();
 305         friend class Deleter;
 306         friend class Session;
 307         friend class Driver;
 308 };
 309
 310 enum Capability {
 311         GET = SR_CONF_GET,
 312         SET = SR_CONF_SET,
 313         LIST = SR_CONF_LIST
 314 };
 315
 316 /** An object that can be configured. */
 317 class SR_API Configurable
 318 {
 319 public:
 320         /** Read configuration for the given key.
 321          * @param key ConfigKey to read. */
 322         Glib::VariantBase config_get(const ConfigKey *key);
 323         /** Set configuration for the given key to a specified value.
 324          * @param key ConfigKey to set.
 325          * @param value Value to set. */
 326         void config_set(const ConfigKey *key, Glib::VariantBase value);
 327         /** Enumerate available values for the given configuration key.
 328          * @param key ConfigKey to enumerate values for. */
 329         Glib::VariantContainerBase config_list(const ConfigKey *key);
 330         /** Enumerate available keys, according to a given index key. */
 331         map<const ConfigKey *, set<Capability> > config_keys(const ConfigKey *key);
 332         /** Check for a key in the list from a given index key. */
 333         bool config_check(const ConfigKey *key, const ConfigKey *index_key);
 334 protected:
 335         Configurable(
 336                 struct sr_dev_driver *driver,
 337                 struct sr_dev_inst *sdi,
 338                 struct sr_channel_group *channel_group);
 339         virtual ~Configurable();
 340         struct sr_dev_driver *config_driver;
 341         struct sr_dev_inst *config_sdi;
 342         struct sr_channel_group *config_channel_group;
 343 };
 344
 345 /** A hardware driver provided by the library */
 346 class SR_API Driver :
 347         public ParentOwned<Driver, Context, struct sr_dev_driver>,
 348         public Configurable
 349 {
 350 public:
 351         /** Name of this driver. */
 352         string name();
 353         /** Long name for this driver. */
 354         string long_name();
 355         /** Scan for devices and return a list of devices found.
 356          * @param options Mapping of (ConfigKey, value) pairs. */
 357         vector<shared_ptr<HardwareDevice> > scan(
 358                 map<const ConfigKey *, Glib::VariantBase> options =
 359                         map<const ConfigKey *, Glib::VariantBase>());
 360 protected:
 361         bool _initialized;
 362         vector<HardwareDevice *> _devices;
 363         Driver(struct sr_dev_driver *structure);
 364         ~Driver();
 365         friend class Context;
 366         friend class HardwareDevice;
 367         friend class ChannelGroup;
 368 };
 369
 370 /** A generic device, either hardware or virtual */
 371 class SR_API Device : public Configurable
 372 {
 373 public:
 374         /** Vendor name for this device. */
 375         string vendor();
 376         /** Model name for this device. */
 377         string model();
 378         /** Version string for this device. */
 379         string version();
 380         /** Serial number for this device. */
 381         string serial_number();
 382         /** Connection ID for this device. */
 383         string connection_id();
 384         /** List of the channels available on this device. */
 385         vector<shared_ptr<Channel> > channels();
 386         /** Channel groups available on this device, indexed by name. */
 387         map<string, shared_ptr<ChannelGroup> > channel_groups();
 388         /** Open device. */
 389         void open();
 390         /** Close device. */
 391         void close();
 392 protected:
 393         Device(struct sr_dev_inst *structure);
 394         ~Device();
 395         virtual shared_ptr<Device> get_shared_from_this() = 0;
 396         shared_ptr<Channel> get_channel(struct sr_channel *ptr);
 397         struct sr_dev_inst *_structure;
 398         map<struct sr_channel *, Channel *> _channels;
 399         map<string, ChannelGroup *> _channel_groups;
 400         /** Deleter needed to allow shared_ptr use with protected destructor. */
 401         class Deleter
 402         {
 403         public:
 404                 void operator()(Device *device) { delete device; }
 405         };
 406         friend class Deleter;
 407         friend class Session;
 408         friend class Channel;
 409         friend class ChannelGroup;
 410         friend class Output;
 411         friend class Analog;
 412 };
 413
 414 /** A real hardware device, connected via a driver */
 415 class SR_API HardwareDevice :
 416         public UserOwned<HardwareDevice, struct sr_dev_inst>,
 417         public Device
 418 {
 419 public:
 420         /** Driver providing this device. */
 421         shared_ptr<Driver> driver();
 422 protected:
 423         HardwareDevice(shared_ptr<Driver> driver, struct sr_dev_inst *structure);
 424         ~HardwareDevice();
 425         shared_ptr<Device> get_shared_from_this();
 426         shared_ptr<Driver> _driver;
 427         /** Deleter needed to allow shared_ptr use with protected destructor. */
 428         class Deleter
 429         {
 430         public:
 431                 void operator()(HardwareDevice *device) { delete device; }
 432         };
 433         friend class Deleter;
 434         friend class Driver;
 435         friend class ChannelGroup;
 436 };
 437
 438 /** A virtual device, created by the user */
 439 class SR_API UserDevice :
 440         public UserOwned<UserDevice, struct sr_dev_inst>,
 441         public Device
 442 {
 443 public:
 444         /** Add a new channel to this device. */
 445         shared_ptr<Channel> add_channel(unsigned int index, const ChannelType *type, string name);
 446 protected:
 447         UserDevice(string vendor, string model, string version);
 448         ~UserDevice();
 449         shared_ptr<Device> get_shared_from_this();
 450         /** Deleter needed to allow shared_ptr use with protected destructor. */
 451         class Deleter
 452         {
 453         public:
 454                 void operator()(UserDevice *device) { delete device; }
 455         };
 456         friend class Context;
 457         friend class Deleter;
 458 };
 459
 460 /** A channel on a device */
 461 class SR_API Channel :
 462         public ParentOwned<Channel, Device, struct sr_channel>
 463 {
 464 public:
 465         /** Current name of this channel. */
 466         string name();
 467         /** Set the name of this channel. *
 468          * @param name Name string to set. */
 469         void set_name(string name);
 470         /** Type of this channel. */
 471         const ChannelType *type();
 472         /** Enabled status of this channel. */
 473         bool enabled();
 474         /** Set the enabled status of this channel.
 475          * @param value Boolean value to set. */
 476         void set_enabled(bool value);
 477         /** Get the index number of this channel. */
 478         unsigned int index();
 479 protected:
 480         Channel(struct sr_channel *structure);
 481         ~Channel();
 482         const ChannelType * const _type;
 483         friend class Device;
 484         friend class UserDevice;
 485         friend class ChannelGroup;
 486         friend class Session;
 487         friend class TriggerStage;
 488         friend class Context;
 489 };
 490
 491 /** A group of channels on a device, which share some configuration */
 492 class SR_API ChannelGroup :
 493         public ParentOwned<ChannelGroup, Device, struct sr_channel_group>,
 494         public Configurable
 495 {
 496 public:
 497         /** Name of this channel group. */
 498         string name();
 499         /** List of the channels in this group. */
 500         vector<shared_ptr<Channel> > channels();
 501 protected:
 502         ChannelGroup(Device *device, struct sr_channel_group *structure);
 503         ~ChannelGroup();
 504         vector<Channel *> _channels;
 505         friend class Device;
 506 };
 507
 508 /** A trigger configuration */
 509 class SR_API Trigger : public UserOwned<Trigger, struct sr_trigger>
 510 {
 511 public:
 512         /** Name of this trigger configuration. */
 513         string name();
 514         /** List of the stages in this trigger. */
 515         vector<shared_ptr<TriggerStage> > stages();
 516         /** Add a new stage to this trigger. */
 517         shared_ptr<TriggerStage> add_stage();
 518 protected:
 519         Trigger(shared_ptr<Context> context, string name);
 520         ~Trigger();
 521         shared_ptr<Context> _context;
 522         vector<TriggerStage *> _stages;
 523         friend class Deleter;
 524         friend class Context;
 525         friend class Session;
 526 };
 527
 528 /** A stage in a trigger configuration */
 529 class SR_API TriggerStage :
 530         public ParentOwned<TriggerStage, Trigger, struct sr_trigger_stage>
 531 {
 532 public:
 533         /** Index number of this stage. */
 534         int number();
 535         /** List of match conditions on this stage. */
 536         vector<shared_ptr<TriggerMatch> > matches();
 537         /** Add a new match condition to this stage.
 538          * @param channel Channel to match on.
 539          * @param type TriggerMatchType to apply. */
 540         void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type);
 541         /** Add a new match condition to this stage.
 542          * @param channel Channel to match on.
 543          * @param type TriggerMatchType to apply.
 544          * @param value Threshold value. */
 545         void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type, float value);
 546 protected:
 547         vector<TriggerMatch *> _matches;
 548         TriggerStage(struct sr_trigger_stage *structure);
 549         ~TriggerStage();
 550         friend class Trigger;
 551 };
 552
 553 /** A match condition in a trigger configuration  */
 554 class SR_API TriggerMatch :
 555         public ParentOwned<TriggerMatch, TriggerStage, struct sr_trigger_match>
 556 {
 557 public:
 558         /** Channel this condition matches on. */
 559         shared_ptr<Channel> channel();
 560         /** Type of match. */
 561         const TriggerMatchType *type();
 562         /** Threshold value. */
 563         float value();
 564 protected:
 565         TriggerMatch(struct sr_trigger_match *structure, shared_ptr<Channel> channel);
 566         ~TriggerMatch();
 567         shared_ptr<Channel> _channel;
 568         friend class TriggerStage;
 569 };
 570
 571 /** Type of datafeed callback */
 572 typedef function<void(shared_ptr<Device>, shared_ptr<Packet>)>
 573         DatafeedCallbackFunction;
 574
 575 /* Data required for C callback function to call a C++ datafeed callback */
 576 class SR_PRIV DatafeedCallbackData
 577 {
 578 public:
 579         void run(const struct sr_dev_inst *sdi,
 580                 const struct sr_datafeed_packet *pkt);
 581 protected:
 582         DatafeedCallbackFunction _callback;
 583         DatafeedCallbackData(Session *session,
 584                 DatafeedCallbackFunction callback);
 585         Session *_session;
 586         friend class Session;
 587 };
 588
 589 /** Type of source callback */
 590 typedef function<bool(Glib::IOCondition)>
 591         SourceCallbackFunction;
 592
 593 /* Data required for C callback function to call a C++ source callback */
 594 class SR_PRIV SourceCallbackData
 595 {
 596 public:
 597         bool run(int revents);
 598 protected:
 599         SourceCallbackData(shared_ptr<EventSource> source);
 600         shared_ptr<EventSource> _source;
 601         friend class Session;
 602 };
 603
 604 /** An I/O event source */
 605 class SR_API EventSource
 606 {
 607 public:
 608         /** Create an event source from a file descriptor.
 609          * @param fd File descriptor.
 610          * @param events GLib IOCondition event mask.
 611          * @param timeout Timeout in milliseconds.
 612          * @param callback Callback of the form callback(events) */
 613         static shared_ptr<EventSource> create(int fd, Glib::IOCondition events,
 614                 int timeout, SourceCallbackFunction callback);
 615         /** Create an event source from a GLib PollFD
 616          * @param pollfd GLib PollFD
 617          * @param timeout Timeout in milliseconds.
 618          * @param callback Callback of the form callback(events) */
 619         static shared_ptr<EventSource> create(Glib::PollFD pollfd, int timeout,
 620                 SourceCallbackFunction callback);
 621         /** Create an event source from a GLib IOChannel
 622          * @param channel GLib IOChannel.
 623          * @param events GLib IOCondition event mask.
 624          * @param timeout Timeout in milliseconds.
 625          * @param callback Callback of the form callback(events) */
 626         static shared_ptr<EventSource> create(
 627                 Glib::RefPtr<Glib::IOChannel> channel, Glib::IOCondition events,
 628                 int timeout, SourceCallbackFunction callback);
 629 protected:
 630         EventSource(int timeout, SourceCallbackFunction callback);
 631         ~EventSource();
 632         enum source_type {
 633                 SOURCE_FD,
 634                 SOURCE_POLLFD,
 635                 SOURCE_IOCHANNEL
 636         } _type;
 637         int _fd;
 638         Glib::PollFD _pollfd;
 639         Glib::RefPtr<Glib::IOChannel> _channel;
 640         Glib::IOCondition _events;
 641         int _timeout;
 642         SourceCallbackFunction _callback;
 643         /** Deleter needed to allow shared_ptr use with protected destructor. */
 644         class Deleter
 645         {
 646         public:
 647                 void operator()(EventSource *source) { delete source; }
 648         };
 649         friend class Deleter;
 650         friend class Session;
 651         friend class SourceCallbackData;
 652 };
 653
 654 /** A virtual device associated with a stored session */
 655 class SR_API SessionDevice :
 656         public ParentOwned<SessionDevice, Session, struct sr_dev_inst>,
 657         public Device
 658 {
 659 protected:
 660         SessionDevice(struct sr_dev_inst *sdi);
 661         ~SessionDevice();
 662         shared_ptr<Device> get_shared_from_this();
 663         /** Deleter needed to allow shared_ptr use with protected destructor. */
 664         class Deleter
 665         {
 666         public:
 667                 void operator()(SessionDevice *device) { delete device; }
 668         };
 669         friend class Deleter;
 670         friend class Session;
 671 };
 672
 673 /** A sigrok session */
 674 class SR_API Session : public UserOwned<Session, struct sr_session>
 675 {
 676 public:
 677         /** Add a device to this session.
 678          * @param device Device to add. */
 679         void add_device(shared_ptr<Device> device);
 680         /** List devices attached to this session. */
 681         vector<shared_ptr<Device> > devices();
 682         /** Remove all devices from this session. */
 683         void remove_devices();
 684         /** Add a datafeed callback to this session.
 685          * @param callback Callback of the form callback(Device, Packet). */
 686         void add_datafeed_callback(DatafeedCallbackFunction callback);
 687         /** Remove all datafeed callbacks from this session. */
 688         void remove_datafeed_callbacks();
 689         /** Add an I/O event source.
 690          * @param source EventSource to add. */
 691         void add_source(shared_ptr<EventSource> source);
 692         /** Remove an event source.
 693          * @param source EventSource to remove. */
 694         void remove_source(shared_ptr<EventSource> source);
 695         /** Start the session. */
 696         void start();
 697         /** Run the session event loop. */
 698         void run();
 699         /** Stop the session. */
 700         void stop();
 701         /** Begin saving session to a file.
 702          * @param filename File name string. */
 703         void begin_save(string filename);
 704         /** Append a packet to the session file being saved.
 705          * @param packet Packet to append. */
 706         void append(shared_ptr<Packet> packet);
 707         /** Append raw logic data to the session file being saved. */
 708         void append(void *data, size_t length, unsigned int unit_size);
 709         /** Get current trigger setting. */
 710         shared_ptr<Trigger> trigger();
 711         /** Get the context. */
 712         shared_ptr<Context> context();
 713         /** Set trigger setting.
 714          * @param trigger Trigger object to use. */
 715         void set_trigger(shared_ptr<Trigger> trigger);
 716         /** Get filename this session was loaded from. */
 717         string filename();
 718 protected:
 719         Session(shared_ptr<Context> context);
 720         Session(shared_ptr<Context> context, string filename);
 721         ~Session();
 722         shared_ptr<Device> get_device(const struct sr_dev_inst *sdi);
 723         const shared_ptr<Context> _context;
 724         map<const struct sr_dev_inst *, SessionDevice *> _owned_devices;
 725         map<const struct sr_dev_inst *, shared_ptr<Device> > _other_devices;
 726         vector<DatafeedCallbackData *> _datafeed_callbacks;
 727         map<shared_ptr<EventSource>, SourceCallbackData *> _source_callbacks;
 728         string _filename;
 729         bool _saving;
 730         bool _save_initialized;
 731         string _save_filename;
 732         uint64_t _save_samplerate;
 733         shared_ptr<Trigger> _trigger;
 734         friend class Deleter;
 735         friend class Context;
 736         friend class DatafeedCallbackData;
 737         friend class SessionDevice;
 738 };
 739
 740 /** A packet on the session datafeed */
 741 class SR_API Packet : public UserOwned<Packet, const struct sr_datafeed_packet>
 742 {
 743 public:
 744         /** Type of this packet. */
 745         const PacketType *type();
 746         /** Payload of this packet. */
 747         shared_ptr<PacketPayload> payload();
 748 protected:
 749         Packet(shared_ptr<Device> device,
 750                 const struct sr_datafeed_packet *structure);
 751         ~Packet();
 752         shared_ptr<Device> _device;
 753         PacketPayload *_payload;
 754         friend class Deleter;
 755         friend class Session;
 756         friend class Output;
 757         friend class DatafeedCallbackData;
 758         friend class Header;
 759         friend class Meta;
 760         friend class Logic;
 761         friend class Analog;
 762         friend class Context;
 763 };
 764
 765 /** Abstract base class for datafeed packet payloads */
 766 class SR_API PacketPayload
 767 {
 768 protected:
 769         PacketPayload();
 770         virtual ~PacketPayload() = 0;
 771         virtual shared_ptr<PacketPayload> get_shared_pointer(Packet *parent) = 0;
 772         /** Deleter needed to allow shared_ptr use with protected destructor. */
 773         class Deleter
 774         {
 775         public:
 776                 void operator()(PacketPayload *payload) { delete payload; }
 777         };
 778         friend class Deleter;
 779         friend class Packet;
 780         friend class Output;
 781 };
 782
 783 /** Payload of a datafeed header packet */
 784 class SR_API Header :
 785         public ParentOwned<Header, Packet, const struct sr_datafeed_header>,
 786         public PacketPayload
 787 {
 788 public:
 789         /* Feed version number. */
 790         int feed_version();
 791         /* Start time of this session. */
 792         Glib::TimeVal start_time();
 793 protected:
 794         Header(const struct sr_datafeed_header *structure);
 795         ~Header();
 796         shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
 797         friend class Packet;
 798 };
 799
 800 /** Payload of a datafeed metadata packet */
 801 class SR_API Meta :
 802         public ParentOwned<Meta, Packet, const struct sr_datafeed_meta>,
 803         public PacketPayload
 804 {
 805 public:
 806         /* Mapping of (ConfigKey, value) pairs. */
 807         map<const ConfigKey *, Glib::VariantBase> config();
 808 protected:
 809         Meta(const struct sr_datafeed_meta *structure);
 810         ~Meta();
 811         shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
 812         map<const ConfigKey *, Glib::VariantBase> _config;
 813         friend class Packet;
 814 };
 815
 816 /** Payload of a datafeed packet with logic data */
 817 class SR_API Logic :
 818         public ParentOwned<Logic, Packet, const struct sr_datafeed_logic>,
 819         public PacketPayload
 820 {
 821 public:
 822         /* Pointer to data. */
 823         void *data_pointer();
 824         /* Data length in bytes. */
 825         size_t data_length();
 826         /* Size of each sample in bytes. */
 827         unsigned int unit_size();
 828 protected:
 829         Logic(const struct sr_datafeed_logic *structure);
 830         ~Logic();
 831         shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
 832         friend class Packet;
 833 };
 834
 835 /** Payload of a datafeed packet with analog data */
 836 class SR_API Analog :
 837         public ParentOwned<Analog, Packet, const struct sr_datafeed_analog>,
 838         public PacketPayload
 839 {
 840 public:
 841         /** Pointer to data. */
 842         float *data_pointer();
 843         /** Number of samples in this packet. */
 844         unsigned int num_samples();
 845         /** Channels for which this packet contains data. */
 846         vector<shared_ptr<Channel> > channels();
 847         /** Measured quantity of the samples in this packet. */
 848         const Quantity *mq();
 849         /** Unit of the samples in this packet. */
 850         const Unit *unit();
 851         /** Measurement flags associated with the samples in this packet. */
 852         vector<const QuantityFlag *> mq_flags();
 853 protected:
 854         Analog(const struct sr_datafeed_analog *structure);
 855         ~Analog();
 856         shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
 857         friend class Packet;
 858 };
 859
 860 /** An input format supported by the library */
 861 class SR_API InputFormat :
 862         public ParentOwned<InputFormat, Context, const struct sr_input_module>
 863 {
 864 public:
 865         /** Name of this input format. */
 866         string name();
 867         /** Description of this input format. */
 868         string description();
 869         /** A list of preferred file name extensions for this file format.
 870          * @note This list is a recommendation only. */
 871         vector<string> extensions();
 872         /** Options supported by this input format. */
 873         map<string, shared_ptr<Option> > options();
 874         /** Create an input using this input format.
 875          * @param options Mapping of (option name, value) pairs. */
 876         shared_ptr<Input> create_input(map<string, Glib::VariantBase> options =
 877                 map<string, Glib::VariantBase>());
 878 protected:
 879         InputFormat(const struct sr_input_module *structure);
 880         ~InputFormat();
 881         friend class Context;
 882         friend class InputDevice;
 883 };
 884
 885 /** An input instance (an input format applied to a file or stream) */
 886 class SR_API Input : public UserOwned<Input, const struct sr_input>
 887 {
 888 public:
 889         /** Virtual device associated with this input. */
 890         shared_ptr<InputDevice> device();
 891         /** Send next stream data.
 892          * @param data Next stream data.
 893          * @param length Length of data. */
 894         void send(void *data, size_t length);
 895         /** Signal end of input data. */
 896         void end();
 897 protected:
 898         Input(shared_ptr<Context> context, const struct sr_input *structure);
 899         ~Input();
 900         shared_ptr<Context> _context;
 901         InputDevice *_device;
 902         friend class Deleter;
 903         friend class Context;
 904         friend class InputFormat;
 905 };
 906
 907 /** A virtual device associated with an input */
 908 class SR_API InputDevice :
 909         public ParentOwned<InputDevice, Input, struct sr_dev_inst>,
 910         public Device
 911 {
 912 protected:
 913         InputDevice(shared_ptr<Input> input, struct sr_dev_inst *sdi);
 914         ~InputDevice();
 915         shared_ptr<Device> get_shared_from_this();
 916         shared_ptr<Input> _input;
 917         friend class Input;
 918 };
 919
 920 /** An option used by an output format */
 921 class SR_API Option : public UserOwned<Option, const struct sr_option>
 922 {
 923 public:
 924         /** Short name of this option suitable for command line usage. */
 925         string id();
 926         /** Short name of this option suitable for GUI usage. */
 927         string name();
 928         /** Description of this option in a sentence. */
 929         string description();
 930         /** Default value for this option. */
 931         Glib::VariantBase default_value();
 932         /** Possible values for this option, if a limited set. */
 933         vector<Glib::VariantBase> values();
 934 protected:
 935         Option(const struct sr_option *structure,
 936                 shared_ptr<const struct sr_option *> structure_array);
 937         ~Option();
 938         shared_ptr<const struct sr_option *> _structure_array;
 939         friend class Deleter;
 940         friend class InputFormat;
 941         friend class OutputFormat;
 942 };
 943
 944 /** An output format supported by the library */
 945 class SR_API OutputFormat :
 946         public ParentOwned<OutputFormat, Context, const struct sr_output_module>
 947 {
 948 public:
 949         /** Name of this output format. */
 950         string name();
 951         /** Description of this output format. */
 952         string description();
 953         /** A list of preferred file name extensions for this file format.
 954          * @note This list is a recommendation only. */
 955         vector<string> extensions();
 956         /** Options supported by this output format. */
 957         map<string, shared_ptr<Option> > options();
 958         /** Create an output using this format.
 959          * @param device Device to output for.
 960          * @param options Mapping of (option name, value) pairs. */
 961         shared_ptr<Output> create_output(
 962                 shared_ptr<Device> device,
 963                 map<string, Glib::VariantBase> options =
 964                         map<string, Glib::VariantBase>());
 965         /** Create an output using this format.
 966          * @param filename Name of destination file.
 967          * @param device Device to output for.
 968          * @param options Mapping of (option name, value) pairs. */
 969         shared_ptr<Output> create_output(string filename,
 970                 shared_ptr<Device> device,
 971                 map<string, Glib::VariantBase> options =
 972                         map<string, Glib::VariantBase>());
 973         /**
 974          * Checks whether a given flag is set.
 975          * @param flag Flag to check
 976          * @return true if flag is set for this module
 977          * @see sr_output_flags
 978          */
 979         bool test_flag(const OutputFlag *flag);
 980 protected:
 981         OutputFormat(const struct sr_output_module *structure);
 982         ~OutputFormat();
 983         friend class Context;
 984         friend class Output;
 985 };
 986
 987 /** An output instance (an output format applied to a device) */
 988 class SR_API Output : public UserOwned<Output, const struct sr_output>
 989 {
 990 public:
 991         /** Update output with data from the given packet.
 992          * @param packet Packet to handle. */
 993         string receive(shared_ptr<Packet> packet);
 994 protected:
 995         Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
 996         Output(shared_ptr<OutputFormat> format,
 997                 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
 998         Output(string filename, shared_ptr<OutputFormat> format,
 999                 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
1000         ~Output();
1001         const shared_ptr<OutputFormat> _format;
1002         const shared_ptr<Device> _device;
1003         const map<string, Glib::VariantBase> _options;
1004         friend class Deleter;
1005         friend class OutputFormat;
1006 };
1007
1008 /** Base class for objects which wrap an enumeration value from libsigrok */
1009 template <class Class, typename Enum> class SR_API EnumValue
1010 {
1011 public:
1012         /** The integer constant associated with this value. */
1013         int id() const
1014         {
1015                 return static_cast<int>(_id);
1016         }
1017         /** The name associated with this value. */
1018         string name() const
1019         {
1020                 return _name;
1021         }
1022         /** Get value associated with a given integer constant. */
1023         static const Class *get(int id)
1024         {
1025                 auto key = static_cast<Enum>(id);
1026                 if (_values.find(key) == _values.end())
1027                         throw Error(SR_ERR_ARG);
1028                 return _values.at(key);
1029         }
1030         /** Get possible values. */
1031         static std::vector<const Class *> values()
1032         {
1033                 std::vector<const Class *> result;
1034                 for (auto entry : _values)
1035                         result.push_back(entry.second);
1036                 return result;
1037         }
1038 protected:
1039         EnumValue(Enum id, const char name[]) : _id(id), _name(name)
1040         {
1041         }
1042         ~EnumValue()
1043         {
1044         }
1045         static const std::map<const Enum, const Class * const> _values;
1046         const Enum _id;
1047         const string _name;
1048 };
1049
1050 #include "enums.hpp"
1051
1052 }
1053
1054 #endif