X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=bindings%2Fcxx%2Finclude%2Flibsigrok%2Flibsigrok.hpp;h=ad683218a384820766be27d5ee6e74b9affc199d;hb=70d3b20ba6189093c3a18473b3376644683f729d;hp=5435b83e0d24f4a9b516e122e800ffa851176af3;hpb=06bd935e161dd273788ce9f1b455732fb91efd84;p=libsigrok.git diff --git a/bindings/cxx/include/libsigrok/libsigrok.hpp b/bindings/cxx/include/libsigrok/libsigrok.hpp index 5435b83e..ad683218 100644 --- a/bindings/cxx/include/libsigrok/libsigrok.hpp +++ b/bindings/cxx/include/libsigrok/libsigrok.hpp @@ -111,6 +111,7 @@ class SR_API QuantityFlag; class SR_API InputFileDevice; 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 @@ -192,21 +193,26 @@ 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); protected: struct sr_context *structure; @@ -236,7 +242,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: @@ -253,11 +260,15 @@ 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. */ + /** Enumerate available values for the given configuration key. + * @param key ConfigKey to enumerate values for. */ Glib::VariantContainerBase config_list(const ConfigKey *key); protected: Configurable( @@ -332,13 +343,15 @@ 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(); @@ -373,8 +386,11 @@ protected: 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); @@ -396,9 +412,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; @@ -411,8 +436,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); @@ -458,13 +486,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); @@ -497,19 +536,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(); @@ -517,15 +560,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. */ + /** 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); @@ -608,7 +654,9 @@ 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); @@ -622,6 +670,7 @@ 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); @@ -682,9 +731,12 @@ public: string get_name(); /** Description of this input format. */ string get_description(); - /** Check whether a given file matches this input format. */ + /** Check whether a given file matches this input format. + * @param filename File name string. */ bool format_match(string filename); - /** Open a file using this input format. */ + /** Open a file using this input format. + * @param filename File name string. + * @param options Mapping of (option name, value) strings. */ shared_ptr open_file(string filename, map options = {}); protected: @@ -717,19 +769,54 @@ protected: friend class InputFormat; }; +/** 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; @@ -739,17 +826,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 {