2 * This file is part of the libsigrok project.
4 * Copyright (C) 2013-2014 Martin Ling <martin-sigrok@earth.li>
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.
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.
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/>.
22 @mainpage API Reference
27 The libsigrokcxx API provides an object-oriented C++ interface to the
28 functionality in libsigrok, including automatic memory and resource management.
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.
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.
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.
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.
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.
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.
70 #ifndef LIBSIGROKCXX_HPP
71 #define LIBSIGROKCXX_HPP
73 #include <libsigrok/libsigrok.h>
75 /* Suppress warnings due to glibmm's use of std::auto_ptr<> in a public
76 * header file. To be removed once glibmm is fixed. */
77 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
79 G_GNUC_END_IGNORE_DEPRECATIONS
92 /* Forward declarations */
97 class SR_API HardwareDevice;
100 class SR_API ConfigKey;
101 class SR_API Capability;
102 class SR_API InputFormat;
103 class SR_API OutputFormat;
104 class SR_API OutputFlag;
105 class SR_API LogLevel;
106 class SR_API ChannelGroup;
107 class SR_API Trigger;
108 class SR_API TriggerStage;
109 class SR_API TriggerMatch;
110 class SR_API TriggerMatchType;
111 class SR_API ChannelType;
113 class SR_API PacketPayload;
114 class SR_API PacketType;
115 class SR_API Quantity;
117 class SR_API QuantityFlag;
118 class SR_API Rational;
120 class SR_API InputDevice;
122 class SR_API DataType;
124 class SR_API UserDevice;
126 /** Exception thrown when an error code is returned by any libsigrok call. */
127 class SR_API Error: public exception
130 explicit Error(int result);
133 const char *what() const noexcept;
136 /* Base template for classes whose resources are owned by a parent object. */
137 template <class Class, class Parent>
138 class SR_API ParentOwned
141 /* Weak pointer for shared_from_this() implementation. */
142 weak_ptr<Class> _weak_this;
144 static void reset_parent(Class *object)
146 if (!object->_parent)
147 throw Error(SR_ERR_BUG);
148 object->_parent.reset();
152 /* Parent object which owns this child object's underlying structure.
154 This shared pointer will be null when this child is unused, but
155 will be assigned to point to the parent before any shared pointer
156 to this child is handed out to the user.
158 When the reference count of this child falls to zero, this shared
159 pointer to its parent is reset by a custom deleter on the child's
162 This strategy ensures that the destructors for both the child and
163 the parent are called at the correct time, i.e. only when all
164 references to both the parent and all its children are gone. */
165 shared_ptr<Parent> _parent;
169 /* Note, this implementation will create a new smart_ptr if none exists. */
170 shared_ptr<Class> shared_from_this()
172 shared_ptr<Class> shared = _weak_this.lock();
176 shared.reset(static_cast<Class *>(this), &reset_parent);
183 shared_ptr<Class> share_owned_by(shared_ptr<Parent> parent)
186 throw Error(SR_ERR_BUG);
187 this->_parent = parent;
188 return shared_from_this();
192 /* Get parent object that owns this object. */
193 shared_ptr<Parent> parent()
199 /* Base template for classes whose resources are owned by the user. */
200 template <class Class>
201 class SR_API UserOwned : public enable_shared_from_this<Class>
206 shared_ptr<Class> shared_from_this()
208 auto shared = enable_shared_from_this<Class>::shared_from_this();
210 throw Error(SR_ERR_BUG);
215 /** Type of log callback */
216 typedef function<void(const LogLevel *, string message)> LogCallbackFunction;
218 /** Resource reader delegate. */
219 class SR_API ResourceReader
223 virtual ~ResourceReader();
225 /** Resource open hook. */
226 virtual void open(struct sr_resource *res, string name) = 0;
227 /** Resource close hook. */
228 virtual void close(struct sr_resource *res) = 0;
229 /** Resource read hook. */
230 virtual size_t read(const struct sr_resource *res, void *buf, size_t count) = 0;
232 static SR_PRIV int open_callback(struct sr_resource *res,
233 const char *name, void *cb_data) noexcept;
234 static SR_PRIV int close_callback(struct sr_resource *res,
235 void *cb_data) noexcept;
236 static SR_PRIV gssize read_callback(const struct sr_resource *res,
237 void *buf, size_t count, void *cb_data) noexcept;
238 friend class Context;
241 /** The global libsigrok context */
242 class SR_API Context : public UserOwned<Context>
245 /** Create new context */
246 static shared_ptr<Context> create();
247 /** libsigrok package version. */
248 static string package_version();
249 /** libsigrok library version. */
250 static string lib_version();
251 /** Available hardware drivers, indexed by name. */
252 map<string, shared_ptr<Driver> > drivers();
253 /** Available input formats, indexed by name. */
254 map<string, shared_ptr<InputFormat> > input_formats();
255 /** Available output formats, indexed by name. */
256 map<string, shared_ptr<OutputFormat> > output_formats();
257 /** Current log level. */
258 const LogLevel *log_level() const;
259 /** Set the log level.
260 * @param level LogLevel to use. */
261 void set_log_level(const LogLevel *level);
262 /** Set the log callback.
263 * @param callback Callback of the form callback(LogLevel, string). */
264 void set_log_callback(LogCallbackFunction callback);
265 /** Set the log callback to the default handler. */
266 void set_log_callback_default();
267 /** Install a delegate for reading resource files.
268 * @param reader The resource reader delegate, or nullptr to unset. */
269 void set_resource_reader(ResourceReader *reader);
270 /** Create a new session. */
271 shared_ptr<Session> create_session();
272 /** Create a new user device. */
273 shared_ptr<UserDevice> create_user_device(
274 string vendor, string model, string version);
275 /** Create a header packet. */
276 shared_ptr<Packet> create_header_packet(Glib::TimeVal start_time);
277 /** Create a meta packet. */
278 shared_ptr<Packet> create_meta_packet(
279 map<const ConfigKey *, Glib::VariantBase> config);
280 /** Create a logic packet. */
281 shared_ptr<Packet> create_logic_packet(
282 void *data_pointer, size_t data_length, unsigned int unit_size);
283 /** Create an analog packet. */
284 shared_ptr<Packet> create_analog_packet(
285 vector<shared_ptr<Channel> > channels,
286 const float *data_pointer, unsigned int num_samples, const Quantity *mq,
287 const Unit *unit, vector<const QuantityFlag *> mqflags);
288 /** Load a saved session.
289 * @param filename File name string. */
290 shared_ptr<Session> load_session(string filename);
291 /** Create a new trigger.
292 * @param name Name string for new trigger. */
293 shared_ptr<Trigger> create_trigger(string name);
294 /** Open an input file.
295 * @param filename File name string. */
296 shared_ptr<Input> open_file(string filename);
297 /** Open an input stream based on header data.
298 * @param header Initial data from stream. */
299 shared_ptr<Input> open_stream(string header);
300 map<string, string> serials(shared_ptr<Driver> driver) const;
302 struct sr_context *_structure;
303 map<string, unique_ptr<Driver> > _drivers;
304 map<string, unique_ptr<InputFormat> > _input_formats;
305 map<string, unique_ptr<OutputFormat> > _output_formats;
307 LogCallbackFunction _log_callback;
310 friend class Session;
312 friend struct std::default_delete<Context>;
315 /** An object that can be configured. */
316 class SR_API Configurable
319 /** Supported configuration keys. */
320 set<const ConfigKey *> config_keys() const;
321 /** Read configuration for the given key.
322 * @param key ConfigKey to read. */
323 Glib::VariantBase config_get(const ConfigKey *key) const;
324 /** Set configuration for the given key to a specified value.
325 * @param key ConfigKey to set.
326 * @param value Value to set. */
327 void config_set(const ConfigKey *key, const Glib::VariantBase &value);
328 /** Enumerate available values for the given configuration key.
329 * @param key ConfigKey to enumerate values for. */
330 Glib::VariantContainerBase config_list(const ConfigKey *key) const;
331 /** Enumerate configuration capabilities for the given configuration key.
332 * @param key ConfigKey to enumerate capabilities for. */
333 set<const Capability *> config_capabilities(const ConfigKey *key) const;
334 /** Check whether a configuration capability is supported for a given key.
335 * @param key ConfigKey to check.
336 * @param capability Capability to check for. */
337 bool config_check(const ConfigKey *key, const Capability *capability) const;
340 struct sr_dev_driver *driver,
341 struct sr_dev_inst *sdi,
342 struct sr_channel_group *channel_group);
343 virtual ~Configurable();
344 struct sr_dev_driver *config_driver;
345 struct sr_dev_inst *config_sdi;
346 struct sr_channel_group *config_channel_group;
349 /** A hardware driver provided by the library */
350 class SR_API Driver : public ParentOwned<Driver, Context>, public Configurable
353 /** Name of this driver. */
355 /** Long name for this driver. */
356 string long_name() const;
357 /** Scan options supported by this driver. */
358 set<const ConfigKey *> scan_options() const;
359 /** Scan for devices and return a list of devices found.
360 * @param options Mapping of (ConfigKey, value) pairs. */
361 vector<shared_ptr<HardwareDevice> > scan(map<const ConfigKey *, Glib::VariantBase>
362 options = map<const ConfigKey *, Glib::VariantBase>());
364 struct sr_dev_driver *_structure;
366 vector<HardwareDevice *> _devices;
367 explicit Driver(struct sr_dev_driver *structure);
369 friend class Context;
370 friend class HardwareDevice;
371 friend class ChannelGroup;
372 friend struct std::default_delete<Driver>;
375 /** A generic device, either hardware or virtual */
376 class SR_API Device : public Configurable
379 /** Vendor name for this device. */
380 string vendor() const;
381 /** Model name for this device. */
382 string model() const;
383 /** Version string for this device. */
384 string version() const;
385 /** Serial number for this device. */
386 string serial_number() const;
387 /** Connection ID for this device. */
388 string connection_id() const;
389 /** List of the channels available on this device. */
390 vector<shared_ptr<Channel> > channels();
391 /** Channel groups available on this device, indexed by name. */
392 map<string, shared_ptr<ChannelGroup> > channel_groups();
398 explicit Device(struct sr_dev_inst *structure);
400 virtual shared_ptr<Device> get_shared_from_this() = 0;
401 shared_ptr<Channel> get_channel(struct sr_channel *ptr);
403 struct sr_dev_inst *_structure;
404 map<struct sr_channel *, unique_ptr<Channel> > _channels;
406 map<string, unique_ptr<ChannelGroup> > _channel_groups;
408 friend class Session;
409 friend class Channel;
410 friend class ChannelGroup;
413 friend struct std::default_delete<Device>;
416 /** A real hardware device, connected via a driver */
417 class SR_API HardwareDevice :
418 public UserOwned<HardwareDevice>,
422 /** Driver providing this device. */
423 shared_ptr<Driver> driver();
425 HardwareDevice(shared_ptr<Driver> driver, struct sr_dev_inst *structure);
427 shared_ptr<Device> get_shared_from_this();
428 shared_ptr<Driver> _driver;
431 friend class ChannelGroup;
432 friend struct std::default_delete<HardwareDevice>;
435 /** A virtual device, created by the user */
436 class SR_API UserDevice :
437 public UserOwned<UserDevice>,
441 /** Add a new channel to this device. */
442 shared_ptr<Channel> add_channel(unsigned int index, const ChannelType *type, string name);
444 UserDevice(string vendor, string model, string version);
446 shared_ptr<Device> get_shared_from_this();
448 friend class Context;
449 friend struct std::default_delete<UserDevice>;
452 /** A channel on a device */
453 class SR_API Channel :
454 public ParentOwned<Channel, Device>
457 /** Current name of this channel. */
459 /** Set the name of this channel. *
460 * @param name Name string to set. */
461 void set_name(string name);
462 /** Type of this channel. */
463 const ChannelType *type() const;
464 /** Enabled status of this channel. */
465 bool enabled() const;
466 /** Set the enabled status of this channel.
467 * @param value Boolean value to set. */
468 void set_enabled(bool value);
469 /** Get the index number of this channel. */
470 unsigned int index() const;
472 explicit Channel(struct sr_channel *structure);
474 struct sr_channel *_structure;
475 const ChannelType * const _type;
477 friend class UserDevice;
478 friend class ChannelGroup;
479 friend class Session;
480 friend class TriggerStage;
481 friend class Context;
482 friend struct std::default_delete<Channel>;
485 /** A group of channels on a device, which share some configuration */
486 class SR_API ChannelGroup :
487 public ParentOwned<ChannelGroup, Device>,
491 /** Name of this channel group. */
493 /** List of the channels in this group. */
494 vector<shared_ptr<Channel> > channels();
496 ChannelGroup(const Device *device, struct sr_channel_group *structure);
498 vector<Channel *> _channels;
500 friend struct std::default_delete<ChannelGroup>;
503 /** A trigger configuration */
504 class SR_API Trigger : public UserOwned<Trigger>
507 /** Name of this trigger configuration. */
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();
514 Trigger(shared_ptr<Context> context, string name);
516 struct sr_trigger *_structure;
517 shared_ptr<Context> _context;
518 vector<unique_ptr<TriggerStage> > _stages;
519 friend class Context;
520 friend class Session;
521 friend struct std::default_delete<Trigger>;
524 /** A stage in a trigger configuration */
525 class SR_API TriggerStage :
526 public ParentOwned<TriggerStage, Trigger>
529 /** Index number of this stage. */
531 /** List of match conditions on this stage. */
532 vector<shared_ptr<TriggerMatch> > matches();
533 /** Add a new match condition to this stage.
534 * @param channel Channel to match on.
535 * @param type TriggerMatchType to apply. */
536 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type);
537 /** Add a new match condition to this stage.
538 * @param channel Channel to match on.
539 * @param type TriggerMatchType to apply.
540 * @param value Threshold value. */
541 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type, float value);
543 struct sr_trigger_stage *_structure;
544 vector<unique_ptr<TriggerMatch> > _matches;
545 explicit TriggerStage(struct sr_trigger_stage *structure);
547 friend class Trigger;
548 friend struct std::default_delete<TriggerStage>;
551 /** A match condition in a trigger configuration */
552 class SR_API TriggerMatch :
553 public ParentOwned<TriggerMatch, TriggerStage>
556 /** Channel this condition matches on. */
557 shared_ptr<Channel> channel();
558 /** Type of match. */
559 const TriggerMatchType *type() const;
560 /** Threshold value. */
563 TriggerMatch(struct sr_trigger_match *structure, shared_ptr<Channel> channel);
565 struct sr_trigger_match *_structure;
566 shared_ptr<Channel> _channel;
567 friend class TriggerStage;
568 friend struct std::default_delete<TriggerMatch>;
571 /** Type of session stopped callback */
572 typedef function<void()> SessionStoppedCallback;
574 /** Type of datafeed callback */
575 typedef function<void(shared_ptr<Device>, shared_ptr<Packet>)>
576 DatafeedCallbackFunction;
578 /* Data required for C callback function to call a C++ datafeed callback */
579 class SR_PRIV DatafeedCallbackData
582 void run(const struct sr_dev_inst *sdi,
583 const struct sr_datafeed_packet *pkt);
585 DatafeedCallbackFunction _callback;
586 DatafeedCallbackData(Session *session,
587 DatafeedCallbackFunction callback);
589 friend class Session;
592 /** A virtual device associated with a stored session */
593 class SR_API SessionDevice :
594 public ParentOwned<SessionDevice, Session>,
598 explicit SessionDevice(struct sr_dev_inst *sdi);
600 shared_ptr<Device> get_shared_from_this();
602 friend class Session;
603 friend struct std::default_delete<SessionDevice>;
606 /** A sigrok session */
607 class SR_API Session : public UserOwned<Session>
610 /** Add a device to this session.
611 * @param device Device to add. */
612 void add_device(shared_ptr<Device> device);
613 /** List devices attached to this session. */
614 vector<shared_ptr<Device> > devices();
615 /** Remove all devices from this session. */
616 void remove_devices();
617 /** Add a datafeed callback to this session.
618 * @param callback Callback of the form callback(Device, Packet). */
619 void add_datafeed_callback(DatafeedCallbackFunction callback);
620 /** Remove all datafeed callbacks from this session. */
621 void remove_datafeed_callbacks();
622 /** Start the session. */
624 /** Run the session event loop. */
626 /** Stop the session. */
628 /** Return whether the session is running. */
629 bool is_running() const;
630 /** Set callback to be invoked on session stop. */
631 void set_stopped_callback(SessionStoppedCallback callback);
632 /** Get current trigger setting. */
633 shared_ptr<Trigger> trigger();
634 /** Get the context. */
635 shared_ptr<Context> context();
636 /** Set trigger setting.
637 * @param trigger Trigger object to use. */
638 void set_trigger(shared_ptr<Trigger> trigger);
639 /** Get filename this session was loaded from. */
640 string filename() const;
642 explicit Session(shared_ptr<Context> context);
643 Session(shared_ptr<Context> context, string filename);
645 shared_ptr<Device> get_device(const struct sr_dev_inst *sdi);
646 struct sr_session *_structure;
647 const shared_ptr<Context> _context;
648 map<const struct sr_dev_inst *, unique_ptr<SessionDevice> > _owned_devices;
649 map<const struct sr_dev_inst *, shared_ptr<Device> > _other_devices;
650 vector<unique_ptr<DatafeedCallbackData> > _datafeed_callbacks;
651 SessionStoppedCallback _stopped_callback;
653 shared_ptr<Trigger> _trigger;
655 friend class Context;
656 friend class DatafeedCallbackData;
657 friend class SessionDevice;
658 friend struct std::default_delete<Session>;
661 /** A packet on the session datafeed */
662 class SR_API Packet : public UserOwned<Packet>
665 /** Type of this packet. */
666 const PacketType *type() const;
667 /** Payload of this packet. */
668 shared_ptr<PacketPayload> payload();
670 Packet(shared_ptr<Device> device,
671 const struct sr_datafeed_packet *structure);
673 const struct sr_datafeed_packet *_structure;
674 shared_ptr<Device> _device;
675 unique_ptr<PacketPayload> _payload;
677 friend class Session;
679 friend class DatafeedCallbackData;
684 friend class Context;
685 friend struct std::default_delete<Packet>;
688 /** Abstract base class for datafeed packet payloads */
689 class SR_API PacketPayload
693 virtual ~PacketPayload() = 0;
695 virtual shared_ptr<PacketPayload> share_owned_by(shared_ptr<Packet> parent) = 0;
699 friend struct std::default_delete<PacketPayload>;
702 /** Payload of a datafeed header packet */
703 class SR_API Header :
704 public ParentOwned<Header, Packet>,
708 /* Feed version number. */
709 int feed_version() const;
710 /* Start time of this session. */
711 Glib::TimeVal start_time() const;
713 explicit Header(const struct sr_datafeed_header *structure);
715 shared_ptr<PacketPayload> share_owned_by(shared_ptr<Packet> parent);
717 const struct sr_datafeed_header *_structure;
722 /** Payload of a datafeed metadata packet */
724 public ParentOwned<Meta, Packet>,
728 /* Mapping of (ConfigKey, value) pairs. */
729 map<const ConfigKey *, Glib::VariantBase> config() const;
731 explicit Meta(const struct sr_datafeed_meta *structure);
733 shared_ptr<PacketPayload> share_owned_by(shared_ptr<Packet> parent);
735 const struct sr_datafeed_meta *_structure;
736 map<const ConfigKey *, Glib::VariantBase> _config;
741 /** Payload of a datafeed packet with logic data */
743 public ParentOwned<Logic, Packet>,
747 /* Pointer to data. */
748 void *data_pointer();
749 /* Data length in bytes. */
750 size_t data_length() const;
751 /* Size of each sample in bytes. */
752 unsigned int unit_size() const;
754 explicit Logic(const struct sr_datafeed_logic *structure);
756 shared_ptr<PacketPayload> share_owned_by(shared_ptr<Packet> parent);
758 const struct sr_datafeed_logic *_structure;
762 friend struct std::default_delete<Logic>;
765 /** Payload of a datafeed packet with analog data */
766 class SR_API Analog :
767 public ParentOwned<Analog, Packet>,
771 /** Pointer to data. */
772 void *data_pointer();
774 * Fills dest pointer with the analog data converted to float.
775 * The pointer must have space for num_samples() floats.
777 void get_data_as_float(float *dest);
778 /** Number of samples in this packet. */
779 unsigned int num_samples() const;
780 /** Channels for which this packet contains data. */
781 vector<shared_ptr<Channel> > channels();
782 /** Size of a single sample in bytes. */
783 unsigned int unitsize() const;
784 /** Samples use a signed data type. */
785 bool is_signed() const;
786 /** Samples use float. */
787 bool is_float() const;
788 /** Samples are stored in big-endian order. */
789 bool is_bigendian() const;
791 * Number of significant digits after the decimal point if positive,
792 * or number of non-significant digits before the decimal point if negative
793 * (refers to the value we actually read on the wire).
797 bool is_digits_decimal() const;
799 shared_ptr<Rational> scale();
801 shared_ptr<Rational> offset();
802 /** Measured quantity of the samples in this packet. */
803 const Quantity *mq() const;
804 /** Unit of the samples in this packet. */
805 const Unit *unit() const;
806 /** Measurement flags associated with the samples in this packet. */
807 vector<const QuantityFlag *> mq_flags() const;
809 * Provides a Logic packet that contains a conversion of the analog
810 * data using a simple threshold.
812 * @param threshold Threshold to use.
813 * @param data_ptr Pointer to num_samples() bytes where the logic
814 * samples are stored. When nullptr, memory for
815 * logic->data_pointer() will be allocated and must
816 * be freed by the caller.
818 shared_ptr<Logic> get_logic_via_threshold(float threshold,
819 uint8_t *data_ptr=nullptr) const;
821 * Provides a Logic packet that contains a conversion of the analog
822 * data using a Schmitt-Trigger.
824 * @param lo_thr Low threshold to use (anything below this is low).
825 * @param hi_thr High threshold to use (anything above this is high).
826 * @param state Points to a byte that contains the current state of the
827 * converter. For best results, set to value of logic
829 * @param data_ptr Pointer to num_samples() bytes where the logic
830 * samples are stored. When nullptr, memory for
831 * logic->data_pointer() will be allocated and must be
832 * freed by the caller.
834 shared_ptr<Logic> get_logic_via_schmitt_trigger(float lo_thr,
835 float hi_thr, uint8_t *state, uint8_t *data_ptr=nullptr) const;
837 explicit Analog(const struct sr_datafeed_analog *structure);
839 shared_ptr<PacketPayload> share_owned_by(shared_ptr<Packet> parent);
841 const struct sr_datafeed_analog *_structure;
846 /** Number represented by a numerator/denominator integer pair */
847 class SR_API Rational :
848 public ParentOwned<Rational, Analog>
851 /** Numerator, i.e. the dividend. */
852 int64_t numerator() const;
853 /** Denominator, i.e. the divider. */
854 uint64_t denominator() const;
855 /** Actual (lossy) value. */
858 explicit Rational(const struct sr_rational *structure);
860 shared_ptr<Rational> share_owned_by(shared_ptr<Analog> parent);
862 const struct sr_rational *_structure;
865 friend struct std::default_delete<Rational>;
868 /** An input format supported by the library */
869 class SR_API InputFormat :
870 public ParentOwned<InputFormat, Context>
873 /** Name of this input format. */
875 /** Description of this input format. */
876 string description() const;
877 /** A list of preferred file name extensions for this file format.
878 * @note This list is a recommendation only. */
879 vector<string> extensions() const;
880 /** Options supported by this input format. */
881 map<string, shared_ptr<Option> > options();
882 /** Create an input using this input format.
883 * @param options Mapping of (option name, value) pairs. */
884 shared_ptr<Input> create_input(map<string, Glib::VariantBase>
885 options = map<string, Glib::VariantBase>());
887 explicit InputFormat(const struct sr_input_module *structure);
890 const struct sr_input_module *_structure;
892 friend class Context;
893 friend class InputDevice;
894 friend struct std::default_delete<InputFormat>;
897 /** An input instance (an input format applied to a file or stream) */
898 class SR_API Input : public UserOwned<Input>
901 /** Virtual device associated with this input. */
902 shared_ptr<InputDevice> device();
903 /** Send next stream data.
904 * @param data Next stream data.
905 * @param length Length of data. */
906 void send(void *data, size_t length);
907 /** Signal end of input data. */
911 Input(shared_ptr<Context> context, const struct sr_input *structure);
913 const struct sr_input *_structure;
914 shared_ptr<Context> _context;
915 unique_ptr<InputDevice> _device;
917 friend class Context;
918 friend class InputFormat;
919 friend struct std::default_delete<Input>;
922 /** A virtual device associated with an input */
923 class SR_API InputDevice :
924 public ParentOwned<InputDevice, Input>,
928 InputDevice(shared_ptr<Input> input, struct sr_dev_inst *sdi);
930 shared_ptr<Device> get_shared_from_this();
931 shared_ptr<Input> _input;
933 friend struct std::default_delete<InputDevice>;
936 /** An option used by an output format */
937 class SR_API Option : public UserOwned<Option>
940 /** Short name of this option suitable for command line usage. */
942 /** Short name of this option suitable for GUI usage. */
944 /** Description of this option in a sentence. */
945 string description() const;
946 /** Default value for this option. */
947 Glib::VariantBase default_value() const;
948 /** Possible values for this option, if a limited set. */
949 vector<Glib::VariantBase> values() const;
950 /** Parse a string argument into the appropriate type for this option. */
951 Glib::VariantBase parse_string(string value);
953 Option(const struct sr_option *structure,
954 shared_ptr<const struct sr_option *> structure_array);
956 const struct sr_option *_structure;
957 shared_ptr<const struct sr_option *> _structure_array;
959 friend class InputFormat;
960 friend class OutputFormat;
961 friend struct std::default_delete<Option>;
964 /** An output format supported by the library */
965 class SR_API OutputFormat :
966 public ParentOwned<OutputFormat, Context>
969 /** Name of this output format. */
971 /** Description of this output format. */
972 string description() const;
973 /** A list of preferred file name extensions for this file format.
974 * @note This list is a recommendation only. */
975 vector<string> extensions() const;
976 /** Options supported by this output format. */
977 map<string, shared_ptr<Option> > options();
978 /** Create an output using this format.
979 * @param device Device to output for.
980 * @param options Mapping of (option name, value) pairs. */
981 shared_ptr<Output> create_output(shared_ptr<Device> device,
982 map<string, Glib::VariantBase> options = map<string, Glib::VariantBase>());
983 /** Create an output using this format.
984 * @param filename Name of destination file.
985 * @param device Device to output for.
986 * @param options Mapping of (option name, value) pairs. */
987 shared_ptr<Output> create_output(string filename,
988 shared_ptr<Device> device,
989 map<string, Glib::VariantBase> options = map<string, Glib::VariantBase>());
991 * Checks whether a given flag is set.
992 * @param flag Flag to check
993 * @return true if flag is set for this module
994 * @see sr_output_flags
996 bool test_flag(const OutputFlag *flag) const;
998 explicit OutputFormat(const struct sr_output_module *structure);
1001 const struct sr_output_module *_structure;
1003 friend class Context;
1004 friend class Output;
1005 friend struct std::default_delete<OutputFormat>;
1008 /** An output instance (an output format applied to a device) */
1009 class SR_API Output : public UserOwned<Output>
1012 /** Update output with data from the given packet.
1013 * @param packet Packet to handle. */
1014 string receive(shared_ptr<Packet> packet);
1016 Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
1017 Output(shared_ptr<OutputFormat> format,
1018 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
1019 Output(string filename, shared_ptr<OutputFormat> format,
1020 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
1023 const struct sr_output *_structure;
1024 const shared_ptr<OutputFormat> _format;
1025 const shared_ptr<Device> _device;
1026 const map<string, Glib::VariantBase> _options;
1028 friend class OutputFormat;
1029 friend struct std::default_delete<Output>;
1032 /** Base class for objects which wrap an enumeration value from libsigrok */
1033 template <class Class, typename Enum> class SR_API EnumValue
1036 /** The integer constant associated with this value. */
1039 return static_cast<int>(_id);
1041 /** The name associated with this value. */
1046 /** Get value associated with a given integer constant. */
1047 static const Class *get(int id)
1049 const auto pos = _values.find(static_cast<Enum>(id));
1050 if (pos == _values.end())
1051 throw Error(SR_ERR_ARG);
1054 /** Get possible values. */
1055 static std::vector<const Class *> values()
1057 std::vector<const Class *> result;
1058 for (auto entry : _values)
1059 result.push_back(entry.second);
1063 EnumValue(Enum id, const char name[]) : _id(id), _name(name)
1070 static const std::map<const Enum, const Class * const> _values;
1077 #include <libsigrokcxx/enums.hpp>