Расширения HandyCache

Расширения HandyCache

Расширение представляет из себя организованный специальным образом скрипт на языке lua .

Для начала использования расширений в HandyCache необходимо чтобы в папке HandyCache находился файл библиотеки lua5.x.dll.

В начале расширения располагается заголовок. Заголовок имеет следующую структуру:

--[[ <HCEXTENSION>
@field  value
@field  value
@field  value
...
@field  value
</HCEXTENSION> ]]

Поля заголовка расширения

Имя (field)

Значение (value)

name Наименование расширения
author Имя автора расширения
version Номер версии расширения
description Краткое описание расширения
rule Правило (регулярное выражение), которым будет проверяться URL запроса перед вызовом расширения. В заголовке может быть несколько полей rule.
exception Исключение (регулярное выражение), которым будет проверяться URL запроса перед вызовом расширения. В заголовке может быть несколько полей exception.
event Наименование события, для обработки которого будет вызываться расширение, и через косую черту имя функции, предназначенной для обработки этого события. В заголовке может быть несколько полей event.

 

Пример заголовка расширения

--[[ <HCEXTENSION>
@name          Save or block 403 and 404
@author        DenZzz
@version       0.01
@description   Сохраняет или блокирует ответы 403 и 404
@exception     _rtsi?_|rts_chart_ru|informer\.rts\.ru/|aton-line\.ru/.*index\.gif
@exception     ^http://[^/]*rambler\.ru/|^http://192\.168\.\d+\.
@event         AnswerHeaderReceived/answer
</HCEXTENSION> ]]

За заголовком следуют функции-обработчики событий, а также функции вызываемые из этих обработчиков. Когда в HandyCache наступает событие, для которого зарегистрирован обработчик, вызывается соответсвующая функция.

Список обрабатываемых событий

Событие

Условия возникновения

Init Возникает при загрузке расширений во время старта HandyCache и при нажатии кнопки Перечитать расширение на вкладке Настройки/Расширения. При загрузке расширения текст файла расширения сохраняется в памяти. Поэтому, если файл расширения изменился, нужно выделить расширение в списке и нажать кнопку Перечитать расширение .
Options Возникает при нажатии кнопки Настройки расширения на вкладке Настройки/Расширения .
Timer1s Возникает раз в секунду.
Timer1m Возникает раз в минуту.
URLToFileNameConverting Возникает, когда требуется выполнить преобразование URL в имя файла в кэше.
RequestHeaderReceived Возникает, когда получен заголовок запроса от клиента.
BeforeRequestHeaderSend Возникает, когда заголовок запроса готов к отправке на сервер.
AnswerHeaderReceived Возникает, когда получен заголовок ответа от сервера.
BeforeAnswerHeaderSend Возникает, когда заголовок ответа готов к отправке клиенту. Заголовок может быть получен от сервера или сформирован самим HandyCache.
BeforeAnswerBodySend Возникает, когда получена очередная порция данных для отправки клиенту. Данные могут быть получены от сервера или взяты из кэша. Если данные упакованы, то они перед передачей обработчику распаковываются.
Destroy Возникает при завершении работы расширения (при удалении расширения по кнопке Удалить расширение, при перезагрузке расширения по кнопке Перечитать расширение, при закрытии HandyCache)

Перед вызовом функций расширения HandyCache создает  в lua-машине две таблицы: hc и re. В первой собраны значения и функции, позволяющие получать информацию о значениях внутренних переменных HandyCache и изменять некоторые из них. Во второй собраны функции, позволяющие использовать в расширениях возможности библиотеки регулярных выражений PCRE .

Значения таблицы hc, доступные в расширениях

Имя

 Допустимые действия

События

Допустимые значения

Описание
script_name чтение

Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend, Destroy 

"<строка>" Имя текущего расширения.
event чтение

Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySen, Destroy 

"<строка>" Содержит наименование обрабатываемого события.
ini_path чтение

Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerBodySend, Destroy 

"<строка>" Содержит путь к папке с файлами настройки.
cache_path чтение

Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerBodySend, Destroy

