Platform Package reference: Function EwInvoke()

Description of the function EwInvoke() 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 EwInvoke( XInvokeProc aProc, const void* aData )

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 pass in the invocation of aProc.

Discussion

The function EwInvoke() 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, EwInvoke() 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 may refer a data structure to pass during the execution of aProc. aProc can thereupon access this data structure. Doing this, remember that aProc will be executed asynchronously. You have to ensure that the data pointed by aData remains valid when aProc is executed. Alternatively you can use the function EwInvokeCopy(), which copies the data referred by aData. You don't need to worry about the memory management in this case.

The following example demonstrates the usage of the function to trigger a system event from a foreign thread:

/* Function to perform code in context of the GUI thread. */ static void TriggerSystemEventProc( const void* aData ) { ApplicationDeviceClass device = EwGetAutoObject( &ApplicationDevice, ApplicationDeviceClass ); ApplicationDeviceClass__TriggerEvent( device ); } /* Function running in context of a foreign thread. */ static void WorkerThreadProc( void ) { for ( ;; ) { [...] /* Schedule an invocation of the function 'TriggerSystemEventProc' in context of the GUI thread. */ EwInvoke( TriggerSystemEventProc, 0 ); } }

All scheduled invocations are stored within an internal queue. If there is not sufficient space in the queue to record aProc, EwInvoke() 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 EwInvoke() again. Please note, when EwInvoke() 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).