Browse Source

* document source api

master
Alex 'AdUser' Z 8 years ago
parent
commit
b3d25ea62c
  1. 123
      src/sources/source.h

123
src/sources/source.h

@ -14,16 +14,121 @@
#include "../strlcpy.h" #include "../strlcpy.h"
/**
* @file
* This header describes module API of type 'source'
*
* Sample workflow of module usage:
*
* @msc
* f2b, source;
* f2b => source [label="create(init)"];
* f2b << source [label="module handler, cfg_t *cfg"];
* |||;
* f2b => source [label="config(cfg, param, value)"];
* f2b << source [label="true"];
* f2b => source [label="config(cfg, param, value)"];
* f2b << source [label="true"];
* f2b => source [label="config(cfg, param, value)"];
* f2b << source [label="false"];
* f2b => source [label="error(cfg)"];
* f2b << source [label="const char *error"];
* |||;
* f2b => source [label="errcb(cfg, cb), optional"];
* |||;
* f2b => source [label="ready(cfg)"];
* f2b << source [label="true"];
* --- [label="source is ready for start()"];
* f2b => source [label="start()"];
* f2b << source [label="true"];
* --- [label="source is ready to use"];
* f2b => source [label="next(cfg, buf, sizeof(buf), true)"];
* f2b << source [label="false"];
* ... [label="no data this time, try later"];
* f2b => source [label="next(cfg, buf, sizeof(buf), true)"];
* f2b << source [label="true"];
* f2b => source [label="next(cfg, buf, sizeof(buf), false)"];
* f2b <<= source [label="errcb(char *error)"];
* f2b << source [label="true"];
* f2b => source [label="next(cfg, buf, sizeof(buf), false)"];
* f2b << source [label="false"];
* ... [label="time passed"];
* f2b => source [label="stop(cfg)"];
* f2b << source [label="true"];
* --- [label="now you may config(), start() or destroy() source"];
* f2b => source [label="destroy(cfg)"];
* @endmsc
*/
/**
* @def INIT_MAX
* Defines max length of @a init param in @a create()
*/
#define INIT_MAX 256 #define INIT_MAX 256
/**
* Opaque module handler, contains module internal structs
*/
typedef struct _config cfg_t; typedef struct _config cfg_t;
/**
* @brief Create instance of module
* @param init Module-specific init string
* @returns Opaque module handler or NULL on failure
*/
extern cfg_t *create(const char *init); extern cfg_t *create(const char *init);
extern bool config(cfg_t *c, const char *key, const char *value); /**
extern bool ready(cfg_t *c); * @brief Configure module instance
extern char *error(cfg_t *c); * @param cfg Module handler
extern void errcb(cfg_t *c, void (*cb)(char *errstr)); * @param key Parameter name
extern bool start(cfg_t *c); * @param value Parameter value
extern bool next(cfg_t *c, char *buf, size_t bufsize, bool reset); * @returns true on success, false on error with setting intenal error buffer
extern bool stop(cfg_t *c); */
extern void destroy(cfg_t *c); extern bool config(cfg_t *cfg, const char *key, const char *value);
/**
* @brief Checks is module ready for usage
* @param cfg Module handler
* @returns true if ready, false if not
*/
extern bool ready(cfg_t *cfg);
/**
* @brief Returns last error description
* @param cfg Module handler
* @returns Pointer to string with description of last error
* @note Returned pointer not marked with const, because libdl complains,
* but contents on pointer should not be modified or written in any way
*/
extern char *error(cfg_t *cfg);
/**
* @brief Sets the error callback for use in processing
* @param cfg Module handler
* @param cb Error callback
* @note Optional, if this function is not called, processing errors will be suppressed
*/
extern void errcb(cfg_t *cfg, void (*cb)(char *errstr));
/**
* @brief Allocate resources and start processing
* @param cfg Module handler
* @returns true on success, false on error with setting intenal error buffer
*/
extern bool start(cfg_t *cfg);
/**
* @brief Poll source for new data
* @param cfg Module handler
* @param buf Pointer to buffer for storing result
* @param bufsize Size of buffer above (in bytes)
* @param reset Reset internals to start of list
* @returns false if no new data available, or true otherwise with filling @a buf
*/
extern bool next(cfg_t *cfg, char *buf, size_t bufsize, bool reset);
/**
* @brief Deallocate resources, prepare for module destroy
* @param cfg Module handler
* @returns true on success
*/
extern bool stop(cfg_t *cfg);
/**
* @brief Free module handle
* @param cfg Module handler
* @note Module handler becomes invalid after calling this function on it
*/
extern void destroy(cfg_t *cfg);

Loading…
Cancel
Save