"<строка>" Содержит путь к папке кэша.
url чтение URLToFileNameConverting, RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend В соответствие с RFC 2616 п.3.2.2 URL запроса
method чтение RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend В соответствие с RFC 2616 п.9 Метод, использованный в запросе
use_proxy чтение, запись RequestHeaderReceived, BeforeRequestHeaderSend "<строка>" Содержит параметры внешнего HTTP прокси-сервера, назначенного для текущего запроса. Пример: "192.186.55.2:8080" или "proxy.com:8081"
use_proxy_login чтение, запись RequestHeaderReceived, BeforeRequestHeaderSend "<строка>" Содержит логин доступа внешнего HTTP прокси-сервера, назначенного для текущего запроса (basic-авторизация). Пример: "user:password"
use_bound_ip чтение, запись RequestHeaderReceived, BeforeRequestHeaderSend "<строка>" Содержит IP-адрес сетевого устройства, через которое будет отправлен запрос. Пример: "192.186.0.2"
request_header чтение, запись RequestHeaderReceived, BeforeRequestHeaderSend В соответствие с RFC 2616 Содержит заголовок запроса. Если расширение изменит значение этой переменной, измененный заголовок будет отправлен серверу.
cache_file_name чтение RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived "<строка>" Имя файла в кэше, соответсвующего текущему запросу.
cache_file_size чтение RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived <число> Размер файла в кэше (-1 если файла нет).
cache_file_age чтение RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived <число> Возраст файла в кэше в секундах.
cache_file_content_type чтение RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived "<строка>" Тип содержимого файла в кэше.
user_name чтение URLToFileNameConverting, RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend "<строка>" Имя пользователя, от которого поступил запрос.
user_from_internet чтение RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend <число> Количество данных, полученных пользователем из интернета за текущие сутки.
user_from_cache чтение RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend <число> Количество данных, полученных пользователем из кэша за текущие сутки.
user_to_internet чтение RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend <число> Количество данных, отправленных пользователем за текущие сутки.
answer_header чтение, запись RequestHeaderReceived, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend В соответствие с RFC 2616 Заголовок ответа, полученный от сервера или сформированный расширением. Если этой переменной расширение присвоило новое значение, то клиенту будет передан измененный заголовок.
answer_body чтение, запись RequestHeaderReceived, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend "<строка>",
"file=<имя файла>",
"file=URLToCache(<URL>)"

При обработке событий RequestHeaderReceived, AnswerHeaderReceived, BeforeAnswerHeaderSend содержит тело ответа, сформированное расширением. Если этой переменной присвоено значение, то клиенту будет передано содержимое этой переменной в качестве тела ответа.
Этой переменной вместо непосредственно тела ответа может быть присвоено также имя файла, который будет использован в качестве тела ответа ("file=c:\abc\qwerty.html"), или URL ("file=URLToCache(http://site.ru/abc.gif)"). В последнем случае в качестве тела ответа будет использован файл в кэше, соответствующий указанному URL.

При обработке события BeforeAnswerBodySend через эту переменную расширение получает очередную порцию данных для обработки. В эту же переменную расширение записывает результат обработки.
last_part чтение BeforeAnswerBodySend true, false Принимает значение true, когда расширение вызывается последний раз для обработки текущего запроса.
action чтение, запись RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived Для RequestHeaderReceived:
"stop",
"dont_update",
"only_from_cache",
Для AnswerHeaderReceived:
"stop",
"dont_update",
"save",
"dont_save"		 Действие, которое должен выполнить НС:
  • "stop" - заблокировать загрузку;
  • "dont_update" - не обновлять файл (отдать из кэша).
  • "only_from_cache" - если файл есть в кэше, то отдать его клиенту, иначе заблокировать загрузку.
  • "save" - записать файл в кэш;
  • "dont_save" - не записывать файл в кэш, даже если сработал список Запись в кэш.
Если поставить знак "-" в конце названия действия, то данное действие будет применено только в случае активности соответствующего списка для данного запроса. Например: действие "stop-" заблокирует загрузку, только если Черный список не был отключен галкой Разрешить, горячей клавишей или Белым списком .
read_from_cache_on чтение, запись RequestHeaderReceived true, false Присвоение false запрещает чтение из кэша для текущего запроса.
white_mask чтение, запись RequestHeaderReceived "<строка>" Маска Белого списка - в эту переменную можно добавить по одному символу для каждого из списков, если нужно, чтобы этот список не работал с данным запросом. Для обозначения списков можно использовать символы:
  • W или Б - Белый список
  • B или Ч - Черный список
  • S или З - список Запись в кэш
  • D или Н - список Не обновлять
  • O или Т - список Только из кэша
  • R или А - список Переадресация
  • U или П - список Преобразование URL
