Автор:	© Анатолий Камынин
Дата публикации:	2010

Кроме известной библиотеки JfwAPI, позволяющей приложениям при помощи сообщений MS Windows напрямую взаимодействовать с программой экранного доступа JAWS , существует другой вариант такого взаимодействия. Этот вариант основан на реализованном в JAWS компоненте OLE-Automation, интерфейс которого, названный IJawsApi , содержит методы, аналогичные по своему назначению функциям из JfwAPI.

Очевидным преимуществом взаимодействия через интерфейс IJawsApi является возможность использовать его не только в приложениях, но и сценариях на таких языках, как JScript, VBScript, AutoIt и так далее, то есть в тех языках, где реализована поддержка механизмов OLE-Automation. В остальном методы IJawsApi страдают теми же недостатками, что и функции JfwApi. В причины этого мы вдаваться не будем, а сразу перейдём к изучению методов IJawsApi.

Методы IJawsApi

Интерфейс IJawsApi поддерживает шесть методов. За исключением метода StopSpeech, все методы возвращают в случае успешного выполнения значение -1 (минус один), интерпретируемое как true; а в случае ошибки возвращают значение 0, интерпретируемое как false. Ниже представлен список методов с кратким описанием их параметров:

• Выполнить скрипт JAWS:
  Object.RunScript(parameter1);
  где parameter1- строковая переменная или строковый литерал с именем выполняемого скрипта JAWS.
• Произнести фрагмент текста:
  Object.SayString(parameter1, parameter2);
  где parameter1 -- это строковая переменная или строковый литерал с озвучиваемым текстом, parameter2 -- это опциональный параметр, указывающий , надо ли немедленно прервать текущий речевой вывод JAWS (по умолчанию равен -1, т.е. текущий речевой вывод будет прерван при вызове этого метода).
• Прервать речь JAWS:
  Object.StopSpeech();
  Метод не возвращает значений.
• Недокументировано:
  Object.Enable(parameter1);
  где parameter1 -- либо true (или -1), либо false (или 0).
• Недокументировано:
  Object.Disable();
  Вызов этого метода, по всей видимости, приводит к переходу JAWS в "спящий" режим(однако вызов методов IJawsApi поддерживается и в этом состоянии). Вернуть JAWS в активное состояние позволяет вызов метода Enable().
• Выполнить функцию JAWS:
  Object.RunFunction(parameter1);
  где parameter1 -- это строковая функция или строковый литерал с полной строкой вызова функции, т.е. с именем функции и фактическими аргументами, заключенными в круглые скобки.

Инициализация

Прежде чем использовать интерфейс IJawsApi нужно создать сам объект OLE-Automation. В различных скриптовых языках это действие может выполняться различными способами, но большинство из них имеют схожую семантику. Как правило, в качестве аргумента передается независимый от версии строковый идентификатор объекта (VersionIndependentProgID), который в нашем случае выглядит так: "FreedomSci.JawsApi".

Конкретные примеры будут рассмотрены далее.

Примеры

В качестве примеров ниже приводятся фрагменты кода на JScript и AutoIt. Ради простоты изложения, в коде обработка ошибок сведена к минимуму.

Пример на JScript

// Файл: hello.js
// Пример использования IJawsApi.

// Инициализировать объект и получить интерфейс
var jawsApi = new ActiveXObject("FreedomSci.JawsApi");

// произнести строку
jawsApi.SayString("Hello, world!");

// выполнить скрипт, озвучивающий текущее время
jawsApi.RunScript("SaySystemTime");

// вызвать последовательно несколько функций
jawsApi.RunFunction("TypeKey(\"Ctrl+Esc\")");
jawsApi.RunFunction("Delay(10)");
jawsApi.RunFunction("TypeKey(\"Esc\")");

Пример на AutoIt

; Файл hello.au3
; Пример использования IJawsApi.

$oJawsApi= ObjCreate("FreedomSci.JawsApi")
if @error then
	Msgbox(0,"JawsApi Test","Failed to create OLE-Object. Error code: " & hex(@error,8))
	exit
endif

; произнести строку
$oJawsApi.SayString("Hello, world!")

; выполнить скрипт, озвучивающий текущее время
$oJawsApi.RunScript("SaySystemTime")

; вызвать последовательно несколько функций
$oJawsApi.RunFunction('TypeKey("Ctrl+Esc")')
$oJawsApi.RunFunction("Delay(10)")
$oJawsApi.RunFunction('TypeKey("Esc")')

exit

Пример для C#

Для C# ниже приведены фрагменты кода с инициализацией объекта JfW API, а также вызов одного из методов. Остальные методы API можно вызывать аналогичным образом

// Рабочий фрагмент для .Net 3.5:

 Type jfwApi = Type.GetTypeFromProgID("FreedomSci.JawsApi");
 object o = Activator.CreateInstance( jfwApi);
jfwApi.InvokeMember("SayString",
System.Reflection.BindingFlags.InvokeMethod,
null,
o,
new Object[1] {"Hello"});
...

// В .net 4.0 должен работать пример для .Net 3.5,
// но также вполне пригоден следующий вариант :
Type jfwApi = Type.GetTypeFromProgID("FreedomSci.JawsApi");
dynamic o= Activator.CreateInstance( jfwApi);
o.SayString("hello");
...

Использование IJawsApi в программах на C++

Для использования интерфейса IJawsApi в программе на C++ необходимо создать заголовочный файл с объявлением соответствующего класса и файл с определением GUID для объекта и IID для интерфейса.

Если используемый компилятор поддерживает директиву #import, то эту задачу можно возложить на нее, указав в качестве импортируемого файл Fsapi.dll. Полный путь к этому файлу можно узнать из системного реестра, отыскав ветку:

HKEY_CLASSES_ROOT\CLSID\{CCE5B1E5-B2ED-45D5-B09F-8EC54B75ABF4}\

И Искомое значение будет находиться в подразделе InprocServer32.

Если компилятор не поддерживает директиву #import, то необходимые файлы придется создавать вручную. Ниже приведены исходные тексты файлов jawsapi.h и guids.cpp, написанные, так сказать, в духе "чистого COM".

// Файл: jawsapi.h
// Объявление интерфейса IJawsApi.
#ifndef __JAWSAPI_H__
#define __JAWSAPI_H__

#include 
#include 

#undef INTERFACE
#define INTERFACE  IJawsApi

DECLARE_INTERFACE_(IJawsApi ,IDispatch)
{
	STDMETHOD(RunScript)(THIS_ /* [in] */ BSTR ScriptName, VARIANT_BOOL* retval) PURE;
	STDMETHOD(SayString)(THIS_ /*  [in]*/ BSTR StringToSpeak,
				/*[in, optional, defaultvalue(-1)]*/ VARIANT_BOOL bFlush, VARIANT_BOOL* retval) PURE;
	STDMETHOD(StopSpeech)(THIS_ ) PURE;
	STDMETHOD(Enable)(THIS_ /*[in]*/ VARIANT_BOOL vbNoDDIHooks,
				VARIANT_BOOL* retval) PURE;
	STDMETHOD(Disable)(THIS_ VARIANT_BOOL* retval) PURE;
	STDMETHOD(RunFunction)(THIS_ /*[in]*/ BSTR FunctionName, VARIANT_BOOL* retval) PURE;
};
#endif

// Файл: guids.cpp.
#include 
#include 
#include 

/* {CCE5B1E5-B2ED-45D5-B09F-8EC54B75ABF4} */
DEFINE_GUID(CLSID_JAWSCLASS ,
0x0CCE5B1E5, 0x0B2ED, 0x45D5,0xB0, 0x9F, 0x8E, 0x0C5, 0x4B, 0x75, 0x0AB, 0x0F4);

/* {123DEDB4-2CF6-429C-A2AB-CC809E5516CE} */
DEFINE_GUID(IID_IJAWSAPI ,
0x123DEDB4,0x2CF6, 0x429C, 0x0A2, 0x0AB, 0x0CC, 0x80, 0x9E, 0x55, 0x16, 0x0CE);

Файл guids.cpp должен быть включён в проект (если используется интегрированная среда разработки) или указан в командной строке компилятора непосредственно. Файл jawsapi.h подключается при помощи директивы #include в тех файлах с исходным кодом, где предполагается использовать интерфейс IJawsApi. Также в этих файлах необходимо объявить две внешние переменные:

extern const CLSID CLSID_JAWSCLASS ;
extern const IID IID_IJAWSAPI ;

Пример использования IJawsApi в программе на языке C++ приведён ниже. Это консольное приложение, единственным действием которого будет озвучивание текущего времени при помощи скрипта JAWS.