API_DOC.txt

STB API

API для обработки интерфейса STB через java приложение

все имена функций передаются в параметре act,
пример:
url.com/stb.pl?act=movie_show_location&аргументы

Параметры:
- с типом int:
user_id, movie_id, from, to, serial_id, friend_id, playlist_id
- с типом char(4):
sort, sort_order

остальные типы пишутся сразу за названием аргумента.
возможные варианты значений аргумента пишутся за типом в скобках разделенные |
пример: (name|date) - означает что аргумент sort может принимать два значения name или date

############################################
# Методы для обработки событий с "Фильмами"
############################################

# сомнения насчет правильности передаваемых аргументов и алгоритма (алгоритма вообще нет)
movie_show_location
 Назначение: Показать список фильмов из location
 Аргументы (* - помечены необязательные):
 user_id (int) - ID пользователя системы
 location(varchar(100)) - местоположение файлов в сети
 dir(directory_id)(varchar(100)) - содержимое директории (даже для корневой необходимо указывать)*, зависит от контекста
 from(int),to(int) - определяет размер выборки (от и до) для списка *
 sort(name|date)(char(4)) - сортировать выборку по имени (умолчание), дате *
 sort_order(asc|desc)(char(4)) - направление сортировки, asc по умолчанию *
 Возвращает: массив хэшей с именами ключей:
 1. {movie_id} id фильма 
 2. {dir_id} id директории
 3. {foto_url} url на фото
 4. {movie_name} название фильма/директории
 5. {date_create} дата создания, 6. {date_upload} дата загрузки, 7. {date_changes} дата изменения
 8. {paid_status} статус оплаты (1|0);


movie_show_order
 Назначение: Показать список фильмов из заказов
 Аргументы (* - помечены необязательные):
 user_id(int),
 serial_id(int),(если сериал) *
 from(int),to(int) - определяет размер выборки (от и до) для списка *
 sort(name|date)(char(4)) - сортировать выборку по имени (умолчание), дате *
 sort_order(asc|desc)(char(4)) - направление сортировки, asc по умолчанию *
 Возвращает: массив хэшей с именами ключей:
 1. {movie_id} id фильма
 2. {percent} - процент заказчики
 3. {foto_url} url на фото
 4. {movie_name} название фильма/сериала
 5. {date_create} дата создания, 6. {date_upload} дата загрузки, 7. {date_changes} дата изменения
 8. {paid_status} статус оплаты (1|0);
 9. {serial_id}  - будет !=0 если является фильм сериалом


movie_show_playlist
 Назначение: Показать список фильмов из плейлиста
 Аргументы (* - помечены необязательные):
 user_id(int), playlist_id(int),
 serial_id(int),(если сериал) *
 from(int),to(int) - определяет размер выборки (от и до) для списка *
 sort(name|date)(char(4)) - сортировать выборку по имени (умолчание), дате *
 sort_order(asc|desc)(char(4)) - направление сортировки, asc по умолчанию *
 Возвращает: массив хэшей с именами ключей:
 1. {movie_id} id фильма
 2. {foto_url} url на фото
 3. {movie_name} название фильма/сериала
 4. {serial_id}  - будет !=0 если является фильм сериалом


movie_show_detail
 Назначение: Показать инфорацию о фильме подробно
 Аргументы (* - помечены необязательные):
 user_id(int), movie_id(int),
 Возвращает: массив:
 1. id фильма
 2. url на фото
 3. [массив url на трейлеры]
 4. название фильма/сериала
 5. [массив тэгов]
 6. Жанр
 7. год выпуска
 8. режисер
 9. [актеры]
 10. Описание
 11. Стоимость
 12. Рейтинг
 Алгоритм: 1. запрос из БД, запрос из ЛБ стоимости фильма, запрос из ИМХОНЕТ рейтинга

########################################
# Действия на стр.8 для интерфейса
########################################

movie_rate
 Назначение: Отправить рейтинг (проголосовать)
 Аргументы (* - помечены необязательные):
 movie_id(int), user_id(int), rate(bit) (1..5)
 Возвращает: новое значение рейтинга

movie_add_tag
 Назначение: Добавить тэг
 Аргументы (* - помечены необязательные):
 movie_id(int), user_id(int), tag(varchar(50)) # сколько давать для тэга? #
 Возвращает: массив тэгов, статус операции (0/1):

movie_mark_favor
 Назначение: Отметить как понравилось
 Аргументы (* - помечены необязательные):
 movie_id, user_id, flag(bit) (1|0) - (1 - понравилсь, 0 - снять статус понравившегося)
 Возвращает: статус операции (0|1);