Символы могут быть строчные или заглавные. Например, для выключения Черного списка, списка Только из кэша и списка Преобразование URL значение переменной может быть такое: hc.white_mask="ЧТu".
file_speed_limit чтение, запись RequestHeaderReceived, AnswerHeaderReceived <число> Если этой переменной присвоить значение больше 0, то это значение будет использоваться как лимит скорости (в байтах в секунду) для загрузки данного файла.
user_speed_limit чтение, запись RequestHeaderReceived, AnswerHeaderReceived <число> Если этой переменной присвоить значение больше 0, то это значение будет использоваться как лимит скорости (в байтах в секунду) для данного пользователя до задания другого значения или перезапуска HandyCache. hc.user_speed_limit=0 снимает ограничения скорости для данного пользователя.
dont_load_large_files_on чтение

Init, Options, Timer1s, Timer1m,
RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend

true, false Принимает текущее состояние опции Не загружать большие файлы.
speed_limit_on чтение

Init, Options, Timer1s, Timer1m,
RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend

true, false Принимает текущее состояние опции Ограничить скорость загрузки.
offline_on чтение

Init, Options, Timer1s, Timer1m,
RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend

true, false Принимает текущее состояние опции Автономный режим.
monitor_string чтение, запись URLToFileNameConverting, RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend "<строка>" Содержит значение, присвоенное предыдущими расширениями при обработке текущего события. Расширение может присвоить свое значение этой переменной. Значение этой переменной будет выведено в колонке Правила в Мониторе в строке текущего запроса.

Функции таблицы hc

Имя

Описание

shell_execute

Функция является оберткой Windows API функции ShellExecute (аргумент Operation="Open"). Подробнее смотрите здесь.

Аргументы функции:
File - имя открываемого файла;
Parameters - строка параматров, которая будет послана открываемому приложению;
Directory - стандартный каталог (default directory), передаваемый приложению.
ShowCmd - флаг, задающий состояние окна приложения при открытии, может принимать значения 'SW_HIDE', 'SW_MAXIMIZE', 'SW_MINIMIZE', 'SW_RESTORE', 'SW_SHOW', 'SW_SHOWDEFAULT','SW_SHOWMAXIMIZED', 'SW_SHOWMINIMIZED', 'SW_SHOWMINNOACTIVE', 'SW_SHOWNA', 'SW_SHOWNOACTIVATE', 'SW_SHOWNORMAL'.

Возвращаемое значение: Возвращает строку 'OK' при успешном вызове функции. В случае ошибки, возвращает сообщение об ошибке.

Пример использования: hc.shell_execute('notepad.exe', 'stat.txt', nil, 'SW_SHOW')

play_sound

Функция является оберткой Windows API функции PlaySound. Подробнее смотрите здесь.

Аргументы функции:
Sound - имя wav-файла или системного события ('SystemAsterisk', 'SystemDefault', 'SystemExclamation', 'SystemExit', 'SystemHand', 'SystemQuestion', 'SystemStart', 'SystemWelcome').

Возвращаемое значение: нет.

Примеры использования:
hc.play_sound('blocked.wav')
hc.play_sound('SystemExclamation')

execute_cmd

Функция выполняет команду (те же команды, что и для утилиты HCCmd).

Аргументы функции:
 Cmd - команда.

