API в основном используется клиентами программ контроля, хотя может быть полезным и для любых сторонних утилит.
Все функции реализованы ввиде COM-сервера.
Примеры использования для C, C++, Delphi находятся
здесь
Общие замечания:
- доступ к функциям осуществляется через единый интерфейс IRunpadProShell
- старые интерфейсы IRunpadShell/IRunpadShell2 доступны лишь для обратной совместимости
- попытки использовать API на момент, когда еще не выполнен Logon пользователя, приведут к неудаче (это следует учесть в сервисных приложениях)
- все функции возвращают S_OK в случае успеха и другие коды в противном случае
- функции не являются Unicode
- API доступно только в 32-битном виде
HRESULT GetShellPid(OUT DWORD *lpdwPID);
Возвращает PID процесса шелла.
Клиент может использовать эту информацию, чтобы не снимать и не закрывать процесс шелла. Это рекомендуется, несмотря на встроенную защиту шелла от снятия процесса.
Если шелл не загружен, то будет возвращена ошибка.
HRESULT GetShellMode(OUT DWORD *lpdwFlags);
Возвращает флаги режимов шелла:
RSM_MONITOR - показывает, включен (1) или отключен (0) монитор
RSM_INPUT - показывает, разрешены (1) или запрещены (0) мышь и клавиатура
RSM_BLOCKED - показывает, заблокирован (1) или разблокирован (0) запуск программ
HRESULT IsShellOwnedWindow(HWND hWnd, OUT BOOL *lpbOwned);
Проверяет, является ли какое-угодно окно окном шелла.
С такими окнами рекомендуется ничего не делать клиенту (хотя в шелле встроена защита от подобных действий).
HRESULT GetFolderPath(RSHELLFOLDER dwFolderType, OUT LPSTR lpszPath, DWORD cbPathLen);
Возвращает путь к папке шелла (буфер должен быть длиной не менее MAX_PATH):
RSF_USERFOLDER - папка пользователя
RSF_VIPFOLDER - личная (VIP) папка пользователя. Последний элемент в VIP-папке всегда является именем текущего VIP-пользователя
При отсутствии ресурса может быть возвращена пустая строка.
HRESULT GetCurrentSheet(OUT LPSTR lpszName, DWORD cbNameLen);
Возвращает имя рабочей закладки (длина буфера должна быть не менее MAX_PATH)
HRESULT EnableSheets(IN LPCSTR lpszName, BOOL bEnable);
Запрещает или разрешает закладку, заданную по имени. Если lpszName равно NULL, то действие применяется ко всем закладкам.
Изменения хранятся только в данном сеансе пользователя. При следующем старте шелла все закладки снова будут разрешены.
Функция является асинхронной.
HRESULT RegisterClient(IN LPCSTR lpszClientName, IN LPCSTR lpszClientPath, DWORD dwFlags);
Выполняет регистрацию программы клиента.
Регистрация нужна для того, чтобы нельзя было запускать ярлыки до старта клиента, работал режим автовосстановления клиента (на случай если его снимут), а также чтобы разрешить иконку клиента в трее и добавить его в список неснимаемых задач шелла.
Все эти действия можно сделать вручную, путем прописывания в настройках шелла файла клиента, а можно автоматически через данное API.
Рекомендуется вызывать данную функцию при старте клиента один раз. Все изменения не сохраняются в последующих сеансах работы шелла.
В качестве параметров передается символическое название клиента (например, "GameClass Client"), а также полный путь к его EXE-файлу.
Параметр dwFlags зарезервирован и должен быть нулевым.
Функция является асинхронной.
HRESULT ShowInfoMessage(IN LPCSTR lpszText, DWORD dwFlags);
Показывает информационное сообщение на экране или во всплывающей подсказке в трее.
Длина строки не должна превышать 255 символов.
В поле флагов HIWORD задает длительность отображения в секундах (0 - по умолчанию), LOWORD может быть одним из значений:
RSMSG_DESKTOP - сообщение на экране
RSMSG_TRAY - сообщение во всплывающей подсказке в трее
RSMSG_STATUS - изменение статусной строки, длительность игнорируется
Функция является асинхронной.
HRESULT DoSingleAction(RSHELLACTION dwAction);
Выполняет определенное действие:
RSA_MINIMIZEALLWINDOWS - минимизирует все активные окна
RSA_KILLALLTASKS - снимает все разрешенные задачи (аналог команды шелла/программы оператора)
RSA_RESTOREVMODE - восстанавливает видеорежим (после выхода из проблемных игр)
RSA_CLOSECHILDWINDOWS - закрывает все дочерние окна шелла
RSA_CLOSEACTIVESHEET - закрывает активную закладку
RSA_TURNMONITORON - включает монитор
RSA_TURNMONITOROFF - отключает монитор
RSA_ENDVIPSESSION - завершает личную (VIP) сессию клиента
RSA_RUNPROGRAMDISABLE - запрещает запуск ярлыков. Смотрите также опцию настроек шелла "Блокировка".
RSA_RUNPROGRAMENABLE - разрешает запуск ярлыков. Смотрите также опцию настроек шелла "Блокировка".
RSA_LOGOFF - завершение сеанса
RSA_LOGOFFFORCE - завершение сеанса (форсированное)
RSA_RUNSCREENSAVER - запуск хранителя экрана
RSA_SHOWLA - показывает окно лицензионного соглашения (если установлено в настройках шелла)
Функция является асинхронной.
HRESULT VipLogin(IN LPCSTR lpszLogin, IN LPCSTR lpszPassword, BOOL bWait);
Выполняет операцию входа в личную (VIP) сессию пользователя по логину и паролю.
Пароль игнорируется если включена соотв. опция в настройках шелла (см. вкладку "VIP-клиенты").
Если в текущий момент сессия уже начата, то сначала произойдет завершение текущей сессии, а затем начало новой.
Функция не будет работать если в шелле не разрешена работа с VIP-сессиями (запрещен соотв. пункт главного меню).
Параметр bWait определяет, ожидать фактического выполнения команды или нет. Если не ожидать, то функция будет асинхронной, а с ожиданием таймаут может быть вплоть до 10-12 секунд.
Следует учесть, что в синхронном варианте при ожидании обрабатываются оконные сообщения Windows.
Код возврата имеет смысл проверять только если bWait=TRUE
HRESULT VipRegister(IN LPCSTR lpszLogin, IN LPCSTR lpszPassword, BOOL bWait);
Полностью аналогична предыдущей функции с тем лишь отличием, что происходит регистрация нового пользователя в базе.
Ошибка может быть возвращена если регистрация запрещена на сервере или пользователь уже есть в базе.
При успешном выполнении происходит автоматический логин пользователя.
HRESULT VipLogout(BOOL bWait);
Завершает личную сессию пользователя.
См. также функции VipLogin, VipRegister.
HRESULT TempOffShell(IN LPCSTR lpszPasswordMD5, BOOL bShowReminder);
Выполняет временное отключение шелла.
На вкладке настроек "Аварийное отключение" должен быть установлен пароль аварийного отключения, MD5-хэш которого нужно передать в эту функцию (при вычислении MD5 пароль нужно привести к нижнему регистру).
Второй параметр позволяет показывать или не показывать предупреждение о завершении сеанса после простоя N-минут, при этом если предупреждения не показывать, то и автоматического завершения сеанса не произойдет.
Переменные окружения
Доступны следующие переменные окружения (при включенном шелле):
%RS_FOLDER% - Путь к базовой папке, куда установлен клиентский шелл
%RS_MACHINE% - Описание машины (может быть ее номер)
%RS_LOC% - Местоположение машины
%RS_VIPFOLDER% - Путь к личной VIP-папке пользователя
%RS_VIPSESSION% - Название личной VIP-сессии (имя VIP-пользователя)
%RS_USERFOLDER% - Путь к папке пользователя