bindings/cxx/include/libsigrok/libsigrok.hpp

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2013-2014 Martin Ling <martin-sigrok@earth.li>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef LIBSIGROK_HPP
  21 #define LIBSIGROK_HPP
  22
  23 #include "libsigrok/libsigrok.h"
  24 #include <glibmm-2.4/glibmm.h>
  25
  26 #include <stdexcept>
  27 #include <memory>
  28 #include <vector>
  29 #include <map>
  30
  31 namespace sigrok
  32 {
  33
  34 using namespace std;
  35
  36 /* Forward declarations */
  37 class SR_API Error;
  38 class SR_API Context;
  39 class SR_API Driver;
  40 class SR_API Device;
  41 class SR_API HardwareDevice;
  42 class SR_API Channel;
  43 class SR_API EventSource;
  44 class SR_API Session;
  45 class SR_API ConfigKey;
  46 class SR_API InputFormat;
  47 class SR_API OutputFormat;
  48 class SR_API LogLevel;
  49 class SR_API ChannelGroup;
  50 class SR_API Trigger;
  51 class SR_API TriggerStage;
  52 class SR_API TriggerMatch;
  53 class SR_API TriggerMatchType;
  54 class SR_API ChannelType;
  55 class SR_API Packet;
  56 class SR_API PacketPayload;
  57 class SR_API PacketType;
  58 class SR_API Quantity;
  59 class SR_API Unit;
  60 class SR_API QuantityFlag;
  61 class SR_API InputFileDevice;
  62 class SR_API Output;
  63 class SR_API DataType;
  64
  65 /** Exception thrown when an error code is returned by any libsigrok call. */
  66 class SR_API Error: public exception
  67 {
  68 public:
  69         Error(int result);
  70         ~Error() throw();
  71         const int result;
  72         const char *what() const throw();
  73 };
  74
  75 /** Base template for most classes which wrap a struct type from libsigrok. */
  76 template <class Parent, typename Struct> class SR_API StructureWrapper :
  77         public enable_shared_from_this<StructureWrapper<Parent, Struct> >
  78 {
  79 public:
  80         /** Parent object which owns this child object's underlying structure.
  81
  82                 This shared pointer will be null when this child is unused, but
  83                 will be assigned to point to the parent before any shared pointer
  84                 to this child is handed out to the user.
  85
  86                 When the reference count of this child falls to zero, this shared
  87                 pointer to its parent is reset by a custom deleter on the child's
  88                 shared pointer.
  89
  90                 This strategy ensures that the destructors for both the child and
  91                 the parent are called at the correct time, i.e. only when all
  92                 references to both the parent and all its children are gone. */
  93         shared_ptr<Parent> parent;
  94 protected:
  95         Struct *structure;
  96
  97         StructureWrapper<Parent, Struct>(Struct *structure) :
  98                 structure(structure)
  99         {
 100         }
 101 };
 102
 103 /** Type of log callback */
 104 typedef function<void(const LogLevel *, string message)> LogCallbackFunction;
 105
 106 /** Context */
 107 class SR_API Context : public enable_shared_from_this<Context>
 108 {
 109 public:
 110         /** Create new context */
 111         static shared_ptr<Context> create();
 112         /** libsigrok package version. */
 113         string get_package_version();
 114         /** libsigrok library version. */
 115         string get_lib_version();
 116         /** Available hardware drivers, indexed by name. */
 117         map<string, shared_ptr<Driver> > get_drivers();
 118         /** Available input formats, indexed by name. */
 119         map<string, shared_ptr<InputFormat> > get_input_formats();
 120         /** Available output formats, indexed by name. */
 121         map<string, shared_ptr<OutputFormat> > get_output_formats();
 122         /** Current log level. */
 123         const LogLevel *get_log_level();
 124         /** Set the log level. */
 125         void set_log_level(const LogLevel *level);
 126         /** Current log domain. */
 127         string get_log_domain();
 128         /** Set the log domain. */
 129         void set_log_domain(string value);
 130         /** Set the log callback. */
 131         void set_log_callback(LogCallbackFunction callback);
 132         /** Set the log callback to the default handler. */
 133         void set_log_callback_default();
 134         /** Create a new session. */
 135         shared_ptr<Session> create_session();
 136         /** Load a saved session. */
 137         shared_ptr<Session> load_session(string filename);
 138         /** Create a new trigger. */
 139         shared_ptr<Trigger> create_trigger(string name);
 140 protected:
 141         struct sr_context *structure;
 142         map<string, Driver *> drivers;
 143         map<string, InputFormat *> input_formats;
 144         map<string, OutputFormat *> output_formats;
 145         Session *session;
 146         LogCallbackFunction log_callback;
 147         Context();
 148         ~Context();
 149         /** Deleter needed to allow shared_ptr use with protected destructor. */
 150         class Deleter
 151         {
 152         public:
 153                 void operator()(Context *context) { delete context; }
 154         };
 155         friend class Deleter;
 156         friend class Session;
 157         friend class Driver;
 158 };
 159
 160 /** Hardware driver */
 161 class SR_API Driver : public StructureWrapper<Context, struct sr_dev_driver>
 162 {
 163 public:
 164         /** Name of this driver. */
 165         string get_name();
 166         /** Long name for this driver. */
 167         string get_long_name();
 168         /** Scan for devices and return a list of devices found. */
 169         vector<shared_ptr<HardwareDevice> > scan(
 170                 map<const ConfigKey *, Glib::VariantBase> options = {});
 171 protected:
 172         bool initialized;
 173         vector<HardwareDevice *> devices;
 174         Driver(struct sr_dev_driver *structure);
 175         ~Driver();
 176         friend class Context;
 177         friend class HardwareDevice;
 178         friend class ChannelGroup;
 179 };
 180
 181 /** An object that can be configured. */
 182 class SR_API Configurable
 183 {
 184 public:
 185         /** Read configuration for the given key. */
 186         Glib::VariantBase config_get(const ConfigKey *key);
 187         /** Set configuration for the given key to a specified value. */
 188         void config_set(const ConfigKey *key, Glib::VariantBase value);
 189         /** Enumerate available values for the given configuration key. */
 190         Glib::VariantBase config_list(const ConfigKey *key);
 191 protected:
 192         Configurable(
 193                 struct sr_dev_driver *driver,
 194                 struct sr_dev_inst *sdi,
 195                 struct sr_channel_group *channel_group);
 196         virtual ~Configurable();
 197         struct sr_dev_driver *config_driver;
 198         struct sr_dev_inst *config_sdi;
 199         struct sr_channel_group *config_channel_group;
 200 };
 201
 202 /** Generic device (may be real or from an input file) */
 203 class SR_API Device :
 204         public Configurable,
 205         public StructureWrapper<Context, struct sr_dev_inst>
 206 {
 207 public:
 208         /** Vendor name for this device. */
 209         string get_vendor();
 210         /** Model name for this device. */
 211         string get_model();
 212         /** Version string for this device. */
 213         string get_version();
 214         /** List of the channels available on this device. */
 215         vector<shared_ptr<Channel> > get_channels();
 216         /** Open device. */
 217         void open();
 218         /** Close device. */
 219         void close();
 220 protected:
 221         Device(struct sr_dev_inst *structure);
 222         ~Device();
 223         vector<Channel *> channels;
 224         /** Deleter needed to allow shared_ptr use with protected destructor. */
 225         class Deleter
 226         {
 227         public:
 228                 void operator()(Device *device) { delete device; }
 229         };
 230         friend class Deleter;
 231         friend class Session;
 232         friend class Channel;
 233         friend class ChannelGroup;
 234         friend class Output;
 235 };
 236
 237 /** Hardware device (connected via a driver) */
 238 class SR_API HardwareDevice : public Device
 239 {
 240 public:
 241         /** Driver providing this device. */
 242         shared_ptr<Driver> get_driver();
 243         /** Channel groups available on this device, indexed by name. */
 244         map<string, shared_ptr<ChannelGroup> > get_channel_groups();
 245 protected:
 246         HardwareDevice(Driver *driver, struct sr_dev_inst *structure);
 247         ~HardwareDevice();
 248         Driver *driver;
 249         map<string, ChannelGroup *> channel_groups;
 250         friend class Driver;
 251         friend class ChannelGroup;
 252 };
 253
 254 /** Channel */
 255 class SR_API Channel : public StructureWrapper<Device, struct sr_channel>
 256 {
 257 public:
 258         /** Current name of this channel. */
 259         string get_name();
 260         /** Set the name of this channel. */
 261         void set_name(string name);
 262         /** Type of this channel. */
 263         const ChannelType *get_type();
 264         /** Enabled status of this channel. */
 265         bool get_enabled();
 266         /** Set the enabled status of this channel. */
 267         void set_enabled(bool value);
 268 protected:
 269         Channel(struct sr_channel *structure);
 270         ~Channel();
 271         const ChannelType * const type;
 272         friend class Device;
 273         friend class ChannelGroup;
 274         friend class Session;
 275         friend class TriggerStage;
 276 };
 277
 278 /** Channel group */
 279 class SR_API ChannelGroup :
 280         public StructureWrapper<HardwareDevice, struct sr_channel_group>,
 281         public Configurable
 282 {
 283 public:
 284         /** Name of this channel group. */
 285         string get_name();
 286         /** List of the channels in this group. */
 287         vector<shared_ptr<Channel> > get_channels();
 288 protected:
 289         ChannelGroup(HardwareDevice *device, struct sr_channel_group *structure);
 290         ~ChannelGroup();
 291         vector<Channel *> channels;
 292         friend class HardwareDevice;
 293 };
 294
 295 /** Trigger */
 296 class SR_API Trigger : public enable_shared_from_this<Trigger>
 297 {
 298 public:
 299         string get_name();
 300         vector<shared_ptr<TriggerStage> > get_stages();
 301         shared_ptr<TriggerStage> add_stage();
 302 protected:
 303         Trigger(shared_ptr<Context> context, string name);
 304         ~Trigger();
 305         struct sr_trigger *structure;
 306         shared_ptr<Context> context;
 307         vector<TriggerStage *> stages;
 308         /** Deleter needed to allow shared_ptr use with protected destructor. */
 309         class Deleter
 310         {
 311         public:
 312                 void operator()(Trigger *trigger) { delete trigger; }
 313         };
 314         friend class Context;
 315 };
 316
 317 /** Trigger stage */
 318 class SR_API TriggerStage : public StructureWrapper<Trigger, struct sr_trigger_stage>
 319 {
 320 public:
 321         int get_number();
 322         vector<shared_ptr<TriggerMatch> > get_matches();
 323         void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type);
 324         void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type, float value);
 325 protected:
 326         vector<TriggerMatch *> matches;
 327         TriggerStage(struct sr_trigger_stage *structure);
 328         ~TriggerStage();
 329         friend class Trigger;
 330 };
 331
 332 /** Trigger match */
 333 class SR_API TriggerMatch : public StructureWrapper<TriggerStage, struct sr_trigger_match>
 334 {
 335 public:
 336         shared_ptr<Channel> get_channel();
 337         const TriggerMatchType *get_type();
 338         float get_value();
 339 protected:
 340         TriggerMatch(struct sr_trigger_match *structure, shared_ptr<Channel> channel);
 341         ~TriggerMatch();
 342         shared_ptr<Channel> channel;
 343         friend class TriggerStage;
 344 };
 345
 346 /** Type of datafeed callback */
 347 typedef function<void(shared_ptr<Device>, shared_ptr<Packet>)>
 348         DatafeedCallbackFunction;
 349
 350 /** Data required for C callback function to call a C++ datafeed callback */
 351 class SR_PRIV DatafeedCallbackData
 352 {
 353 public:
 354         void run(const struct sr_dev_inst *sdi,
 355                 const struct sr_datafeed_packet *pkt);
 356 protected:
 357         DatafeedCallbackFunction callback;
 358         DatafeedCallbackData(Session *session,
 359                 DatafeedCallbackFunction callback);
 360         Session *session;
 361         friend class Session;
 362 };
 363
 364 /** Type of source callback */
 365 typedef function<bool(Glib::IOCondition)>
 366         SourceCallbackFunction;
 367
 368 /** Data required for C callback function to call a C++ source callback */
 369 class SR_PRIV SourceCallbackData
 370 {
 371 public:
 372         bool run(int revents);
 373 protected:
 374         SourceCallbackData(shared_ptr<EventSource> source);
 375         shared_ptr<EventSource> source;
 376         friend class Session;
 377 };
 378
 379 /** Event source. */
 380 class SR_API EventSource
 381 {
 382 public:
 383         /** Create an event source from a file descriptor. */
 384         static shared_ptr<EventSource> create(int fd, Glib::IOCondition events,
 385                 int timeout, SourceCallbackFunction callback);
 386         /** Create an event source from a Glib::PollFD */
 387         static shared_ptr<EventSource> create(Glib::PollFD pollfd, int timeout,
 388                 SourceCallbackFunction callback);
 389         /** Create an event source from a Glib::IOChannel */
 390         static shared_ptr<EventSource> create(
 391                 Glib::RefPtr<Glib::IOChannel> channel, Glib::IOCondition events,
 392                 int timeout, SourceCallbackFunction callback);
 393 protected:
 394         EventSource(int timeout, SourceCallbackFunction callback);
 395         ~EventSource();
 396         enum source_type {
 397                 SOURCE_FD,
 398                 SOURCE_POLLFD,
 399                 SOURCE_IOCHANNEL
 400         } type;
 401         int fd;
 402         Glib::PollFD pollfd;
 403         Glib::RefPtr<Glib::IOChannel> channel;
 404         Glib::IOCondition events;
 405         int timeout;
 406         SourceCallbackFunction callback;
 407         /** Deleter needed to allow shared_ptr use with protected destructor. */
 408         class Deleter
 409         {
 410         public:
 411                 void operator()(EventSource *source) { delete source; }
 412         };
 413         friend class Deleter;
 414         friend class Session;
 415         friend class SourceCallbackData;
 416 };
 417
 418 /** Session */
 419 class SR_API Session
 420 {
 421 public:
 422         /** Add a device to this session. */
 423         void add_device(shared_ptr<Device> device);
 424         /** List devices attached to this session. */
 425         vector<shared_ptr<Device> > get_devices();
 426         /** Remove all devices from this session. */
 427         void remove_devices();
 428         /** Add a datafeed callback to this session. */
 429         void add_datafeed_callback(DatafeedCallbackFunction callback);
 430         /** Remove all datafeed callbacks from this session. */
 431         void remove_datafeed_callbacks();
 432         /** Add an event source. */
 433         void add_source(shared_ptr<EventSource> source);
 434         /** Remove an event source. */
 435         void remove_source(shared_ptr<EventSource> source);
 436         /** Start the session. */
 437         void start();
 438         /** Run the session event loop. */
 439         void run();
 440         /** Stop the session. */
 441         void stop();
 442         /** Begin saving session to a file. */
 443         void begin_save(string filename);
 444         /** Append a packet to the session file being saved. */
 445         void append(shared_ptr<Device> device, shared_ptr<Packet> packet);
 446 protected:
 447         Session(shared_ptr<Context> context);
 448         Session(shared_ptr<Context> context, string filename);
 449         ~Session();
 450         struct sr_session *structure;
 451         const shared_ptr<Context> context;
 452         map<const struct sr_dev_inst *, shared_ptr<Device> > devices;
 453         vector<DatafeedCallbackData *> datafeed_callbacks;
 454         map<shared_ptr<EventSource>, SourceCallbackData *> source_callbacks;
 455         bool saving;
 456         bool save_initialized;
 457         string save_filename;
 458         uint64_t save_samplerate;
 459         /** Deleter needed to allow shared_ptr use with protected destructor. */
 460         class Deleter
 461         {
 462         public:
 463                 void operator()(Session *session) { delete session; }
 464         };
 465         friend class Deleter;
 466         friend class Context;
 467         friend class DatafeedCallbackData;
 468 };
 469
 470 /** Datafeed packet */
 471 class SR_API Packet
 472 {
 473 public:
 474         /** Payload of this packet. */
 475         PacketPayload *get_payload();
 476 protected:
 477         Packet(const struct sr_datafeed_packet *structure);
 478         ~Packet();
 479         const struct sr_datafeed_packet *structure;
 480         PacketPayload *payload;
 481         /** Deleter needed to allow shared_ptr use with protected destructor. */
 482         class Deleter
 483         {
 484         public:
 485                 void operator()(Packet *packet) { delete packet; }
 486         };
 487         friend class Deleter;
 488         friend class Session;
 489         friend class Output;
 490         friend class DatafeedCallbackData;
 491 };
 492
 493 /** Abstract base class for datafeed packet payloads. */
 494 class SR_API PacketPayload
 495 {
 496 protected:
 497         PacketPayload();
 498         virtual ~PacketPayload() = 0;
 499         virtual void *get_data() = 0;
 500         virtual size_t get_data_size() = 0;
 501         friend class Packet;
 502         friend class Output;
 503 };
 504
 505 /** Logic data payload */
 506 class SR_API Logic : public PacketPayload
 507 {
 508 protected:
 509         Logic(const struct sr_datafeed_logic *structure);
 510         ~Logic();
 511         const struct sr_datafeed_logic *structure;
 512         vector<uint8_t> data;
 513         void *get_data();
 514         size_t get_data_size();
 515         friend class Packet;
 516 };
 517
 518 /** Analog data payload */
 519 class SR_API Analog : public PacketPayload
 520 {
 521 public:
 522         /** Number of samples in this packet. */
 523         unsigned int get_num_samples();
 524         /** Measured quantity of the samples in this packet. */
 525         const Quantity *get_mq();
 526         /** Unit of the samples in this packet. */
 527         const Unit *get_unit();
 528         /** Measurement flags associated with the samples in this packet. */
 529         vector<const QuantityFlag *> get_mq_flags();
 530 protected:
 531         Analog(const struct sr_datafeed_analog *structure);
 532         ~Analog();
 533         const struct sr_datafeed_analog *structure;
 534         void *get_data();
 535         size_t get_data_size();
 536         friend class Packet;
 537 };
 538
 539 /** Input format */
 540 class SR_API InputFormat :
 541         public StructureWrapper<Context, struct sr_input_format>
 542 {
 543 public:
 544         /** Name of this input format. */
 545         string get_name();
 546         /** Description of this input format. */
 547         string get_description();
 548         /** Check whether a given file matches this input format. */
 549         bool format_match(string filename);
 550         /** Open a file using this input format. */
 551         shared_ptr<InputFileDevice> open_file(string filename,
 552                 map<string, string> options = {});
 553 protected:
 554         InputFormat(struct sr_input_format *structure);
 555         ~InputFormat();
 556         friend class Context;
 557         friend class InputFileDevice;
 558 };
 559
 560 /** Virtual device associated with an input file */
 561 class SR_API InputFileDevice : public Device
 562 {
 563 public:
 564         /** Load data from file. */
 565         void load();
 566 protected:
 567         InputFileDevice(shared_ptr<InputFormat> format,
 568                 struct sr_input *input, string filename);
 569         ~InputFileDevice();
 570         struct sr_input *input;
 571         shared_ptr<InputFormat> format;
 572         string filename;
 573         /** Deleter needed to allow shared_ptr use with protected destructor. */
 574         class Deleter
 575         {
 576         public:
 577                 void operator()(InputFileDevice *device) { delete device; }
 578         };
 579         friend class Deleter;
 580         friend class InputFormat;
 581 };
 582
 583 /** Output format */
 584 class SR_API OutputFormat :
 585         public StructureWrapper<Context, struct sr_output_format>
 586 {
 587 public:
 588         /** Name of this output format. */
 589         string get_name();
 590         /** Description of this output format. */
 591         string get_description();
 592         /** Create an output using this format. */
 593         shared_ptr<Output> create_output(shared_ptr<Device> device, map<string, string> options = {});
 594 protected:
 595         OutputFormat(struct sr_output_format *structure);
 596         ~OutputFormat();
 597         friend class Context;
 598         friend class Output;
 599 };
 600
 601 /** Output instance (an output format applied to a device) */
 602 class SR_API Output
 603 {
 604 public:
 605         /** Update output with data from the given packet. */
 606         string receive(shared_ptr<Packet> packet);
 607 protected:
 608         Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
 609         Output(shared_ptr<OutputFormat> format,
 610                 shared_ptr<Device> device, map<string, string> options);
 611         ~Output();
 612         struct sr_output *structure;
 613         const shared_ptr<OutputFormat> format;
 614         const shared_ptr<Device> device;
 615         const map<string, string> options;
 616         /** Deleter needed to allow shared_ptr use with protected destructor. */
 617         class Deleter
 618         {
 619         public:
 620                 void operator()(Output *output) { delete output; }
 621         };
 622         friend class Deleter;
 623         friend class OutputFormat;
 624 };
 625
 626 /** Base class for objects which wrap an enumeration value from libsigrok */
 627 template <typename T> class SR_API EnumValue
 628 {
 629 public:
 630         /** The enum constant associated with this value. */
 631         T get_id() const { return id; }
 632         /** The name associated with this value. */
 633         string get_name() const { return name; }
 634 protected:
 635         EnumValue(T id, const char name[]) : id(id), name(name) {}
 636         ~EnumValue() {}
 637         const T id;
 638         const string name;
 639 };
 640
 641 #include "enums.hpp"
 642
 643 }
 644
 645 #endif // LIBSIGROK_HPP