Список команд.
'AddToWhiteList URL' - добавить в Белый список
'AddToBlackList URL' - добавить в Черный список
'AddToSaveToCacheList URL' - добавить в список Запись в кэш
'AddToDontUpdateList URL' - добавить в список Не обновлять
'AddToOnlyFromCacheList URL' - добавить в список Только из кэша
'ViewWindow' - показать главное окно
'ViewWhiteList' - показать Белый список
'ViewBlackList' - показать Черный список
'ViewSaveToCacheList' - показать список Запись в кэш
'ViewDontUpdateList' - показать список Не обновлять
'ViewOnlyFromCacheList' - показать список Только из кэша
'WhiteList on|off|switch' - управление Белым списом
'BlackList on|off|switch' - управление Черным списом
'SaveToCacheList on|off|switch' - управление списом Запись в кэш
'DontUpdateList on|off|switch' - управление списом Не обновлять
'OnlyFromCacheList on|off|switch' - управление списом Только из кэша
'OffLine on|off|switch' - управление Автономным режимом
'RedirectList on|off|switch' - управление списом Переадресация
'FreshFiles on|off|switch' - управление опцией Не обновлять свежие файлы
'ReadFromCache on|off|switch' - управление чтением из кэша
'LoadURL' - загрузить URL в кэш
'DeleteURL' - удалить URL из кэша
'StopURL' - остановить загрузку URL
'ClearCache' - запустить очистку кэша
'Exit' - завершить выполнение программы
'URLTransformingList on|off|switch' - управление списом Преобразование URL
'DontLoadLargeFiles on|off|switch' - управление опцией Не загружать большие файлы
'SpeedLimit on|off|switch' - управление опцией Ограничить скорость загрузки
'MediatorServers on|off|switch' - управление списком серверов-посредников
'DNSCache on|off|switch' - управление DNS-кэшем
'ParentProxy on|off|switch' - управление внешними прокси
'UnconditionalProxy on|off|switch' - управление безусловными прокси
'ConditionalProxy on|off|switch' - управление условными прокси
'Statistics on|off|switch' - управление ведением статистики

Возвращаемое значение: нет.

Примеры использования:
hc.execute_cmd('BlackList on')
hc.execute_cmd('ClearCache')

put_msg

Функция вызывает появление на экране информационного окошка с заданным сообщением.

Аргументы функции:
Msg - сообщение.

Возращаемое значение: нет.

Пример использования: hc.put_msg('Очистка кэша запущена')

put_to_log

Функция помещает заданное сообщение в лог программы.

Аргументы функции:
Msg - сообщение.

Возращаемое значение: нет.

Пример использования: hc.put_to_log('method='..hc.method)

get_keyboard_state

Функция получает список нажатых клавиш.

Аргументы функции: нет.

Возвращаемое значение: Строка со списком нажатых клавиш.
Перечень имен клавиш:
'VK_LBUTTON', 'VK_RBUTTON', 'VK_CANCEL', 'VK_MBUTTON', 'VK_XBUTTON1', 'VK_XBUTTON2','VK_BACK', 'VK_TAB', 'VK_CLEAR', 'VK_RETURN', 'VK_SHIFT', 'VK_CONTROL', 'VK_MENU','VK_PAUSE', 'VK_CAPITAL', 'VK_KANA', 'VK_JUNJA', 'VK_FINAL', 'VK_HANJA', 'VK_KANJI','VK_ESCAPE', 'VK_CONVERT', 'VK_NONCONVERT', 'VK_ACCEPT', 'VK_MODECHANGE', 'VK_SPACE','VK_PRIOR', 'VK_NEXT', 'VK_END', 'VK_HOME', 'VK_LEFT', 'VK_UP', 'VK_RIGHT', 'VK_DOWN','VK_SELECT', 'VK_PRINT', 'VK_EXECUTE', 'VK_SNAPSHOT', 'VK_INSERT', 'VK_DELETE','VK_HELP', 'VK_0', 'VK_1', 'VK_2', 'VK_3', 'VK_4', 'VK_5', 'VK_6', 'VK_7', 'VK_8', 'VK_9','VK_A', 'VK_B', 'VK_C', 'VK_D', 'VK_E', 'VK_F', 'VK_G', 'VK_H', 'VK_I', 'VK_J','VK_K', 'VK_L', 'VK_M', 'VK_N', 'VK_O', 'VK_P', 'VK_Q', 'VK_R', 'VK_S', 'VK_T','VK_U', 'VK_V', 'VK_W', 'VK_X', 'VK_Y', 'VK_Z', 'VK_LWIN', 'VK_RWIN', 'VK_APPS','VK_SLEEP', 'VK_NUMPAD0', 'VK_NUMPAD1', 'VK_NUMPAD2', 'VK_NUMPAD3', 'VK_NUMPAD4','VK_NUMPAD5', 'VK_NUMPAD6', 'VK_NUMPAD7', 'VK_NUMPAD8', 'VK_NUMPAD9', 'VK_MULTIPLY', 'VK_ADD', 'VK_SEPARATOR', 'VK_SUBTRACT', 'VK_DECIMAL', 'VK_DIVIDE', 'VK_F1', 'VK_F2','VK_F3', 'VK_F4', 'VK_F5', 'VK_F6', 'VK_F7', 'VK_F8', 'VK_F9', 'VK_F10', 'VK_F11','VK_F12', 'VK_F13', 'VK_F14', 'VK_F15', 'VK_F16', 'VK_F17', 'VK_F18', 'VK_F19','VK_F20', 'VK_F21', 'VK_F22', 'VK_F23', 'VK_F24', 'VK_NUMLOCK', 'VK_SCROLL','VK_LSHIFT', 'VK_RSHIFT', 'VK_LCONTROL', 'VK_RCONTROL', 'VK_LMENU', 'VK_RMENU','VK_BROWSER_BACK', 'VK_BROWSER_FORWARD', 'VK_BROWSER_REFRESH', 'VK_BROWSER_STOP','VK_BROWSER_SEARCH', 'VK_BROWSER_FAVORITES', 'VK_BROWSER_HOME', 'VK_VOLUME_MUTE','VK_VOLUME_DOWN', 'VK_VOLUME_UP', 'VK_MEDIA_NEXT_TRACK', 'VK_MEDIA_PREV_TRACK','VK_MEDIA_STOP', 'VK_MEDIA_PLAY_PAUSE', 'VK_LAUNCH_MAIL', 'VK_LAUNCH_MEDIA_SELECT','VK_LAUNCH_APP1', 'VK_LAUNCH_APP2', 'VK_OEM_1', 'VK_OEM_PLUS', 'VK_OEM_COMMA','VK_OEM_MINUS', 'VK_OEM_PERIOD', 'VK_OEM_2', 'VK_OEM_3', 'VK_OEM_4', 'VK_OEM_5','VK_OEM_6', 'VK_OEM_7', 'VK_OEM_8', 'VK_OEM_102', 'VK_PROCESSKEY', 'VK_PACKET', 'VK_ATTN', 'VK_CRSEL', 'VK_EXSEL', 'VK_EREOF', 'VK_PLAY', 'VK_ZOOM', 'VK_NONAME','VK_PA1', 'VK_OEM_CLEAR'

