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/>.
23 #include "libsigrok/libsigrok.h"
24 #include <glibmm-2.4/glibmm.h>
36 /* Forward declarations */
41 class SR_API HardwareDevice;
43 class SR_API EventSource;
45 class SR_API ConfigKey;
46 class SR_API InputFormat;
47 class SR_API OutputFormat;
48 class SR_API LogLevel;
49 class SR_API ChannelGroup;
51 class SR_API TriggerStage;
52 class SR_API TriggerMatch;
53 class SR_API TriggerMatchType;
54 class SR_API ChannelType;
56 class SR_API PacketPayload;
57 class SR_API PacketType;
58 class SR_API Quantity;
60 class SR_API QuantityFlag;
61 class SR_API InputFileDevice;
63 class SR_API DataType;
65 /** Exception thrown when an error code is returned by any libsigrok call. */
66 class SR_API Error: public exception
72 const char *what() const throw();
75 /** Base template for most classes which wrap a struct type from libsigrok. */
76 template <class Parent, typename Struct> class SR_API StructureWrapper :
77 public enable_shared_from_this<StructureWrapper<Parent, Struct> >
80 /** Parent object which owns this child object's underlying structure.
82 This shared pointer will be null when this child is unused, but
83 will be assigned to point to the parent before any shared pointer
84 to this child is handed out to the user.
86 When the reference count of this child falls to zero, this shared
87 pointer to its parent is reset by a custom deleter on the child's
90 This strategy ensures that the destructors for both the child and
91 the parent are called at the correct time, i.e. only when all
92 references to both the parent and all its children are gone. */
93 shared_ptr<Parent> parent;
97 StructureWrapper<Parent, Struct>(Struct *structure) :
103 /** Type of log callback */
104 typedef function<void(const LogLevel *, string message)> LogCallbackFunction;
107 class SR_API Context : public enable_shared_from_this<Context>
110 /** Create new context */
111 static shared_ptr<Context> create();
112 /** libsigrok package version. */
113 string get_package_version();
114 /** libsigrok library version. */
115 string get_lib_version();
116 /** Available hardware drivers, indexed by name. */
117 map<string, shared_ptr<Driver> > get_drivers();
118 /** Available input formats, indexed by name. */
119 map<string, shared_ptr<InputFormat> > get_input_formats();
120 /** Available output formats, indexed by name. */
121 map<string, shared_ptr<OutputFormat> > get_output_formats();
122 /** Current log level. */
123 const LogLevel *get_log_level();
124 /** Set the log level. */
125 void set_log_level(const LogLevel *level);
126 /** Current log domain. */
127 string get_log_domain();
128 /** Set the log domain. */
129 void set_log_domain(string value);
130 /** Set the log callback. */
131 void set_log_callback(LogCallbackFunction callback);
132 /** Set the log callback to the default handler. */
133 void set_log_callback_default();
134 /** Create a new session. */
135 shared_ptr<Session> create_session();
136 /** Load a saved session. */
137 shared_ptr<Session> load_session(string filename);
138 /** Create a new trigger. */
139 shared_ptr<Trigger> create_trigger(string name);
141 struct sr_context *structure;
142 map<string, Driver *> drivers;
143 map<string, InputFormat *> input_formats;
144 map<string, OutputFormat *> output_formats;
146 LogCallbackFunction log_callback;
149 /** Deleter needed to allow shared_ptr use with protected destructor. */
153 void operator()(Context *context) { delete context; }
155 friend class Deleter;
156 friend class Session;
160 /** Hardware driver */
161 class SR_API Driver : public StructureWrapper<Context, struct sr_dev_driver>
164 /** Name of this driver. */
166 /** Long name for this driver. */
167 string get_long_name();
168 /** Scan for devices and return a list of devices found. */
169 vector<shared_ptr<HardwareDevice> > scan(
170 map<const ConfigKey *, Glib::VariantBase> options = {});
173 vector<HardwareDevice *> devices;
174 Driver(struct sr_dev_driver *structure);
176 friend class Context;
177 friend class HardwareDevice;
178 friend class ChannelGroup;
181 /** An object that can be configured. */
182 class SR_API Configurable
185 /** Read configuration for the given key. */
186 Glib::VariantBase config_get(const ConfigKey *key);
187 /** Set configuration for the given key to a specified value. */
188 void config_set(const ConfigKey *key, Glib::VariantBase value);
189 /** Enumerate available values for the given configuration key. */
190 Glib::VariantBase config_list(const ConfigKey *key);
193 struct sr_dev_driver *driver,
194 struct sr_dev_inst *sdi,
195 struct sr_channel_group *channel_group);
196 virtual ~Configurable();
197 struct sr_dev_driver *config_driver;
198 struct sr_dev_inst *config_sdi;
199 struct sr_channel_group *config_channel_group;
202 /** Generic device (may be real or from an input file) */
203 class SR_API Device :
205 public StructureWrapper<Context, struct sr_dev_inst>
208 /** Vendor name for this device. */
210 /** Model name for this device. */
212 /** Version string for this device. */
213 string get_version();
214 /** List of the channels available on this device. */
215 vector<shared_ptr<Channel> > get_channels();
221 Device(struct sr_dev_inst *structure);
223 vector<Channel *> channels;
224 /** Deleter needed to allow shared_ptr use with protected destructor. */
228 void operator()(Device *device) { delete device; }
230 friend class Deleter;
231 friend class Session;
232 friend class Channel;
233 friend class ChannelGroup;
237 /** Hardware device (connected via a driver) */
238 class SR_API HardwareDevice : public Device
241 /** Driver providing this device. */
242 shared_ptr<Driver> get_driver();
243 /** Channel groups available on this device, indexed by name. */
244 map<string, shared_ptr<ChannelGroup> > get_channel_groups();
246 HardwareDevice(Driver *driver, struct sr_dev_inst *structure);
249 map<string, ChannelGroup *> channel_groups;
251 friend class ChannelGroup;
255 class SR_API Channel : public StructureWrapper<Device, struct sr_channel>
258 /** Current name of this channel. */
260 /** Set the name of this channel. */
261 void set_name(string name);
262 /** Type of this channel. */
263 const ChannelType *get_type();
264 /** Enabled status of this channel. */
266 /** Set the enabled status of this channel. */
267 void set_enabled(bool value);
269 Channel(struct sr_channel *structure);
271 const ChannelType * const type;
273 friend class ChannelGroup;
274 friend class Session;
275 friend class TriggerStage;
279 class SR_API ChannelGroup :
280 public StructureWrapper<HardwareDevice, struct sr_channel_group>,
284 /** Name of this channel group. */
286 /** List of the channels in this group. */
287 vector<shared_ptr<Channel> > get_channels();
289 ChannelGroup(HardwareDevice *device, struct sr_channel_group *structure);
291 vector<Channel *> channels;
292 friend class HardwareDevice;
296 class SR_API Trigger : public enable_shared_from_this<Trigger>
300 vector<shared_ptr<TriggerStage> > get_stages();
301 shared_ptr<TriggerStage> add_stage();
303 Trigger(shared_ptr<Context> context, string name);
305 struct sr_trigger *structure;
306 shared_ptr<Context> context;
307 vector<TriggerStage *> stages;
308 /** Deleter needed to allow shared_ptr use with protected destructor. */
312 void operator()(Trigger *trigger) { delete trigger; }
314 friend class Context;
318 class SR_API TriggerStage : public StructureWrapper<Trigger, struct sr_trigger_stage>
322 vector<shared_ptr<TriggerMatch> > get_matches();
323 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type);
324 void add_match(shared_ptr<Channel> channel, const TriggerMatchType *type, float value);
326 vector<TriggerMatch *> matches;
327 TriggerStage(struct sr_trigger_stage *structure);
329 friend class Trigger;
333 class SR_API TriggerMatch : public StructureWrapper<TriggerStage, struct sr_trigger_match>
336 shared_ptr<Channel> get_channel();
337 const TriggerMatchType *get_type();
340 TriggerMatch(struct sr_trigger_match *structure, shared_ptr<Channel> channel);
342 shared_ptr<Channel> channel;
343 friend class TriggerStage;
346 /** Type of datafeed callback */
347 typedef function<void(shared_ptr<Device>, shared_ptr<Packet>)>
348 DatafeedCallbackFunction;
350 /** Data required for C callback function to call a C++ datafeed callback */
351 class SR_PRIV DatafeedCallbackData
354 void run(const struct sr_dev_inst *sdi,
355 const struct sr_datafeed_packet *pkt);
357 DatafeedCallbackFunction callback;
358 DatafeedCallbackData(Session *session,
359 DatafeedCallbackFunction callback);
361 friend class Session;
364 /** Type of source callback */
365 typedef function<bool(Glib::IOCondition)>
366 SourceCallbackFunction;
368 /** Data required for C callback function to call a C++ source callback */
369 class SR_PRIV SourceCallbackData
372 bool run(int revents);
374 SourceCallbackData(shared_ptr<EventSource> source);
375 shared_ptr<EventSource> source;
376 friend class Session;
380 class SR_API EventSource
383 /** Create an event source from a file descriptor. */
384 static shared_ptr<EventSource> create(int fd, Glib::IOCondition events,
385 int timeout, SourceCallbackFunction callback);
386 /** Create an event source from a Glib::PollFD */
387 static shared_ptr<EventSource> create(Glib::PollFD pollfd, int timeout,
388 SourceCallbackFunction callback);
389 /** Create an event source from a Glib::IOChannel */
390 static shared_ptr<EventSource> create(
391 Glib::RefPtr<Glib::IOChannel> channel, Glib::IOCondition events,
392 int timeout, SourceCallbackFunction callback);
394 EventSource(int timeout, SourceCallbackFunction callback);
403 Glib::RefPtr<Glib::IOChannel> channel;
404 Glib::IOCondition events;
406 SourceCallbackFunction callback;
407 /** Deleter needed to allow shared_ptr use with protected destructor. */
411 void operator()(EventSource *source) { delete source; }
413 friend class Deleter;
414 friend class Session;
415 friend class SourceCallbackData;
422 /** Add a device to this session. */
423 void add_device(shared_ptr<Device> device);
424 /** List devices attached to this session. */
425 vector<shared_ptr<Device> > get_devices();
426 /** Remove all devices from this session. */
427 void remove_devices();
428 /** Add a datafeed callback to this session. */
429 void add_datafeed_callback(DatafeedCallbackFunction callback);
430 /** Remove all datafeed callbacks from this session. */
431 void remove_datafeed_callbacks();
432 /** Add an event source. */
433 void add_source(shared_ptr<EventSource> source);
434 /** Remove an event source. */
435 void remove_source(shared_ptr<EventSource> source);
436 /** Start the session. */
438 /** Run the session event loop. */
440 /** Stop the session. */
442 /** Begin saving session to a file. */
443 void begin_save(string filename);
444 /** Append a packet to the session file being saved. */
445 void append(shared_ptr<Device> device, shared_ptr<Packet> packet);
447 Session(shared_ptr<Context> context);
448 Session(shared_ptr<Context> context, string filename);
450 struct sr_session *structure;
451 const shared_ptr<Context> context;
452 map<const struct sr_dev_inst *, shared_ptr<Device> > devices;
453 vector<DatafeedCallbackData *> datafeed_callbacks;
454 map<shared_ptr<EventSource>, SourceCallbackData *> source_callbacks;
456 bool save_initialized;
457 string save_filename;
458 uint64_t save_samplerate;
459 /** Deleter needed to allow shared_ptr use with protected destructor. */
463 void operator()(Session *session) { delete session; }
465 friend class Deleter;
466 friend class Context;
467 friend class DatafeedCallbackData;
470 /** Datafeed packet */
474 /** Payload of this packet. */
475 PacketPayload *get_payload();
477 Packet(const struct sr_datafeed_packet *structure);
479 const struct sr_datafeed_packet *structure;
480 PacketPayload *payload;
481 /** Deleter needed to allow shared_ptr use with protected destructor. */
485 void operator()(Packet *packet) { delete packet; }
487 friend class Deleter;
488 friend class Session;
490 friend class DatafeedCallbackData;
493 /** Abstract base class for datafeed packet payloads. */
494 class SR_API PacketPayload
498 virtual ~PacketPayload() = 0;
499 virtual void *get_data() = 0;
500 virtual size_t get_data_size() = 0;
505 /** Logic data payload */
506 class SR_API Logic : public PacketPayload
509 Logic(const struct sr_datafeed_logic *structure);
511 const struct sr_datafeed_logic *structure;
512 vector<uint8_t> data;
514 size_t get_data_size();
518 /** Analog data payload */
519 class SR_API Analog : public PacketPayload
522 /** Number of samples in this packet. */
523 unsigned int get_num_samples();
524 /** Measured quantity of the samples in this packet. */
525 const Quantity *get_mq();
526 /** Unit of the samples in this packet. */
527 const Unit *get_unit();
528 /** Measurement flags associated with the samples in this packet. */
529 vector<const QuantityFlag *> get_mq_flags();
531 Analog(const struct sr_datafeed_analog *structure);
533 const struct sr_datafeed_analog *structure;
535 size_t get_data_size();
540 class SR_API InputFormat :
541 public StructureWrapper<Context, struct sr_input_format>
544 /** Name of this input format. */
546 /** Description of this input format. */
547 string get_description();
548 /** Check whether a given file matches this input format. */
549 bool format_match(string filename);
550 /** Open a file using this input format. */
551 shared_ptr<InputFileDevice> open_file(string filename,
552 map<string, string> options = {});
554 InputFormat(struct sr_input_format *structure);
556 friend class Context;
557 friend class InputFileDevice;
560 /** Virtual device associated with an input file */
561 class SR_API InputFileDevice : public Device
564 /** Load data from file. */
567 InputFileDevice(shared_ptr<InputFormat> format,
568 struct sr_input *input, string filename);
570 struct sr_input *input;
571 shared_ptr<InputFormat> format;
573 /** Deleter needed to allow shared_ptr use with protected destructor. */
577 void operator()(InputFileDevice *device) { delete device; }
579 friend class Deleter;
580 friend class InputFormat;
584 class SR_API OutputFormat :
585 public StructureWrapper<Context, struct sr_output_format>
588 /** Name of this output format. */
590 /** Description of this output format. */
591 string get_description();
592 /** Create an output using this format. */
593 shared_ptr<Output> create_output(shared_ptr<Device> device, map<string, string> options = {});
595 OutputFormat(struct sr_output_format *structure);
597 friend class Context;
601 /** Output instance (an output format applied to a device) */
605 /** Update output with data from the given packet. */
606 string receive(shared_ptr<Packet> packet);
608 Output(shared_ptr<OutputFormat> format, shared_ptr<Device> device);
609 Output(shared_ptr<OutputFormat> format,
610 shared_ptr<Device> device, map<string, string> options);
612 struct sr_output *structure;
613 const shared_ptr<OutputFormat> format;
614 const shared_ptr<Device> device;
615 const map<string, string> options;
616 /** Deleter needed to allow shared_ptr use with protected destructor. */
620 void operator()(Output *output) { delete output; }
622 friend class Deleter;
623 friend class OutputFormat;
626 /** Base class for objects which wrap an enumeration value from libsigrok */
627 template <typename T> class SR_API EnumValue
630 /** The enum constant associated with this value. */
631 T get_id() const { return id; }
632 /** The name associated with this value. */
633 string get_name() const { return name; }
635 EnumValue(T id, const char name[]) : id(id), name(name) {}
645 #endif // LIBSIGROK_HPP