Add Doxyfile for C++ bindings and adaptations to C++ header file.
This commit is contained in:
parent
90ba83f21d
commit
07443fd204
File diff suppressed because it is too large
Load Diff
|
@ -17,6 +17,56 @@
|
|||
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
@mainpage API Reference
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
The sigrok++ API provides an object-oriented C++ interface to the functionality
|
||||
in libsigrok, including automatic memory and resource management.
|
||||
|
||||
It is built on top of the public libsigrok C API, and is designed to be used as
|
||||
a standalone alternative API. Programs should not mix usage of the C and C++
|
||||
APIs; the C++ interface code needs to have full control of all C API calls for
|
||||
resources to be managed correctly.
|
||||
|
||||
Memory management
|
||||
-----------------
|
||||
|
||||
All runtime objects created through the C++ API are passed and accessed via
|
||||
shared pointers, using the C++11 std::shared_ptr implementation. This means
|
||||
that a reference count is kept for each object.
|
||||
|
||||
Shared pointers can be copied and assigned in a user's program, automatically
|
||||
updating their reference count and deleting objects when they are no longer in
|
||||
use. The C++ interface code also keeps track of internal dependencies between
|
||||
libsigrok resources, and ensures that objects are not prematurely deleted when
|
||||
their resources are in use by other objects.
|
||||
|
||||
This means that management of sigrok++ objects and their underlying libsigrok
|
||||
resources can be treated as fully automatic. As long as all shared pointers to
|
||||
objects are deleted or reassigned when no longer in use, all underlying
|
||||
resources will be released at the right time.
|
||||
|
||||
Getting started
|
||||
---------------
|
||||
|
||||
Usage of the C++ API needs to begin with a call to sigrok::Context::create().
|
||||
This will create the global libsigrok context and returns a shared pointer to
|
||||
the sigrok::Context object. Methods on this object provide access to the
|
||||
hardware drivers, input and output formats supported by the library, as well
|
||||
as means of creating other objects such as sessions and triggers.
|
||||
|
||||
Error handling
|
||||
--------------
|
||||
|
||||
When any libsigrok C API call returns an error, a sigrok::Error exception is
|
||||
raised, which provides access to the error code and description.
|
||||
|
||||
*/
|
||||
|
||||
#ifndef LIBSIGROK_HPP
|
||||
#define LIBSIGROK_HPP
|
||||
|
||||
|
@ -72,12 +122,12 @@ public:
|
|||
const char *what() const throw();
|
||||
};
|
||||
|
||||
/** Base template for most classes which wrap a struct type from libsigrok. */
|
||||
/* Base template for most classes which wrap a struct type from libsigrok. */
|
||||
template <class Parent, typename Struct> class SR_API StructureWrapper :
|
||||
public enable_shared_from_this<StructureWrapper<Parent, Struct> >
|
||||
{
|
||||
public:
|
||||
/** Parent object which owns this child object's underlying structure.
|
||||
/* Parent object which owns this child object's underlying structure.
|
||||
|
||||
This shared pointer will be null when this child is unused, but
|
||||
will be assigned to point to the parent before any shared pointer
|
||||
|
@ -103,7 +153,7 @@ protected:
|
|||
/** Type of log callback */
|
||||
typedef function<void(const LogLevel *, string message)> LogCallbackFunction;
|
||||
|
||||
/** Context */
|
||||
/** The global libsigrok context */
|
||||
class SR_API Context : public enable_shared_from_this<Context>
|
||||
{
|
||||
public:
|
||||
|
@ -157,7 +207,7 @@ protected:
|
|||
friend class Driver;
|
||||
};
|
||||
|
||||
/** Hardware driver */
|
||||
/** A hardware driver provided by the library */
|
||||
class SR_API Driver : public StructureWrapper<Context, struct sr_dev_driver>
|
||||
{
|
||||
public:
|
||||
|
@ -199,7 +249,7 @@ protected:
|
|||
struct sr_channel_group *config_channel_group;
|
||||
};
|
||||
|
||||
/** Generic device (may be real or from an input file) */
|
||||
/** A generic device, either hardware or virtual */
|
||||
class SR_API Device :
|
||||
public Configurable,
|
||||
public StructureWrapper<Context, struct sr_dev_inst>
|
||||
|
@ -234,7 +284,7 @@ protected:
|
|||
friend class Output;
|
||||
};
|
||||
|
||||
/** Hardware device (connected via a driver) */
|
||||
/** A real hardware device, connected via a driver */
|
||||
class SR_API HardwareDevice : public Device
|
||||
{
|
||||
public:
|
||||
|
@ -251,7 +301,7 @@ protected:
|
|||
friend class ChannelGroup;
|
||||
};
|
||||
|
||||
/** Channel */
|
||||
/** A channel on a device */
|
||||
class SR_API Channel : public StructureWrapper<Device, struct sr_channel>
|
||||
{
|
||||
public:
|
||||
|
@ -275,7 +325,7 @@ protected:
|
|||
friend class TriggerStage;
|
||||
};
|
||||
|
||||
/** Channel group */
|
||||
/** A group of channels on a device, which share some configuration */
|
||||
class SR_API ChannelGroup :
|
||||
public StructureWrapper<HardwareDevice, struct sr_channel_group>,
|
||||
public Configurable
|
||||
|
@ -292,7 +342,7 @@ protected:
|
|||
friend class HardwareDevice;
|
||||
};
|
||||
|
||||
/** Trigger */
|
||||
/** A trigger configuration */
|
||||
class SR_API Trigger : public enable_shared_from_this<Trigger>
|
||||
{
|
||||
public:
|
||||
|
@ -315,7 +365,7 @@ protected:
|
|||
friend class Session;
|
||||
};
|
||||
|
||||
/** Trigger stage */
|
||||
/** A stage in a trigger configuration */
|
||||
class SR_API TriggerStage : public StructureWrapper<Trigger, struct sr_trigger_stage>
|
||||
{
|
||||
public:
|
||||
|
@ -330,7 +380,7 @@ protected:
|
|||
friend class Trigger;
|
||||
};
|
||||
|
||||
/** Trigger match */
|
||||
/** A match condition in a trigger configuration */
|
||||
class SR_API TriggerMatch : public StructureWrapper<TriggerStage, struct sr_trigger_match>
|
||||
{
|
||||
public:
|
||||
|
@ -348,7 +398,7 @@ protected:
|
|||
typedef function<void(shared_ptr<Device>, shared_ptr<Packet>)>
|
||||
DatafeedCallbackFunction;
|
||||
|
||||
/** Data required for C callback function to call a C++ datafeed callback */
|
||||
/* Data required for C callback function to call a C++ datafeed callback */
|
||||
class SR_PRIV DatafeedCallbackData
|
||||
{
|
||||
public:
|
||||
|
@ -366,7 +416,7 @@ protected:
|
|||
typedef function<bool(Glib::IOCondition)>
|
||||
SourceCallbackFunction;
|
||||
|
||||
/** Data required for C callback function to call a C++ source callback */
|
||||
/* Data required for C callback function to call a C++ source callback */
|
||||
class SR_PRIV SourceCallbackData
|
||||
{
|
||||
public:
|
||||
|
@ -377,7 +427,7 @@ protected:
|
|||
friend class Session;
|
||||
};
|
||||
|
||||
/** Event source. */
|
||||
/** An I/O event source */
|
||||
class SR_API EventSource
|
||||
{
|
||||
public:
|
||||
|
@ -416,7 +466,7 @@ protected:
|
|||
friend class SourceCallbackData;
|
||||
};
|
||||
|
||||
/** Session */
|
||||
/** A sigrok session */
|
||||
class SR_API Session
|
||||
{
|
||||
public:
|
||||
|
@ -473,7 +523,7 @@ protected:
|
|||
friend class DatafeedCallbackData;
|
||||
};
|
||||
|
||||
/** Datafeed packet */
|
||||
/** A packet on the session datafeed */
|
||||
class SR_API Packet
|
||||
{
|
||||
public:
|
||||
|
@ -498,7 +548,7 @@ protected:
|
|||
friend class DatafeedCallbackData;
|
||||
};
|
||||
|
||||
/** Abstract base class for datafeed packet payloads. */
|
||||
/** Abstract base class for datafeed packet payloads */
|
||||
class SR_API PacketPayload
|
||||
{
|
||||
protected:
|
||||
|
@ -510,7 +560,7 @@ protected:
|
|||
friend class Output;
|
||||
};
|
||||
|
||||
/** Logic data payload */
|
||||
/** Payload of a datafeed packet with logic data */
|
||||
class SR_API Logic : public PacketPayload
|
||||
{
|
||||
protected:
|
||||
|
@ -523,7 +573,7 @@ protected:
|
|||
friend class Packet;
|
||||
};
|
||||
|
||||
/** Analog data payload */
|
||||
/** Payload of a datafeed packet with analog data */
|
||||
class SR_API Analog : public PacketPayload
|
||||
{
|
||||
public:
|
||||
|
@ -544,7 +594,7 @@ protected:
|
|||
friend class Packet;
|
||||
};
|
||||
|
||||
/** Input format */
|
||||
/** An input format supported by the library */
|
||||
class SR_API InputFormat :
|
||||
public StructureWrapper<Context, struct sr_input_format>
|
||||
{
|
||||
|
@ -565,7 +615,7 @@ protected:
|
|||
friend class InputFileDevice;
|
||||
};
|
||||
|
||||
/** Virtual device associated with an input file */
|
||||
/** A virtual device associated with an input file */
|
||||
class SR_API InputFileDevice : public Device
|
||||
{
|
||||
public:
|
||||
|
@ -588,7 +638,7 @@ protected:
|
|||
friend class InputFormat;
|
||||
};
|
||||
|
||||
/** Output format */
|
||||
/** An output format supported by the library */
|
||||
class SR_API OutputFormat :
|
||||
public StructureWrapper<Context, struct sr_output_format>
|
||||
{
|
||||
|
@ -606,7 +656,7 @@ protected:
|
|||
friend class Output;
|
||||
};
|
||||
|
||||
/** Output instance (an output format applied to a device) */
|
||||
/** An output instance (an output format applied to a device) */
|
||||
class SR_API Output
|
||||
{
|
||||
public:
|
||||
|
|
Loading…
Reference in New Issue