Пример использования:
_,_,x = string.find(hc.get_keyboard_state(), 'VK_F11')
if x~=nil then ... end

systime_to_str

Функция преобразует системное время в строковое представление.

Аргументы функции:
time - время в числовом представлении;
gmt - формат представления времени, принимает значения true или false (по умолчанию true). Если передано значение true, то на выходе функции время будет по Гринвичу. Если передано значение false, то на выходе функции будет локальное время.

Возвращаемое значение: Время в строковом представлении.

Пример использования: s = hc.systime_to_str(os.time(), false)

str_to_systime

Функция преобразует строковое представление времени в числовое.

Аргументы функции:
str - время в формате, применяемом в http-заголовках;

Возращаемое значение: Время в числовом представлении (время в секундах, прошедшее после 0 часов 0 минут 1 января 1970 года).

Пример использования:
t1=hc.str_to_systime('Tue, 25 Nov 2008 02:52:14 GMT')
t2=os.time()
hc.put_to_log('C 25 ноября 2008 г. прошло '..(t2-t1)/3600/24..' дней')

prepare_path

Функция создает каталоги в соответсвии с путем, заданным аргументом.

Аргументы функции:
path - путь к папке;

Возвращаемое значение: Нет.

Пример использования: hc.prepare_path('c:\program files\handycache\cache\example')

call_me_for

Функция регистрирует функцию текущего расширения в качестве обработчика события для текущего запроса.

Аргументы функции:
event - наименование события;
function - имя функции текущего расширения;

Возвращаемое значение: Нет.

Пример использования: hc.call_me_for('BeforeAnswerBodySend', 'body')

server_disconnect

Разрывает соединение с сервером.

Аргументы функции: Нет.

Возвращаемое значение: Нет.

Пример использования: hc.server_disconnect()

prepare_url

Функция выполняет преобразование заданного URL в имя файла в кэше без вызова обработчика события URLToFileNameConverting.

Аргументы функции:
url - ссылка на сетевой ресурс;
URLTransformingList - разрешение использования списка Преобразование URL при исполнении функции, принимает значения true или false (по умолчанию true ).

