Platform Package reference: Function EwInvokeCopy()
Description of the function EwInvokeCopy() available in Platform Packages for C compatible target systems. This function is intended to be used when integrating the Embedded Wizard created GUI application with the underlying graphics subsystem, graphics hardware or other external GUI applications coexisting on the same system.
Declaration
int EwInvokeCopy( XInvokeProc aProc, const void* aData, int aSize )
Parameters
aProc
Function to schedule its invocation in context of Embedded Wizard's own thread or task. The function declaration must match the type definition XInvokeProc.
aData
Pointer to a data structure to be copied and passed in the invocation of aProc.
aSize
Size of the data structure aData in bytes to copy and pass in the invocation of aProc.
Discussion
The function EwInvokeCopy() schedules the function aProc to be called during the next iteration through Embedded Wizard application's main loop. This ensures that aProc is invoked in the safe context of Embedded Wizard's own thread or task. The implementation of aProc can thereupon access and use all Embedded Wizard functionality without any restriction.
Unlike all other Embedded Wizard functions, EwInvokeCopy() is explicitly allowed to be called in context of foreign threads, tasks or even interrupt service routines. In this manner, the thread, task or interrupt service routine can easily communicate with Embedded Wizard application. It can, for example, trigger system events in the GUI application or send data to it.
The pointer aData refers to a data structure to pass during the execution of aProc. aProc can thereupon access this data structure. Unlike EwInvoke() the function EwInvokeCopy() copies the data structure on the internal queue, what frees you from the necessity to take care of the memory management. You don't need to worry about the validity of aData when aProc is executed. The function aProc will simply receive a pointer to the copied data.
The following example demonstrates the usage of the function to update a property from a foreign thread:
/* Function to perform code in context of the GUI thread. In this example we assume that aData will refer to a zero terminated ANSI string. */ static void TriggerUpdatePropertyProc( const void* aData ) { const char* text = (const char*)aData; ApplicationDeviceClass device = EwGetAutoObject( &ApplicationDevice, ApplicationDeviceClass ); ApplicationDeviceClass__UpdateProperty( device, EwNewStringAnsi( text )); } /* Function running in context of a foreign thread. */ static void WorkerThreadProc( void ) { for ( ;; ) { char text[32]; [...] /* Schedule an invocation of the function 'TriggerUpdatePropertyProc' in context of the GUI thread. The string stored in the array 'text' is passed as copy to the function 'TriggerUpdatePropertyProc'. */ EwInvokeCopy( TriggerUpdatePropertyProc, text, strlen( text ) + 1 ); } }
All scheduled invocations are stored within an internal queue. If there is not sufficient space in the queue to record aProc and the copy of aData, EwInvokeCopy() will fail and return 0 (zero). Your implementation should then wait a while giving the Embedded Wizard application time to process the queue content. Then call EwInvokeCopy() again. Please note, when EwInvokeCopy() is called in context of an interrupt service routine, you may not wait. In such case, ensure in advance that the queue is large enough for the worst case.
If the invocation could be scheduled, the function returns a value != 0. If there was not enough space in the internal queue, the function returns 0 (zero).