/** @endcond */, so that Doxygen doesn't include them in the output.
Variables that are "static" don't need to be marked like this.
+ - Mark all public API functions (SR_API) with a @since tag which indicates
+ in which release the respective function was added. If the function has
+ existed before, but its API changed later, document this as well.
+
+ Non-public functions (static ones, and those marked SR_PRIV) don't need
+ to have @since markers.
+
+ The @since tag should be the last one, i.e. it should come after @param,
+ @return, @see, and so on.
+
+ Examples:
+
+ @since 0.1.0
+
+ @since 0.1.1 (but the API changed in 0.2.0)
+
Testsuite
---------
* the 'ctx' pointer is undefined and should not be used. Upon success,
* the context will be free'd by sr_exit() as part of the libsigrok
* shutdown.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
*/
SR_API int sr_init(struct sr_context **ctx)
{
* @param ctx Pointer to a libsigrok context struct. Must not be NULL.
*
* @return SR_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
*/
SR_API int sr_exit(struct sr_context *ctx)
{
* of the string is made.
*
* @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
*/
SR_API int sr_dev_probe_name_set(const struct sr_dev_inst *sdi,
int probenum, const char *name)
* @param state TRUE to enable the probe, FALSE to disable.
*
* @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
+ *
+ * @since 0.2.0
*/
SR_API int sr_dev_probe_enable(const struct sr_dev_inst *sdi, int probenum,
gboolean state)
* @param trigger Trigger string, in the format used by sigrok-cli
*
* @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
*/
SR_API int sr_dev_trigger_set(const struct sr_dev_inst *sdi, int probenum,
const char *trigger)
* @return TRUE if the device has the specified option, FALSE otherwise.
* FALSE is also returned on invalid input parameters or other
* error conditions.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
*/
SR_API gboolean sr_dev_has_option(const struct sr_dev_inst *sdi, int key)
{
g_free(sdi->model);
g_free(sdi->version);
g_free(sdi);
-
}
#ifdef HAVE_LIBUSB_1_0
#endif
-/** @private
- * @param pathname OS-specific serial port specification. Examples:
- * "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1".
- * @param serialcomm A serial communication parameters string, in the form
- * of <speed>/<data bits><parity><stopbits>, for example "9600/8n1" or
- * "600/7o2". This is an optional parameter; it may be filled in later.
- * @return A pointer to a newly initialized struct sr_serial_dev_inst,
- * or NULL on error.
+/**
+ * @private
*
* Both parameters are copied to newly allocated strings, and freed
* automatically by sr_serial_dev_inst_free().
+ *
+ * @param pathname OS-specific serial port specification. Examples:
+ * "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1".
+ * @param serialcomm A serial communication parameters string, in the form
+ * of <speed>/<data bits><parity><stopbits>, for example
+ * "9600/8n1" or "600/7o2". This is an optional parameter;
+ * it may be filled in later.
+ *
+ * @return A pointer to a newly initialized struct sr_serial_dev_inst,
+ * or NULL on error.
*/
SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
const char *serialcomm)
* Return a human-readable error string for the given libsigrok error code.
*
* @param error_code A libsigrok error code number, such as SR_ERR_MALLOC.
+ *
* @return A const string containing a short, human-readable (English)
* description of the error, such as "memory allocation error".
* The string must NOT be free'd by the caller!
+ *
* @see sr_strerror_name
+ *
+ * @since 0.2.0
*/
SR_API const char *sr_strerror(int error_code)
{
* a libsigrok error code is useful.
*
* @param error_code A libsigrok error code number, such as SR_ERR_MALLOC.
+ *
* @return A const string containing the "name" of the error code as string.
* The string must NOT be free'd by the caller!
+ *
* @see sr_strerror
+ *
+ * @since 0.2.0
*/
SR_API const char *sr_strerror_name(int error_code)
{
* or SR_ERR_ARG upon invalid arguments.
* If something other than SR_OK is returned, the values of
* out_unitsize, data_out, and length_out are undefined.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
*/
SR_API int sr_filter_probes(unsigned int in_unitsize, unsigned int out_unitsize,
const GArray *probe_array, const uint8_t *data_in,
* SR_LOG_INFO, SR_LOG_DBG, or SR_LOG_SPEW).
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid loglevel.
+ *
+ * @since 0.1.0
*/
SR_API int sr_log_loglevel_set(int loglevel)
{
* Get the libsigrok loglevel.
*
* @return The currently configured libsigrok loglevel.
+ *
+ * @since 0.1.0
*/
SR_API int sr_log_loglevel_get(void)
{
* the caller does not need to keep it around.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid logdomain.
+ *
+ * @since 0.1.0
*/
SR_API int sr_log_logdomain_set(const char *logdomain)
{
* @return A copy of the currently configured libsigrok logdomain
* string. The caller is responsible for g_free()ing the string when
* it is no longer needed.
+ *
+ * @since 0.1.0
*/
SR_API char *sr_log_logdomain_get(void)
{
* to be NULL if the caller doesn't need/want to pass any data.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
+ *
+ * @since 0.1.0
*/
SR_API int sr_log_callback_set(sr_log_callback_t cb, void *cb_data)
{
* Additionally, the internal 'sr_log_callback_data' pointer is set to NULL.
*
* @return SR_OK upon success, a negative error code otherwise.
+ *
+ * @since 0.1.0
*/
SR_API int sr_log_callback_set_default(void)
{
*
* Version number querying functions, definitions, and macros.
*
+ * This set of API calls returns two different version numbers related
+ * to libsigrok. The "package version" is the release version number of the
+ * libsigrok tarball in the usual "major.minor.micro" format, e.g. "0.1.0".
+ *
+ * The "library version" is independent of that; it is the libtool version
+ * number in the "current:revision:age" format, e.g. "2:0:0".
+ * See http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning for details.
+ *
+ * Both version numbers (and/or individual components of them) can be
+ * retrieved via the API calls at runtime, and/or they can be checked at
+ * compile/preprocessor time using the respective macros.
+ *
* @{
*/
+/**
+ * Get the major libsigrok package version number.
+ *
+ * @return The major package version number.
+ *
+ * @since 0.1.0
+ */
SR_API int sr_package_version_major_get(void)
{
return SR_PACKAGE_VERSION_MAJOR;
}
+/**
+ * Get the minor libsigrok package version number.
+ *
+ * @return The minor package version number.
+ *
+ * @since 0.1.0
+ */
SR_API int sr_package_version_minor_get(void)
{
return SR_PACKAGE_VERSION_MINOR;
}
+/**
+ * Get the micro libsigrok package version number.
+ *
+ * @return The micro package version number.
+ *
+ * @since 0.1.0
+ */
SR_API int sr_package_version_micro_get(void)
{
return SR_PACKAGE_VERSION_MICRO;
}
+/**
+ * Get the libsigrok package version number as a string.
+ *
+ * @return The package version number string. The returned string is
+ * static and thus should NOT be free'd by the caller.
+ *
+ * @since 0.1.0
+ */
SR_API const char *sr_package_version_string_get(void)
{
return SR_PACKAGE_VERSION_STRING;
}
+/**
+ * Get the "current" part of the libsigrok library version number.
+ *
+ * @return The "current" library version number.
+ *
+ * @since 0.1.0
+ */
SR_API int sr_lib_version_current_get(void)
{
return SR_LIB_VERSION_CURRENT;
}
+/**
+ * Get the "revision" part of the libsigrok library version number.
+ *
+ * @return The "revision" library version number.
+ *
+ * @since 0.1.0
+ */
SR_API int sr_lib_version_revision_get(void)
{
return SR_LIB_VERSION_REVISION;
}
+/**
+ * Get the "age" part of the libsigrok library version number.
+ *
+ * @return The "age" library version number.
+ *
+ * @since 0.1.0
+ */
SR_API int sr_lib_version_age_get(void)
{
return SR_LIB_VERSION_AGE;
}
+/**
+ * Get the libsigrok library version number as a string.
+ *
+ * @return The library version number string. The returned string is
+ * static and thus should NOT be free'd by the caller.
+ *
+ * @since 0.1.0
+ */
SR_API const char *sr_lib_version_string_get(void)
{
return SR_LIB_VERSION_STRING;
projects / libsigrok.git / commitdiff