Возвращаемое значение: Имя файла в кэше, полученное из заданного URL с помощью встроенного алгоритма преобразования;

Пример использования: local s= hc.prepare_url(hc.url)

preform_cache_file_name

Функция задает имя файла в кэше, которое может быть сформировано расширением в обработчике события URLToFileNameConverting. HandyCache, если потребуется, может изменить заданное имя файла для его адаптации к текущему состоянию кэша. Путь к файлу может быть задан абсолютным (начинается с имени диска) или относительным. Во втором случае в начало имени добавляется путь к папке кэша.

Замечание. По умолчанию HandyCache не использует файлы вне папки кэша. Чтобы разрешить использование файлов вне папки кэша, нужно в файл HandyCache.ini  в секции MainForm добавить строку ReadOnlyFromCachePath=False

Аргументы функции:
path - путь к файлу;

Возвращаемое значение: Нет.

Пример использования: hc.preform_cache_file_name('site1.ru\example.jpg')

get_cache_file_name

Функция получает имя файла в кэше и его наличие для заданного URL.

Аргументы функции:
url - ссылка на сетевой ресурс;

Возвращаемое значение: Первым значением возвращается имя файла; вторым - наличие файла в кэше (true/false );

Пример использования: s,e=hc.get_cache_file_name('http://handycache.ru/')

delete_cache_file

Функция удаляет файл в кэше, соответствующий заданному URL.

Аргументы функции:
url - ссылка на сетевой ресурс;

Возвращаемое значение: Нет.

Пример использования: hc.delete_cache_file('http://site.ru/example.gif')

update_url_info

Функция удаляет информацию о заданном файле из RAM-кэша и очищает внутренние переменные HandyCache, хранящие информацию об этом файле. Если информация о файле понадобится, она будет добываться из дискового кэша заново.

Аргументы функции:
url - ссылка на сетевой ресурс;

Возвращаемое значение: Нет.

Пример использования: hc.update_url_info('http://handycache.ru/')

set_global

Функция позволяет сохранить в памяти значение глобальной переменной. Сразу после завершения работы этой функции присвоенное значение будет доступно из других потоков.

Аргументы функции:
name - имя переменной, которой нужно присвоить значение value (если такой переменной нет, она будет создана);
value - значение, которое нужно присвоить глобальной переменной (тип значения - любой доступный в lua кроме функции); если этот аргумент пропущен или nil, то переменная с именем name будет удалена из памяти;

Возвращаемое значение: Нет.

Пример использования: hc.set_global('MyVar', 'Value')

get_global

Функция позволяет получить значение глобальной переменной.

Аргументы функции:
name - имя переменной, значение которой нужно получить;

Возвращаемое значение: Значение переменной name. Если переменной с заданным именем нет, то возвращается nil.

Пример использования:
 local t1={}
t1[1]=1
t1['item1']='first item'
local t2={}
t2[1]=11
t2[2]=22
t2[3]=t1
hc.set_global('var1', t2)
local t=hc.get_global('var1')
hc.put_to_log(t[3]['item1'])

window_pos

Функция получает положение и размер главного окна HandyCache.

Аргументы функции: Нет.

Возвращаемое значение: Первым значением возвращается горизонтальная координата верхнего левого угла окна; вторым - вертикальная координата верхнего левого угла окна; третьим - ширина окна; четвертым - высота окна;

Пример использования: x,y,w,h=hc.window_pos()

enable_extension

Функция позволяет разрешать или запрещать работу расширения с заданным именем.

Аргументы функции:
name - имя расширения;
enable - флаг, разрешающий или запрещающий работу расширения (true/false); если этот аргумент опущен, функция не меняет текущее состояние флага;

Возвращаемое значение: Текущее состояние разрешения работы расширения (true/false).

Пример использования: hc.enable_extension('Cache cleaner', true)

reload_extension

Функция заставляет HandyCache перечитать файл расширения с заданным именем с последущим вызовом обработчика события Init.

Аргументы функции:
name - имя расширения;

Возвращаемое значение: Нет.

Пример использования: hc.reload_extension('Cache cleaner')

Функции таблицы re для работы с регулярными выражениями

Имя

Описание

set_regex

Задает регулярное выражение.

Аргументы функции:
regex - регулярное выражение;

