Добавление и редактирование серверов

На текущий момент в программе отсутствуют встроенные возможности по модифицированию списка серверов. Информация о серверах, доступных в программе, содержится в файлe servers.xml, находящемся в подкаталоге Data каталога, в который установлена программа, либо в системной папке %appdata%\Image Uploader, относящейся к текущему пользователю. Программа использует этот файл в режиме "только для чтения". Этот файл не предназначен для редактирования. Все изменения будут потеряны после следующего обновления программы. Свои сервера следует добавлять в папку Data\Servers\ (если вы используете портативную версию) или %appdata%\Image Uploader\Servers\ (если вы использовали инсталлятор) в xml файлы с такой же структурой, как у файла servers.xml.

Файл составлен в соответствии со стандартом XML и должен быть сохранен в кодировке utf-8.

servers.xml должен иметь следующую структуру:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Servers>
  <Server>
      ...
  </Server>
  <Server>
      ...
  </Server>
  ...
</Servers>

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

Каждый вложенный узел <Server> имеет следующий вид:

<Server Name="название_сервера" [атрибуты] >
  <SupportedFormats>
    ...
  </SupportedFormats>	
  <Actions>
    <Action [атрибуты] />
    <Action [атрибуты] />
    ...
  </Actions>
  <Result ImageUrlTemplate="..." ThumbUrlTemplate="..." DownloadUrlTemplate="..."/>
</Server>

Узел <Server> может иметь следующие необязательные атрибуты:

• Authorize — указывает, поддерживает ли сервер учетные записи.
  Значения: 0 (по умолчанию) — без авторизации, 1 — сервер поддерживает авторизацию, 2 — авторизация обязательна.
• FileHost — указывает на то, что сервер является хостингом для любых типов файлов (не только изображений).
  Значения: 0 (по умолчанию) — хостинг картинок (эквивалентен Type="image"), 1 — файловый хостинг (эквивалентен Type="file") .
• Type — (ver >= 1.2.8 ) тип сервера. Если задан, то атрибут FileHost игнорируется.
  Значения: image (по умолчанию) — хостинг картинок, file — файловый хостинг (при этом FileHost="1" тоже обязательно нужно указывать), urlshortening — сервис сокращения ссылок (для них вместо xml-узла <Server> следует использовать <Server2>).
  searchbyimage — серис обратного поиска по изображению
• Types - (ver >= 1.3.2 )
  Список типов через пробел, например file image urlshortening
• NeedPassword — (ver >= 1.2.9 build 4186) нужен ли пароль для авторизации. Необходимо для серверов с авторизацией через OAuth 2.0.
  Значения: 1 (по умолчанию) — нужен, 0 - не нужен (поле ввода пароля будет не активно)
• Debug — параметр, предназначенный для тестирования и отладки загрузки на данный сервер. При значении 1 любая загрузка на данный сервер в программе будет сопровождаться отображением информации об отправляемых запросах и принимаемых данных.
• MaxFileSize — максимальный размер загружаемого файла, поддерживаемого сервером. Значение указывается в байтах. Значение по умолчанию — 0, что означает, что файл может быть какого угодно размера.
• MinVersion — (ver >= 1.3.1 ) Минимальная версия программы, поддерживаемая данным сервером. Следует использовать, если вы используете возможности, отсутствующие в старых версиях программы. Атрибут должен иметь формат x.x.x или x.x.x.xxxx. При этом вместо узла <Server> следует использовать <Server3>.
• Plugin — содержит название файла плагина (без расширения .nut), отвечающего за загрузку на этот сервер. Скрипт должен быть расположен в каталоге Data\Scripts, и иметь расширение .nut. Если данный атрибут не пустой, весь узел <Actions> игнорируется, и всё взаимодействие с серверами перекладывается на скрипт. Однако, узел Actions всё равно может быть задан, для обратной совместимости с версиями программы < 1.2.5.
  Подробнее о создании плагинов...
