API Notes
The BIG Don'ts for API Development
Don't pass a pointer to queues or call back methods
Communication of a driver is asynchronous. If you pass a pointer to a callback object, the pointer might not be valid anymore if the callback is executed. The same applies to send/receive queues.
Don't call WinCC OA methods from another thread
WinCC OA methods are generally not thread safe and not reentrant, therefore they must only be called from the WinCC OA thread.
If a method is called from another thread, e.g. a communication stack, you must implement a queue as an interface to the WinCC OA thread. Writing to and reading from the queue must be properly safeguarded by locking protocols.
You may use the WinCC OA implementation of a mutex (Mutex.hxx, ScopeMutex.hxx).
Don't use blocking code
WinCC OA API components (EWO, CtrlExt, Driver, DrvPlugin, Manager, AccessControlPlugin) are single threaded.
- Never use any blocking code
- Never implement a synchronous call
Always consider that a single WinCC OA driver usually services many peripheral devices. If the manager, i.e. the threads waits for a single device to finish with whatever routine, all other devices are also blocked.
Don't use dispatch in any call-back
The Manager::doReceive() function is automatically called by the Manager::dispatch()
function for each incoming message. The manager processes incoming messages in the
Manager::doReceive() function. Call-back functions are processed by the Manager::dispatch()
function.
Call-back functions are e.g.: WaitForAnswer::callBack()
, HotLinkWaitForAnswer::hotLinkCallBack()
, Manager::doReceive()
,
CNSObserver::update()
, etc.
Don't call the Manager::dispatch()
function from any call-back function to avoid recursion and undefined behavior.
Don't call the Manager::dispatch()
function in EWO, CtrlExt, Driver, DrvPlugin and AccessControlPlugin, because this is done internally in the framework.
Manager::dispatch()
function should be called only in the Manager::run() function. This is already done and prepared for you in the API Manager example. See:
wincc_oa\api\TemplateManager\_TEMPLATE_Manager.cxx
.