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 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;
763 /** Payload of a datafeed packet with analog data */
764 class SR_API Analog :
765 public ParentOwned<Analog, Packet>,
769 /** Pointer to data. */
770 void *data_pointer();
772 * Fills dest pointer with the analog data converted to float.
773 * The pointer must have space for num_samples() floats.
775 void get_data_as_float(float *dest);
776 /** Number of samples in this packet. */
777 unsigned int num_samples() const;
778 /** Channels for which this packet contains data. */
779 vector<shared_ptr<Channel> > channels();
780 /** Size of a single sample in bytes. */
781 unsigned int unitsize() const;
782 /** Samples use a signed data type. */
783 bool is_signed() const;
784 /** Samples use float. */
785 bool is_float() const;
786 /** Samples are stored in big-endian order. */
787 bool is_bigendian() const;
789 * Number of significant digits after the decimal point if positive,
790 * or number of non-significant digits before the decimal point if negative
791 * (refers to the value we actually read on the wire).
795 bool is_digits_decimal() const;
797 shared_ptr<Rational> scale();
799 shared_ptr<Rational> offset();
800 /** Measured quantity of the samples in this packet. */
801 const Quantity *mq() const;
802 /** Unit of the samples in this packet. */
803 const Unit *unit() const;
804 /** Measurement flags associated with the samples in this packet. */
805 vector<const QuantityFlag *> mq_flags() const;
807 explicit Analog(const struct sr_datafeed_analog *structure);
809 shared_ptr<PacketPayload> share_owned_by(shared_ptr<Packet> parent);
811 const struct sr_datafeed_analog *_structure;
816 /** Number represented by a numerator/denominator integer pair */
817 class SR_API Rational :
818 public ParentOwned<Rational, Analog>
821 /** Numerator, i.e. the dividend. */
822 int64_t numerator() const;
823 /** Denominator, i.e. the divider. */
824 uint64_t denominator() const;
825 /** Actual (lossy) value. */
828 explicit Rational(const struct sr_rational *structure);
830 shared_ptr<Rational> share_owned_by(shared_ptr<Analog> parent);
832 const struct sr_rational *_structure;
835 friend struct std::default_delete<Rational>;
838 /** An input format supported by the library */
839 class SR_API InputFormat :
840 public ParentOwned<InputFormat, Context>
843 /** Name of this input format. */
845 /** Description of this input format. */
846 string description() const;
847 /** A list of preferred file name extensions for this file format.
848 * @note This list is a recommendation only. */
849 vector<string> extensions() const;
850 /** Options supported by this input format. */
851 map<string, shared_ptr<Option> > options();
852 /** Create an input using this input format.
853 * @param options Mapping of (option name, value) pairs. */
854 shared_ptr<Input> create_input(map<string, Glib::VariantBase>
855 options = map<string, Glib::VariantBase>());
857 explicit InputFormat(const struct sr_input_module *structure);
860 const struct sr_input_module *_structure;
862 friend class Context;
863 friend class InputDevice;
864 friend struct std::default_delete<InputFormat>;
867 /** An input instance (an input format applied to a file or stream) */
868 class SR_API Input : public UserOwned<Input>
871 /** Virtual device associated with this input. */
872 shared_ptr<InputDevice> device();
873 /** Send next stream data.
874 * @param data Next stream data.
875 * @param length Length of data. */
876 void send(void *data, size_t length);
877 /** Signal end of input data. */
881 Input(shared_ptr<Context> context, const struct sr_input *structure);
883 const struct sr_input *_structure;
884 shared_ptr<Context> _context;
885 unique_ptr<InputDevice> _device;
887 friend class Context;
888 friend class InputFormat;
889 friend struct std::default_delete<Input>;
892 /** A virtual device associated with an input */
893 class SR_API InputDevice :
894 public ParentOwned<InputDevice, Input>,
898 InputDevice(shared_ptr<Input> input, struct sr_dev_inst *sdi);
900 shared_ptr<Device> get_shared_from_this();
901 shared_ptr<Input> _input;
903 friend struct std::default_delete<InputDevice>;
906 /** An option used by an output format */
907 class SR_API Option : public UserOwned<Option>
910 /** Short name of this option suitable for command line usage. */
912 /** Short name of this option suitable for GUI usage. */
914 /** Description of this option in a sentence. */
915 string description() const;
916 /** Default value for this option. */
917 Glib::VariantBase default_value() const;
918 /** Possible values for this option, if a limited set. */
919 vector<Glib::VariantBase> values() const;
920 /** Parse a string argument into the appropriate type for this option. */
921 Glib::VariantBase parse_string(string value);
923 Option(const struct sr_option *structure,
924 shared_ptr<const struct sr_option *> structure_array);
926 const struct sr_option *_structure;
927 shared_ptr<const struct sr_option *> _structure_array;
929 friend class InputFormat;
930 friend class OutputFormat;
931 friend struct std::default_delete<Option>;
934 /** An output format supported by the library */
935 class SR_API OutputFormat :
936 public ParentOwned<OutputFormat, Context>
939 /** Name of this output format. */
941 /** Description of this output format. */
942 string description() const;
943 /** A list of preferred file name extensions for this file format.
944 * @note This list is a recommendation only. */
945 vector<string> extensions() const;
946 /** Options supported by this output format. */
947 map<string, shared_ptr<Option> > options();
948 /** Create an output using this format.
949 * @param device Device to output for.
950 * @param options Mapping of (option name, value) pairs. */
951 shared_ptr<Output> create_output(shared_ptr<Device> device,
952 map<string, Glib::VariantBase> options = map<string, Glib::VariantBase>());
953 /** Create an output using this format.
954 * @param filename Name of destination file.
955 * @param device Device to output for.
956 * @param options Mapping of (option name, value) pairs. */
957 shared_ptr<Output> create_output(string filename,
958 shared_ptr<Device> device,
959 map<string, Glib::VariantBase> options = map<string, Glib::VariantBase>());
961 * Checks whether a given flag is set.
962 * @param flag Flag to check
963 * @return true if flag is set for this module
964 * @see sr_output_flags
966 bool test_flag(const OutputFlag *flag) const;
968 explicit OutputFormat(const struct sr_output_module *structure);
971 const struct sr_output_module *_structure;
973 friend class Context;
975 friend struct std::default_delete<OutputFormat>;
978 /** An output instance (an output format applied to a device) */
979 class SR_API Output : public UserOwned<Output>
982 /** Update output with data from the given packet.
983 * @param packet Packet to handle. */
984 string receive(shared_ptr<Packet> packet);
986 Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
987 Output(shared_ptr<OutputFormat> format,
988 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
989 Output(string filename, shared_ptr<OutputFormat> format,
990 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
993 const struct sr_output *_structure;
994 const shared_ptr<OutputFormat> _format;
995 const shared_ptr<Device> _device;
996 const map<string, Glib::VariantBase> _options;
998 friend class OutputFormat;
999 friend struct std::default_delete<Output>;
1002 /** Base class for objects which wrap an enumeration value from libsigrok */
1003 template <class Class, typename Enum> class SR_API EnumValue
1006 /** The integer constant associated with this value. */
1009 return static_cast<int>(_id);
1011 /** The name associated with this value. */
1016 /** Get value associated with a given integer constant. */
1017 static const Class *get(int id)
1019 const auto pos = _values.find(static_cast<Enum>(id));
1020 if (pos == _values.end())
1021 throw Error(SR_ERR_ARG);
1024 /** Get possible values. */
1025 static std::vector<const Class *> values()
1027 std::vector<const Class *> result;
1028 for (auto entry : _values)
1029 result.push_back(entry.second);
1033 EnumValue(Enum id, const char name[]) : _id(id), _name(name)
1040 static const std::map<const Enum, const Class * const> _values;
1047 #include <libsigrokcxx/enums.hpp>