»спользование интерфейса IJawsApi

(— примерами на JScript, AutoIt, C# и C++)
ƒата публикации:2010
Twitter Facebook Vkontakte

 роме известной библиотеки 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.

// ‘айл: main.cpp #include #include "jawsapi.h" extern const CLSID CLSID_JAWSCLASS ; extern const IID IID_IJAWSAPI ; int main () { IJawsApi* pJawsApi= NULL; CoInitialize(NULL); HRESULT hr = CoCreateInstance(CLSID_JAWSCLASS,NULL, CLSCTX_INPROC_SERVER, IID_IJAWSAPI, reinterpret_cast(&pJawsApi)); if (SUCCEEDED(hr) && pJawsApi) { VARIANT_BOOL retval; BSTR param = SysAllocString(L"SaySystemTime"); pJawsApi->RunScript(param,&retval); SysFreeString(param); } CoUninitialize(); return 0; }

ѕриведЄнный пример можно скомпилировать компил€тором из набора Borland Builder C++ 5.5 command line tools или C++-компил€тором из пакета MinGW (в последнем случае в опци€х командной строки компил€тора необходимо добавить: -lole32 -loleaut32).



–аспространение материалов сайта означает, что распространитель прин€л услови€ лицензионного соглашени€.
»де€ и реализаци€: © ¬ладимир ƒовыденков и јнатолий  амынин,  2004-2021