doc groups
This commit is contained in:
@@ -23,95 +23,101 @@
|
||||
#include "pipropertystorage.h"
|
||||
|
||||
|
||||
/*! \class PIIODevice
|
||||
* \brief Base class for input/output classes
|
||||
*
|
||||
* \section PIIODevice_sec0 Synopsis
|
||||
* This class provide open/close logic, threaded read/write and virtual input/output
|
||||
* functions \a read() and \a write(). You should implement pure virtual
|
||||
* function \a openDevice() in your subclass.
|
||||
*
|
||||
* \section PIIODevice_sec1 Open and close
|
||||
* PIIODevice have boolean variable indicated open status. Returns of functions
|
||||
* \a openDevice() and \a closeDevice() change this variable.
|
||||
*
|
||||
* \section PIIODevice_sec2 Threaded read
|
||||
* PIIODevice based on PIThread, so it`s overload \a run() to exec \a read()
|
||||
* in background thread. If read is successful virtual function \a threadedRead()
|
||||
* is executed. Default implementation of this function execute external static
|
||||
* function set by \a setThreadedReadSlot() with data set by \a setThreadedReadData().
|
||||
* Extrenal static function should have format \n
|
||||
* bool func_name(void * Threaded_read_data, uchar * readed_data, int readed_size)\n
|
||||
* Threaded read starts with function \a startThreadedRead().
|
||||
*
|
||||
* \section PIIODevice_sec3 Threaded write
|
||||
* PIIODevice aggregate another PIThread to perform a threaded write by function
|
||||
* \a writeThreaded(). This function add task to internal queue and return
|
||||
* queue entry ID. You should start write thread by function \a startThreadedWrite.
|
||||
* On successful write event \a threadedWriteEvent is raised with two arguments -
|
||||
* task ID and written bytes count.
|
||||
*
|
||||
* \section PIIODevice_sec4 Internal buffer
|
||||
* PIIODevice have internal buffer for threaded read, and \a threadedRead() function
|
||||
* receive pointer to this buffer in first argument. You can adjust size of this buffer
|
||||
* by function \a setThreadedReadBufferSize() \n
|
||||
* Default size of this buffer is 4096 bytes.
|
||||
*
|
||||
* \section PIIODevice_sec5 Reopen
|
||||
* When threaded read is begin its call \a open() if device is closed. While threaded
|
||||
* read running PIIODevice check if device opened every read and if not call \a open()
|
||||
* every reopen timeout if reopen enabled. Reopen timeout is set by \a setReopenTimeout(),
|
||||
* reopen enable is set by \a setReopenEnabled().
|
||||
*
|
||||
* \section PIIODevice_sec6 Configuration
|
||||
* This is virtual function \a configureDevice() which executes when \a configure()
|
||||
* executes. This function takes two arguments: "e_main" and "e_parent" as void*. There
|
||||
* are pointers to PIConfig::Entry entries of section "section" and their parent. If
|
||||
* there is no parent "e_parent" = 0. Function \a configure() set three parameters of
|
||||
* device: "reopenEnabled", "reopenTimeout" and "threadedReadBufferSize", then execute
|
||||
* function \a configureDevice().
|
||||
* \n Each ancestor of %PIIODevice reimlements \a configureDevice() function to be able
|
||||
* to be confured from configuration file. This parameters described at section
|
||||
* "Configurable parameters" in the class reference. \n Usage example:
|
||||
* \snippet piiodevice.cpp configure
|
||||
* Implementation example:
|
||||
* \snippet piiodevice.cpp configureDevice
|
||||
*
|
||||
* \section PIIODevice_sec7 Creating devices by unambiguous string
|
||||
* There are some virtual functions to describe child class without its declaration.
|
||||
* \n \a fullPathPrefix() should returns unique prefix of device
|
||||
* \n \a constructFullPath() should returns full unambiguous string, contains prefix and all device parameters
|
||||
* \n \a configureFromFullPath() provide configuring device from full unambiguous string without prefix and "://"
|
||||
* \n Macro PIIODEVICE should be used instead of PIOBJECT
|
||||
* \n Macro REGISTER_DEVICE should be used after definition of class, i.e. at the last line of *.cpp file
|
||||
* \n \n If custom I/O device corresponds there rules, it can be returned by function \a createFromFullPath().
|
||||
* \n Each PIP I/O device has custom unambiguous string description:
|
||||
* * PIFile: "file://<path>"
|
||||
* * PIBinaryLog: "binlog://<logDir>[:<filePrefix>][:<defaultID>]"
|
||||
* * PISerial: "ser://<device>:<speed(50|...|115200)>[:<dataBitsCount(6|7|8)>][:<parity(N|E|O)>][:<stopBits(1|2)>]"
|
||||
* * PIEthernet: UDP "eth://UDP:<readIP>:<readPort>:<sendIP>:<sendPort>[:<multicast(mcast:<ip>)>]"
|
||||
* * PIEthernet: TCP "eth://TCP:<IP>:<Port>"
|
||||
* * PIUSB: "usb://<vid>:<pid>[:<deviceNumber>][:<readEndpointNumber>][:<writeEndpointNumber>]"
|
||||
* \n \n Examples:
|
||||
* * PIFile: "file://../text.txt"
|
||||
* * PIBinaryLog: "binlog://../logs/:mylog_:1"
|
||||
* * PISerial: "ser:///dev/ttyUSB0:9600:8:N:1", equivalent "ser:///dev/ttyUSB0:9600"
|
||||
* * PIEthernet: "eth://TCP:127.0.0.1:16666", "eth://UDP:192.168.0.5:16666:192.168.0.6:16667:mcast:234.0.2.1:mcast:234.0.2.2"
|
||||
* * PIUSB: "usb://0bb4:0c86:1:1:2"
|
||||
* \n \n
|
||||
* So, custom I/O device can be created with next call:
|
||||
* \code{cpp}
|
||||
* // creatring devices
|
||||
* PISerial * ser = (PISerial * )PIIODevice::createFromFullPath("ser://COM1:115200");
|
||||
* PIEthernet * eth = (PIEthernet * )PIIODevice::createFromFullPath("eth://UDP:127.0.0.1:4001:127.0.0.1:4002");
|
||||
* // examine devices
|
||||
* piCout << ser << ser->properties();
|
||||
* piCout << eth << eth->properties();
|
||||
* \endcode
|
||||
*
|
||||
* \section PIIODevice_ex0 Example
|
||||
* \snippet piiodevice.cpp 0
|
||||
*/
|
||||
//! \addtogroup IO
|
||||
//! \{
|
||||
//! \class PIIODevice piiodevice.h
|
||||
//! \brief
|
||||
//! \~english Base class for input/output classes
|
||||
//! \~russian Базовый класс утройств ввода/вывода
|
||||
//!
|
||||
//! \~\details
|
||||
//! \section PIIODevice_sec0 Synopsis
|
||||
//! This class provide open/close logic, threaded read/write and virtual input/output
|
||||
//! functions \a read() and \a write(). You should implement pure virtual
|
||||
//! function \a openDevice() in your subclass.
|
||||
//!
|
||||
//! \section PIIODevice_sec1 Open and close
|
||||
//! PIIODevice have boolean variable indicated open status. Returns of functions
|
||||
//! \a openDevice() and \a closeDevice() change this variable.
|
||||
//!
|
||||
//! \section PIIODevice_sec2 Threaded read
|
||||
//! PIIODevice based on PIThread, so it`s overload \a run() to exec \a read()
|
||||
//! in background thread. If read is successful virtual function \a threadedRead()
|
||||
//! is executed. Default implementation of this function execute external static
|
||||
//! function set by \a setThreadedReadSlot() with data set by \a setThreadedReadData().
|
||||
//! Extrenal static function should have format \n
|
||||
//! bool func_name(void * Threaded_read_data, uchar * readed_data, int readed_size)\n
|
||||
//! Threaded read starts with function \a startThreadedRead().
|
||||
//!
|
||||
//! \section PIIODevice_sec3 Threaded write
|
||||
//! PIIODevice aggregate another PIThread to perform a threaded write by function
|
||||
//! \a writeThreaded(). This function add task to internal queue and return
|
||||
//! queue entry ID. You should start write thread by function \a startThreadedWrite.
|
||||
//! On successful write event \a threadedWriteEvent is raised with two arguments -
|
||||
//! task ID and written bytes count.
|
||||
//!
|
||||
//! \section PIIODevice_sec4 Internal buffer
|
||||
//! PIIODevice have internal buffer for threaded read, and \a threadedRead() function
|
||||
//! receive pointer to this buffer in first argument. You can adjust size of this buffer
|
||||
//! by function \a setThreadedReadBufferSize() \n
|
||||
//! Default size of this buffer is 4096 bytes.
|
||||
//!
|
||||
//! \section PIIODevice_sec5 Reopen
|
||||
//! When threaded read is begin its call \a open() if device is closed. While threaded
|
||||
//! read running PIIODevice check if device opened every read and if not call \a open()
|
||||
//! every reopen timeout if reopen enabled. Reopen timeout is set by \a setReopenTimeout(),
|
||||
//! reopen enable is set by \a setReopenEnabled().
|
||||
//!
|
||||
//! \section PIIODevice_sec6 Configuration
|
||||
//! This is virtual function \a configureDevice() which executes when \a configure()
|
||||
//! executes. This function takes two arguments: "e_main" and "e_parent" as void*. There
|
||||
//! are pointers to PIConfig::Entry entries of section "section" and their parent. If
|
||||
//! there is no parent "e_parent" = 0. Function \a configure() set three parameters of
|
||||
//! device: "reopenEnabled", "reopenTimeout" and "threadedReadBufferSize", then execute
|
||||
//! function \a configureDevice().
|
||||
//! \n Each ancestor of %PIIODevice reimlements \a configureDevice() function to be able
|
||||
//! to be confured from configuration file. This parameters described at section
|
||||
//! "Configurable parameters" in the class reference. \n Usage example:
|
||||
//! \snippet piiodevice.cpp configure
|
||||
//! Implementation example:
|
||||
//! \snippet piiodevice.cpp configureDevice
|
||||
//!
|
||||
//! \section PIIODevice_sec7 Creating devices by unambiguous string
|
||||
//! There are some virtual functions to describe child class without its declaration.
|
||||
//! \n \a fullPathPrefix() should returns unique prefix of device
|
||||
//! \n \a constructFullPath() should returns full unambiguous string, contains prefix and all device parameters
|
||||
//! \n \a configureFromFullPath() provide configuring device from full unambiguous string without prefix and "://"
|
||||
//! \n Macro PIIODEVICE should be used instead of PIOBJECT
|
||||
//! \n Macro REGISTER_DEVICE should be used after definition of class, i.e. at the last line of *.cpp file
|
||||
//! \n \n If custom I/O device corresponds there rules, it can be returned by function \a createFromFullPath().
|
||||
//! \n Each PIP I/O device has custom unambiguous string description:
|
||||
//! * PIFile: "file://<path>"
|
||||
//! * PIBinaryLog: "binlog://<logDir>[:<filePrefix>][:<defaultID>]"
|
||||
//! * PISerial: "ser://<device>:<speed(50|...|115200)>[:<dataBitsCount(6|7|8)>][:<parity(N|E|O)>][:<stopBits(1|2)>]"
|
||||
//! * PIEthernet: UDP "eth://UDP:<readIP>:<readPort>:<sendIP>:<sendPort>[:<multicast(mcast:<ip>)>]"
|
||||
//! * PIEthernet: TCP "eth://TCP:<IP>:<Port>"
|
||||
//! * PIUSB: "usb://<vid>:<pid>[:<deviceNumber>][:<readEndpointNumber>][:<writeEndpointNumber>]"
|
||||
//! \n \n Examples:
|
||||
//! * PIFile: "file://../text.txt"
|
||||
//! * PIBinaryLog: "binlog://../logs/:mylog_:1"
|
||||
//! * PISerial: "ser:///dev/ttyUSB0:9600:8:N:1", equivalent "ser:///dev/ttyUSB0:9600"
|
||||
//! * PIEthernet: "eth://TCP:127.0.0.1:16666", "eth://UDP:192.168.0.5:16666:192.168.0.6:16667:mcast:234.0.2.1:mcast:234.0.2.2"
|
||||
//! * PIUSB: "usb://0bb4:0c86:1:1:2"
|
||||
//! \n \n
|
||||
//! So, custom I/O device can be created with next call:
|
||||
//! \code{cpp}
|
||||
//! // creatring devices
|
||||
//! PISerial * ser = (PISerial * )PIIODevice::createFromFullPath("ser://COM1:115200");
|
||||
//! PIEthernet * eth = (PIEthernet * )PIIODevice::createFromFullPath("eth://UDP:127.0.0.1:4001:127.0.0.1:4002");
|
||||
//! // examine devices
|
||||
//! piCout << ser << ser->properties();
|
||||
//! piCout << eth << eth->properties();
|
||||
//! \endcode
|
||||
//!
|
||||
//! \section PIIODevice_ex0 Example
|
||||
//! \snippet piiodevice.cpp 0
|
||||
//!
|
||||
//! \}
|
||||
|
||||
|
||||
PIMutex PIIODevice::nfp_mutex;
|
||||
|
||||
Reference in New Issue
Block a user