• Engine — (ver >= 1.3.2 build 4551) название встроенного движка загрузки. Чтобы использовался стандартный движок, нужно оставить поле пустым. Другие возможные значения: "MegaNz".
• SupportsFolders — поддержка альбомов скриптом загрузки. Используется вместе с атрибутом Plugin.
• WebsiteUrl — (ver >= 1.4.1 ) адрес веб-сайта.
• RegistrationUrl — адрес, по которому можно зарегистрироваться на данном сервере.
• LoginLabel — (ver >= 1.3.2.4616 ) — надпись перед полем ввода логина (это может быть "E-mail", "Login" и т.п.). Если текст будет слишком длинным, он не будет полностью отображен.
• PasswordLabel — (ver >= 1.3.2.4616 ) — надпись перед полем ввода пароля (это может быть "Password", "API Key" и т.п.). Если текст будет слишком длинным, он не будет полностью отображен.
• UserAgent — (ver >= 1.3.2.4432 ) — custom http header "User-Agent"
• MaxThreads — (ver >= 1.3.2 ) — ограничение количества одновременных соединений (потоков) к этому серверу. Этот ограничивающий параметр введен по двум причинам: Во-первых, некоторые серверы ограничивают и блокируют параллельные запросы к ним. Во-вторых, чтобы сохранить порядок изображений в альбоме (при MaxThreads=1). По-умолчанию, количество потоков не ограничено.
• DefaultForTypes - (ver >= 1.3.3 )
  Список типов серверов через пробел, например file image, для которых этот сервер является сервером по-умолчанию. Если в файле servers.xml встречается несколько серверов с атрибутом DefaultForTypes и типы пересекаются, в качестве сервера по-умолчанию будет использоваться тот, что встречается в файле позже.
• UploadToTempServer (ver >= 1.4.1 ) — указывает, нужно ли загружать изображение на промежуточный сервер (актуально только для сервисов поиска по изображению). Эта опция может использоваться, если сервис поиска не поддерживает поиск по загруженному файлу.

Узел SupportedFormats

Необязательный узел. Поддерживается начиная с версии 1.4.1. Узел должен содержать вложенные узлы FormatGroup.

Необязательные атрибуты узла FormatGroup:

• MaxFileSize — максимальный размер файла в этой группе (в байтах).
• Authorized — если равен 1, то эта группа форматов относится только к авторизованному пользователю.

Узел FormatGroup содержит вложенные узлы Format:

<Format MimeType="image/jpeg">*.jpg,*.jpeg</Format>

В атрибуте MimeType перечисляются (через запятую) разрешенные MIME-типы файлов, которые могут содержать подстановочные символы - wildcards, а в тексте узла перечисляются расширения файлов (через запятую), которые также могут содержать подстановочные символы. Если в одном узле Format указан только MIME-тип(-ы), или только расширение(-ия), то проверка файлов будет производиться только по одному признаку.

Узел Actions

Узел <Actions> (без атрибутов) содержит вложенные узлы Action, каждый из которых обозначает одно действие (как правило, это запрос к серверу). Запросы выполняются в том порядке, в котором они указаны в файле, т.е. сверху вниз.

<Action Type="get" Url="http://example.com/" RegExp="id(\d+)" AssignVars="ИмяПеременной:0" 
    [дополнительные атрибуты]/>

Каждый узел <Action> может иметь следующие атрибуты:

• Url — обязательный атрибут. Должен содержать HTTP, HTTPS или FTP адрес. Может содержать переменные.
• Type — тип запроса к серверу (или другого действия).
  Может принимать следующие значения:
  • get — метод GET протокола HTTP
  • post — метод POST протокола HTTP
  • login — то же, что и post, но предназначено только для авторизации.
  • upload — POST-запрос в формате multipart/form-data. Именно этот тип запроса используется в большинстве случаев для загрузки файлов.
  • put — загрузка файла с помощью HTTP PUT запроса или загрузка на FTP. Поддерживается лишь некоторыми серверами.
  • openurl (version >= 1.4.1) — открытие URL в приложении по-умолчанию
• PostParams — список параметров, передаваемых серверу по протоколу POST (Type=post или Type=upload), разделенных точкой с запятой.
  Список имеет следующий вид: НазваниеПараметра1=Значение1;НазваниеПараметра2=Значение2;...
  Значения могут содержать названия переменных, которые будут автоматически подставлены (раскрыты) перед выполнением запроса. Также есть особое значение — %filename%, вместо которого в запрос подставляется содержимое загружаемого файла (не надо путать с _FILENAME ). Чтобы в значениях использовать сам символ ;, необходимо его экранировать: \; .
• RegExp — регулярное выражение в формате PCRE. Служит для извлечения необходимой информации (ссылок, идентификаторов) из текста ответа, полученного от сервера (чаще всего HTML страницы). Если сопоставление регулярному выражению не удалось, программа генерирует предупреждение в лог ошибок и повторяет запрос.
• AssignVars — в данном атрибуте перечисляются имена новых переменных, и сопоставленные им номера подмасок (subpatterns) регулярного выражения. Параметр AssignVars имеет формат НазваниеПеременной:НомерПодмаски;.... Подмаска в регулярном выражении это то, что заключено в круглые скобки. Нумерация подмасок начинается с нуля. Имя переменной может содержать символы A-z, 0-9 и символ подчеркивания. Подробнее о переменных в servers.xml
• OnlyOnce — значение 1 означает, что данный запрос будет выполняться лишь 1 раз за всю сессию загрузки. Чаще всего таким запросом является авторизация на сервере. Значение 0 - данный запрос выполняется при загрузке КАЖДОГО файла.
• Referer — (опциональный параметр) адрес страницы источника запроса. Используется, если сервер ограничивает запросы с чужих сайтов. По умолчанию программа устанавливает Referer такой же, как предыдущий адрес.
• Description — опциональный параметр, содержащий описание текущего действия. Отображается в окне программы.
• CustomHeaders — (ver >= 1.3.2.4432) список дополнительных полей заголовка, разделенных точкой с запятой. Список должен иметь следующий вид: НазваниеПараметра1:Значение1;НазваниеПараметра2:Значение2;...
  To remove default field, pass an empty value.
• Вложенные узлы (version >= 1.3.2)
  RegExp

  <Action Type="upload" Url="http://imgur.com/api/upload.xml" PostParams="image=%filename%;key=2dd16e2e19119996855ae9312b7a1305;" RegExp='&lt;original_image&gt;(.*?)&lt;\/original_image&gt;([\s\S]*?)&lt;small_thumbnail&gt;(.*?)&lt;\/small_thumbnail&gt;' AssignVars="Image:0;Thumb:2">
  	<RegExp Pattern="&lt;delete_page&gt;(.*?)&lt;\/delete_page&gt;" AssignVars="DeleteUrl:0;"/>
  </Action>
  

  • Pattern - то же самое, что атрибут RegExp у узла Action.
  • AssignVars - то же самое, что атрибут AssignVars у узла Action.
  • Required - генерировать ошибку, если сопоставление регулярному выражению не удалось. (по умолчанию 0)
  • Data - в каком тексте производить поиск. Может содержать переменные. (по умолчанию - текст ответа от сервера)
  Call - вызов функции (version >= 1.4.0)

  <Call Function="json" Arg1="files[0].url" AssignVars="DownloadUrl:0;"/>
  

  • Function - название функции. Пока доступны только функции json и regexp. Примеры синтаксиса json path можно увидеть здесь.
  • Arg[n] (Arg0, Arg1, Arg2) - аргументы. Arg0 по-умолчанию содержит тело ответа. Могут содержать переменные.
  • AssignVars - то же самое, что атрибут AssignVars у узла Action.
  • Required - генерировать ошибку, если функция завершилась с ошибкой (по умолчанию 0)

Узел Result

Типичный вид xml-узла Result:

<Result ImageUrlTemplate="$(Image)" ThumbUrlTemplate="$(Thumb)" DownloadUrlTemplate="$(View)"/>

Атрибуты узла Result:

• ImageUrlTemplate — строка-шаблон для генерации ПРЯМОЙ ссылки на картинку или файл.
• ThumbUrlTemplate — строка-шаблон для генерации ПРЯМОЙ ссылки на файл миниатюры. Если не задан, программа будет сама генерировать миниатюры, даже если включена опция "Использовать серверные миниатюры". Генерирование миниатюры будет невозможно, если параметр ImageUrlTemplate не задан или принимает пустое значение.
• DownloadUrlTemplate — строка-шаблон для генерации ссылки на страницу просмотра, скачивания и т.п.
• DeleteUrl — (ver >= 1.3.2) ссылка для удаления файла
• EditUrl — (ver >= 1.3.2) ссылка для редактирования файла