Возвращаемое значение: Нет.

Пример использования: re.set_regex([[(.*\.).*]])

set_subj

Задает строку, над которой буде исполняться регулярное выражение.

Аргументы функции:
subj - строка;

Возвращаемое значение: Нет.

Пример использования: re.set_subj(hc.answer_header)

set_callout

Задает имя callout-функции.

Аргументы функции:
func - имя callout-функции;

Возвращаемое значение: Нет.

Пример использования: re.set_callout('callout_func')

match

Вызывает исполнение регулярного выражения.

Аргументы функции:
subj - строка, над которой будет исполняться регулярное выражение; если на месте этого аргумента задан nil или этот аргумент опущен, то будет использоваться subj-строка, заданная предыдущей функцией.
regex - регулярное выражение; если на месте этого аргумента задан nil или этот аргумент опущен, то будет использоваться регулярное выражение, заданное предыдущей функцией;
offset - смещение позиции в subj-строке, с которой начнется исполнение регулярного выражения; если на месте этого аргумента задан nil или этот аргумент опущен, то исполнение регулярного выражения начнется с начала строки (1-й позиции);
partial - флаг, разрешающий использовать частичное совпадение (true/false ); если на месте этого аргумента задан nil или этот аргумент опущен, то частичные совпадения не используются;

Возвращаемое значение: Если в результате исполнения регулярного выражения найдена хотя бы одна подстрока, то первым значением функция возвращает таблицу; в этой таблице для каждой найденной подстроки находится по паре значений: begin_pos и end_pos; эти значения задают соответственно позиции в subj-строке для начала и конца каждой найденной подстроки; если в результате исполнения регулярного выражения не найдено ни одной подстроки, то первому возвращаемому значению присваивается nil, а в качестве второго значения возвращается строка с описанием ошибки.

Пример использования:
local t=re.match(s, regex)
if t then  hc.put_to_log('длина подстроки='..t[0].end_pos-t[0].begin_pos+1) end

substr_count

Получает количество подстрок, найденных в результате последнего исполнения регулярного выражения.

Аргументы функции: Нет.

Возвращаемое значение: Количество найденных подстрок.

Пример использования: local num= re.substr_count()

substr

Получает подстроку с заданным номером, найденную в результате последнего исполнения регулярного выражения.

Аргументы функции:
num - номер подстроки (счет начинается с 0);

Возвращаемое значение: Возвращается подстрока; если подстроки с заданным номером нет, то возвращается nil ;

Пример использования: local s=re.substr(0)

substr_length

Получает длину подстроки с заданным номером, найденной в результате последнего исполнения регулярного выражения.

Аргументы функции:
num - номер подстроки;

Возвращаемое значение: Возвращается длина подстроки; если подстроки с заданным номером нет, то возвращается -1;

Пример использования: local l=re.substr_length(0)

substr_offset

Получает смещение позиции начала подстроки с заданным номером в subj-строке, найденной в результате последнего исполнения регулярного выражения.

Аргументы функции:
num - номер подстроки;

Возвращаемое значение: Возвращается смещение подстроки; если подстроки с заданным номером нет, то возвращается -1 ;

Пример использования: local offset=re.substr_offset(0)

named_substr_index

Получает индекс именованной подстроки, найденной в результате последнего исполнения регулярного выражения.

Аргументы функции:
name - имя подстроки;

Возвращаемое значение: Возвращается индекс подстроки с заданным именем; если подстроки с заданным именем нет, то возвращается -1 ;

Пример использования:
 t= re.match(s, 'a(?<name>b)')
i=re.named_substr_index('name')
if i>0 then l= t[i].end_pos-t[i].begin_pos

find

Получает значение заданной подстроки.

Аргументы функции:
subj - строка, над которой будет исполняться регулярное выражение; если на месте этого аргумента задан nil или этот аргумент опущен, то будет использоваться строка, заданная предыдущей функцией.
regex - регулярное выражение; если на месте этого аргумента задан nil или этот аргумент опущен, то будет использоваться регулярное выражение, заданное предыдущей функцией;
num -  номер искомой подстроки; если на месте этого аргумента задан nil или этот аргумент опущен, то ищется подстрока с номером 0;

