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>
87 /* Forward declarations */
92 class SR_API HardwareDevice;
95 class SR_API ConfigKey;
96 class SR_API InputFormat;
97 class SR_API OutputFormat;
98 class SR_API OutputFlag;
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;
107 class SR_API PacketPayload;
108 class SR_API PacketType;
109 class SR_API Quantity;
111 class SR_API QuantityFlag;
113 class SR_API InputDevice;
115 class SR_API DataType;
117 class SR_API UserDevice;
119 /** Exception thrown when an error code is returned by any libsigrok call. */
120 class SR_API Error: public exception
126 const char *what() const throw();
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
134 /* Parent object which owns this child object's underlying structure.
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.
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
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;
149 /* Weak pointer for shared_from_this() implementation. */
150 weak_ptr<Class> _weak_this;
153 /* Get parent object that owns this object. */
154 shared_ptr<Parent> parent()
159 /* Note, this implementation will create a new smart_ptr if none exists. */
160 shared_ptr<Class> shared_from_this()
162 shared_ptr<Class> shared;
164 if (!(shared = _weak_this.lock()))
166 shared = shared_ptr<Class>(static_cast<Class *>(this), reset_parent);
173 shared_ptr<Class> get_shared_pointer(shared_ptr<Parent> parent)
176 throw Error(SR_ERR_BUG);
177 this->_parent = parent;
178 return shared_from_this();
181 shared_ptr<Class> get_shared_pointer(Parent *parent)
184 throw Error(SR_ERR_BUG);
185 return get_shared_pointer(parent->shared_from_this());
188 static void reset_parent(Class *object)
190 if (!object->_parent)
191 throw Error(SR_ERR_BUG);
192 object->_parent.reset();
197 ParentOwned<Class, Parent, Struct>(Struct *structure) :
198 _structure(structure)
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>
208 shared_ptr<Class> shared_from_this()
210 auto shared = enable_shared_from_this<Class>::shared_from_this();
212 throw Error(SR_ERR_BUG);
218 UserOwned<Class, Struct>(Struct *structure) :
219 _structure(structure)
223 /* Deleter needed to allow shared_ptr use with protected destructor. */
227 void operator()(Class *object) { delete object; }
231 /** Type of log callback */
232 typedef function<void(const LogLevel *, string message)> LogCallbackFunction;
234 /** Resource reader delegate. */
235 class SR_API ResourceReader
239 virtual ~ResourceReader();
241 /** Resource open hook. */
242 virtual void open(struct sr_resource *res, string name) = 0;
243 /** Resource close hook. */
244 virtual void close(struct sr_resource *res) = 0;
245 /** Resource read hook. */
246 virtual size_t read(const struct sr_resource *res, void *buf, size_t count) = 0;
248 static SR_PRIV int open_callback(struct sr_resource *res,
249 const char *name, void *cb_data);
250 static SR_PRIV int close_callback(struct sr_resource *res,
252 static SR_PRIV ssize_t read_callback(const struct sr_resource *res,
253 void *buf, size_t count, void *cb_data);
254 friend class Context;
257 /** The global libsigrok context */
258 class SR_API Context : public UserOwned<Context, struct sr_context>
261 /** Create new context */
262 static shared_ptr<Context> create();
263 /** libsigrok package version. */
264 string package_version();
265 /** libsigrok library version. */
266 string lib_version();
267 /** Available hardware drivers, indexed by name. */
268 map<string, shared_ptr<Driver> > drivers();
269 /** Available input formats, indexed by name. */
270 map<string, shared_ptr<InputFormat> > input_formats();
271 /** Available output formats, indexed by name. */
272 map<string, shared_ptr<OutputFormat> > output_formats();
273 /** Current log level. */
274 const LogLevel *log_level();
275 /** Set the log level.
276 * @param level LogLevel to use. */
277 void set_log_level(const LogLevel *level);
278 /** Set the log callback.
279 * @param callback Callback of the form callback(LogLevel, string). */
280 void set_log_callback(LogCallbackFunction callback);
281 /** Set the log callback to the default handler. */
282 void set_log_callback_default();
283 /** Install a delegate for reading resource files.
284 * @param reader The resource reader delegate, or nullptr to unset. */
285 void set_resource_reader(ResourceReader *reader);
286 /** Create a new session. */
287 shared_ptr<Session> create_session();
288 /** Create a new user device. */
289 shared_ptr<UserDevice> create_user_device(
290 string vendor, string model, string version);
291 /** Create a header packet. */
292 shared_ptr<Packet> create_header_packet(Glib::TimeVal start_time);
293 /** Create a meta packet. */
294 shared_ptr<Packet> create_meta_packet(
295 const map<const ConfigKey *, Glib::VariantBase> &config);
296 /** Create a logic packet. */
297 shared_ptr<Packet> create_logic_packet(
298 void *data_pointer, size_t data_length, unsigned int unit_size);
299 /** Create an analog packet. */
300 shared_ptr<Packet> create_analog_packet(
301 const vector<shared_ptr<Channel> > &channels,
302 float *data_pointer, unsigned int num_samples, const Quantity *mq,
303 const Unit *unit, const vector<const QuantityFlag *> &mqflags);
304 /** Load a saved session.
305 * @param filename File name string. */
306 shared_ptr<Session> load_session(string filename);
307 /** Create a new trigger.
308 * @param name Name string for new trigger. */
309 shared_ptr<Trigger> create_trigger(string name);
310 /** Open an input file.
311 * @param filename File name string. */
312 shared_ptr<Input> open_file(string filename);
313 /** Open an input stream based on header data.
314 * @param header Initial data from stream. */
315 shared_ptr<Input> open_stream(string header);
316 map<string, string> serials(shared_ptr<Driver> driver);
318 map<string, Driver *> _drivers;
319 map<string, InputFormat *> _input_formats;
320 map<string, OutputFormat *> _output_formats;
322 LogCallbackFunction _log_callback;
325 friend class Deleter;
326 friend class Session;
336 /** An object that can be configured. */
337 class SR_API Configurable
340 /** Read configuration for the given key.
341 * @param key ConfigKey to read. */
342 Glib::VariantBase config_get(const ConfigKey *key);
343 /** Set configuration for the given key to a specified value.
344 * @param key ConfigKey to set.
345 * @param value Value to set. */
346 void config_set(const ConfigKey *key, const Glib::VariantBase &value);
347 /** Enumerate available values for the given configuration key.
348 * @param key ConfigKey to enumerate values for. */
349 Glib::VariantContainerBase config_list(const ConfigKey *key);
350 /** Enumerate available keys, according to a given index key. */
351 map<const ConfigKey *, set<Capability> > config_keys(const ConfigKey *key);
352 /** Check for a key in the list from a given index key. */
353 bool config_check(const ConfigKey *key, const ConfigKey *index_key);
356 struct sr_dev_driver *driver,
357 struct sr_dev_inst *sdi,
358 struct sr_channel_group *channel_group);
359 virtual ~Configurable();
360 struct sr_dev_driver *config_driver;
361 struct sr_dev_inst *config_sdi;
362 struct sr_channel_group *config_channel_group;
365 /** A hardware driver provided by the library */
366 class SR_API Driver :
367 public ParentOwned<Driver, Context, struct sr_dev_driver>,
371 /** Name of this driver. */
373 /** Long name for this driver. */
375 /** Scan for devices and return a list of devices found.
376 * @param options Mapping of (ConfigKey, value) pairs. */
377 vector<shared_ptr<HardwareDevice> > scan(
378 const map<const ConfigKey *, Glib::VariantBase> &options = {});
381 vector<HardwareDevice *> _devices;
382 Driver(struct sr_dev_driver *structure);
384 friend class Context;
385 friend class HardwareDevice;
386 friend class ChannelGroup;
389 /** A generic device, either hardware or virtual */
390 class SR_API Device : public Configurable
393 /** Vendor name for this device. */
395 /** Model name for this device. */
397 /** Version string for this device. */
399 /** Serial number for this device. */
400 string serial_number();
401 /** Connection ID for this device. */
402 string connection_id();
403 /** List of the channels available on this device. */
404 vector<shared_ptr<Channel> > channels();
405 /** Channel groups available on this device, indexed by name. */
406 map<string, shared_ptr<ChannelGroup> > channel_groups();
412 Device(struct sr_dev_inst *structure);
414 virtual shared_ptr<Device> get_shared_from_this() = 0;
415 shared_ptr<Channel> get_channel(struct sr_channel *ptr);
416 struct sr_dev_inst *_structure;
417 map<struct sr_channel *, Channel *> _channels;
418 map<string, ChannelGroup *> _channel_groups;
419 /** Deleter needed to allow shared_ptr use with protected destructor. */
423 void operator()(Device *device) { delete device; }
425 friend class Deleter;
426 friend class Session;
427 friend class Channel;
428 friend class ChannelGroup;
433 /** A real hardware device, connected via a driver */
434 class SR_API HardwareDevice :
435 public UserOwned<HardwareDevice, struct sr_dev_inst>,
439 /** Driver providing this device. */
440 shared_ptr<Driver> driver();
442 HardwareDevice(shared_ptr<Driver> driver, struct sr_dev_inst *structure);
444 shared_ptr<Device> get_shared_from_this();
445 shared_ptr<Driver> _driver;
446 /** Deleter needed to allow shared_ptr use with protected destructor. */
450 void operator()(HardwareDevice *device) { delete device; }
452 friend class Deleter;
454 friend class ChannelGroup;
457 /** A virtual device, created by the user */
458 class SR_API UserDevice :
459 public UserOwned<UserDevice, struct sr_dev_inst>,
463 /** Add a new channel to this device. */
464 shared_ptr<Channel> add_channel(unsigned int index, const ChannelType *type, string name);
466 UserDevice(string vendor, string model, string version);
468 shared_ptr<Device> get_shared_from_this();
469 /** Deleter needed to allow shared_ptr use with protected destructor. */
473 void operator()(UserDevice *device) { delete device; }
475 friend class Context;
476 friend class Deleter;
479 /** A channel on a device */
480 class SR_API Channel :
481 public ParentOwned<Channel, Device, struct sr_channel>
484 /** Current name of this channel. */
486 /** Set the name of this channel. *
487 * @param name Name string to set. */
488 void set_name(string name);
489 /** Type of this channel. */
490 const ChannelType *type();
491 /** Enabled status of this channel. */
493 /** Set the enabled status of this channel.
494 * @param value Boolean value to set. */
495 void set_enabled(bool value);
496 /** Get the index number of this channel. */
497 unsigned int index();
499 Channel(struct sr_channel *structure);
501 const ChannelType * const _type;
503 friend class UserDevice;
504 friend class ChannelGroup;
505 friend class Session;
506 friend class TriggerStage;
507 friend class Context;
510 /** A group of channels on a device, which share some configuration */
511 class SR_API ChannelGroup :
512 public ParentOwned<ChannelGroup, Device, struct sr_channel_group>,
516 /** Name of this channel group. */
518 /** List of the channels in this group. */
519 vector<shared_ptr<Channel> > channels();
521 ChannelGroup(Device *device, struct sr_channel_group *structure);
523 vector<Channel *> _channels;
527 /** A trigger configuration */
528 class SR_API Trigger : public UserOwned<Trigger, struct sr_trigger>
531 /** Name of this trigger configuration. */
533 /** List of the stages in this trigger. */
534 vector<shared_ptr<TriggerStage> > stages();
535 /** Add a new stage to this trigger. */
536 shared_ptr<TriggerStage> add_stage();
538 Trigger(shared_ptr<Context> context, string name);
540 shared_ptr<Context> _context;
541 vector<TriggerStage *> _stages;
542 friend class Deleter;
543 friend class Context;
544 friend class Session;
547 /** A stage in a trigger configuration */
548 class SR_API TriggerStage :
549 public ParentOwned<TriggerStage, Trigger, struct sr_trigger_stage>
552 /** Index number of this stage. */
554 /** List of match conditions on this stage. */
555 vector<shared_ptr<TriggerMatch> > matches();
556 /** Add a new match condition to this stage.
557 * @param channel Channel to match on.
558 * @param type TriggerMatchType to apply. */
559 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type);
560 /** Add a new match condition to this stage.
561 * @param channel Channel to match on.
562 * @param type TriggerMatchType to apply.
563 * @param value Threshold value. */
564 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type, float value);
566 vector<TriggerMatch *> _matches;
567 TriggerStage(struct sr_trigger_stage *structure);
569 friend class Trigger;
572 /** A match condition in a trigger configuration */
573 class SR_API TriggerMatch :
574 public ParentOwned<TriggerMatch, TriggerStage, struct sr_trigger_match>
577 /** Channel this condition matches on. */
578 shared_ptr<Channel> channel();
579 /** Type of match. */
580 const TriggerMatchType *type();
581 /** Threshold value. */
584 TriggerMatch(struct sr_trigger_match *structure, shared_ptr<Channel> channel);
586 shared_ptr<Channel> _channel;
587 friend class TriggerStage;
590 /** Type of session stopped callback */
591 typedef function<void()> SessionStoppedCallback;
593 /** Type of datafeed callback */
594 typedef function<void(shared_ptr<Device>, shared_ptr<Packet>)>
595 DatafeedCallbackFunction;
597 /* Data required for C callback function to call a C++ datafeed callback */
598 class SR_PRIV DatafeedCallbackData
601 void run(const struct sr_dev_inst *sdi,
602 const struct sr_datafeed_packet *pkt);
604 DatafeedCallbackFunction _callback;
605 DatafeedCallbackData(Session *session,
606 DatafeedCallbackFunction callback);
608 friend class Session;
611 /** A virtual device associated with a stored session */
612 class SR_API SessionDevice :
613 public ParentOwned<SessionDevice, Session, struct sr_dev_inst>,
617 SessionDevice(struct sr_dev_inst *sdi);
619 shared_ptr<Device> get_shared_from_this();
620 /** Deleter needed to allow shared_ptr use with protected destructor. */
624 void operator()(SessionDevice *device) { delete device; }
626 friend class Deleter;
627 friend class Session;
630 /** A sigrok session */
631 class SR_API Session : public UserOwned<Session, struct sr_session>
634 /** Add a device to this session.
635 * @param device Device to add. */
636 void add_device(shared_ptr<Device> device);
637 /** List devices attached to this session. */
638 vector<shared_ptr<Device> > devices();
639 /** Remove all devices from this session. */
640 void remove_devices();
641 /** Add a datafeed callback to this session.
642 * @param callback Callback of the form callback(Device, Packet). */
643 void add_datafeed_callback(DatafeedCallbackFunction callback);
644 /** Remove all datafeed callbacks from this session. */
645 void remove_datafeed_callbacks();
646 /** Start the session. */
648 /** Run the session event loop. */
650 /** Stop the session. */
652 /** Return whether the session is running. */
653 bool is_running() const;
654 /** Set callback to be invoked on session stop. */
655 void set_stopped_callback(SessionStoppedCallback callback);
656 /** Get current trigger setting. */
657 shared_ptr<Trigger> trigger();
658 /** Get the context. */
659 shared_ptr<Context> context();
660 /** Set trigger setting.
661 * @param trigger Trigger object to use. */
662 void set_trigger(shared_ptr<Trigger> trigger);
663 /** Get filename this session was loaded from. */
666 Session(shared_ptr<Context> context);
667 Session(shared_ptr<Context> context, string filename);
669 shared_ptr<Device> get_device(const struct sr_dev_inst *sdi);
670 const shared_ptr<Context> _context;
671 map<const struct sr_dev_inst *, SessionDevice *> _owned_devices;
672 map<const struct sr_dev_inst *, shared_ptr<Device> > _other_devices;
673 vector<DatafeedCallbackData *> _datafeed_callbacks;
674 SessionStoppedCallback _stopped_callback;
676 shared_ptr<Trigger> _trigger;
677 friend class Deleter;
678 friend class Context;
679 friend class DatafeedCallbackData;
680 friend class SessionDevice;
683 /** A packet on the session datafeed */
684 class SR_API Packet : public UserOwned<Packet, const struct sr_datafeed_packet>
687 /** Type of this packet. */
688 const PacketType *type();
689 /** Payload of this packet. */
690 shared_ptr<PacketPayload> payload();
692 Packet(shared_ptr<Device> device,
693 const struct sr_datafeed_packet *structure);
695 shared_ptr<Device> _device;
696 PacketPayload *_payload;
697 friend class Deleter;
698 friend class Session;
700 friend class DatafeedCallbackData;
705 friend class Context;
708 /** Abstract base class for datafeed packet payloads */
709 class SR_API PacketPayload
713 virtual ~PacketPayload() = 0;
714 virtual shared_ptr<PacketPayload> get_shared_pointer(Packet *parent) = 0;
715 /** Deleter needed to allow shared_ptr use with protected destructor. */
719 void operator()(PacketPayload *payload) { delete payload; }
721 friend class Deleter;
726 /** Payload of a datafeed header packet */
727 class SR_API Header :
728 public ParentOwned<Header, Packet, const struct sr_datafeed_header>,
732 /* Feed version number. */
734 /* Start time of this session. */
735 Glib::TimeVal start_time();
737 Header(const struct sr_datafeed_header *structure);
739 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
743 /** Payload of a datafeed metadata packet */
745 public ParentOwned<Meta, Packet, const struct sr_datafeed_meta>,
749 /* Mapping of (ConfigKey, value) pairs. */
750 map<const ConfigKey *, Glib::VariantBase> config();
752 Meta(const struct sr_datafeed_meta *structure);
754 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
755 map<const ConfigKey *, Glib::VariantBase> _config;
759 /** Payload of a datafeed packet with logic data */
761 public ParentOwned<Logic, Packet, const struct sr_datafeed_logic>,
765 /* Pointer to data. */
766 void *data_pointer();
767 /* Data length in bytes. */
768 size_t data_length();
769 /* Size of each sample in bytes. */
770 unsigned int unit_size();
772 Logic(const struct sr_datafeed_logic *structure);
774 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
778 /** Payload of a datafeed packet with analog data */
779 class SR_API Analog :
780 public ParentOwned<Analog, Packet, const struct sr_datafeed_analog>,
784 /** Pointer to data. */
785 void *data_pointer();
786 /** Number of samples in this packet. */
787 uint32_t num_samples();
788 /** Channels for which this packet contains data. */
789 vector<shared_ptr<Channel> > channels();
790 /** Measured quantity of the samples in this packet. */
791 const Quantity *mq();
792 /** Unit of the samples in this packet. */
794 /** Measurement flags associated with the samples in this packet. */
795 vector<const QuantityFlag *> mq_flags();
797 Analog(const struct sr_datafeed_analog *structure);
799 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
803 /** An input format supported by the library */
804 class SR_API InputFormat :
805 public ParentOwned<InputFormat, Context, const struct sr_input_module>
808 /** Name of this input format. */
810 /** Description of this input format. */
811 string description();
812 /** A list of preferred file name extensions for this file format.
813 * @note This list is a recommendation only. */
814 vector<string> extensions();
815 /** Options supported by this input format. */
816 map<string, shared_ptr<Option> > options();
817 /** Create an input using this input format.
818 * @param options Mapping of (option name, value) pairs. */
819 shared_ptr<Input> create_input(const map<string, Glib::VariantBase> &options = {});
821 InputFormat(const struct sr_input_module *structure);
823 friend class Context;
824 friend class InputDevice;
827 /** An input instance (an input format applied to a file or stream) */
828 class SR_API Input : public UserOwned<Input, const struct sr_input>
831 /** Virtual device associated with this input. */
832 shared_ptr<InputDevice> device();
833 /** Send next stream data.
834 * @param data Next stream data.
835 * @param length Length of data. */
836 void send(void *data, size_t length);
837 /** Signal end of input data. */
840 Input(shared_ptr<Context> context, const struct sr_input *structure);
842 shared_ptr<Context> _context;
843 InputDevice *_device;
844 friend class Deleter;
845 friend class Context;
846 friend class InputFormat;
849 /** A virtual device associated with an input */
850 class SR_API InputDevice :
851 public ParentOwned<InputDevice, Input, struct sr_dev_inst>,
855 InputDevice(shared_ptr<Input> input, struct sr_dev_inst *sdi);
857 shared_ptr<Device> get_shared_from_this();
858 shared_ptr<Input> _input;
862 /** An option used by an output format */
863 class SR_API Option : public UserOwned<Option, const struct sr_option>
866 /** Short name of this option suitable for command line usage. */
868 /** Short name of this option suitable for GUI usage. */
870 /** Description of this option in a sentence. */
871 string description();
872 /** Default value for this option. */
873 Glib::VariantBase default_value();
874 /** Possible values for this option, if a limited set. */
875 vector<Glib::VariantBase> values();
877 Option(const struct sr_option *structure,
878 shared_ptr<const struct sr_option *> structure_array);
880 shared_ptr<const struct sr_option *> _structure_array;
881 friend class Deleter;
882 friend class InputFormat;
883 friend class OutputFormat;
886 /** An output format supported by the library */
887 class SR_API OutputFormat :
888 public ParentOwned<OutputFormat, Context, const struct sr_output_module>
891 /** Name of this output format. */
893 /** Description of this output format. */
894 string description();
895 /** A list of preferred file name extensions for this file format.
896 * @note This list is a recommendation only. */
897 vector<string> extensions();
898 /** Options supported by this output format. */
899 map<string, shared_ptr<Option> > options();
900 /** Create an output using this format.
901 * @param device Device to output for.
902 * @param options Mapping of (option name, value) pairs. */
903 shared_ptr<Output> create_output(
904 shared_ptr<Device> device,
905 const map<string, Glib::VariantBase> &options = {});
906 /** Create an output using this format.
907 * @param filename Name of destination file.
908 * @param device Device to output for.
909 * @param options Mapping of (option name, value) pairs. */
910 shared_ptr<Output> create_output(string filename,
911 shared_ptr<Device> device,
912 const map<string, Glib::VariantBase> &options = {});
914 * Checks whether a given flag is set.
915 * @param flag Flag to check
916 * @return true if flag is set for this module
917 * @see sr_output_flags
919 bool test_flag(const OutputFlag *flag);
921 OutputFormat(const struct sr_output_module *structure);
923 friend class Context;
927 /** An output instance (an output format applied to a device) */
928 class SR_API Output : public UserOwned<Output, const struct sr_output>
931 /** Update output with data from the given packet.
932 * @param packet Packet to handle. */
933 string receive(shared_ptr<Packet> packet);
935 Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
936 Output(shared_ptr<OutputFormat> format,
937 shared_ptr<Device> device, const map<string, Glib::VariantBase> &options);
938 Output(string filename, shared_ptr<OutputFormat> format,
939 shared_ptr<Device> device, const map<string, Glib::VariantBase> &options);
941 const shared_ptr<OutputFormat> _format;
942 const shared_ptr<Device> _device;
943 const map<string, Glib::VariantBase> _options;
944 friend class Deleter;
945 friend class OutputFormat;
948 /** Base class for objects which wrap an enumeration value from libsigrok */
949 template <class Class, typename Enum> class SR_API EnumValue
952 /** The integer constant associated with this value. */
955 return static_cast<int>(_id);
957 /** The name associated with this value. */
962 /** Get value associated with a given integer constant. */
963 static const Class *get(int id)
965 auto key = static_cast<Enum>(id);
966 if (_values.find(key) == _values.end())
967 throw Error(SR_ERR_ARG);
968 return _values.at(key);
970 /** Get possible values. */
971 static std::vector<const Class *> values()
973 std::vector<const Class *> result;
974 for (auto entry : _values)
975 result.push_back(entry.second);
979 EnumValue(Enum id, const char name[]) : _id(id), _name(name)
985 static const std::map<const Enum, const Class * const> _values;
990 #include <libsigrokcxx/enums.hpp>