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