Возвращаемое значение: Если в результате исполнения регулярного выражения найдена подстрока с заданным номером, то первым значением функция возвращает эту подстроку; если не найдена заданная подстрока, то первому возвращаемому значению присваивается nil; если при исполнении регулярного выражения произошла ошибка, то в качестве второго значения возвращается строка с описанием ошибки.

Пример использования: local s=re.find(hc.answer_header, [[^Content-Length: (.+)]], 1)

replace

Заменяет в строке найденные подстроки заданным значением.

Аргументы функции:
subj - строка, над которой будет исполняться регулярное выражение и в которой будут заменяться найденные подстроки; если на месте этого аргумента задан nil или этот аргумент опущен, то будет использоваться subj-строка, заданная предыдущей функцией.
regex - регулярное выражение; если на месте этого аргумента задан nil или этот аргумент опущен, то будет использоваться регулярное выражение, заданное вызовом предыдущей функцией;
repl  - строка, которой будут заменяться найденные подстроки; если на месте этого аргумента задан nil или этот аргумент опущен, то найденные подстроки будут заменяться пустой строкой (удаляться);
all - флаг, указывающий, что применение регулярного выражения и выполнение замены должно производиться повторно пока будет обнаруживаться совпадение (true/false ); если на месте этого аргумента задан nil или этот аргумент опущен, то применение регулярного выражения и выполнение замены производится однократно (значение false );

Возвращаемое значение: Если при исполнении регулярного выражения не было ошибок (даже если не найдено ни одной подстроки), то первым значением функция возвращает строку - результат обработки (в противном случае nil); вторым значением возвращается число произведенных замен; третьим значением функция возвращает позицию в исходной строке, с которой начинается неизмененная часть; если в результате исполнения регулярного выражения произошла ошибка, то четвертым значением возвращается строка с описанием ошибки.

Пример использования: s=re.replace(hc.answer_header, [[(?-s)(Cache-Control:.*\r\n)]], nil)

Хранение данных, используемых расширениями

Для исполнения обработчиков событий в каждом потоке-обработчике запроса клиента создается своя lua-машина. Глобальные переменные, создаваемые обработчиками в lua -машине доступны для всех обработчиков, которые будут вызваны позднее в этом потоке.

При загрузке каждого расширения в HandyCache создается пустая таблица hc_static, привязанная к этому расширению. Следом для каждого расширения вызывается обработчик Init (если таковой зарегистрирован). Он может сохранить значения в таблице hc_static и они будут доступны во всех обработчиках этого расширения при обработке всех последующих запросов. Также обработчик Options (вызывается нажатием кнопки Настройки расширения на вкладке Расширения ) может изменить значения в этой таблице (или добавить новые) и они будут доступны при обработке всех последующих запросов.

Когда создается поток-обработчик запроса клиента, в нем создается копия таблицы hc_static для каждого расширения и внутри потока работа идет уже с этой копией. Обработчики событий могут добавлять/изменять переменные, но доступны эти значения будут только внутри этого потока.

Обработчики событий при необходимости могут сохранять значения в глобальных переменных. Значения, сохраненные в глобальных переменных, с момента присвоения и до завершения работы программы становятся доступны из всех обработчиков всех потоков. Для доступа к глобальным переменным используются функции hc.set_global и hc.get_global .

Графический интерфейс пользователя

Расширения HandyCache как и другие программы на lua могут использовать графический интерфейс пользователя. Вот несколько примеров предназначенных для таких целей библиотек: wxlua, LuaInterface, VCLua. Мне наиболее подходящей для расширений HandyCache показалась библиотека VCLua (сравнительно просто использовать, малый размер dll). Пример использования этой библиотеки в обработчике события Options можно найти в расширении eCacheCleaner (для использования этой библиотеки в папке HandyCache должен находиться файл vcl.dll ).

Тестирование расширений

В файле LuaTest.exe находится программа для тестирования работы расширений. Для тестирования расширения загрузите его в эту программу и нажмите кнопку Перечитать. В появившемся ниже списке обработчиков событий выберите интерисующий и нажмите кнопку Выполнить (F5) для вызова выделенной функции-обработчика. Чтобы выполнить функцию, отсутствующую в списке, впишите ее имя в поле ввода рядом с кнопкой Выполнить и нажмите эту кнопку.

Информацию о языке lua можно найти, например, здесь: по-английски или по-русски .