Share this page
rdp_sync_on_image
Waits until an image appears on, or disappears from, the RDP client window.
| Example: rdp_sync_on_image | Synchronization Functions |
int rdp_sync_on_image( "StepDescription=<step_description>", ["ConnectionID=<connection_identifier>",] ["WaitFor=<Appear|Change>|NotAppear",] ["Tolerance=<tolerance_level>",] ["Timeout=<timeout_value>",] "AddOffsetToInput=<Yes|No|Default>", ["FailStepIfNotFound=<Yes|No|Default>",] ["FoundImageParam=<parameter_name>",] IMAGEDATA, "ImageName=<image_name>", "ImageLeft=<y_pos>", "ImageWidth=<bitmap_width>", "ImageTop=<x_pos>", "ImageWidth=<bitmap_width>", "ImageHeight=<bitmap_height>", ENDIMAGE, RDP_LAST );
This function returns LR_PASS (0) on success, LR_FAIL (1) on failure, and LR_NOT_FOUND (2) if the function times out without causing the function to fail.
All string arguments (char type) can be parameterized using standard parameterization.
| Argument | Description |
|---|---|
| StepDescription | A descriptive, unique name for this step. Use any text. |
| 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 not required. |
| AddOffsetToInput | The offset is the change in the position where the image was found during test run from the position when recorded. This argument indicates whether to add the offset to subsequent input, for example, mouse-click coordinates. Possible values are: Yes (Add offset), No (Do not add offset), Default (Take the value from the runtime options). |
| WaitFor | The event to occur on one of the specified areas and images. The value is one of Appear, NotAppear, or Change . The default is Appear. This argument is optional. |
| Tolerance | The tolerance level for accepting images. The possible values are: Exact. No tolerance. The specified area of the image returned by the server during the test run must match the recorded image exactly. This includes the pixel colors. One consequence of this is that if an area is selected when the image is saved and is not selected during test run, the synchronization may fail due to the selection highlighting. Low. Low tolerance. The area returned by the server during test run must closely resemble the saved image. Medium. Medium tolerance. A portion of the area must resemble the saved image. High. Loose tolerance. The area returned by the server must be a coarse match of the saved image. This argument is optional. |
| 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 image is not found and this argument is set to No , then the function returns LR_NOT_FOUND (2). |
| FoundImageParam | The name of a parameter in which to store the name of the image in which the match was found. This argument is optional. |
| ImageName | The name of the image file to compare to the area in the RDP client window. |
| ImageLeft | The X-coordinate of the top-left corner of the area on which the comparison is performed. The distance is relative to the RDP client window. |
| ImageTop | The Y-coordinate of the top-left corner of the area on which the comparison is performed. The distance is relative to the RDP client window. |
| ImageWidth | The width of the area of the image on which the comparison is performed |
| ImageHeight | The height of the area of the image on which the comparison is performed. |
| RDP_LAST | The delimiter marking the end of the argument list. |
The rdp_sync_on_image function is a synchronization function that suspends the script run until the specified event occurs or the function times out. The function can wait on several images. When the specified action occurs with respect to one of the, the function completes.
If the WaitFor event is Appear, the function waits for the specified area to match one of the specified images.
If the WaitFor event is Change, the function waits for the specified area to match one of the specified images and then not to match it. That is, the match is found and then the area changes so that it not longer matches.
If the WaitFor event is NotAppear, the function returns LR_FAIL if the image appears before the function times out. If the time-out is reached and the image has not appeared, the function returns LR_PASS.
Specify the image or images in the image block. The image block starts with the IMAGEDATA marker. For each separate image, specify the ImageLeft, ImageTop, ImageWidth, ImageHeight and ImageName attributes, followed by an ENDIMAGE tag.
