Расширение представляет из себя организованный специальным образом скрипт на языке lua.
Для начала использования расширений в HandyCache необходимо чтобы в папке HandyCache находился файл библиотеки lua5.x.dll.
В начале расширения располагается заголовок. Заголовок имеет следующую структуру:
--[[ <HCEXTENSION> @field value @field value @field value .. @field value </HCEXTENSION> ]]
|
Имя (field) |
Значение (value) |
| name | Наименование расширения |
| author | Имя автора расширения |
| version | Номер версии расширения |
| min_HC_version | Номер версии HandyCache, начиная с которой возможно использование данного расширения. |
| description | Краткое описание расширения |
| rule | Правило (регулярное выражение), которым будет проверяться URL запроса перед вызовом расширения. В заголовке может быть несколько полей rule. |
| exception | Исключение (регулярное выражение), которым будет проверяться URL запроса перед вызовом расширения. В заголовке может быть несколько полей exception. |
| event | Наименование события, для обработки которого будет вызываться расширение, и через косую черту имя функции, предназначенной для обработки этого события. В заголовке может быть несколько полей event. |
--[[ <HCEXTENSION> @name Save or block 403 and 404 @author DenZzz @version 0.01 @min_HC_version 1.0.0.193 @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 в имя файла в кэше. |
| BeforeViewInMonitor | Возникает перед созданием новой строки в мониторе. |
| RequestHeaderReceived | Возникает, когда получен заголовок запроса от клиента. |
| BeforeRequestHeaderSend | Возникает, когда заголовок запроса готов к отправке на сервер. |
| BeforeRequestBodySend | Возникает, когда получена очередная порция данных для отправки на сервер методом POST. |
| AnswerHeaderReceived | Возникает, когда получен заголовок ответа от сервера. |
| BeforeAnswerHeaderSend | Возникает, когда заголовок ответа готов к отправке клиенту. Заголовок может быть получен от сервера или сформирован самим HandyCache. |
| BeforeAnswerBodySend | Возникает, когда получена очередная порция данных для отправки клиенту. Данные могут быть получены от сервера или взяты из кэша. Если данные упакованы, то они перед передачей обработчику распаковываются. |
| Destroy | Возникает при завершении работы расширения (при удалении расширения по кнопке Удалить расширение, при перезагрузке расширения по кнопке Перечитать расширение, при закрытии HandyCache) |
Перед вызовом функций расширения HandyCache создает в lua-машине две таблицы: hc и re. В первой собраны переменные и функции, позволяющие получать информацию о значениях внутренних переменных HandyCache и изменять некоторые из них. Во второй собраны функции, позволяющие использовать в расширениях возможности библиотеки регулярных выражений PCRE.
|
Имя |
Допустимые действия |
События |
Допустимые значения |
Описание |
| ver | чтение | Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend, Destroy |
"<строка>" | Строка, содержащая версию HandyCache, например, 'Version 1.00 RC3 (1.0.0.250)' |
| version_number | чтение | Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend, Destroy |
"<строка>" | Строка, содержащая номер версии HandyCache, например, '1.0.0.250' |
| language_id | чтение | Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend, Destroy |
<число> | Идентификатор языка, используемого в интерфейсе пользователя в данный момент. Список идентификаторов можно посмотреть, например, здесь. |
| script_name | чтение |
Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
BeforeViewInMonitor, |
"<строка>" | Путь к файлу текущего расширения. |
| event | чтение |
Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
BeforeViewInMonitor, |
"<строка>" | Содержит наименование обрабатываемого события. |
| ini_path | чтение |
Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
BeforeViewInMonitor, |
"<строка>" | Содержит путь к папке с файлами настройки. |
| cache_path | чтение |
Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
BeforeViewInMonitor, |
"<строка>" | Содержит путь к папке кэша. |
| listening_port | чтение |
Init, Options, Timer1s, Timer1m, URLToFileNameConverting,
BeforeViewInMonitor, |
"<строка>" | Содержит порт доступа к HandyCache |
| client_connected | чтение | BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | true, false | Принимает значение true, если имеется соединение с клиентом, и - false , если соединение с клиентом разорвано |
| connection_index | чтение | URLToFileNameConverting, BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | <число> | Принимает значение номера соединения, для которого вызвано расширение (не путать с номером строки) |
| url | чтение | URLToFileNameConverting, BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | В соответствие с RFC 2616 п.3.2.2 | URL запроса |
| method | чтение | RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | В соответствие с RFC 2616 п.9 | Метод, использованный в запросе |
| is_https | чтение | RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | true, false | Принимает значение true, если текущий запрос передается по https-протоколу. |
|
request_ims |
чтение |
BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived,
BeforeAnswerHeaderSend, BeforeAnswerBodySend |
<число> |
Время по Гринвичу в числовом представлении, полученное
из поля заголовка запроса If-Modified-Since. Если поля
If-Modified-Since в заголовке запроса клиента не было, то значение
переменной равно нулю. |
|
hc_ims |
чтение |
BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend,
BeforeAnswerBodySend |
<число> |
Время по Гринвичу в числовом представлении,
добавленное в поле заголовка запроса If-Modified-Since
HandyCache при включенной опции Добавить If-Modified-Since при наличии
файла в кэше. Если HandyCache не добавлял свое значение в поле
If-Modified-Since, то значение переменной равно нулю. |
| ignore_traffic | чтение, запись (только в обработчиках BeforeViewInMonitor, RequestHeaderReceived) | URLToFileNameConverting, BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | "<строка>" |
Добавив в эту строку определенные символы можно запретить учет определенного вида трафика для текущего запроса. Для запрета учета трафика, поступившего из интернета нужно добавить латинский символ "i" или кирилический "и" (строчный или заглавный). Для запрета учета трафика из кэша нужно добавить латинский символ "c" или кирилический "к". Для запрета учета отправленного трафика нужно добавить латинский символ "u" или кирилический "о". Например, для запрета учета всех видов трафика можно добавить в обработчик события строку hc.ignore_traffic='IкО' |
| use_proxy | чтение, запись | RequestHeaderReceived, BeforeRequestHeaderSend | "<строка>" | Содержит параметры внешнего HTTP прокси-сервера, назначенного для текущего запроса. Пример: "192.186.55.2:8080" или "proxy.com:8081"; если этой переменной присвоено значение "direct", то запрос будет отправлен без использования прокси |
| use_proxy_login | чтение, запись | RequestHeaderReceived, BeforeRequestHeaderSend | "<строка>" | Содержит логин доступа внешнего HTTP прокси-сервера, назначенного для текущего запроса (basic-авторизация). Пример: "user:password" |
| use_bound_ip | чтение, запись | RequestHeaderReceived, BeforeRequestHeaderSend | "<строка>" | Содержит IP-адрес сетевого устройства, через которое будет отправлен запрос. Пример: "192.186.0.2" |
| request_header | чтение, запись | BeforeViewInMonitor (только чтение), RequestHeaderReceived, BeforeRequestHeaderSend | В соответствие с RFC 2616 | Содержит заголовок запроса. Если расширение изменит значение этой переменной, измененный заголовок будет отправлен серверу. |
|
request_body |
чтение, запись |
BeforeRequestHeaderSend, BeforeRequestBodySend |
"<строка>" |
Пример расширения для обработки тела запроса:
--[[ <HCExtension>
@name ReqBody @author mai @version 0.2 @description Example @min_HC_version 1.0.0.310 @rule mmm\.ru/form/ @event BeforeRequestHeaderSend/header @event BeforeRequestBodySend/body </HCExtension> ]] function header()
if hc.method == 'POST' then local s1= re.find(hc.request_header, [[[^\r]*\r\n]], 0) local s2= re.replace(hc.request_header, [[[^\r]*\r\n]], '') hc.request_header = s1 hc_static['req_header']= s2 end end function body()
if not hc_static['req_body'] then hc_static['req_body']= '' end hc_static['req_body']= hc_static['req_body']..hc.request_body hc.request_body= '' if hc.last_part then -- Здесь выполняются необходимые действия над телом запроса -- Затем корректируется заголовок запроса, например, заменяется -- длина тела запроса hc.request_body= hc_static['req_header']..hc_static['req_body'] hc_static['req_header']= nil hc_static['req_body']= nil end end В обработчике BeforeRequestHeaderSend header() первая строка заголовка запроса отсылается на сервер а остальные строки заголовка запоминаются в таблице hc_static. В обработчике BeforeRequestBodySend body() расширение получает порции тела запроса из переменной hc.request_body и сохраняет их в таблице hc_static. Когда переменной hc.last_part будет присвоено значение true, расширение должно исправить тело и заголовок запроса в соответствии с замыслом автора расширения и отослать их на сервер. |
| cache_file_name | чтение | RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived | "<строка>" | Имя файла в кэше, соответсвующего текущему запросу (пустая строка, если файла нет). |
| cache_file_size | чтение | RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived | <число> | Размер файла в кэше (-1, если файла нет) за вычетом служебной информации, расположенной в конце файла. |
| cache_file_age | чтение | RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived | <число> | Возраст (интервал времени между моментом последнего обновления файла и текущим моментом) файла в кэше в секундах (0, если файла нет). |
| cache_file_content_type | чтение | RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived | "<строка>" | Тип содержимого файла в кэше (пустая строка, если файла нет в кэше или
если не удалось определить его тип). |
| user_name | чтение | URLToFileNameConverting, BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | "<строка>" | Имя пользователя, от которого поступил запрос. |
| user_ip | чтение | URLToFileNameConverting, BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | "<строка>" | IP комрпьютера, с которого поступил запрос пользователя. |
| user_from_internet | чтение | RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | <число> | Количество данных, полученных пользователем из интернета за текущие сутки. |
| user_from_cache | чтение | RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | <число> | Количество данных, полученных пользователем из кэша за текущие сутки. |
| user_to_internet | чтение | RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | <число> | Количество данных, отправленных пользователем за текущие сутки. |
| answer_header | чтение, запись | RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | В соответствие с RFC 2616 | Заголовок ответа, полученный от сервера или сформированный расширением. Если этой переменной расширение присвоило новое значение, то клиенту будет передан измененный заголовок. |
| answer_body | чтение, запись |
RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend |
"<строка>", "file=<имя файла>", "file=URLToCache(<URL>)" |
При обработке событий RequestHeaderReceived, AnswerHeaderReceived,
BeforeAnswerHeaderSend содержит тело ответа, сформированное
расширением. Если этой переменной присвоено значение, то клиенту будет
передано содержимое этой переменной в качестве тела ответа. При обработке события BeforeAnswerBodySend через эту переменную расширение получает очередную порцию данных для обработки. В эту же переменную расширение записывает результат обработки. |
| last_part | чтение | BeforeAnswerBodySend | true, false | Принимает значение true, когда расширение вызывается последний раз для обработки текущего запроса. |
| action | чтение, запись | RequestHeaderReceived, BeforeRequestHeaderSend, AnswerHeaderReceived | Для RequestHeaderReceived и BeforeRequestHeaderSend: можно использовать все допустимые значения Для AnswerHeaderReceived: "stop", "dont_update", "save", "dont_save" |
Действие, которое должен выполнить НС:
|
| extensions_on | чтение, запись | RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | true, false | Если присвоить этой переменной значение false, то для текущего запроса все последующие обработчики событий вызываться уже не будут. |
| read_from_cache_on | чтение, запись | RequestHeaderReceived | true, false | Присвоение false запрещает чтение из кэша для текущего запроса. |
| add_ims_on | чтение, запись | RequestHeaderReceived | true, false | Присвоение значения этой переменной управляет опцией Добавить if-Modified-Since при наличии файла в кэше для текущего запроса. |
| offline_disable | запись | RequestHeaderReceived | true, false | Присвоение этой переменной true запрещает автономный режим для текущего запроса. |
| white_mask | чтение, запись | BeforeViewInMonitor, RequestHeaderReceived | "<строка>" | Маска Белого списка - в эту переменную можно добавить по
одному символу для каждого из списков, если нужно, чтобы этот список не
работал с данным запросом. Для обозначения списков можно использовать
символы:
|
| file_speed_limit | чтение, запись | RequestHeaderReceived, AnswerHeaderReceived | <число> | Если этой переменной присвоить значение больше 0, то это значение будет использоваться как лимит скорости (в байтах в секунду) для загрузки данного файла. Присвоение переменной значения 0 снимает ограничение. |
| user_speed_limit | чтение, запись | RequestHeaderReceived, AnswerHeaderReceived | <число> | Если этой переменной присвоить значение больше 0, то это значение будет использоваться как лимит скорости (в байтах в секунду) для данного пользователя до задания другого значения или перезапуска HandyCache. hc.user_speed_limit=0 снимает ограничения скорости для данного пользователя. |
| dont_load_large_files_on | чтение |
Init, Options, Timer1s, Timer1m,
BeforeViewInMonitor, |
true, false | Принимает текущее состояние опции Не загружать большие файлы. |
| speed_limit_on | чтение |
Init, Options, Timer1s, Timer1m,
BeforeViewInMonitor, |
true, false | Принимает текущее состояние опции Ограничить скорость загрузки. |
| offline_on | чтение |
Init, Options, Timer1s, Timer1m,
BeforeViewInMonitor, |
true, false | Принимает текущее состояние опции Автономный режим. |
| monitor_index | чтение | BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend |
<число> | Принимает значение номера строки в мониторе, соответствующей текущему запросу. |
| hide_in_active_list | чтение, запись | BeforeViewInMonitor | true, false | Если этой переменной присвоено значение true, то строка в в списке активных запросов, соответсвующая текущему запросу будет спрятана. |
| hide_in_monitor | чтение, запись | BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | true, false | Если этой переменной присвоено значение true, то строка в мониторе, соответсвующая текущему запросу будет спрятана. |
| monitor_text_color | чтение, запись | BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend | <число> | Задает цвет текста в строке монитора. Если уровни основных цветовых составляющих R, G и B, то цвет задается числом R+G*256+B*256*256. R, G и B могут принимать значения от 0 до 255. |
| monitor_parent_url | чтение, запись (только в обработчике BeforeViewInMonitor) | BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | "<строка>" | Задает URL строки монитора, которая будет 'родительской' для строки текущего запроса. Если переменной значение не было присвоено, то при чтении этой переменной выдается значение поля Referer заголовка запроса. |
| monitor_string | чтение, запись | URLToFileNameConverting, BeforeViewInMonitor, RequestHeaderReceived, BeforeRequestHeaderSend, BeforeRequestBodySend, AnswerHeaderReceived, BeforeAnswerHeaderSend, BeforeAnswerBodySend | "<строка>" | Содержит значение, присвоенное предыдущими расширениями при обработке текущего события. Расширение может присвоить свое значение этой переменной. Значение этой переменной будет выведено в колонке Правила в Мониторе в строке текущего запроса. |
|
Имя |
Описание |
| shell_execute |
Функция является оберткой Windows API функции ShellExecute (аргумент Operation="Open"). Подробнее смотрите здесь. Аргументы функции: Возвращаемое значение: Возвращает строку 'OK' при успешном вызове функции. В случае ошибки, возвращает сообщение об ошибке. Пример использования: hc.shell_execute('notepad.exe', 'stat.txt', nil, 'SW_SHOW') |
| execute_and_wait |
Функция запускает на выполнение программу и дожидается ее завершения. Аргументы функции: Возвращаемое значение: Код завершения запускаемой программы. Пример использования: hc.execute_and_wait('notepad.exe stat.txt') |
| play_sound |
Функция является оберткой Windows API функции PlaySound. Подробнее смотрите здесь. Аргументы функции: Возвращаемое значение: нет. Примеры использования:
|
| crc32 |
Функция выполняет подсчет хэша crc32 для входной строки. Аргументы функции: Возвращаемое значение: Crc32 хэш-код входной строки (число). Пример использования: crc = hc.crc32(str_line) |
| decode_base64 |
Функция выполняет декодирование строки, кодированной в формате base64. Аргументы функции: Возвращаемое значение: Результат декодирования строки. Пример использования: crc = hc.base64(str_line) |
| recode |
Функция выполняет преобразование одной кодировки строки в другую. Аргументы функции: Возвращаемое значение: Первым значением возвращается выходная строка в заданной кодировке. Вторым значением является true или false в зависимости от того потебовалось использовать символ DefaultChar или нет. Примеры использования: local WC_COMPOSITECHECK = 512 --convert
composite to precomposed |
| execute_cmd |
Функция выполняет команду (те же команды, что и для утилиты HCCmd). Аргументы функции: Список команд. Возвращаемое значение: нет. Примеры использования: |
| send_request |
Функция отправляет через HandyCache http-запрос. Этот запрос обрабатывается HandyCache таким же образом, как все другие запросы, проходящие через него (работают все опции, списки, расширения). Аргументы функции: Возращаемое значение: нет. Пример использования: |
| sleep |
Функция останавливает выполнение расширения на заданный интервал времени. Аргументы функции: Возращаемое значение: нет. Пример использования: hc.sleep(1000) |
| put_msg |
Функция вызывает появление на экране информационного окошка с заданным сообщением. Аргументы функции: Возращаемое значение: нет. Пример использования: hc.put_msg(10, 'Очистка кэша запущена') |
| put_to_log |
Функция помещает заданное сообщение в лог программы. Аргументы
функции: Возращаемое значение: нет. Пример использования: hc.put_to_log('method='..hc.method) |
| get_keyboard_state |
Функция получает список нажатых клавиш. Аргументы функции: нет. Возвращаемое значение: Строка со списком нажатых
клавиш. Пример использования: |
| systime_to_str |
Функция преобразует системное время в строковое представление. Аргументы функции: Возвращаемое значение: Время в строковом представлении. Пример использования: s = hc.systime_to_str(os.time(), false) |
| str_to_systime |
Функция преобразует строковое представление времени в числовое. Аргументы функции: Возращаемое значение: Время по Гринвичу в числовом представлении (время в секундах, прошедшее после 0 часов 0 минут 1 января 1970 года). Пример использования: |
| get_host_IP |
Функция получает IP-адрес для заданного имени сетевого узла. Аргументы
функции: Возвращаемое значение: Первым значением возвращается IP-адрес в виде строки; если IP-адрес не найден, то первое значение равно nil; вторым значением функция возвращает строку - сообщение; в случае удачи сообщается был ли найден адрес в кэше; в случае неудачи - причина. Пример использования: ip,e=hc.get_host_IP('handycache.ru') |
| ssl_handling_enabled |
Функция сообщает разрешена обработка SSL или нет. Аргументы
функции: Возвращаемое значение: Если функция вызвана без аргументов, то она возвращает состояние опции Обработка SSL. Если значения аргументов заданы, то функция сообщает разрешена ли обработка SSL для данного URL и пользователя. Пример использования: en=hc.ssl_handling_enabled('https://mail.ru', 'Boss') |
| enable_user |
Функция позволяет разрешить или запретить пользователю доступ к HandyCache. Аргументы
функции: Возвращаемое значение: true, если пользователю разрешен доступ, и - false, если доступ запрещен; Пример использования: hc.enable_user('Boss', true) |
| get_users_stat |
Функция позволяет получить информацию о пользователях. Аргументы
функции: Возвращаемое значение: Таблица с информацией о пользователях; каждый элемент возвращаемой таблицы имеет следующие поля: 'from_internet', 'from_cache', 'to_internet', 'connections_number', 'speed_limit '; Пример использования: |
| set_user_speed |
Функция позволяет задать ограничение скорости загрузки для пользователя. Аргументы
функции: Возвращаемое значение: лимит скорости загрузки пользователя; если скорость загрузки пользователя не ограничена, то возвращается ноль; если пользователь с именем name не найден, то возвращается nil; Пример использования: hc.set_user_speed('Boss', 0) |
| prepare_path |
Функция создает каталоги в соответсвии с путем, заданным аргументом. Аргументы функции: Возвращаемое значение: Нет. Пример использования: hc.prepare_path('c:\\program files\\handycache\\cache\\example\\') |
| get_dir_files_list |
Функция позволяет получить список файлов у указанном каталоге. Аргументы функции:
Возвращаемое значение: Таблица со списком файлов, индекс таблицы от 0. Пример использования: |
| repeat_options |
Функция задает опции, управляющие процессом получения данных от удаленного сервера. Аргументы функции: Возвращаемое значение: Нет. Пример использования: hc.repeat_options('connect', 30, 3) |
| call_me_for |
Функция регистрирует функцию текущего расширения в качестве обработчика события для текущего запроса. Аргументы функции: Возвращаемое значение: Нет. Пример использования: hc.call_me_for('BeforeAnswerBodySend', 'body') |
| client_disconnect |
Разрывает заданное соединение с клиентом. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: hc.client_disconnect(123) |
| server_disconnect |
Разрывает соединение с сервером. Аргументы функции: Нет. Возвращаемое значение: Нет. Пример использования: hc.server_disconnect() |
| user_disconnect |
Функция разрывает все установленные на данный момент соединения заданного пользователя. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: hc.user_disconnect('Иванов') |
| prepare_url |
Функция выполняет преобразование заданного URL в имя файла в кэше без вызова обработчика события URLToFileNameConverting. Аргументы
функции: Возвращаемое значение: Имя файла в кэше, полученное из заданного URL с помощью встроенного алгоритма преобразования; Пример использования: local s= hc.prepare_url(hc.url) |
| preform_cache_file_name |
Функция задает имя файла в кэше, которое может быть сформировано расширением в обработчике события URLToFileNameConverting. HandyCache, если потребуется, может изменить заданное имя файла для его адаптации к текущему состоянию кэша. Путь к файлу может быть задан абсолютным (начинается с имени диска) или относительным. Во втором случае в начало имени добавляется путь к папке кэша. Замечание. По умолчанию HandyCache не использует файлы вне папки кэша. Чтобы разрешить использование файлов вне папки кэша, нужно в файл HandyCache.ini в секции MainForm добавить строку ReadOnlyFromCachePath=False Аргументы функции: Возвращаемое значение: Нет. Пример использования: hc.preform_cache_file_name('site1.ru\example.jpg') |
| get_cache_file_name |
Функция получает имя файла в кэше и его наличие для заданного URL. Аргументы
функции: Возвращаемое значение: Первым значением возвращается имя файла; вторым - наличие файла в кэше (true/false ); Пример использования: s,e=hc.get_cache_file_name('http://handycache.ru/') |
| get_cache_file_size |
Функция получает размер файла в кэше. Аргументы
функции: Возвращаемое значение: Размер данных в файле за вычетом служебной информации, расположенной в конце файла; если файл не найден, возвращается значение -1. Пример использования: len=hc.get_cache_file_size('c:\cache\site.ru\img\qqq.jpg') |
| get_cache_file_age |
Функция получает возраст файла в кэше. Аргументы
функции: Возвращаемое значение: Время в секундах, прощедшее с момента последнего изменения файла; Пример использования: age=hc.get_cache_file_age('c:\cache\site.ru\img\qqq.jpg') |
| get_cache_file_content_type |
Функция получает тип данных и способ кодирования данных в файле в кэше. Аргументы
функции: Возвращаемое значение: Первым значением возвращается строка, содержащая тип данных в файле в формате поля Content-Type http-заголовков; вторым значением возвращается строка, содержащая способ кодирования данных в файле в формате поля Content-Encoding http-заголовков; Пример использования: type,encoding=hc.get_cache_file_content_type([[c:\cache\site.ru\img\qqq.jpg]]) |
| delete_cache_file |
Функция удаляет файл в кэше, соответствующий заданному URL. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: hc.delete_cache_file([[http://site.ru/example.gif]]) |
| delete_file |
Функция удаляет файл или каталог вместе с файлами, находящимися в указанном каталоге. В имени файла можно задавать маску с использованием символов '?' и '*'. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: hc.delete_file([[c:\cache\site.ru\*.gif]]) |
| file_last_modified_time |
Функция получает время последнего изменения файла. Аргументы функции: Возвращаемое значение: время последнего изменения файла в числовом представлении. Пример использования: |
| update_url_info |
Функция удаляет информацию о заданном файле из RAM-кэша и очищает внутренние переменные HandyCache, хранящие информацию об этом файле. Если информация о файле понадобится, она будет добываться из дискового кэша заново. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: hc.update_url_info('http://handycache.ru/') |
| set_global |
Функция позволяет сохранить в памяти значение глобальной переменной. Сразу после завершения работы этой функции присвоенное значение будет доступно из других потоков. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: hc.set_global('MyVar', 'Value') |
| get_global |
Функция позволяет получить значение глобальной переменной. Аргументы
функции: Возвращаемое значение: Значение переменной name. Если переменной с заданным именем нет, то возвращается nil. Пример использования: |
| exists_global |
Функция позволяет выяснить имеется ли в памяти глобальная переменная. Аргументы
функции: Возвращаемое значение: Если переменная с заданным именем существует, то возвращается true, в противном случае - nil. Пример использования: if hc.exists_global('var1') then a=hc.get_global('var1') end |
| remove_global |
Функция позволяет удалить глобальную переменную. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: if hc.exists_global('var1') then a=hc.remove_global('var1') end |
| set_global_table_item |
Функция позволяет сохранить значение в глобальной таблице. Сразу после завершения работы этой функции присвоенное значение будет доступно из других потоков. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: hc.set_global_table_item('MyTable', 'Index1', 'Index2', 'Value') |
| get_global_table_item |
Функция позволяет получить значение элемента глобальной таблицы. Аргументы
функции: Возвращаемое значение: Значение элемента глобальной таблицы item_name. Если элемента глобальной таблицы с заданным именем нет, то возвращается nil. Пример использования: |
| exists_global_table_item |
Функция позволяет выяснить имеется ли в памяти значение элемента глобальной таблицы. Аргументы
функции: Возвращаемое значение: Если значение элемента глобальной таблицы с заданным именем существует, то возвращается true, в противном случае - nil. Пример использования: if hc.exists_global_table_item('var1',3,'a') then a=hc.get_global_table_item('var1',3,'a') end |
| remove_global_table_item |
Функция позволяет удалить элемент глобальной таблицы. Аргументы
функции: Возвращаемое значение: Нет . Пример использования: if hc.exists_global_table_item('var1',3,'a') then a=hc.remove_global_table_item('var1',3,'a') end |
| window_pos |
Функция получает положение и размер главного окна HandyCache. Аргументы функции: Нет. Возвращаемое значение: Первым значением возвращается горизонтальная координата верхнего левого угла окна; вторым - вертикальная координата верхнего левого угла окна; третьим - ширина окна; четвертым - высота окна; Пример использования: x,y,w,h=hc.window_pos() |
| enable_extension |
Функция позволяет разрешать или запрещать работу расширения с заданным именем. Аргументы
функции: Возвращаемое значение: Текущее состояние разрешения работы расширения (true/false.) Пример использования: hc.enable_extension('Cache cleaner', true) |
| reload_extension |
Функция заставляет HandyCache перечитать файл расширения с заданным именем с последущим вызовом обработчика события Init. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: hc.reload_extension('Cache cleaner') |
Для выполнения регулярных выражений в HandyCache и расширениях используется библиотека PCRE.
PCRE License
PCRE is a library of functions to support regular expressions whose syntax
and semantics are as close as possible to those of the Perl 5 language.
Written by Philip Hazel
Copyright (c) 1997-2009 University of Cambridge
-----------------------------------------------------------------------------
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the University of Cambridge nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
|
Имя |
Допустимые действия |
События |
Допустимые значения |
Описание |
| engine | чтение, запись | Все события | 1..20 |
Расширения могут использовать до двадцати движков, исполняющих регулярные выражения. Значение engine позволяет выбрать для использования один из этих движков. Как правило, для выполнения своей работы расширению достаточно одного движка. Если не присвоить значение этой переменной, то по умолчанию будет использоваться первый движок. Однако, если, например, в callout-функции требуется выполнить регулярное выражение, то использовать для этой цели первый движок уже нельзя, это вызовет нарушение работы первого движка после выхода из callout-функции. Для использования в callout-функции нужно использовать другой движок. В callout-функции следует перед выполнением регулярных выражений включить другой движок присвоив переменной engine значение отличное от единицы, а потом вернуть расширение к использованию первого движка. Прочитав значение этой переменной расширение может узнать номер текущего движка. |
| info_options | Чтение | Все события |
Получает опции, с которыми было скомпилировано, регулярное выражение. Опции, с которыми было скомпилировано,
регулярное выражение. Значения опций представлены битовой
маской: Пример использования: local opt= re.info_options |
|
| info_maxlookbehind | Чтение | Все события |
Выдает количество символов в самом длинном lookbehind assertion последнего регулярного выражения. Эта информация полезна при организации поиска по регулярному выражению в условиях неполноты (поступления по частям) анализируемой строки. Пример использования: local max_len= re.info_maxlookbehind |
|
| info_jit | Чтение | Все события |
Получает значение 1, если регулярное выражение было скомпилировано с опцией PCRE_STUDY_JIT_COMPILE и jit-компиляция завершилась успешно. Возвращает 0, если использовние jit по каким-то причинам оказалось невозможным. Пример использования: local jit= re.info_jit |
Функции таблицы re для работы с регулярными выражениями
|
Имя |
Описание |
| select_engine |
Эта функция делает то же действие, что и присвоение значения переменной engine (функция оставлена для сохранения совместимости со старыми версия расширений). C помощью этой функции можно выбрать какой из имеющихся движков будет использоваться. Аргументы функции: Возвращаемое значение: Нет. Пример
использования: |
| set_regex |
Задает регулярное выражение. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: re.set_regex([[(.*\.).*]]) |
| set_subj |
Задает строку, над которой буде исполняться регулярное выражение. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: re.set_subj(hc.answer_header) |
| set_callout |
Задает имя callout-функции. Аргументы
функции: Возвращаемое значение: Нет. Пример использования: re.set_callout('callout_func') |
| match |
Вызывает исполнение регулярного выражения. Аргументы
функции: Возвращаемое значение: Если в результате исполнения регулярного выражения найдена хотя бы одна подстрока, то первым значением функция возвращает таблицу; в таблице будет ровно столько элементов, сколько нужно для размещения значений для всех найденных подстрок (например, если номер последней найденной подстроки равен два, то в таблице будет три элемента с индексами 0, 1 и 2); в этой таблице для каждой подстроки находится по паре значений: begin_pos и end_pos; эти значения задают соответственно позиции в subj-строке для начала и конца каждой подстроки; если подстрока не была найдена, то для нее будут записаны значения begin_pos и end_pos равные -1; если в результате исполнения регулярного выражения не найдено ни одной подстроки, то первому возвращаемому значению присваивается nil, а в качестве второго значения возвращается строка с описанием ошибки; в качестве третьего значения функции всегда выводится значение (*Mark). Пример использования: |
| substr_count |
Получает номер последней подстроки, найденной в результате последнего исполнения регулярного выражения. Аргументы функции: Нет. Возвращаемое значение: Номер последней найденной подстроки. Пример использования: local num= re.substr_count() |
| substr |
Получает подстроку с заданным номером, найденную в результате последнего исполнения регулярного выражения. Аргументы
функции: Возвращаемое значение: Возвращается подстрока; если подстрока с заданным номером не найдена, то возвращается пустая строка; Пример использования: local s=re.substr(0) |
| substr_length |
Получает длину подстроки с заданным номером, найденной в результате последнего исполнения регулярного выражения. Аргументы
функции: Возвращаемое значение: Возвращается длина подстроки; если подстроки с заданным номером нет, то возвращается значение меньше единицы ; Пример использования: local l=re.substr_length(0) |
| substr_offset |
Получает смещение позиции начала подстроки с заданным номером в subj-строке, найденной в результате последнего исполнения регулярного выражения. Аргументы
функции: Возвращаемое значение: Возвращается смещение подстроки; если подстроки с заданным номером нет, то возвращается значение меньше единицы (символы в lua-строке нумеруются начиная с 1, поэтому значение меньше единицы можно использовать как признак того, что данная подстрока не была найдена); Пример использования: local offset=re.substr_offset(0) |
| named_substr_index |
Получает индекс именованной подстроки, найденной в результате последнего исполнения регулярного выражения. Аргументы
функции: Возвращаемое значение: Возвращается индекс подстроки с заданным именем; если подстроки с заданным именем нет, то возвращается -1; Пример использования: |
| offsets_vector_size |
Получает размер вектора (массива) результатов выполнения регулярного выражения. Аргументы функции: Нет. Возвращаемое значение: Возвращается размер массива результатов; Пример использования: local n=re.offsets_vector_size() |
| offsets_vector |
Получает элемент вектора (массива) результатов выполнения регулярного выражения. Аргументы
функции: Возвращаемое значение: Возвращается элемент массива результатов, обычно это смещение от начала строки, с которой работает регулярное выражение; если элемента с заданным номером нет, то возвращается -1; Пример использования: local offset=re.offsets_vector(0) |
| find |
Получает значение заданной подстроки. Аргументы
функции: Возвращаемое значение: Если в результате исполнения регулярного выражения найдена подстрока с заданным номером, то первым значением функция возвращает эту подстроку; если не найдена заданная подстрока, то первому возвращаемому значению присваивается nil; если при исполнении регулярного выражения не было обнаружено ошибок, то вторым значением функции будет nil; если при исполнении регулярного выражения произошла ошибка, то в качестве второго значения возвращается строка с описанием ошибки; в качестве третьего значения функции выводится значение (*Mark). Пример использования: local s=re.find(hc.answer_header, [[^Content-Length: (.+)]], 1) |
| replace |
Заменяет в строке найденные подстроки заданным значением. Аргументы
функции: Возвращаемое значение: Если при исполнении регулярного выражения не было ошибок (даже если не найдено ни одной подстроки), то первым значением функция возвращает строку - результат обработки (в противном случае nil); вторым значением возвращается число произведенных замен; третьим значением функция возвращает позицию в результирующей строке, с которой начинается неизмененная часть; если в результате исполнения регулярного выражения произошла ошибка, то четвертым значением возвращается строка с описанием ошибки. Пример использования: s=re.replace(hc.answer_header, [[(?-s)(Cache-Control:.*\r\n)]], nil) |
| register_regex |
Регистрирует регулярное выражение. Аргументы
функции: Возвращаемое значение: Возвращается идентификатор зарегистрированного регулярного выражения. В дальнейшем расширения могут использовать этот идентификатор при вызове функций в качестве аргумента вместо самого регулярного выражения; Пример использования: |
| registered_regex |
Проверяет заегистрировано регулярное выражение с заданным идентификатором или нет. Аргументы
функции: Возвращаемое значение: true, если регулярное выражение с заданным идентификатором есть в кэше; Пример использования: |
| unregister_regex |
Удаляет из кэша регулярное выражение с заданным идентификатором (освобождает память). Аргументы
функции: Возвращаемое значение: Нет. Пример использования: re.unregister_regex(reg_id) |
Для исполнения обработчиков событий в каждом потоке-обработчике соединения с клиентом создается своя 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 можно найти, например, здесь: