Home Products Purchase Support Training About Us Vision Loss Facts

Research It Developer's Guide

This document is intended for script developers and software developers. It provides information necessary to create custom rule sets and lookup modules for Research It. Before you begin, you should be familiar with JAWS, XQuery, XPath, XML, and HTML.

A comprehensive book on XQuery is available from Bookshare (for Bookshare subscribers) at:

For basic tutorials about XQuery, XPath, XML, and HTML, refer to:

Research It is a JAWS tool that uses queries written in XQuery to manipulate XML databases and other data sources. Using the information outlined in this document, you can create a basic query by making your own rule set files to use with the supplied Freedom Scientific lookup module DLL, or you can create your own lookup module DLL to support and perform customized research operations.

Use the following links to move to a topic of interest:

• What is Research It?
• Definitions
• Creating a Rule Set
• Testing a Rule Set with JAWS
• Lookup Sources
• Lookup Module API
• Built-in Script API
• Script Wrapper Functions

What is Research It?

Features such as Web Slices in Internet Explorer 8 and gadgets saved to your desktop or Windows Sidebar are intended to make it easy for you to quickly obtain information. This material is presented in a format that is quick to scan visually. However, when using assistive technology tools, there is often extra information presented that is easier to ignore visually than when listening or reading with braille.

Research It is a JAWS feature that provides quick access to information while also making it easy to return to your primary task. Use just a few keystrokes to look up information and display salient data in the Virtual Viewer. When you have finished researching, press another keystroke to return to the task you were performing before the research started.

Definitions

• Lookup Module: A dynamic link library (dll) that encapsulates a particular lookup technology that can support one or more lookup sources. For example, LiveResourceLookup.dll is the generic lookup module distributed with JAWS.
• Lookup Source: The XML database or data source that is queried. Some of the lookup sources provided with JAWS are Major League Baseball scores, National Football League scores, Top News Stories, Wikipedia, and Wiktionary. These items are visible to a JAWS user when he or she opens the Research It dialog box.
• LiveResourceLookup.dll: The Freedom Scientific lookup module. It resides in the LookupModules subdirectory of the JAWS program directory. This DLL can support multiple lookup sources: those created by Freedom Scientific and supplied with JAWS, and those created by third-party developers who want to create their own queries.
• Lookup Module Raw Name: The name of a lookup module DLL, if one has been implemented and it has no rule sets associated with it (for example, MyLookup.dll), or the name of a rule set file (for example, LRL_Wiki) if the module uses them.
• Lookup Module Friendly Name: The localized name of a lookup module. This name is used in the Configuration Manager as well as the Lookup Module selection dialog which is displayed by the scripts. For a custom DLL, the developer can specify this information inside the DLL. For a rule set, this is the value from the RUL file.
• Rule Set: A rule set is a set of instructions that allow users to quickly and easily specify how to access information from a lookup source. Users can create rule sets for new lookup sources and use them with Freedom Scientific’s generic lookup module and scripts. A rule set consists of an RUL file, which specifies the friendly name, description, and other configuration information, and a QRY file, which contains the XQuery used to query the lookup source.
• Primary Lookup Source: This is the default lookup source as set in Configuration Manager by a JAWS user.
• Research It: A JAWS feature that uses queries written in XQuery to search XML databases and other data sources. A developer creates a rule set to perform the search. When implemented, a JAWS user can launch Research It using a variety of JAWS keystrokes. When initiated, the feature uses the selected lookup resource, as defined by a rule set, to display data in the JAWS Virtual Viewer window. After reading or copying the data, the user closes the Virtual Viewer and returns to his or her previous cursor location prior to launching the search.
• XQilla: An open source implementation of XQuery. Developers who are creating Research It rule sets can use XQilla functions in their queries. These functions are documented at http://xqilla.sourceforge.net/ExtensionFunctions.
• Rule File: A rule file is a file with the RUL extension. The rule file contains general configuration information for a rule set.
• Query File: A query file is a file with the QRY extension. The query file contains the XQuery used to gather information from the lookup source.
• JAWS Key: The primary modifier key used with JAWS keystrokes. In the Desktop keyboard layout, the INSERT key is used by default. In the Laptop keyboard layout, the CAPS LOCK key is used by default.
• JAWS Key+WINDOWS Key+R: The JAWS keystroke that launches Research It. The primary lookup source is used.
• JAWS Key+CTRL+WINDOWS Key+R: A JAWS keystroke that opens the Research It edit field. Use it to type and submit a search string and then select any lookup source to use.
• JAWS Key+SPACEBAR, R: A JAWS keystroke that opens the Research It edit field. Use it to type and submit a search string and then select any lookup source to use. This is the most efficient way for a user to launch Research It.
• JAWS Key+F2: The JAWS keystroke that opens the JAWS Manager dialog box. You can then select Research It from the available list of managers to run the Research It feature, or you can select Configuration Manager from the list to set the Research It options for a specific application.

Back to top from Definitions

Creating a Custom Rule Set

At its core, Research It consists of a lookup module and a rule set. The Freedom Scientific lookup module, LiveResourceLookup.dll, supports user-defined rule sets. A rule set consists of a query and a variety of settings that specify how the rule set is exposed to the end user and how the query is executed.

To create a custom rule set, you must provide two files: a rule file, which uses the .rul file name extension, and a query file, which uses the .qry file name extension. Both files must use the same base name, for example, Wiktionary.rul and Wiktionary.qry. For additional information, see File Name and File Folder Location.

Use a text editor to create the rule and query files.

Key Name	Value
FriendlyName	A string specifying a “friendly” name for the rule set. Mandatory. Maximum 100 characters. This is the text that appears in the lookup source list when a JAWS user opens the Research It dialog box.
Description	A string containing a brief description for the rule set. Optional. Maximum 500 characters. This is the information that appears when a JAWS user selects the Description button in the Research It dialog box in JAWS Configuration manager.
Timeout	An unsigned integer containing the timeout in milliseconds to be used for queries. Any query using this rule set will be aborted if it exceeds the timeout specified. The default timeout is 15000 milliseconds. This value is used if no timeout value is specified. A longer timeout may be required if the Web site that is queried is slow, or a large amount of data is returned, or if the query is complicated.

Rule File Example

The following is an example of a valid RUL file:

Query File (.qry)

The query file uses XQuery to retrieve a specific resource (for example, a Wikipedia page), parse the results, and then return output as a single string. A number of additional XQilla and XSLT functions are available for use within the query file. The XQilla implementation of XQuery lets you parse an HTML page as an XML document. For additional details and information, refer to http://xqilla.sourceforge.net/ExtensionFunctions.

The method to get the HTML document as an XML document node is:

where $URL is the full URL path string.

Search Token

Within a query file, you can use the token |ARG_1...ARG_n| to mark a location where input is substituted into the query string. It is not necessary to place the token directly into a search URL. You can place a token into a variable that can be further parsed or modified prior to its use. This lets you pass multiple arguments into |ARG_1...ARG_n| and parse them into separate variables within the query code.

Query File Example

The following is an example of a valid query:

In this query, the |ARG_1...ARG_n| token will be replaced by the search term that is passed down from the JAWS script.

Function Library for Query Tasks

Freedom Scientific has a function library to aid you in performing common query tasks. Import the library in your query using an import statement:

You can then use functions and variables from the ResearchItLibrary in your own scripts; just prefix those calls with the namespace you chose (fsi, in the previous example). For example, the ResearchItLibrary function "output-clean-lines" allows you to easily output a sequence of nodes as plain text, separated by new lines, with whitespace normalized:

The ResearchItLibrary.jri file is located in the LookupModules subfolder of the JAWS folder. For example: C:\Program Files\Freedom Scientific\JAWS\<version number>\LookupModules.

Use a text editor to open and read the file.

File Name and File Folder Location

When naming and saving rule set files, do the following:

• Use the .rul file name extension for the RUL file.
• Use the .qry file name extension for the QRY file.
• Use the same base name for both the RUL and QRY files, for example, Wiktionary.rul and Wiktionary.qry.
• Save both RUL and QRY files to the same RuleSets folder.
  
  For example, in Windows 7 and Windows Vista, save rule set files to the following user location:
  
  
  C:\Users\<user name>\AppData\Roaming\Freedom Scientific\JAWS\<version number>\SETTINGS\enu\RuleSets\<file name.rul> and <file name.qry>
  
  In Windows XP, save rule set files to the following user location:
  
  
  C:\Documents and Settings\<user name>\Application Data\Freedom Scientific\JAWS\<version number>\SETTINGS\enu\RuleSets\<file name.rul> and <file name.qry>

Shortcut to JAWS User and Shared Locations

When JAWS is installed, you can quickly access user and shared folder locations using the Explore JAWS submenu. To use this shortcut, do the following:

1. Press WINDOWS Key to open the Start menu.
2. Select All Programs and then press RIGHT ARROW.
3. Press J to navigate to the correct JAWS submenu version (for example, JAWS 11.0), and then press RIGHT ARROW to open the JAWS program group. The Explore JAWS submenu is the first item.
4. Press RIGHT ARROW and then do one of the following:

5. Finally, select and open the RuleSets folder.

Back to top from Creating a Custom Rule Set

Testing a Rule Set with JAWS

After creating the rule set files, and copying the files to the appropriate user location on your computer, you can run a quick test using JAWS and JAWS scripts to verify if your lookup source works.

1. Launch JAWS.
2. Do one of the following to turn on Script Utility Mode:

3. Press JAWS Key+WINDOWS Key+D to launch the Select Rule Set to Debug dialog box. A list that contains all rule sets appears.
4. Press UP or DOWN ARROW to navigate to your rule set, and then press ENTER. The Apply Search Term to Debug dialog box opens.
5. Type one or more words into the edit field and press ENTER.
6. The Virtual Viewer window opens and displays an error code. If the rule set is successful, the error code is 0 and feedback, based on your query, appears. If the rule set fails, use the error code and feedback to help you troubleshoot your rule set files.

Making a Rule Set Discoverable

The following describes how to use the JAWS Configuration Manager (JCF) to make your rule set visible to JAWS while running the debugger as described earlier.

1. With JAWS running, press JAWS Key+F2 to open the Run JAWS Manager dialog box.
2. Press C to navigate to Configuration Manager in the list and then press ENTER.
3. Press ALT+S and then R to open the Research It Options dialog box.
   It contains a list box showing all lookup source items (rule sets) currently available to JAWS. Each item in the list has a check box. When an item’s check box is clear, it will not appear in the lookup list for the current JCF file.
4. Press UP or DOWN ARROW to select your rule set, and then press SPACEBAR to select the check box.
5. Select OK to save changes and close the Research It Options dialog box.
6. Press ALT+F followed by S to save Configuration Manager changes, and then ALT+F4 to close Configuration Manager.

Back to top from Testing a Rule Set with JAWS

Lookup Sources

The following briefly describes the lookup sources provided with JAWS. URLs are also available so that you can reference the actual locations where Research It looks for Web results. In most cases, these are mobile Web sites with simple pages, which are not as complicated as regular Web pages that you view in a full Web browser.

Wiktionary

This lookup source provides a dictionary description of the word at the current cursor location in a document or Web page. You can also use the edit field to enter a word to lookup. Wiktionary is the primary lookup source.

To verify the lookup source, use the following URL where the variable %term% is substituted for the item that you want to lookup.

Area Code to Location

This lookup source displays the city, state, or province for the U.S. or Canadian area code typed into the edit field.

To verify the lookup source, use the following URL where the variable %term% is substituted for the area code that you want to lookup.

Amazon Product Search

This lookup source displays search results from Amazon.com® for the word or item entered in the edit field. Results appear as links followed by price and shipping information.

To verify the lookup source, use the following URL where the variable %term% is substituted for the item that you want to lookup.

Bookshare Book Search

This lookup source displays search results from Bookshare.org based on an author’s name, a book’s ISBN number, or words found in a book title or book description. If a match is found, the result appears as a link containing the author, title, and copyright date.

To verify the lookup source, use the following URL where the variable %term% is substituted for the item that you want to lookup.

Business Search

