Using the Event Structure (It_Event) 

Use

The program using the GUI Library can:

Your program does so by getting an event using the It_GetEvent (or It_GetEventEx) and sending an event using It_SendEvent (or It_SendEventEx) functions respectively, as illustrated in the following diagram.

If your application is controlling or recording the interaction of an end user with the standard SAPGUI screens, your program can also:

Your program uses the It_SendEvent and It_GetEventEx with special flags for sending or getting the data from Front (as opposed to from the R/3 application server)

The following illustration summarizes the flow of screen data between the R/3 application server, the event structure, and Front.

Prerequisite

You must establish a connection to R/3 before getting or sending data to R/3.

Procedure

  1. The client application first reads an event by calling It_GetEvent or It_GetEventEx. These are blocking calls, meaning that they return only when the server has sent a response.

    2. The program calling It_GetEvent and It_GetEvent Ex waits until a DYNP event arrives. It_GetEvent and It_GetEvent Ex then return the result in a pointer to the It_Event structure.

    If any error occurs, then these functions return FALSE; otherwise they return TRUE.

  2. Before sending an event back to the application server, the client application can alter the event structure either by direct manipulation of the event structure or by using the various ItEv_* functions.
  3. The client would then call It_SendEvent, to pass the It_Event structure.

If no error occurs, It_SendEvent processes the It_Event structure and prepares a packet to be sent to the application server.

It_SendEvent then frees up the It_Event and zeros out the It_Event pointer.

After this point, the client application should not access the event structure, as this event is already sent and is no longer valid.

To send a modified event to the server, you can also use:
  1. After It_SendEvent is called, the client can call It_GetEvent to get the application server’s response.

Making a Copy of the Event Structure

You can keep a copy of the event structure for later use or for off-line processing, by calling It_Dup.

This function returns a copy of the event structure, which should not be used for communicating data to the application server, meaning that you should not use it with It_SendEvent.

When you are done with the copied structure, you should call It_FreeEvent to free the structure.

Peeking at the Event Structure

It_PeekEvent performs similar function to the It_GetEvent, only it allows you to see the contents of the same event several times before you actually get the event with an It_GetEvent* call.

This is especially useful if two procedures need to access the same event information.

In the example below, the program uses the It_PeekEvent as a way to handle possible errors. It uses the It_PeekEvent to check that the event returned no error. Only if no error occurred does it use It_GetEvent.

Since the It_PeekEvent fills the event structure, you need to use It_FreeEvent to free the event structure after using the It_PeekEvent.

Example

The flexibility of this architecture can be demonstrated by looking at the code of It_Login, which is implemented using It_GetEvent and It_SendReturn, (a variant of It_SendEvent).

DWORD DLEX It_Login (HANDLE hMerlin, char* client, char* name,
char* passwd, char* lang)
{
PIT_EVENT pEvt = 0;
if (It_GetEvent(hMerlin, &pEvt))
{
ItEv_SetValue(pEvt, 1, client);
ItEv_SetValue(pEvt, 3, name);
ItEv_SetValue(pEvt, 5, passwd);
ItEv_SetValue(pEvt, 7, lang);

It_SendReturn(hMerlin, &pEvt);

It_PeekEvent(hMerlin, &pEvt);
if(pEvt->eventtype & EVT_MESSAGE)
{
It_FreeEvent(&pEvt);
return FALSE;
}
// Bypass copyright screen
It_GetEvent(hMerlin, &pEvt);
It_SendReturn(hMerlin, &pEvt);
}
return TRUE;
}