Universitaet Bremen
FB3->Group BKB

->Main->API->Information about API Answers
Service & Support

Information about API Answers

Information about API Answers

Answer at initialization time

uDraw(Graph) can be connected to an application program using several options, refer to page How to connect an Application for details. After connecting uDraw(Graph) to the application, an initial answer ok is sent to the application to signal preparedness for receiving commands. An application must not start sending commands to uDraw(Graph) before receiving the initial "ok" as the first answer from the API.

Answers to confirm API commands

In general, commands sent to the API are confirmed by sending the answer ok back to the application after successfully executing the command. All commands that do not return "ok" are listed below. If an error occurred while executing the command, uDraw(Graph) will send the answer communication_error instead of "ok". Usually, this exception should not happen when the application meets all rules and restrictions of the API. The application can find the reason for the error in the string parameter of answer "communication_error(...)".

These are the API commands that do not return the "ok" answer:

In multi-window mode, the following commands answer open_window instead of ok:

Answers to notify events

Beside the answers used to confirm a command sent to the API, some answers may occur at any time. These are notifications for events that are triggered by the user. A uDraw(Graph) application must be prepared to receive these answers at any time, even in the time interval between sending a command and receiving the corresponding confirmation answer. The API sends the following events:

VERY IMPORTANT: Due to the strange effects of asynchronous communication caused by message delays, an event must also be expected by the application after sending a command to the API and before receiving the corresponding confirmation answer! uDraw(Graph) guarantees that event answers are not propagated during execution of an API command, but if the event occurs during transfer time of the command (i.e. after it has been sent by the application and before it has been received by the API), then the event answer may interfere and will arrive at the application side in the time interval after sending the command and before receiving the corresponding confirmation answer. So never expect that the confirmation answer will come back directly after sending an API command. Your application must accept event answers at any time!

Answers in Multi-Graph Mode

When uDraw(Graph) has left the default single-graph mode to enter the multi-graph mode, the behavior for confirming commands and sending event notifications will slightly change. In multi-graph mode, all answers from uDraw(Graph) will always have a preluding answer context(...) to specify the context (graph) where the following answer happened. So in multi-graph mode, an application will always get two answers instead of one: The first one is the context and the second one is the event or confirmation answer.

Answers in Multi-Window Mode

In the multi-view mode where the user (or the application) has opened additional views (base windows) to the graph, the application is unable to access each individual view. To solve this restriction, you can use the multi-window mode by using command-line option -window_api. Here, the behavior of sending two answers with each confirmation or event is the same, but instead the preluding answer context_window(...) is used where the application can find an additional window ID. Further, the commands menu(view(open_new_view)) and menu(view(open_survey_view)) return the confirmation answer open_window instead of the usual ok that is sent by these commands when the multi-window mode is not active.