X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=bindings%2Fcxx%2Finclude%2Flibsigrok%2Flibsigrok.hpp;h=cc57d1a026cd3e470789873fc60a233188b6a578;hb=6e5240f418a8e021a8d1272b6255a8c0f10b5af6;hp=19323a527a0d937d45baef8559db17f94ebc8fe5;hpb=07443fd204f25639d38c87a42aa5eee137380fe9;p=libsigrok.git diff --git a/bindings/cxx/include/libsigrok/libsigrok.hpp b/bindings/cxx/include/libsigrok/libsigrok.hpp index 19323a52..cc57d1a0 100644 --- a/bindings/cxx/include/libsigrok/libsigrok.hpp +++ b/bindings/cxx/include/libsigrok/libsigrok.hpp @@ -108,9 +108,11 @@ class SR_API PacketType; class SR_API Quantity; class SR_API Unit; class SR_API QuantityFlag; -class SR_API InputFileDevice; +class SR_API Input; +class SR_API InputDevice; class SR_API Output; class SR_API DataType; +class SR_API Option; /** Exception thrown when an error code is returned by any libsigrok call. */ class SR_API Error: public exception @@ -126,7 +128,7 @@ public: template class SR_API StructureWrapper : public enable_shared_from_this > { -public: +protected: /* Parent object which owns this child object's underlying structure. This shared pointer will be null when this child is unused, but @@ -141,7 +143,28 @@ public: the parent are called at the correct time, i.e. only when all references to both the parent and all its children are gone. */ shared_ptr parent; + +public: + shared_ptr > + get_shared_pointer(Parent *parent) + { + this->parent = static_pointer_cast(parent->shared_from_this()); + return shared_ptr >( + this, reset_parent); + } + shared_ptr > + get_shared_pointer(shared_ptr parent) + { + this->parent = parent; + return shared_ptr >( + this, reset_parent); + } protected: + static void reset_parent(StructureWrapper *object) + { + object->parent.reset(); + } + Struct *structure; StructureWrapper(Struct *structure) : @@ -171,22 +194,33 @@ public: map > get_output_formats(); /** Current log level. */ const LogLevel *get_log_level(); - /** Set the log level. */ + /** Set the log level. + * @param level LogLevel to use. */ void set_log_level(const LogLevel *level); /** Current log domain. */ string get_log_domain(); - /** Set the log domain. */ + /** Set the log domain. + * @param value Log domain prefix string. */ void set_log_domain(string value); - /** Set the log callback. */ + /** Set the log callback. + * @param callback Callback of the form callback(LogLevel, string). */ void set_log_callback(LogCallbackFunction callback); /** Set the log callback to the default handler. */ void set_log_callback_default(); /** Create a new session. */ shared_ptr create_session(); - /** Load a saved session. */ + /** Load a saved session. + * @param filename File name string. */ shared_ptr load_session(string filename); - /** Create a new trigger. */ + /** Create a new trigger. + * @param name Name string for new trigger. */ shared_ptr create_trigger(string name); + /** Open an input file. + * @param filename File name string. */ + shared_ptr open_file(string filename); + /** Open an input stream based on header data. + * @param header Initial data from stream. */ + shared_ptr open_stream(string header); protected: struct sr_context *structure; map drivers; @@ -215,7 +249,8 @@ public: string get_name(); /** Long name for this driver. */ string get_long_name(); - /** Scan for devices and return a list of devices found. */ + /** Scan for devices and return a list of devices found. + * @param options Mapping of (ConfigKey, value) pairs. */ vector > scan( map options = {}); protected: @@ -232,12 +267,16 @@ protected: class SR_API Configurable { public: - /** Read configuration for the given key. */ + /** Read configuration for the given key. + * @param key ConfigKey to read. */ Glib::VariantBase config_get(const ConfigKey *key); - /** Set configuration for the given key to a specified value. */ + /** Set configuration for the given key to a specified value. + * @param key ConfigKey to set. + * @param value Value to set. */ void config_set(const ConfigKey *key, Glib::VariantBase value); - /** Enumerate available values for the given configuration key. */ - Glib::VariantBase config_list(const ConfigKey *key); + /** Enumerate available values for the given configuration key. + * @param key ConfigKey to enumerate values for. */ + Glib::VariantContainerBase config_list(const ConfigKey *key); protected: Configurable( struct sr_dev_driver *driver, @@ -251,10 +290,12 @@ protected: /** A generic device, either hardware or virtual */ class SR_API Device : - public Configurable, - public StructureWrapper + public enable_shared_from_this, + public Configurable { public: + /** Description identifying this device. */ + string get_description(); /** Vendor name for this device. */ string get_vendor(); /** Model name for this device. */ @@ -263,6 +304,8 @@ public: string get_version(); /** List of the channels available on this device. */ vector > get_channels(); + /** Channel groups available on this device, indexed by name. */ + map > get_channel_groups(); /** Open device. */ void open(); /** Close device. */ @@ -270,7 +313,10 @@ public: protected: Device(struct sr_dev_inst *structure); ~Device(); - vector channels; + shared_ptr get_channel(struct sr_channel *ptr); + struct sr_dev_inst *structure; + map channels; + map channel_groups; /** Deleter needed to allow shared_ptr use with protected destructor. */ class Deleter { @@ -282,21 +328,21 @@ protected: friend class Channel; friend class ChannelGroup; friend class Output; + friend class Analog; }; /** A real hardware device, connected via a driver */ -class SR_API HardwareDevice : public Device +class SR_API HardwareDevice : + public StructureWrapper, + public Device { public: /** Driver providing this device. */ shared_ptr get_driver(); - /** Channel groups available on this device, indexed by name. */ - map > get_channel_groups(); protected: HardwareDevice(Driver *driver, struct sr_dev_inst *structure); ~HardwareDevice(); Driver *driver; - map channel_groups; friend class Driver; friend class ChannelGroup; }; @@ -307,14 +353,18 @@ class SR_API Channel : public StructureWrapper public: /** Current name of this channel. */ string get_name(); - /** Set the name of this channel. */ + /** Set the name of this channel. * + * @param name Name string to set. */ void set_name(string name); /** Type of this channel. */ const ChannelType *get_type(); /** Enabled status of this channel. */ bool get_enabled(); - /** Set the enabled status of this channel. */ + /** Set the enabled status of this channel. + * @param value Boolean value to set. */ void set_enabled(bool value); + /** Get the index number of this channel. */ + unsigned int get_index(); protected: Channel(struct sr_channel *structure); ~Channel(); @@ -327,7 +377,7 @@ protected: /** A group of channels on a device, which share some configuration */ class SR_API ChannelGroup : - public StructureWrapper, + public StructureWrapper, public Configurable { public: @@ -336,18 +386,21 @@ public: /** List of the channels in this group. */ vector > get_channels(); protected: - ChannelGroup(HardwareDevice *device, struct sr_channel_group *structure); + ChannelGroup(Device *device, struct sr_channel_group *structure); ~ChannelGroup(); vector channels; - friend class HardwareDevice; + friend class Device; }; /** A trigger configuration */ class SR_API Trigger : public enable_shared_from_this { public: + /** Name of this trigger configuration. */ string get_name(); + /** List of the stages in this trigger. */ vector > get_stages(); + /** Add a new stage to this trigger. */ shared_ptr add_stage(); protected: Trigger(shared_ptr context, string name); @@ -369,9 +422,18 @@ protected: class SR_API TriggerStage : public StructureWrapper { public: + /** Index number of this stage. */ int get_number(); + /** List of match conditions on this stage. */ vector > get_matches(); + /** Add a new match condition to this stage. + * @param channel Channel to match on. + * @param type TriggerMatchType to apply. */ void add_match(shared_ptr channel, const TriggerMatchType *type); + /** Add a new match condition to this stage. + * @param channel Channel to match on. + * @param type TriggerMatchType to apply. + * @param value Threshold value. */ void add_match(shared_ptr channel, const TriggerMatchType *type, float value); protected: vector matches; @@ -384,8 +446,11 @@ protected: class SR_API TriggerMatch : public StructureWrapper { public: + /** Channel this condition matches on. */ shared_ptr get_channel(); + /** Type of match. */ const TriggerMatchType *get_type(); + /** Threshold value. */ float get_value(); protected: TriggerMatch(struct sr_trigger_match *structure, shared_ptr channel); @@ -431,13 +496,24 @@ protected: class SR_API EventSource { public: - /** Create an event source from a file descriptor. */ + /** Create an event source from a file descriptor. + * @param fd File descriptor. + * @param events GLib IOCondition event mask. + * @param timeout Timeout in milliseconds. + * @param callback Callback of the form callback(events) */ static shared_ptr create(int fd, Glib::IOCondition events, int timeout, SourceCallbackFunction callback); - /** Create an event source from a Glib::PollFD */ + /** Create an event source from a GLib PollFD + * @param pollfd GLib PollFD + * @param timeout Timeout in milliseconds. + * @param callback Callback of the form callback(events) */ static shared_ptr create(Glib::PollFD pollfd, int timeout, SourceCallbackFunction callback); - /** Create an event source from a Glib::IOChannel */ + /** Create an event source from a GLib IOChannel + * @param channel GLib IOChannel. + * @param events GLib IOCondition event mask. + * @param timeout Timeout in milliseconds. + * @param callback Callback of the form callback(events) */ static shared_ptr create( Glib::RefPtr channel, Glib::IOCondition events, int timeout, SourceCallbackFunction callback); @@ -470,19 +546,23 @@ protected: class SR_API Session { public: - /** Add a device to this session. */ + /** Add a device to this session. + * @param device Device to add. */ void add_device(shared_ptr device); /** List devices attached to this session. */ vector > get_devices(); /** Remove all devices from this session. */ void remove_devices(); - /** Add a datafeed callback to this session. */ + /** Add a datafeed callback to this session. + * @param callback Callback of the form callback(Device, Packet). */ void add_datafeed_callback(DatafeedCallbackFunction callback); /** Remove all datafeed callbacks from this session. */ void remove_datafeed_callbacks(); - /** Add an event source. */ + /** Add an I/O event source. + * @param source EventSource to add. */ void add_source(shared_ptr source); - /** Remove an event source. */ + /** Remove an event source. + * @param source EventSource to remove. */ void remove_source(shared_ptr source); /** Start the session. */ void start(); @@ -490,13 +570,18 @@ public: void run(); /** Stop the session. */ void stop(); - /** Begin saving session to a file. */ + /** Begin saving session to a file. + * @param filename File name string. */ void begin_save(string filename); - /** Append a packet to the session file being saved. */ - void append(shared_ptr device, shared_ptr packet); + /** Append a packet to the session file being saved. + * @param packet Packet to append. */ + void append(shared_ptr packet); + /** Append raw logic data to the session file being saved. */ + void append(void *data, size_t length, unsigned int unit_size); /** Get current trigger setting. */ shared_ptr get_trigger(); - /** Set trigger setting. */ + /** Set trigger setting. + * @param trigger Trigger object to use. */ void set_trigger(shared_ptr trigger); protected: Session(shared_ptr context); @@ -524,17 +609,19 @@ protected: }; /** A packet on the session datafeed */ -class SR_API Packet +class SR_API Packet : public enable_shared_from_this { public: /** Type of this packet. */ const PacketType *get_type(); /** Payload of this packet. */ - PacketPayload *get_payload(); + shared_ptr get_payload(); protected: - Packet(const struct sr_datafeed_packet *structure); + Packet(shared_ptr device, + const struct sr_datafeed_packet *structure); ~Packet(); const struct sr_datafeed_packet *structure; + shared_ptr device; PacketPayload *payload; /** Deleter needed to allow shared_ptr use with protected destructor. */ class Deleter @@ -546,6 +633,10 @@ protected: friend class Session; friend class Output; friend class DatafeedCallbackData; + friend class Header; + friend class Meta; + friend class Logic; + friend class Analog; }; /** Abstract base class for datafeed packet payloads */ @@ -554,31 +645,80 @@ class SR_API PacketPayload protected: PacketPayload(); virtual ~PacketPayload() = 0; - virtual void *get_data() = 0; - virtual size_t get_data_size() = 0; + shared_ptr get_shared_pointer(Packet *parent) { + return static_pointer_cast(get_shared_pointer(parent)); + } + /** Deleter needed to allow shared_ptr use with protected destructor. */ + class Deleter + { + public: + void operator()(PacketPayload *payload) { delete payload; } + }; + friend class Deleter; friend class Packet; friend class Output; }; +/** Payload of a datafeed header packet */ +class SR_API Header : public PacketPayload, + public StructureWrapper +{ +public: + /* Feed version number. */ + int get_feed_version(); + /* Start time of this session. */ + Glib::TimeVal get_start_time(); +protected: + Header(const struct sr_datafeed_header *structure); + ~Header(); + const struct sr_datafeed_header *structure; + friend class Packet; +}; + +/** Payload of a datafeed metadata packet */ +class SR_API Meta : public PacketPayload, + public StructureWrapper +{ +public: + /* Mapping of (ConfigKey, value) pairs. */ + map get_config(); +protected: + Meta(const struct sr_datafeed_meta *structure); + ~Meta(); + const struct sr_datafeed_meta *structure; + map config; + friend class Packet; +}; + /** Payload of a datafeed packet with logic data */ -class SR_API Logic : public PacketPayload +class SR_API Logic : public PacketPayload, + public StructureWrapper { +public: + /* Pointer to data. */ + void *get_data_pointer(); + /* Data length in bytes. */ + size_t get_data_length(); + /* Size of each sample in bytes. */ + unsigned int get_unit_size(); protected: Logic(const struct sr_datafeed_logic *structure); ~Logic(); const struct sr_datafeed_logic *structure; - vector data; - void *get_data(); - size_t get_data_size(); friend class Packet; }; /** Payload of a datafeed packet with analog data */ -class SR_API Analog : public PacketPayload +class SR_API Analog : public PacketPayload, + public StructureWrapper { public: + /** Pointer to data. */ + float *get_data_pointer(); /** Number of samples in this packet. */ unsigned int get_num_samples(); + /** Channels for which this packet contains data. */ + vector > get_channels(); /** Measured quantity of the samples in this packet. */ const Quantity *get_mq(); /** Unit of the samples in this packet. */ @@ -589,68 +729,123 @@ protected: Analog(const struct sr_datafeed_analog *structure); ~Analog(); const struct sr_datafeed_analog *structure; - void *get_data(); - size_t get_data_size(); friend class Packet; }; /** An input format supported by the library */ class SR_API InputFormat : - public StructureWrapper + public StructureWrapper { public: /** Name of this input format. */ string get_name(); /** Description of this input format. */ string get_description(); - /** Check whether a given file matches this input format. */ - bool format_match(string filename); - /** Open a file using this input format. */ - shared_ptr open_file(string filename, - map options = {}); + /** Options supported by this input format. */ + map > get_options(); + /** Create an input using this input format. + * @param options Mapping of (option name, value) pairs. */ + shared_ptr create_input(map options = {}); protected: - InputFormat(struct sr_input_format *structure); + InputFormat(const struct sr_input_module *structure); ~InputFormat(); friend class Context; - friend class InputFileDevice; + friend class InputDevice; }; -/** A virtual device associated with an input file */ -class SR_API InputFileDevice : public Device +/** An input instance (an input format applied to a file or stream) */ +class SR_API Input : public enable_shared_from_this { public: - /** Load data from file. */ - void load(); + /** Virtual device associated with this input. */ + shared_ptr get_device(); + /** Send next stream data. + * @param data Next stream data. */ + void send(string data); protected: - InputFileDevice(shared_ptr format, - struct sr_input *input, string filename); - ~InputFileDevice(); - struct sr_input *input; - shared_ptr format; - string filename; + Input(shared_ptr context, const struct sr_input *structure); + ~Input(); + const struct sr_input *structure; + shared_ptr context; + InputDevice *device; /** Deleter needed to allow shared_ptr use with protected destructor. */ class Deleter { public: - void operator()(InputFileDevice *device) { delete device; } + void operator()(Input *input) { delete input; } }; friend class Deleter; + friend class Context; friend class InputFormat; }; +/** A virtual device associated with an input */ +class SR_API InputDevice : + public StructureWrapper, + public Device +{ +protected: + InputDevice(shared_ptr input, struct sr_dev_inst *sdi); + ~InputDevice(); + shared_ptr input; + /** Deleter needed to allow shared_ptr use with protected destructor. */ + class Deleter + { + public: + void operator()(InputDevice *device) { delete device; } + }; + friend class Deleter; + friend class Input; +}; + +/** An option used by an output format */ +class SR_API Option +{ +public: + /** Short name of this option suitable for command line usage. */ + string get_id(); + /** Short name of this option suitable for GUI usage. */ + string get_name(); + /** Description of this option in a sentence. */ + string get_description(); + /** Default value for this option. */ + Glib::VariantBase get_default_value(); + /** Possible values for this option, if a limited set. */ + vector get_values(); +protected: + Option(const struct sr_option *structure, + shared_ptr structure_array); + ~Option(); + const struct sr_option *structure; + shared_ptr structure_array; + /** Deleter needed to allow shared_ptr use with protected destructor. */ + class Deleter + { + public: + void operator()(Option *option) { delete option; } + }; + friend class Deleter; + friend class OutputFormat; +}; + /** An output format supported by the library */ class SR_API OutputFormat : - public StructureWrapper + public StructureWrapper { public: /** Name of this output format. */ string get_name(); /** Description of this output format. */ string get_description(); - /** Create an output using this format. */ - shared_ptr create_output(shared_ptr device, map options = {}); + /** Options supported by this output format. */ + map > get_options(); + /** Create an output using this format. + * @param device Device to output for. + * @param options Mapping of (option name, value) pairs. */ + shared_ptr create_output(shared_ptr device, + map options = {}); protected: - OutputFormat(struct sr_output_format *structure); + OutputFormat(const struct sr_output_module *structure); ~OutputFormat(); friend class Context; friend class Output; @@ -660,17 +855,18 @@ protected: class SR_API Output { public: - /** Update output with data from the given packet. */ + /** Update output with data from the given packet. + * @param packet Packet to handle. */ string receive(shared_ptr packet); protected: Output(shared_ptr format, shared_ptr device); Output(shared_ptr format, - shared_ptr device, map options); + shared_ptr device, map options); ~Output(); - struct sr_output *structure; + const struct sr_output *structure; const shared_ptr format; const shared_ptr device; - const map options; + const map options; /** Deleter needed to allow shared_ptr use with protected destructor. */ class Deleter {