Share this page
rdp_sync_on_window
Waits for a window to match a specified state.
| Example: rdp_sync_on_window | Synchronization Functions |
int rdp_sync_on_window( "StepDescription=<step_description>", "Snapshot=<snapshot>", ["ConnectionID=<connection_identifier>",] ["WindowTitle[/RE]=<window_title>",] ["WindowOrdinal=<window_ordinal>",] "WindowState=< EXIST | NOT_EXIST | ACTIVE | MINIMIZED | MAXIMIZED >", ["Timeout=<timeout_value>",] ["FailStepIfNotFound=<Default | Yes | No>",] RDP_LAST );
This function returns one of the following:
LR_PASS (0): The function completed without error.
LR_FAIL (1): The function completed with errors.
LR_NOT_FOUND (2): The function's FailStepIfNotFound argument is set to No and the window does not match the specified state.
LR_PASS does not indicate that the test step passed-only that the function ran to completion. For example, LR_PASS does not indicate that the server returned the expected value.
All string arguments (char type) can be parameterized using standard parameterization.
| Argument | Description |
|---|---|
| StepDescription | A descriptive, unique name for this step. Use any text. |
| Snapshot | The name of the snapshot file of the screen state before this step. |
| ConnectionID | The name of the connection on which this function operates. Do not change the recorded ID. If several connections are open and the ID is not specified, the first connection in the script is used. If only one connection is open, the connection ID is unnecessary. |
| "WindowTitle=" "WindowTitle/RE=" |
The title of the window.
The value for Title is a literal string, for example, "Title=Quality Center". If you use WindowTitle/RE, the value is a regular expression, for example, "WindowTitle/RE=^Document[0-9]+ - Microsoft Word".
|
| WindowOrdinal |
The 1-based index of the window among the session windows that match the title specified by WindowTitle or WindowTitle/RE.
For example, if the WindowTitle/RE and WindowOrdinal arguments are "WindowTitle/RE=Document[0-9]+ - Microsoft Word" and "WindowOrdinal=3", the window specified is the third window in the creation order of the existing windows whose title matches the regular expression "Document[0-9]+ - Microsoft Word".
If this optional argument is omitted, the default value is 1.
|
| WindowState | A string value that indicates the desired state of the window for which the script should wait. See Window States. |
| Timeout | The wait time in seconds. If the timeout is exceeded, the function returns LR_FAIL. If no timeout is passed, the default value is taken from the runtime settings. |
| FailStepIfNotFound | Possible values: Yes, No, or Default. If the window does not match the specified state and this argument is set to No, the function returns LR_NOT_FOUND (2). |
| RDP_LAST | The delimiter marking the end of the argument list. |
The rdp_sync_on_window function is a synchronization function that suspends the script run until one of the following occurs: The state of a window on the remote machine matches the specified state, or the function times out.
The rdp_sync_on_window function is generated automatically during code generation when the Use RDP Agent RDP advanced code generation option is selected. The function is placed before keyboard operations. Inserting this function manually into the script before mouse operations (as a synchronization step for these mouse operations) may result in incorrect script execution if there are window position inconsistencies.
If the rdp_sync_on_window function finds at least one window title that matches the specified name, the function prints a list of all the matching windows and their ordinal values to the extended log. If the given ordinal is incorrect, the list of windows is printed to the regular log. Use this list to update the script with the correct ordinal values.
Window States
The following are the supported window states:
| State | Description |
|---|---|
| EXIST | The window exists on the remote machine. |
| NOT_EXIST | The window does not exist on the remote machine. |
| ACTIVE | The window is active on the remote machine. The keyboard events sent to the remote machine are received by the active window. |
| MINIMIZED | The window exists and is minimized on the remote machine. |
| MAXIMIZED | The window exists and is maximized on the remote machine. |