movie_add_comment
 Назначение: Добавить комментарий
 Аргументы (* - помечены необязательные):
 movie_id, user_id, comment (text)
 Возвращает: статус операции (0|1)

movie_show_comments
 Назначение: Показать отзывы о фильме (с .. по ..)
 Аргументы (* - помечены необязательные):
 movie_id, from, to
 Возвращает: массив хэшей с ключами:
 1. {user_id} - 
 2. {user_name} - имя автора
 3. {comment} - текст комментария

movie_pay
 Назначение: Оплатить фильм
 Аргументы (* - помечены необязательные):
 user_id, movie_id
 Возвращает: статус операции (0\1):

movie_offer_friend
 Назначение: Предложить другу (вызывается после получения списка друзей)
 Аргументы (* - помечены необязательные):
 movie_id, user_id, friend_id (передаем id друга/друзей, которому предложить)
 friend_id в случае нескольких id передаем через точку с запятой
 Возвращает: статус операции (0\1):

movie_get_torrent_link
 Назначение: Запрос торрент ссылки по movie_id
 user_id, movie_id
 Возвращает: массив хэшей с ключами:
 {movie_id} => 'url'

#############################################
# Методы для обработки событий с "Плейлистами
#############################################

playlist_add
 Назначение: Добавляем новый playlist
 Аргументы:
 user_id, playlist_name(varchar(255))
 Возвращает: playlist_id, статус операции (0/1):

playlist_del
 Назначение: Удаляем playlist
 Аргументы: user_id, playlist_id 
 Возвращает: статус операции (0/1):

playlist_add_movie
 Назначение: Добавляем в playlist
 Аргументы: user_id, playlist_id, movie_id 
 Возвращает: статус операции (0/1):

playlist_del_movie
 Назначение: Удаляем из playlist
 Аргументы: user_id, playlist_id, movie_id 
 Возвращает: статус операции (0/1):

############################################
# Методы для обработки событий с "Друзьями"
############################################

friends_watched
 Назначение: показать "Друзья смотрели"
 Аргументы: 
 user_id, serial_id*,
 from(int),to(int) - определяет размер выборки (от и до) для списка *
 sort(name|date) - сортировать выборку по имени (умолчание), дате *
 sort_order(asc|desc) - направление сортировки, asc по умолчанию *
 Возвращает: массив хэшей с именами ключей:
 1. {movie_id} id фильма
 2. {foto_url} url на фото
 3. {movie_name} название фильма/сериала
 4. {serial_id}  - будет !=0 если является фильм сериалом
 5. {friend_id} - id пользователя (друга)
 6. {friend_name} - имя друга

friends_list
 Назначение: Список друзей/общих друзей
 Аргументы (* - помечены необязательные):
 user_id, share(bit)* (1|0) - показать общих друзей, показать своих друзей
 Возвращает: массив:
 1. id друга
 2. Имя друга
 3. Ссылка на фото

friend_profile
 Назначение: Показать Профайд друга
 Аргументы: user_id, friend_id
 Возвращает: массив:
1. id друга
2. Имя друга
3. Ссылка на фото
4. О себе

friend_content
 Назначение: Публичный контент друга  
 Аргументы (* - помечены необязательные): 
 user_id, friend_id, serial_id*,
 from(int),to(int) - определяет размер выборки (от и до) для списка *
 sort(name|date) - сортировать выборку по имени (умолчание), дате *
 sort_order(asc|desc) - направление сортировки, asc по умолчанию *
 Возвращает: массив хэшей с именами ключей:
 1. {movie_id} id фильма
 2. {foto_url} url на фото
 3. {movie_name} название фильма/сериала
 4. {serial_id}  - будет !=0 если является фильм сериалом
 5. {friend_id} - id пользователя (друга)
 6. {friend_name} - имя друга

friend_edit
 Назначение: Удаляем/Добавляем друга
 Аргументы: user_id, friend_id, do(char(4)) (add|dell)
 Возвращает: статус операции (0/1):

friend_search
 Назначение: Поиск друзей в системе
 Аргументы: user_id, keyword(varchar(30))
 Возвращает: массив:
 1. id друга
 2. Имя друга
 3. Ссылка на фото

#################################################
# Методы для обработки событий с "Сообщениями"
#################################################

messages_friend
 Назначение: Сообщения друга
 Аргументы (* - помечены необязательные):
 user_id, friend_id, from* , to(int)* (диапазон с .. по ..) 
 Возвращает: массив хэшей с ключами:
 1. user_id
 2. id сообщения
 3. время отправки сообщения unixtime
 4. тело сообщения
 5. friend_id
 6. прочитано ли сообщение получателем (0 или 1)

