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;
94 class SR_API EventSource;
96 class SR_API ConfigKey;
97 class SR_API InputFormat;
98 class SR_API OutputFormat;
99 class SR_API OutputFlag;
100 class SR_API LogLevel;
101 class SR_API ChannelGroup;
102 class SR_API Trigger;
103 class SR_API TriggerStage;
104 class SR_API TriggerMatch;
105 class SR_API TriggerMatchType;
106 class SR_API ChannelType;
108 class SR_API PacketPayload;
109 class SR_API PacketType;
110 class SR_API Quantity;
112 class SR_API QuantityFlag;
114 class SR_API InputDevice;
116 class SR_API DataType;
118 class SR_API UserDevice;
120 /** Exception thrown when an error code is returned by any libsigrok call. */
121 class SR_API Error: public exception
127 const char *what() const throw();
130 /* Base template for classes whose resources are owned by a parent object. */
131 template <class Class, class Parent, typename Struct>
132 class SR_API ParentOwned
135 /* Parent object which owns this child object's underlying structure.
137 This shared pointer will be null when this child is unused, but
138 will be assigned to point to the parent before any shared pointer
139 to this child is handed out to the user.
141 When the reference count of this child falls to zero, this shared
142 pointer to its parent is reset by a custom deleter on the child's
145 This strategy ensures that the destructors for both the child and
146 the parent are called at the correct time, i.e. only when all
147 references to both the parent and all its children are gone. */
148 shared_ptr<Parent> _parent;
150 /* Weak pointer for shared_from_this() implementation. */
151 weak_ptr<Class> _weak_this;
154 /* Get parent object that owns this object. */
155 shared_ptr<Parent> parent()
160 /* Note, this implementation will create a new smart_ptr if none exists. */
161 shared_ptr<Class> shared_from_this()
163 shared_ptr<Class> shared;
165 if (!(shared = _weak_this.lock()))
167 shared = shared_ptr<Class>((Class *) this, reset_parent);
174 shared_ptr<Class> get_shared_pointer(shared_ptr<Parent> parent)
177 throw Error(SR_ERR_BUG);
178 this->_parent = parent;
179 return shared_from_this();
182 shared_ptr<Class> get_shared_pointer(Parent *parent)
185 throw Error(SR_ERR_BUG);
186 return get_shared_pointer(parent->shared_from_this());
189 static void reset_parent(Class *object)
191 if (!object->_parent)
192 throw Error(SR_ERR_BUG);
193 object->_parent.reset();
198 ParentOwned<Class, Parent, Struct>(Struct *structure) :
199 _structure(structure)
204 /* Base template for classes whose resources are owned by the user. */
205 template <class Class, typename Struct>
206 class SR_API UserOwned : public enable_shared_from_this<Class>
209 shared_ptr<Class> shared_from_this()
211 auto shared = enable_shared_from_this<Class>::shared_from_this();
213 throw Error(SR_ERR_BUG);
219 UserOwned<Class, Struct>(Struct *structure) :
220 _structure(structure)
224 /* Deleter needed to allow shared_ptr use with protected destructor. */
228 void operator()(Class *object) { delete object; }
232 /** Type of log callback */
233 typedef function<void(const LogLevel *, string message)> LogCallbackFunction;
235 /** The global libsigrok context */
236 class SR_API Context : public UserOwned<Context, struct sr_context>
239 /** Create new context */
240 static shared_ptr<Context> create();
241 /** libsigrok package version. */
242 string package_version();
243 /** libsigrok library version. */
244 string lib_version();
245 /** Available hardware drivers, indexed by name. */
246 map<string, shared_ptr<Driver> > drivers();
247 /** Available input formats, indexed by name. */
248 map<string, shared_ptr<InputFormat> > input_formats();
249 /** Available output formats, indexed by name. */
250 map<string, shared_ptr<OutputFormat> > output_formats();
251 /** Current log level. */
252 const LogLevel *log_level();
253 /** Set the log level.
254 * @param level LogLevel to use. */
255 void set_log_level(const LogLevel *level);
256 /** Set the log callback.
257 * @param callback Callback of the form callback(LogLevel, string). */
258 void set_log_callback(LogCallbackFunction callback);
259 /** Set the log callback to the default handler. */
260 void set_log_callback_default();
261 /** Create a new session. */
262 shared_ptr<Session> create_session();
263 /** Create a new user device. */
264 shared_ptr<UserDevice> create_user_device(
265 string vendor, string model, string version);
266 /** Create a header packet. */
267 shared_ptr<Packet> create_header_packet(Glib::TimeVal start_time);
268 /** Create a meta packet. */
269 shared_ptr<Packet> create_meta_packet(
270 map<const ConfigKey *, Glib::VariantBase> config);
271 /** Create a logic packet. */
272 shared_ptr<Packet> create_logic_packet(
273 void *data_pointer, size_t data_length, unsigned int unit_size);
274 /** Create an analog packet. */
275 shared_ptr<Packet> create_analog_packet(
276 vector<shared_ptr<Channel> > channels,
277 float *data_pointer, unsigned int num_samples, const Quantity *mq,
278 const Unit *unit, vector<const QuantityFlag *> mqflags);
279 /** Load a saved session.
280 * @param filename File name string. */
281 shared_ptr<Session> load_session(string filename);
282 /** Create a new trigger.
283 * @param name Name string for new trigger. */
284 shared_ptr<Trigger> create_trigger(string name);
285 /** Open an input file.
286 * @param filename File name string. */
287 shared_ptr<Input> open_file(string filename);
288 /** Open an input stream based on header data.
289 * @param header Initial data from stream. */
290 shared_ptr<Input> open_stream(string header);
291 map<string, string> serials(shared_ptr<Driver> driver);
293 map<string, Driver *> _drivers;
294 map<string, InputFormat *> _input_formats;
295 map<string, OutputFormat *> _output_formats;
297 LogCallbackFunction _log_callback;
300 friend class Deleter;
301 friend class Session;
311 /** An object that can be configured. */
312 class SR_API Configurable
315 /** Read configuration for the given key.
316 * @param key ConfigKey to read. */
317 Glib::VariantBase config_get(const ConfigKey *key);
318 /** Set configuration for the given key to a specified value.
319 * @param key ConfigKey to set.
320 * @param value Value to set. */
321 void config_set(const ConfigKey *key, Glib::VariantBase value);
322 /** Enumerate available values for the given configuration key.
323 * @param key ConfigKey to enumerate values for. */
324 Glib::VariantContainerBase config_list(const ConfigKey *key);
325 /** Enumerate available keys, according to a given index key. */
326 map<const ConfigKey *, set<Capability> > config_keys(const ConfigKey *key);
327 /** Check for a key in the list from a given index key. */
328 bool config_check(const ConfigKey *key, const ConfigKey *index_key);
331 struct sr_dev_driver *driver,
332 struct sr_dev_inst *sdi,
333 struct sr_channel_group *channel_group);
334 virtual ~Configurable();
335 struct sr_dev_driver *config_driver;
336 struct sr_dev_inst *config_sdi;
337 struct sr_channel_group *config_channel_group;
340 /** A hardware driver provided by the library */
341 class SR_API Driver :
342 public ParentOwned<Driver, Context, struct sr_dev_driver>,
346 /** Name of this driver. */
348 /** Long name for this driver. */
350 /** Scan for devices and return a list of devices found.
351 * @param options Mapping of (ConfigKey, value) pairs. */
352 vector<shared_ptr<HardwareDevice> > scan(
353 map<const ConfigKey *, Glib::VariantBase> options =
354 map<const ConfigKey *, Glib::VariantBase>());
357 vector<HardwareDevice *> _devices;
358 Driver(struct sr_dev_driver *structure);
360 friend class Context;
361 friend class HardwareDevice;
362 friend class ChannelGroup;
365 /** A generic device, either hardware or virtual */
366 class SR_API Device : public Configurable
369 /** Vendor name for this device. */
371 /** Model name for this device. */
373 /** Version string for this device. */
375 /** Serial number for this device. */
376 string serial_number();
377 /** Connection ID for this device. */
378 string connection_id();
379 /** List of the channels available on this device. */
380 vector<shared_ptr<Channel> > channels();
381 /** Channel groups available on this device, indexed by name. */
382 map<string, shared_ptr<ChannelGroup> > channel_groups();
388 Device(struct sr_dev_inst *structure);
390 virtual shared_ptr<Device> get_shared_from_this() = 0;
391 shared_ptr<Channel> get_channel(struct sr_channel *ptr);
392 struct sr_dev_inst *_structure;
393 map<struct sr_channel *, Channel *> _channels;
394 map<string, ChannelGroup *> _channel_groups;
395 /** Deleter needed to allow shared_ptr use with protected destructor. */
399 void operator()(Device *device) { delete device; }
401 friend class Deleter;
402 friend class Session;
403 friend class Channel;
404 friend class ChannelGroup;
409 /** A real hardware device, connected via a driver */
410 class SR_API HardwareDevice :
411 public UserOwned<HardwareDevice, struct sr_dev_inst>,
415 /** Driver providing this device. */
416 shared_ptr<Driver> driver();
418 HardwareDevice(shared_ptr<Driver> driver, struct sr_dev_inst *structure);
420 shared_ptr<Device> get_shared_from_this();
421 shared_ptr<Driver> _driver;
422 /** Deleter needed to allow shared_ptr use with protected destructor. */
426 void operator()(HardwareDevice *device) { delete device; }
428 friend class Deleter;
430 friend class ChannelGroup;
433 /** A virtual device, created by the user */
434 class SR_API UserDevice :
435 public UserOwned<UserDevice, struct sr_dev_inst>,
439 /** Add a new channel to this device. */
440 shared_ptr<Channel> add_channel(unsigned int index, const ChannelType *type, string name);
442 UserDevice(string vendor, string model, string version);
444 shared_ptr<Device> get_shared_from_this();
445 /** Deleter needed to allow shared_ptr use with protected destructor. */
449 void operator()(UserDevice *device) { delete device; }
451 friend class Context;
452 friend class Deleter;
455 /** A channel on a device */
456 class SR_API Channel :
457 public ParentOwned<Channel, Device, struct sr_channel>
460 /** Current name of this channel. */
462 /** Set the name of this channel. *
463 * @param name Name string to set. */
464 void set_name(string name);
465 /** Type of this channel. */
466 const ChannelType *type();
467 /** Enabled status of this channel. */
469 /** Set the enabled status of this channel.
470 * @param value Boolean value to set. */
471 void set_enabled(bool value);
472 /** Get the index number of this channel. */
473 unsigned int index();
475 Channel(struct sr_channel *structure);
477 const ChannelType * const _type;
479 friend class UserDevice;
480 friend class ChannelGroup;
481 friend class Session;
482 friend class TriggerStage;
483 friend class Context;
486 /** A group of channels on a device, which share some configuration */
487 class SR_API ChannelGroup :
488 public ParentOwned<ChannelGroup, Device, struct sr_channel_group>,
492 /** Name of this channel group. */
494 /** List of the channels in this group. */
495 vector<shared_ptr<Channel> > channels();
497 ChannelGroup(Device *device, struct sr_channel_group *structure);
499 vector<Channel *> _channels;
503 /** A trigger configuration */
504 class SR_API Trigger : public UserOwned<Trigger, struct sr_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 shared_ptr<Context> _context;
517 vector<TriggerStage *> _stages;
518 friend class Deleter;
519 friend class Context;
520 friend class Session;
523 /** A stage in a trigger configuration */
524 class SR_API TriggerStage :
525 public ParentOwned<TriggerStage, Trigger, struct sr_trigger_stage>
528 /** Index number of this stage. */
530 /** List of match conditions on this stage. */
531 vector<shared_ptr<TriggerMatch> > matches();
532 /** Add a new match condition to this stage.
533 * @param channel Channel to match on.
534 * @param type TriggerMatchType to apply. */
535 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type);
536 /** Add a new match condition to this stage.
537 * @param channel Channel to match on.
538 * @param type TriggerMatchType to apply.
539 * @param value Threshold value. */
540 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type, float value);
542 vector<TriggerMatch *> _matches;
543 TriggerStage(struct sr_trigger_stage *structure);
545 friend class Trigger;
548 /** A match condition in a trigger configuration */
549 class SR_API TriggerMatch :
550 public ParentOwned<TriggerMatch, TriggerStage, struct sr_trigger_match>
553 /** Channel this condition matches on. */
554 shared_ptr<Channel> channel();
555 /** Type of match. */
556 const TriggerMatchType *type();
557 /** Threshold value. */
560 TriggerMatch(struct sr_trigger_match *structure, shared_ptr<Channel> channel);
562 shared_ptr<Channel> _channel;
563 friend class TriggerStage;
566 /** Type of datafeed callback */
567 typedef function<void(shared_ptr<Device>, shared_ptr<Packet>)>
568 DatafeedCallbackFunction;
570 /* Data required for C callback function to call a C++ datafeed callback */
571 class SR_PRIV DatafeedCallbackData
574 void run(const struct sr_dev_inst *sdi,
575 const struct sr_datafeed_packet *pkt);
577 DatafeedCallbackFunction _callback;
578 DatafeedCallbackData(Session *session,
579 DatafeedCallbackFunction callback);
581 friend class Session;
584 /** Type of source callback */
585 typedef function<bool(Glib::IOCondition)>
586 SourceCallbackFunction;
588 /* Data required for C callback function to call a C++ source callback */
589 class SR_PRIV SourceCallbackData
592 bool run(int revents);
594 SourceCallbackData(shared_ptr<EventSource> source);
595 shared_ptr<EventSource> _source;
596 friend class Session;
599 /** An I/O event source */
600 class SR_API EventSource
603 /** Create an event source from a file descriptor.
604 * @param fd File descriptor.
605 * @param events GLib IOCondition event mask.
606 * @param timeout Timeout in milliseconds.
607 * @param callback Callback of the form callback(events) */
608 static shared_ptr<EventSource> create(int fd, Glib::IOCondition events,
609 int timeout, SourceCallbackFunction callback);
610 /** Create an event source from a GLib PollFD
611 * @param pollfd GLib PollFD
612 * @param timeout Timeout in milliseconds.
613 * @param callback Callback of the form callback(events) */
614 static shared_ptr<EventSource> create(Glib::PollFD pollfd, int timeout,
615 SourceCallbackFunction callback);
616 /** Create an event source from a GLib IOChannel
617 * @param channel GLib IOChannel.
618 * @param events GLib IOCondition event mask.
619 * @param timeout Timeout in milliseconds.
620 * @param callback Callback of the form callback(events) */
621 static shared_ptr<EventSource> create(
622 Glib::RefPtr<Glib::IOChannel> channel, Glib::IOCondition events,
623 int timeout, SourceCallbackFunction callback);
625 EventSource(int timeout, SourceCallbackFunction callback);
633 Glib::PollFD _pollfd;
634 Glib::RefPtr<Glib::IOChannel> _channel;
635 Glib::IOCondition _events;
637 SourceCallbackFunction _callback;
638 /** Deleter needed to allow shared_ptr use with protected destructor. */
642 void operator()(EventSource *source) { delete source; }
644 friend class Deleter;
645 friend class Session;
646 friend class SourceCallbackData;
649 /** A virtual device associated with a stored session */
650 class SR_API SessionDevice :
651 public ParentOwned<SessionDevice, Session, struct sr_dev_inst>,
655 SessionDevice(struct sr_dev_inst *sdi);
657 shared_ptr<Device> get_shared_from_this();
658 /** Deleter needed to allow shared_ptr use with protected destructor. */
662 void operator()(SessionDevice *device) { delete device; }
664 friend class Deleter;
665 friend class Session;
668 /** A sigrok session */
669 class SR_API Session : public UserOwned<Session, struct sr_session>
672 /** Add a device to this session.
673 * @param device Device to add. */
674 void add_device(shared_ptr<Device> device);
675 /** List devices attached to this session. */
676 vector<shared_ptr<Device> > devices();
677 /** Remove all devices from this session. */
678 void remove_devices();
679 /** Add a datafeed callback to this session.
680 * @param callback Callback of the form callback(Device, Packet). */
681 void add_datafeed_callback(DatafeedCallbackFunction callback);
682 /** Remove all datafeed callbacks from this session. */
683 void remove_datafeed_callbacks();
684 /** Add an I/O event source.
685 * @param source EventSource to add. */
686 void add_source(shared_ptr<EventSource> source);
687 /** Remove an event source.
688 * @param source EventSource to remove. */
689 void remove_source(shared_ptr<EventSource> source);
690 /** Start the session. */
692 /** Run the session event loop. */
694 /** Stop the session. */
696 /** Begin saving session to a file.
697 * @param filename File name string. */
698 void begin_save(string filename);
699 /** Get current trigger setting. */
700 shared_ptr<Trigger> trigger();
701 /** Get the context. */
702 shared_ptr<Context> context();
703 /** Set trigger setting.
704 * @param trigger Trigger object to use. */
705 void set_trigger(shared_ptr<Trigger> trigger);
706 /** Get filename this session was loaded from. */
709 Session(shared_ptr<Context> context);
710 Session(shared_ptr<Context> context, string filename);
712 shared_ptr<Device> get_device(const struct sr_dev_inst *sdi);
713 const shared_ptr<Context> _context;
714 map<const struct sr_dev_inst *, SessionDevice *> _owned_devices;
715 map<const struct sr_dev_inst *, shared_ptr<Device> > _other_devices;
716 vector<DatafeedCallbackData *> _datafeed_callbacks;
717 map<shared_ptr<EventSource>, SourceCallbackData *> _source_callbacks;
719 shared_ptr<Trigger> _trigger;
720 friend class Deleter;
721 friend class Context;
722 friend class DatafeedCallbackData;
723 friend class SessionDevice;
726 /** A packet on the session datafeed */
727 class SR_API Packet : public UserOwned<Packet, const struct sr_datafeed_packet>
730 /** Type of this packet. */
731 const PacketType *type();
732 /** Payload of this packet. */
733 shared_ptr<PacketPayload> payload();
735 Packet(shared_ptr<Device> device,
736 const struct sr_datafeed_packet *structure);
738 shared_ptr<Device> _device;
739 PacketPayload *_payload;
740 friend class Deleter;
741 friend class Session;
743 friend class DatafeedCallbackData;
748 friend class Context;
751 /** Abstract base class for datafeed packet payloads */
752 class SR_API PacketPayload
756 virtual ~PacketPayload() = 0;
757 virtual shared_ptr<PacketPayload> get_shared_pointer(Packet *parent) = 0;
758 /** Deleter needed to allow shared_ptr use with protected destructor. */
762 void operator()(PacketPayload *payload) { delete payload; }
764 friend class Deleter;
769 /** Payload of a datafeed header packet */
770 class SR_API Header :
771 public ParentOwned<Header, Packet, const struct sr_datafeed_header>,
775 /* Feed version number. */
777 /* Start time of this session. */
778 Glib::TimeVal start_time();
780 Header(const struct sr_datafeed_header *structure);
782 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
786 /** Payload of a datafeed metadata packet */
788 public ParentOwned<Meta, Packet, const struct sr_datafeed_meta>,
792 /* Mapping of (ConfigKey, value) pairs. */
793 map<const ConfigKey *, Glib::VariantBase> config();
795 Meta(const struct sr_datafeed_meta *structure);
797 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
798 map<const ConfigKey *, Glib::VariantBase> _config;
802 /** Payload of a datafeed packet with logic data */
804 public ParentOwned<Logic, Packet, const struct sr_datafeed_logic>,
808 /* Pointer to data. */
809 void *data_pointer();
810 /* Data length in bytes. */
811 size_t data_length();
812 /* Size of each sample in bytes. */
813 unsigned int unit_size();
815 Logic(const struct sr_datafeed_logic *structure);
817 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
821 /** Payload of a datafeed packet with analog data */
822 class SR_API Analog :
823 public ParentOwned<Analog, Packet, const struct sr_datafeed_analog>,
827 /** Pointer to data. */
828 float *data_pointer();
829 /** Number of samples in this packet. */
830 unsigned int num_samples();
831 /** Channels for which this packet contains data. */
832 vector<shared_ptr<Channel> > channels();
833 /** Measured quantity of the samples in this packet. */
834 const Quantity *mq();
835 /** Unit of the samples in this packet. */
837 /** Measurement flags associated with the samples in this packet. */
838 vector<const QuantityFlag *> mq_flags();
840 Analog(const struct sr_datafeed_analog *structure);
842 shared_ptr<PacketPayload> get_shared_pointer(Packet *parent);
846 /** An input format supported by the library */
847 class SR_API InputFormat :
848 public ParentOwned<InputFormat, Context, const struct sr_input_module>
851 /** Name of this input format. */
853 /** Description of this input format. */
854 string description();
855 /** A list of preferred file name extensions for this file format.
856 * @note This list is a recommendation only. */
857 vector<string> extensions();
858 /** Options supported by this input format. */
859 map<string, shared_ptr<Option> > options();
860 /** Create an input using this input format.
861 * @param options Mapping of (option name, value) pairs. */
862 shared_ptr<Input> create_input(map<string, Glib::VariantBase> options =
863 map<string, Glib::VariantBase>());
865 InputFormat(const struct sr_input_module *structure);
867 friend class Context;
868 friend class InputDevice;
871 /** An input instance (an input format applied to a file or stream) */
872 class SR_API Input : public UserOwned<Input, const struct sr_input>
875 /** Virtual device associated with this input. */
876 shared_ptr<InputDevice> device();
877 /** Send next stream data.
878 * @param data Next stream data.
879 * @param length Length of data. */
880 void send(void *data, size_t length);
881 /** Signal end of input data. */
884 Input(shared_ptr<Context> context, const struct sr_input *structure);
886 shared_ptr<Context> _context;
887 InputDevice *_device;
888 friend class Deleter;
889 friend class Context;
890 friend class InputFormat;
893 /** A virtual device associated with an input */
894 class SR_API InputDevice :
895 public ParentOwned<InputDevice, Input, struct sr_dev_inst>,
899 InputDevice(shared_ptr<Input> input, struct sr_dev_inst *sdi);
901 shared_ptr<Device> get_shared_from_this();
902 shared_ptr<Input> _input;
906 /** An option used by an output format */
907 class SR_API Option : public UserOwned<Option, const struct sr_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();
916 /** Default value for this option. */
917 Glib::VariantBase default_value();
918 /** Possible values for this option, if a limited set. */
919 vector<Glib::VariantBase> values();
921 Option(const struct sr_option *structure,
922 shared_ptr<const struct sr_option *> structure_array);
924 shared_ptr<const struct sr_option *> _structure_array;
925 friend class Deleter;
926 friend class InputFormat;
927 friend class OutputFormat;
930 /** An output format supported by the library */
931 class SR_API OutputFormat :
932 public ParentOwned<OutputFormat, Context, const struct sr_output_module>
935 /** Name of this output format. */
937 /** Description of this output format. */
938 string description();
939 /** A list of preferred file name extensions for this file format.
940 * @note This list is a recommendation only. */
941 vector<string> extensions();
942 /** Options supported by this output format. */
943 map<string, shared_ptr<Option> > options();
944 /** Create an output using this format.
945 * @param device Device to output for.
946 * @param options Mapping of (option name, value) pairs. */
947 shared_ptr<Output> create_output(
948 shared_ptr<Device> device,
949 map<string, Glib::VariantBase> options =
950 map<string, Glib::VariantBase>());
951 /** Create an output using this format.
952 * @param filename Name of destination file.
953 * @param device Device to output for.
954 * @param options Mapping of (option name, value) pairs. */
955 shared_ptr<Output> create_output(string filename,
956 shared_ptr<Device> device,
957 map<string, Glib::VariantBase> options =
958 map<string, Glib::VariantBase>());
960 * Checks whether a given flag is set.
961 * @param flag Flag to check
962 * @return true if flag is set for this module
963 * @see sr_output_flags
965 bool test_flag(const OutputFlag *flag);
967 OutputFormat(const struct sr_output_module *structure);
969 friend class Context;
973 /** An output instance (an output format applied to a device) */
974 class SR_API Output : public UserOwned<Output, const struct sr_output>
977 /** Update output with data from the given packet.
978 * @param packet Packet to handle. */
979 string receive(shared_ptr<Packet> packet);
981 Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
982 Output(shared_ptr<OutputFormat> format,
983 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
984 Output(string filename, shared_ptr<OutputFormat> format,
985 shared_ptr<Device> device, map<string, Glib::VariantBase> options);
987 const shared_ptr<OutputFormat> _format;
988 const shared_ptr<Device> _device;
989 const map<string, Glib::VariantBase> _options;
990 friend class Deleter;
991 friend class OutputFormat;
994 /** Base class for objects which wrap an enumeration value from libsigrok */
995 template <class Class, typename Enum> class SR_API EnumValue
998 /** The integer constant associated with this value. */
1001 return static_cast<int>(_id);
1003 /** The name associated with this value. */
1008 /** Get value associated with a given integer constant. */
1009 static const Class *get(int id)
1011 auto key = static_cast<Enum>(id);
1012 if (_values.find(key) == _values.end())
1013 throw Error(SR_ERR_ARG);
1014 return _values.at(key);
1016 /** Get possible values. */
1017 static std::vector<const Class *> values()
1019 std::vector<const Class *> result;
1020 for (auto entry : _values)
1021 result.push_back(entry.second);
1025 EnumValue(Enum id, const char name[]) : _id(id), _name(name)
1031 static const std::map<const Enum, const Class * const> _values;
1036 #include <libsigrokcxx/enums.hpp>