Use this lookup source to find a specific or general business in your area. Search results will provide the name, address, and phone number.

The following describes the variables used in the Business Search URL:

• Use the %locationterm% variable for the zip code, city, or city and state to be used in the search.
• Use the %nameterm% variable for the type of business or business name to be used in the search.

To verify the lookup source, use the following URL:

Convert Currency

Use this lookup source to convert an amount of money from one currency into a foreign equivalent. The current day’s exchange rate is used to convert the currency values.

The following describes the variables used in the Convert Currency URL:

• Use the %amtterm% variable for the amount of money to be converted. A decimal point or comma can be used when typing an amount.
• Use the %fromterm% variable for the type of international currency to convert from. This variable is a currency abbreviation.
• Use the %toterm% variable for the type of international currency to convert to. This variable is a currency abbreviation.

To verify the lookup source, use the following URL:

FedEx Tracking

This lookup source returns delivery status information for a valid FedEx® tracking number.

To verify the lookup source, use the following URL where the variable %term% is substituted for a valid FedEx tracking number.

Health Search on WebMD

This lookup source provides search results from the Web site WebMD® for the words entered in the lookup edit field or located at the current cursor position in a document or Web page. If a match is found, results appear as links followed by a brief synopsis.

To verify the lookup source, use the following URL where the variable %term% is substituted for the item that you want to lookup.

MLB Scores

This lookup source reports major league baseball scores and schedules for the date entered in the edit field. If you do not enter a date, you will get today's schedule or game results.

To verify the lookup source, use the following URL where the variable %term% is substituted for the date that you want to lookup. Use the year, month, and day format (yyyymmdd) for the variable. Today's date will be used if no value is entered.

NFL Scores

This lookup source reports national football league scores and schedules for the date entered in the edit field. If you do not enter a date, you will get today's schedule or game results.

To verify the lookup source, use the following URL where the variable %term% is substituted for the date that you want to lookup. Use the year, month, and day format (yyyymmdd) for the variable. Today's date will be used if no value is entered.

People Search

This lookup source allows you to search for individuals using their first and last name, street name (optional), and location. Use semicolons to separate search terms, for example, John Smith; Main Street; St. Petersburg, Florida. Always use a comma to separate the city and state or province location.

The following describes the variables used in the People Search URL:

• Use the %firstterm% variable for the individual's first name.
• Use the %nameterm% variable for the individual's last name.
• The %streetterm% variable is optional. You do not have to enter a street name; however, it may help in refining search results. Substitute this variable for the street name to be used in the search.
• Use the %cityterm% variable for the city, zip code, or postal code to be used in the search.
• Use the %stateterm% variable for the U.S. state or Canadian province to be used in the search.

To verify the lookup source, use the following URL.

Reuters Top News Stories

This lookup source displays a synopsis of the top five news stories as reported by Reuters news agency. A link for the complete story is also available.

To verify the lookup source, use the following URL.

Stock Quotes

This lookup source displays current and up to 52-week historical financial information for the stock symbol entered in the edit field or selected from a document, spreadsheet, or Web page.

To verify the lookup source, use the following URL where the variable %term% is substituted for the stock symbol that you want to lookup. Make sure to replace the variable in both locations in the URL.

Time Search

This lookup source displays the current time and time zone for any location typed into the edit field.

The following describes how to format the %term% variable for the location that you want to lookup using the Time Search lookup source.

• Use the percent sign (%) followed by Hex code 2C to represent a comma inserted between a city and state, province, or country location.
• Use the plus sign (+) to represent a space after the comma. This is a Google Web convention.
  
  So, to lookup the time in London, England, you would type London%2C+England for the %term% variable.

To verify the lookup source, use the following URL.

UPS Tracking

This lookup source returns progress and delivery status information for a valid UPS™ tracking number.

To verify the lookup source, use the following URL where the variable %term% is substituted for a valid UPS tracking number.

Weather

This lookup source reports the current weather forecast for a city or location entered in the edit field.

To verify the lookup source, use the following URL where the variable %term% is substituted for the location that you want to lookup.

Wikipedia

This lookup source provides encyclopedia results for the word at the current cursor location in a document or Web page. You can also use the edit field to enter a word to lookup.

To verify the lookup source, use the following URL where the variable %term% is substituted for the item that you want to lookup.

Back to top from Lookup Sources

Lookup Module API

If you are interacting with a lookup source that does not support XQuery, or you must protect proprietary data, or your lookup source requires user authentication, then you must create your own DLL API. The following describes the API methods that your lookup module must support. Provide this information to your DLL API developer.

Initialize

Syntax

HRESULT Initialize(void);
Your implementation of Initialize should perform any initialization necessary for the lookup module. Any initialization that must not be performed in DllMain (thread creation, synchronization, etc.) should be performed here. JAWS call Initialize prior to calling any other lookup module functions.

Return Value
Return S_OK (0x00000000L) if initialization is successful, otherwise E_FAIL (0x80004005L).

DeInitialize

Syntax

HRESULT DeInitialize(void);
In DeInitialize, perform any cleanup necessary for the lookup module.

Any destruction that must not be performed in DllMain (thread destruction, synchronization, etc.) should be performed here. JAWS calls DeInitialize after all use of the lookup module is complete, immediately prior to calling FreeLibrary.

Return Value

Return S_OK (0x00000000L) if deinitialization is successful, otherwise E_FAIL (0x80004005L).

GetInterfaceSchema

In GetInterfaceSchema return the numeric version of the supported interface. The interface version specified in this documentation is 1. Should additional functions later be supported, the interface version should increment.

Syntax

HRESULT GetInterfaceSchema(
DWORD& dwSchema
);

Parameters

dwSchema [out]
dwSchema will receive the API schema supported by the Lookup Module.

Return Value

If the function succeeds, the return value is S_OK (0x00000000L). Otherwise, return a non-zero value.

GetFriendlyName

GetFriendlyName should return the friendly name(s) for a lookup module or the rule sets belonging to the module.
If a lookup module has no rule sets associated with it, return the localized name for the lookup module.
If a lookup module has rule sets, it returns a bar-delimited list of colon-delimited file name:friendly name pairs for the lookup module.

Example:

LRL_MLB:MLB|LRL_NFL:NFL|LRL_Wiki:Wikipedia

Syntax

HRESULT GetFriendlyName (
LPWSTR lpszName,
DWORD& dwSize
);

Parameters

lpszName [out]
A pointer to a buffer that receives a localized name for the module or file name-friendly name pairs for supported rule sets.

dwSize [in, out]
The size of the lpszName buffer in wide chars. If the output data is larger than the supplied buffer, upon return, this variable should be set to the required size.

Return Value

If the function succeeds, return S_OK (0x00000000L). Otherwise, return one of the following errors:

E_INVALID_ARG (0x80070057L)
lpszName is NULL or dwSize is 0.

E_INSUFFICIENT_BUFFER (0x802A0001L)
lpszName is not large enough to hold the return data. Set dwSize to the required size.

Describe

Implement Describe to return a localized description of the lookup module or specified rule set.
HRESULT Describe (
LPCWSTR lpszRuleSet,
LPWSTR lpszOut,
DWORD& dwSize
);

Parameters

lpszRuleSet [in, optional]
Return a null terminated string containing the name of the RuleSet for which the description should be returned. If this value is null, then the general description for the lookup module should be returned.

lpszOut [out]
A pointer to a buffer that receives the output data.

dwSize [in, out]
The size of the lpszOut buffer in wide chars. If the output data is larger than the supplied buffer, upon return, this variable should be set to the required size.

Return Value

If the function succeeds, return S_OK (0x00000000L). Otherwise, return one of the following errors:

E_INVALIDARG (0x80070057L)
Use this to indicate an invalid argument.

E_RULESET_NOT_FOUND (0x802A0002L)
The rule set specified by lpszRuleSet is not supported by the lookup module.

E_INSUFFICIENT_BUFFER (0x802A0001L)
lpszName is not large enough to hold the return data. Set dwSize to the required size.

Invoke

Implement Invoke to perform the lookup work for your module. Invoke should perform the work synchronously.

Syntax

