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