User Interface API Reference

Handling Client/Server Errors

This section is only applicable if you have configured the Pro client to use the Pro server.

There are some network communication errors from which it is not always possible to recover. These error conditions are listed below:

If any of the above error conditions occur, the Pro API will return qaerr_NOLIVESERVER. This error is fatal - you must therefore close the API by calling QAProWV_UIShutdown. (Any other operations will continue to return the error.)

You may continue operation by attempting to open the API with QAProWV_UIStartup.

If you have multiple servers configured, you will only need to call QAProWV_UIStartup once, as it will attempt to connect to each server in turn before returning qaerr_NOLIVESERVER.

Pseudocode Example Of Pro API

This section provides an overview of how a program using the Pro User Interface (UI) API works at a conceptual level. The pseudocode used is independent of any programming language.

The example below uses the main Pro UI API functions to clarify how they work together. The pseudocode does not use all of the available functions.

The concept of the User Interface API is that a single instance of the Pro application can be controlled through a small set of API functions. To create the application, the function QAProWV_UIStartup must be called. At this point, no graphical display will be visible.

The function take a flag parameter vlFlags which controls the behaviour of the user interface.

Start the Pro application [QAProWV_UIStartup]

As with all API calls, the Open call could fail for various reasons. The most common reasons for this to occur are that the product is not installed or configured properly. If Open fails, address matching will not be available. When integrating the User Interface API, it is useful to enable error logging.

Repeat

The text that you want to search on should be obtained from the user from within the integration environment and passed to the function QAProWV_UISearch. If you do not want to obtain the text from the user integration, but would instead rather just popup the Pro graphical user interface in order to allow the user to enter the search directly into Pro, then pass a blank string to QAProWV_UISearch.

Search with the provided text [QAProWV_UISearch]

This function call will return to the caller either once a final address has been selected, or when the application has been manually closed. The return value from the function QAProWV_UISearch can be tested to determine whether the user completed a search. We will assume in the pseudocode that a search has been successfully completed.

The next step is to retrieve the final address result which will have been formatted using the rules specified in the selected layout. First obtain a count of formatted lines, and then retrieve each one in turn:

Obtain a count of formatted lines [QAProWV_UIResultCount]

For Each formatted line

Retrieve the line text [QAProWV_UIGetResult]

Return text to integration

End For

Until no more searches are required

Once all required searches have been performed, the function QAProWV_UIShutdown must be called to free all allocated resources. For performance reasons, it is advised to only call QAProWV_UIShutdown once all searches have been performed, rather than between separate searches.

Shutdown the application [QAProWV_UIShutdown]