message_post
 Назначение: Написать сообщение
 Аргументы: 
 user_id, friend_id, message(text)
 Возвращает: статус операции (0/1):


#################################################
# Методы для обработки событий с "Locations"
#################################################
# Николай - посмотри методы работы с location

location_add
 Назначение: Добавить location
 Аргументы:  
 user_id, url(varchar(255))
 Возвращает: статус операции (0/1):

location_del
 Назначение: Удалить Location
 Аргументы: 
 user_id, url(varchar(255)) 
 Возвращает: статус операции (0/1):

location_available
 Назначение: Проверить доступность location
 Аргументы: 
 user_id, url(varchar(255)) 
 Возвращает: статус доступности (0 -нет /1 - доступно):

location_scan_lan
 Назначение: Сканировать LAN
 Аргументы: user_id
 Возвращает: массив:
 1. url на фото  (?)
 2. ссылку на ресурс


#################################################
# Методы для обработки событий с "Настройками/ЛК"
#################################################

user_profile
 Назначение: Показывает настройки профиля/ сохраняет настройки при
 передаче необязательных аргументов
 Аргументы (* - помечены необязательные):
 user_id,
 аргументы настройки (показывать инфо или нет):
 hist(bit) - показывать историю * , histXXX(bit) - показывать историю xxx *, public(bit) - показывать информацию,
 принимаемые значения:
 0 - не показывать никому (сброс всех флажков в интерфейсе),
 1 - показывать друзьям,
 2 - показывать всем
 Возвращает массив:
 1. ссылка на фото
 2. массив хэшей с элементами:
 {hist} - показывать историю (1|0)
 {histXXX} - показывать историю XXX (1|0)
 {public} - показывать инфо обо мне (1|0)

user_accounts
 Назначение: Показать список пользователей
 Аргументы:  
 user_id
 Возвращает: массив массивов:
 1. account_id
 2. url на фото
 3. имя пользователя

user_acc_add
 Назначение: Добавить пользователя
 Аргументы:  
 user_id, account_name(varchar(50))
 Возвращает: id пользователя (account_id,) статус операции (0/1)

user_acc_del
 Назначение: Удалить пользователя
 Аргументы:  
 user_id, account_id(int)
 Возвращает: статус операции (0/1):

user_account_details
 Назначение: Показать настройки пользователя/сохранить настройки
 Аргументы (* - помечены необязательные):
 user_id, account_id(int),
 balance(number)*,cost_limit(number)*,age_limit(smallint)*
 PIN*,rePIN* - пин и повтор пина
 browser*
 Возвращает: ссылку на хэш
 {balance} - остаток на счете (number)
 {symbol} - валюта счета 
 {login} - логин на статистику
 {pass} - пароль на статистику
 {email} - email
 {tarifdescr} - наименование тарифа
 {birthdate} - день рождения
 {name} - ФИО 
 {number} - номер лицевого счета
 {cost_limit} - месячный лимит (number)
 {age_limit} - возрастной лимит (8,12,17,21)
 {browser} - разрешить броузер (1|0)

user_balance
 Назначение: Баланс пользователя
 Аргументы:  
 user_id
 Возвращает: ссылку на хэш
 {balance} - остаток на счте (число: %.2f)
 {symbol}  - валюта счета
    
user_statistic
 Назначение: Статистика потребления за период
 Аргументы:  
 user_id, from(datetime), to(datetime)
 Возвращает: массив хэшей
 {date} - дата операции
 {account} - имя пользователя (аккаунта)
 {descr} - описание услуги
 {cost} - списанная сумма

user_reccomend
 Назначение: Рекомендации для пользователя (из имхонета)
 Аргументы:  
 user_id
 Возвращает: массив массивов хэшей с именами ключей:
 1. {movie_id} id фильма
 2. {foto_url} url на фото
 3. {movie_name} название фильма/сериала
 4. {serial_id}  - будет !=0 если является фильм сериалом

###########################################
# Add-on method... или просто то что не учли
###########################################

get_DRM_key
 Назначение: Получить ключ по id транзакции
 Аргументы:  user_id, transact_id(int)
 Возвращает: массив с 1 элементом
 1. drm_key

user_got_movie
 Назначение: Сообщает нам об успешном получении файлов 
 через torrent-клиент на STB (медиаобъекта)
 Аргументы: user_id, movie_id
 Возвращает: 1|0
 
pkuptsov@gmail.com