Каждый из этих атрибутов может содержать переменные.

Один из атрибутов — ImageUrlTemplate или DownloadUrlTemplate — должен быть обязательно задан. Программа использует тот или иной атрибут в зависимости от настроек, и в зависимости от того, какой из атрибутов задан, а какой нет. По-умолчанию предпочтение отдается прямой ссылке. В случае использования скрипта (плагина - атрибут Plugin узла Server), все атрибуты всё равно должны иметь непустые значения.

Переменные в строках и атрибутах

Все переменные, доступные для использования в атрибутах узлов Action и Result, задаются в параметре AssignVars, или же встроены в саму программу.

Название переменной может содержать алфавитно-цифровые символы (A-z, 0-9) и символ подчеркивания. Имена переменных чувствительны к регистру. Если название переменной начинается с символа подчеркивания, это означает, что данная переменная не будет удалена после загрузки файла, и она останется в памяти на всю сессию загрузки. Однако это не означает, что её значение не может быть перезаписано.

Список встроенных переменных:

• _FILENAME — имя загружаемого файла (без пути к файлу).
• _FILENAMEWITHOUTEXT — имя загружаемого файла без расширения.
• _FILEEXT — расширение файла.
• _THUMBWIDTH — ширина миниатюры.
• _THUMBHEIGHT — высота миниатюры.
• _THUMBCREATE (ver >= 1.4.2) — создавать миниатюру (0 или 1).
• _THUMBADDTEXT (ver >= 1.4.2) — добавлять текст на миниатюру (0 или 1).
• _THUMBUSESERVER (ver >= 1.4.2) — использовать серверные миниатюры (0 или 1).
• _RAND16BITS — случайное число от 0 до 65535. Генерируется только один раз при загрузке каждого файла.
• _THREADID — (ver > 1.3.2) идентификатор текущего потока (нити)
• _LOGIN — имя пользователя (задана, если пользователь включил авторизацию в настройках)
• _PASSWORD — пароль пользователя.
• _ORIGINALURL — ссылка, которую надо сократить (только для серверов сокращения ссылок).
• _IMAGEURL (ver > 1.4.1) — прямая ссылка на изображение для поиска по нему (которое может находиться на промежуточном хостинге хранения изображений). Это актуально только для узла Server c Type="searchbyimage".

Для подстановки значений переменных в строковые параметры используются конструкции вида $(ИмяПеременной). Количество подставляемых переменных не ограничивается. Если переменная не существует, вместо неё будет подставлена пустая строка.

Пример:

<Server Name="slil.ru" FileHost="1">
        <Actions>
             <Action Type="upload" Url="http://zalil.ru/upload/" PostParams="file=%filename%;submit=Send" 
		RegExp="http://slil.ru/(\d*)" AssignVars="File:0"/>
        </Actions>
        <Result DownloadUrlTemplate="http://slil.ru/$(File)"/>
</Server>

В строке AssignVars="File:0" задается переменная с именем File и ей присваивается некоторое числовое значение, полученное из первой подмаски регулярного выражения (например, File=12345). Затем созданная переменная используется в параметре DownloadUrlTemplate="http://slil.ru/$(File)", который в результате подстановки принимает значение http://slil.ru/12345. Полученную ссылку пользователь видит в окне программы.

Преобразование переменных с помощью фильтров (version >= 1.2.9)

Переменные можно преобразовывать при выводе. Пример: $(Переменная|НазваниеФильтра)

Список фильтров:

urlencode - процентное кодирование. Пример Url="http://example.com?filename=$(_FILENAME|urlencode)"
htmldecode - (version >= 1.3.2) decode HTML entities

Создание скриптов (плагинов)

Для расширенной поддержки серверов в программе используются скрипты на языке Squirrel 3 (до версии 1.3.2 использовался Squirrel 2).

Они должны быть сохранены в кодировке utf-8 в файлах с расширением .nut.

Scripting API reference

Документация языка Squirrel
Документация стандартной библиотеки языка Squirrel (PDF)