HRESULT Invoke (
LPCWSTR lpszRuleSet,
LPCWSTR lpszIn,
LPCWSTR lpszContext,
DWORD dwOffset,
LCID lcidAppLocale,
LPWSTR lpszOut,
DWORD& dwSize,
LPVOID lpExtra = NULL
);

Parameters

lpszRuleSet [in, optional]
An optional null-terminated string that contains the name of the rule set that the lookup module must use to perform the query.

lpszIn [in]
A null terminated string containing the input data for the query. This may be the word or phrase at the current cursor. This value may be NULL if the lookup module utilizes the Context and Offset arguments.

lpszContext [in]
A null terminated string containing context data for the query. For example, some lookup modules may utilize the sentence or paragraph containing the target word. This argument can be NULL.

dwOffset [in]
The 0-based offset of the targeted word in lpszContext. 0xffffffff indicates no offset.

lcidAppLocale [in]
The locale ID of the calling application. This will allow you to select an appropriate localized lookup source, display a localized UI, or return error messages in the application’s language.

lpszOut [out]
A pointer to a buffer that receives the output data. Depending on the lookup module, this could be an error, command, replacement string, etc.

Return Value

If the function succeeds, return S_OK (0x00000000L). Otherwise, return one of the following errors as appropriate to your module:

E_INVALIDARG (0x80070057L)
The rule set specified by lpszRuleSet is not supported by the lookup module.

E_INSUFFICIENT_BUFFER (0x802A0001L)
lpszName is not large enough to hold the return data. In this case, set dwSize to the required buffer size (in characters including the null terminator) required to hold the data.

E_RULESET_NOT_FOUND (0x802A0002L)
The requested rule set was not found.

E_REQUEST_FAILED (0x802A0003L)
The lookup attempt failed.

E_REQUEST_NO_RESULTS (0x802A0004L)
The lookup succeeded, but there were no results for the search term.

E_REQUEST_TIMEOUT (0x802A0005L)
The lookup took longer than the allowed amount of time.

Back to top from Lookup Module API

Built-in Script API

Built-in functions are functions created by Freedom Scientific developers. They are used as building blocks for your scripts and functions. Although built-in functions can be used anywhere, they cannot be modified.

For an introduction to the Freedom Scientific scripting language, refer to the Basics of Scripting manual on the Freedom Scientific Web site. It provides detailed information on scripting terms, syntax, functionality, and more. There are also numerous exercises to help you practice what you have learned. The Basics of Scripting manual is available in HTML Help format.

The following built-in script functions are available for Research It.

LRL_GetPrimaryLookupModule

The primary lookup module is the one designated to be used when the user single presses the LookupModuleInvoke keystroke. The PrimaryLookupModule key is stored in the JAWS Configuration File [options] section. The key may be application specific.

Syntax

int GetPrimaryLookupModule (
String BYREF strLookupModule,
String BYREF strRuleSet
)

Parameters

strLookupModule [out]
A string that will receive the name of the primary lookup module.

strRuleSet [out]
A string that will receive the rule set name of the primary lookup module. If there is no rule set, the string will be set to “”.

Return Value

If the function succeeds, TRUE (1) is returned. Otherwise FALSE (0) is returned.

LRL_GetFirstLookupModule

LRL_GetFirstLookupModule is used to begin an iteration through the active lookup module/RuleSet combinations. LRL_GetFirstLookupModule will return an index which can be used in the argument to LRL_GetNextLookupModule.

Syntax

LRL_GetFirstLookupModule (
String BYREF strLookupModule,
String BYREF strRuleSet
)

Parameters

strLookupModule [out]
A string that will receive the name of the first lookup module/rule set combination.

strRuleSet [out]
A string that will receive the rule set name of the first lookup module/rule set combination. If there is no rule set, the string will be set to “”.

Return Value

If the function succeeds, TRUE (1) is returned. Otherwise FALSE (0) is returned. If TRUE is returned, the return value can be passed to LRL_GetNextLookupModule to retrieve the next lookup module/rule set combination.

LRL_GetNextLookupModule

LRL_GetNextLookupModule is used to continue an iteration through the active lookup module/RuleSet combinations.

Syntax

LRL_GetFirstLookupModule (
int nDex,
String BYREF strLookupModule,
String BYREF strRuleSet
)

Parameters

strLookupModule [out]
A string that will receive the name of the next lookup module/rule set combination.

strRuleSet [out]
A string that will receive the rule set name of the next lookup module/rule set combination. If there is no rule set, the string will be set to “”.

Return Value

If the function succeeds, TRUE (1) is returned. Otherwise FALSE (0) is returned.

LRL_Invoke

Invoke performs a request from a lookup module.

Syntax

int LRL_Invoke (
String strModuleName,
String strRuleSet,
String strIn,
String strContext,
Int nOffset,
String BYREF strOut,
String strExtra
);

Parameters

strModuleName [in]
A string that contains the name of the lookup module.

strRuleSet [in]
A string that contains the rule set specifier that the lookup module may use to perform the query. This string may be “” if no rule set applies.

strIn [in]
A string containing the input data for the query. This may be the word or phrase at the current cursor. This value may be “” if the lookup module utilizes the Context and Offset arguments.

strContext [in]
A string containing context data for the query. For example, some lookup modules may utilize the sentence or paragraph containing the target word. This argument can be “”.

nOffset [in]
The 0-based offset of the targeted word in lpszContext. -1 indicates no offset.

strOut [out]
A string that will be populated with the returned text.

String strExtra [in]
A string that may be populated with custom formatted, lookup module specific information. For example, a translation lookup module may include information about the input and output locales for the translation. This string may be “”.

Return Value

If the function succeeds, TRUE (1) is returned. Otherwise one of the following error codes is returned:

E_INVALIDARG (0x80070057L)
Use this to indicate an invalid argument.

E_RULESET_NOT_FOUND (0x802A0002L)
The requested rule set was not found.

E_REQUEST_FAILED (0x802A0003L)
The lookup attempt failed. Indicates a malformed query.

E_REQUEST_NO_RESULTS (0x802A0004L)
The lookup succeeded, but there were no results for the search term.

E_REQUEST_TIMEOUT (0x802A0005L)
The lookup took longer than the allowed amount of time.

Back to top from Built-in Script API

Script Wrapper Functions

void RunLookupModuleQuery(string strQuery, string sRuleSet, string sModule, string strError)

Return Type:  void

Parameters:

string strQuery
The text to send to the lookup module and rule set combination.

string sRuleSet
The rule set to apply to the supplied Lookup module.  If no module was supplied, the FSLookup module will be used.  Leave this param blank if you are using the primary (default) or your module does not accept rule sets.

string sModule
Optional lookup module to use.  If not supplied, the FSLookup Module will be used.

string strError
optional error string to use if the query causes Invoke to return non-0 or the string is empty

Description:  Run Query either based on the supplied lookup module / rule set combination, or one or more of the optional parameters.  You can leave both Rule set and Module blank to use the primary lookup module, or fill in one or both parameters.  Fill in just he rule set parameter if you want to use the FS Lookup module.  This is the case unless you have written or been supplied with a module dll using the Live Resource Lookup API.  Most rule sets that apply to web services will use FSLookup (the default).

void RunLookupModuleQueryUsingListOfModules(string strQuery)

Return Type:  void

Parameters:

string strQuery
The query to use - generally the word or selection at the active cursor.

Description:  Generates a list of rule set - lookup module combinations, and generates a query based on the incoming text and the user's choice from the list.

void DebugLookupModuleQueryUsingListOfModules()

Return Type:  void

Description:  Debug output for rule set.  Error codes / text are placed in the Virtual Viewer for developers of rule sets and/or modules.  This function only displays what's thrown up by Invoke calls.  No parameters, as it runs as a stand-alone providing both a list of available rule sets and a prompt to enter the search term.  To make your rule set discoverable first, put at least a dummy version of the files into the RuleSets folder of your subdirectory.  Then go to Configuration Manager | Research It options and make sure yours is checked, so it's available for listing.  When asked for the search term, press ESC to send a blank string, or type the term and press ENTER.

Back to Top