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>((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 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 vector<shared_ptr<Channel> > channels,
302 float *data_pointer, unsigned int num_samples, const Quantity *mq,
303 const Unit *unit, 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, 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 map<const ConfigKey *, Glib::VariantBase> options =
379 map<const ConfigKey *, Glib::VariantBase>());
382 vector<HardwareDevice *> _devices;
383 Driver(struct sr_dev_driver *structure);
385 friend class Context;
386 friend class HardwareDevice;
387 friend class ChannelGroup;
390 /** A generic device, either hardware or virtual */
391 class SR_API Device : public Configurable
394 /** Vendor name for this device. */
396 /** Model name for this device. */
398 /** Version string for this device. */
400 /** Serial number for this device. */
401 string serial_number();
402 /** Connection ID for this device. */
403 string connection_id();
404 /** List of the channels available on this device. */
405 vector<shared_ptr<Channel> > channels();
406 /** Channel groups available on this device, indexed by name. */
407 map<string, shared_ptr<ChannelGroup> > channel_groups();
413 Device(struct sr_dev_inst *structure);
415 virtual shared_ptr<Device> get_shared_from_this() = 0;
416 shared_ptr<Channel> get_channel(struct sr_channel *ptr);
417 struct sr_dev_inst *_structure;
418 map<struct sr_channel *, Channel *> _channels;
419 map<string, ChannelGroup *> _channel_groups;
420 /** Deleter needed to allow shared_ptr use with protected destructor. */
424 void operator()(Device *device) { delete device; }
426 friend class Deleter;
427 friend class Session;
428 friend class Channel;
429 friend class ChannelGroup;
434 /** A real hardware device, connected via a driver */
435 class SR_API HardwareDevice :
436 public UserOwned<HardwareDevice, struct sr_dev_inst>,
440 /** Driver providing this device. */
441 shared_ptr<Driver> driver();
443 HardwareDevice(shared_ptr<Driver> driver, struct sr_dev_inst *structure);
445 shared_ptr<Device> get_shared_from_this();
446 shared_ptr<Driver> _driver;
447 /** Deleter needed to allow shared_ptr use with protected destructor. */
451 void operator()(HardwareDevice *device) { delete device; }
453 friend class Deleter;
455 friend class ChannelGroup;
458 /** A virtual device, created by the user */
459 class SR_API UserDevice :
460 public UserOwned<UserDevice, struct sr_dev_inst>,
464 /** Add a new channel to this device. */
465 shared_ptr<Channel> add_channel(unsigned int index, const ChannelType *type, string name);
467 UserDevice(string vendor, string model, string version);
469 shared_ptr<Device> get_shared_from_this();
470 /** Deleter needed to allow shared_ptr use with protected destructor. */
474 void operator()(UserDevice *device) { delete device; }
476 friend class Context;
477 friend class Deleter;
480 /** A channel on a device */
481 class SR_API Channel :
482 public ParentOwned<Channel, Device, struct sr_channel>
485 /** Current name of this channel. */
487 /** Set the name of this channel. *
488 * @param name Name string to set. */
489 void set_name(string name);
490 /** Type of this channel. */
491 const ChannelType *type();
492 /** Enabled status of this channel. */
494 /** Set the enabled status of this channel.
495 * @param value Boolean value to set. */
496 void set_enabled(bool value);
497 /** Get the index number of this channel. */
498 unsigned int index();
500 Channel(struct sr_channel *structure);
502 const ChannelType * const _type;
504 friend class UserDevice;
505 friend class ChannelGroup;
506 friend class Session;
507 friend class TriggerStage;
508 friend class Context;
511 /** A group of channels on a device, which share some configuration */
512 class SR_API ChannelGroup :
513 public ParentOwned<ChannelGroup, Device, struct sr_channel_group>,
517 /** Name of this channel group. */
519 /** List of the channels in this group. */
520 vector<shared_ptr<Channel> > channels();
522 ChannelGroup(Device *device, struct sr_channel_group *structure);
524 vector<Channel *> _channels;
528 /** A trigger configuration */
529 class SR_API Trigger : public UserOwned<Trigger, struct sr_trigger>
532 /** Name of this trigger configuration. */
534 /** List of the stages in this trigger. */
535 vector<shared_ptr<TriggerStage> > stages();
536 /** Add a new stage to this trigger. */
537 shared_ptr<TriggerStage> add_stage();
539 Trigger(shared_ptr<Context> context, string name);
541 shared_ptr<Context> _context;
542 vector<TriggerStage *> _stages;
543 friend class Deleter;
544 friend class Context;
545 friend class Session;
548 /** A stage in a trigger configuration */
549 class SR_API TriggerStage :
550 public ParentOwned<TriggerStage, Trigger, struct sr_trigger_stage>
553 /** Index number of this stage. */
555 /** List of match conditions on this stage. */
556 vector<shared_ptr<TriggerMatch> > matches();
557 /** Add a new match condition to this stage.
558 * @param channel Channel to match on.
559 * @param type TriggerMatchType to apply. */
560 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type);
561 /** Add a new match condition to this stage.
562 * @param channel Channel to match on.
563 * @param type TriggerMatchType to apply.
564 * @param value Threshold value. */
565 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type, float value);
567 vector<TriggerMatch *> _matches;
568 TriggerStage(struct sr_trigger_stage *structure);
570 friend class Trigger;
573 /** A match condition in a trigger configuration */
574 class SR_API TriggerMatch :
575 public ParentOwned<TriggerMatch, TriggerStage, struct sr_trigger_match>
578 /** Channel this condition matches on. */
579 shared_ptr<Channel> channel();
580 /** Type of match. */
581 const TriggerMatchType *type();
582 /** Threshold value. */
585 TriggerMatch(struct sr_trigger_match *structure, shared_ptr<Channel> channel);
587 shared_ptr<Channel> _channel;
588 friend class TriggerStage;
591 /** Type of session stopped callback */
592 typedef function<void()> SessionStoppedCallback;
594 /** Type of datafeed callback */
595 typedef function<void(shared_ptr<Device>, shared_ptr<Packet>)>
596 DatafeedCallbackFunction;
598 /* Data required for C callback function to call a C++ datafeed callback */
599 class SR_PRIV DatafeedCallbackData
602 void run(const struct sr_dev_inst *sdi,
603 const struct sr_datafeed_packet *pkt);
605 DatafeedCallbackFunction _callback;
606 DatafeedCallbackData(Session *session,
607 DatafeedCallbackFunction callback);
609 friend class Session;
612 /** A virtual device associated with a stored session */
613 class SR_API SessionDevice :
614 public ParentOwned<SessionDevice, Session, struct sr_dev_inst>,
618 SessionDevice(struct sr_dev_inst *sdi);
620 shared_ptr<Device> get_shared_from_this();
621 /** Deleter needed to allow shared_ptr use with protected destructor. */
625 void operator()(SessionDevice *device) { delete device; }
627 friend class Deleter;
628 friend class Session;
631 /** A sigrok session */
632 class SR_API Session : public UserOwned<Session, struct sr_session>
635 /** Add a device to this session.
636 * @param device Device to add. */
637 void add_device(shared_ptr<Device> device);
638 /** List devices attached to this session. */
639 vector<shared_ptr<Device> > devices();
640 /** Remove all devices from this session. */
641 void remove_devices();
642 /** Add a datafeed callback to this session.
643 * @param callback Callback of the form callback(Device, Packet). */
644 void add_datafeed_callback(DatafeedCallbackFunction callback);
645 /** Remove all datafeed callbacks from this session. */
646 void remove_datafeed_callbacks();
647 /** Start the session. */
649 /** Run the session event loop. */
651 /** Stop the session. */
653 /** Return whether the session is running. */
654 bool is_running() const;
655 /** Set callback to be invoked on session stop. */
656 void set_stopped_callback(SessionStoppedCallback callback);
657 /** Get current trigger setting. */
658 shared_ptr<Trigger> trigger();
659 /** Get the context. */
660 shared_ptr<Context> context();
661 /** Set trigger setting.
662 * @param trigger Trigger object to use. */
663 void set_trigger(shared_ptr<Trigger> trigger);
664 /** Get filename this session was loaded from. */
667 Session(shared_ptr<Context> context);
668 Session(shared_ptr<Context> context, string filename);
670 shared_ptr<Device> get_device(const struct sr_dev_inst *sdi);
671 const shared_ptr<Context> _context;
672 map<const struct sr_dev_inst *, SessionDevice *> _owned_devices;
673 map<const struct sr_dev_inst *, shared_ptr<Device> > _other_devices;
674 vector<DatafeedCallbackData *> _datafeed_callbacks;
675 SessionStoppedCallback _stopped_callback;
677 shared_ptr<Trigger> _trigger;
678 friend class Deleter;
679 friend class Context;
680 friend class DatafeedCallbackData;
681 friend class SessionDevice;
684 /** A packet on the session datafeed */
685 class SR_API Packet : public UserOwned<Packet, const struct sr_datafeed_packet>
688 /** Type of this packet. */
689 const PacketType *type();
690 /** Payload of this packet. */
691 shared_ptr<PacketPayload> payload();
693 Packet(shared_ptr<Device> device,
694 const struct sr_datafeed_packet *structure);
696 shared_ptr<Device> _device;
697 PacketPayload *_payload;
698 friend class Deleter;
699 friend class Session;
701 friend class DatafeedCallbackData;
706 friend class Context;
709 /** Abstract base class for datafeed packet payloads */
710 class SR_API PacketPayload
714 virtual ~PacketPayload() = 0;
715 virtual shared_ptr<PacketPayload> get_shared_pointer(Packet *parent) = 0;
716 /** Deleter needed to allow shared_ptr use with protected destructor. */
720 void operator()(PacketPayload *payload) { delete payload; }
722 friend class Deleter;
727 /** Payload of a datafeed header packet */
728 class SR_API Header :
729 public ParentOwned<Header, Packet, const struct sr_datafeed_header>,
733 /* Feed version number. */
735 /* Start time of this session. */
736 Glib::TimeVal start_time();
738 Header(const struct sr_datafeed_header *structure);
740 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
744 /** Payload of a datafeed metadata packet */
746 public ParentOwned<Meta, Packet, const struct sr_datafeed_meta>,
750 /* Mapping of (ConfigKey, value) pairs. */
751 map<const ConfigKey *, Glib::VariantBase> config();
753 Meta(const struct sr_datafeed_meta *structure);
755 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
756 map<const ConfigKey *, Glib::VariantBase> _config;
760 /** Payload of a datafeed packet with logic data */
762 public ParentOwned<Logic, Packet, const struct sr_datafeed_logic>,
766 /* Pointer to data. */
767 void *data_pointer();
768 /* Data length in bytes. */
769 size_t data_length();
770 /* Size of each sample in bytes. */
771 unsigned int unit_size();
773 Logic(const struct sr_datafeed_logic *structure);
775 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
779 /** Payload of a datafeed packet with analog data */
780 class SR_API Analog :
781 public ParentOwned<Analog, Packet, const struct sr_datafeed_analog>,
785 /** Pointer to data. */
786 void *data_pointer();
787 /** Number of samples in this packet. */
788 uint32_t num_samples();
789 /** Channels for which this packet contains data. */
790 vector<shared_ptr<Channel> > channels();
791 /** Measured quantity of the samples in this packet. */
792 const Quantity *mq();
793 /** Unit of the samples in this packet. */
795 /** Measurement flags associated with the samples in this packet. */
796 vector<const QuantityFlag *> mq_flags();
798 Analog(const struct sr_datafeed_analog *structure);
800 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
804 /** An input format supported by the library */
805 class SR_API InputFormat :
806 public ParentOwned<InputFormat, Context, const struct sr_input_module>
809 /** Name of this input format. */
811 /** Description of this input format. */
812 string description();
813 /** A list of preferred file name extensions for this file format.
814 * @note This list is a recommendation only. */
815 vector<string> extensions();
816 /** Options supported by this input format. */
817 map<string, shared_ptr<Option> > options();
818 /** Create an input using this input format.
819 * @param options Mapping of (option name, value) pairs. */
820 shared_ptr<Input> create_input(map<string, Glib::VariantBase> options =
821 map<string, Glib::VariantBase>());
823 InputFormat(const struct sr_input_module *structure);
825 friend class Context;
826 friend class InputDevice;
829 /** An input instance (an input format applied to a file or stream) */
830 class SR_API Input : public UserOwned<Input, const struct sr_input>
833 /** Virtual device associated with this input. */
834 shared_ptr<InputDevice> device();
835 /** Send next stream data.
836 * @param data Next stream data.
837 * @param length Length of data. */
838 void send(void *data, size_t length);
839 /** Signal end of input data. */
842 Input(shared_ptr<Context> context, const struct sr_input *structure);
844 shared_ptr<Context> _context;
845 InputDevice *_device;
846 friend class Deleter;
847 friend class Context;
848 friend class InputFormat;
851 /** A virtual device associated with an input */
852 class SR_API InputDevice :
853 public ParentOwned<InputDevice, Input, struct sr_dev_inst>,
857 InputDevice(shared_ptr<Input> input, struct sr_dev_inst *sdi);
859 shared_ptr<Device> get_shared_from_this();
860 shared_ptr<Input> _input;
864 /** An option used by an output format */
865 class SR_API Option : public UserOwned<Option, const struct sr_option>
868 /** Short name of this option suitable for command line usage. */
870 /** Short name of this option suitable for GUI usage. */
872 /** Description of this option in a sentence. */
873 string description();
874 /** Default value for this option. */
875 Glib::VariantBase default_value();
876 /** Possible values for this option, if a limited set. */
877 vector<Glib::VariantBase> values();
879 Option(const struct sr_option *structure,
880 shared_ptr<const struct sr_option *> structure_array);
882 shared_ptr<const struct sr_option *> _structure_array;
883 friend class Deleter;
884 friend class InputFormat;
885 friend class OutputFormat;
888 /** An output format supported by the library */
889 class SR_API OutputFormat :
890 public ParentOwned<OutputFormat, Context, const struct sr_output_module>
893 /** Name of this output format. */
895 /** Description of this output format. */
896 string description();
897 /** A list of preferred file name extensions for this file format.
898 * @note This list is a recommendation only. */
899 vector<string> extensions();
900 /** Options supported by this output format. */
901 map<string, shared_ptr<Option> > options();
902 /** Create an output using this format.
903 * @param device Device to output for.
904 * @param options Mapping of (option name, value) pairs. */
905 shared_ptr<Output> create_output(
906 shared_ptr<Device> device,
907 map<string, Glib::VariantBase> options =
908 map<string, Glib::VariantBase>());
909 /** Create an output using this format.
910 * @param filename Name of destination file.
911 * @param device Device to output for.
912 * @param options Mapping of (option name, value) pairs. */
913 shared_ptr<Output> create_output(string filename,
914 shared_ptr<Device> device,
915 map<string, Glib::VariantBase> options =
916 map<string, Glib::VariantBase>());
918 * Checks whether a given flag is set.
919 * @param flag Flag to check
920 * @return true if flag is set for this module
921 * @see sr_output_flags
923 bool test_flag(const OutputFlag *flag);
925 OutputFormat(const struct sr_output_module *structure);
927 friend class Context;
931 /** An output instance (an output format applied to a device) */
932 class SR_API Output : public UserOwned<Output, const struct sr_output>
935 /** Update output with data from the given packet.
936 * @param packet Packet to handle. */
937 string receive(shared_ptr<Packet> packet);
939 Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
940 Output(shared_ptr<OutputFormat> format,
941 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
942 Output(string filename, shared_ptr<OutputFormat> format,
943 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
945 const shared_ptr<OutputFormat> _format;
946 const shared_ptr<Device> _device;
947 const map<string, Glib::VariantBase> _options;
948 friend class Deleter;
949 friend class OutputFormat;
952 /** Base class for objects which wrap an enumeration value from libsigrok */
953 template <class Class, typename Enum> class SR_API EnumValue
956 /** The integer constant associated with this value. */
959 return static_cast<int>(_id);
961 /** The name associated with this value. */
966 /** Get value associated with a given integer constant. */
967 static const Class *get(int id)
969 auto key = static_cast<Enum>(id);
970 if (_values.find(key) == _values.end())
971 throw Error(SR_ERR_ARG);
972 return _values.at(key);
974 /** Get possible values. */
975 static std::vector<const Class *> values()
977 std::vector<const Class *> result;
978 for (auto entry : _values)
979 result.push_back(entry.second);
983 EnumValue(Enum id, const char name[]) : _id(id), _name(name)
989 static const std::map<const Enum, const Class * const> _values;
994 #include <libsigrokcxx/enums.hpp>