Программный интерфейс TELE2 API

Программный интерфейс TELE2 API
Введение
Программный интерфейс TELE2 API предназначается для:
• Создания собственных приложений, использующих функциональность TELE2 (проигрывание
видео-клипов с наложенными композициями переднего плана, различными эффектами)
• Кастомизации самой программы TELE, например, с целью добавления системы учета, биллинга,
т.д.
Преимущество TELE2 API, в частности, заключается в том, что все функции интерфейса возвращают
управление мгновенно, так что Ваша программа не будет «повисать», ожидая, когда функция выполнится.
Приложение может быть написано на любом средстве программирования, позволяющем интегрировать
контролы ActiveX, COM-объекты или DLL. Среди них: DHTML (VB, JavaScript), VBA (MS Word, MS Excel,
MS Access), Microsoft Visual Basic 6.0/2003/2005, Microsoft C++ 6.0/2003/2005, Microsoft C# 6.0/2003/2005,
Borland Delphi (for Windows 32/64).
Для интерфейсно-ориентированных средств программирования DHTML, VBA, VB, C# удобнее
использовать ActiveX control TELE2Ctrl. Для добавления его в программу достаточно добавить его в панель
Toolbox (в VS2005 это делается путем нажатия правой кнопкой на нее и выбора “Choose Items” – далее
нужно выбрать из компонентов COM TELE2Ctrl) и перетащить его на редактируемый диалог программы.
Таким образом, обращаться к объекту можно следующими способами:
а) через команду VBasic CreateObject("TELE.API")
б) через ActiveX control TELE2Ctrl
в) непосредственно через файл Logo2.dll, который содержит оба интерфейса и может быть также
импортирован как DLL
Еще одно преимущество TELE2Ctrl перед остальными способами вызова TELE2 API заключается в
наличии событий. Например, событие FastTimer вызывается точно в момент начала каждого кадра.
Возможности TELE2 API включают:
• Контроль проигрывания расписания TELE2 (запуск с любого момента, остановка, запуск
отдельного элемента)
• Загрузка, сохранение, создание расписания, клипов и композиций переднего плана
• Вызов различных интерфейсов программы TELE2
Есть 2 режима использования TELE2 API: с запущенной программой TELE2 и отдельно. Как уже
говорилось, интерфейс может применяться как для управления / кастомизации программы TELE, так и для
создания собственных приложений. В соответствии с этим, часть функций обращается к запущенному
экземпляру TELE2 (т.е. программа TELE2 должна быть запущена), часть функций не требует этого,
поскольку работает независимо.
Функции, работающие независимо от программы TELE2 и не требующие того, чтобы она была
запущена:
Login
AssignValue
ChooseTransition
ConvertFile
EditLogotype
FileClose
FileWriteLine
FileGetLine
GetFilePath
GetVideoClipDuration
GetValue
LoadLogosAndProfiles
RestoreAPro
SendObjDirect
SendObjects
SendPlayWithLogo
SendPlayWithLogos
SendVPlayerStop
SetQueueSize
Функции, используемые для управления программой TELE2 и требующие того, чтобы она была запущена:
AProAssignValue
AProGetValue
AProExecCommand
AProGetStatus
AddSchedItem
DeleteClip
GetSectionValue
GetSectionName
GetSectionKeyByN
GetNumSections
GetSectionLineByN
GetSectionLineByName
DelSchedItem
EditBlock
EditClip
FindSchedItem
PlayBlock
PlayClip
SetItemLogo
SetItemProfile
StartPlaybackFromItem
StartPlaybackFromTime
StartSystemPlay
StopPlayback
ParseLine
PreviewOn
PreviewOff
RegisterClip
Любая программа должна в начале вызывать функцию Login, чтобы программа получила доступ к
TELE2API. Эта функция вызывается в любом случае – если она использует TELE2 или если она работает
самостоятельно, используя только TELE2 API.
Композиции переднего плана хранятся в файле XML. Сама TELE хранит их в файле LogosAndProfiles.XML,
который находится в директории Alphapro. Однако, функции работающие независимо от TELE могут
использовать любой другой файл. Все что нужно сделать – это загрузить его при помощи команды
LoadLogosAndProfiles. Возможна загрузка и использование самого файла LogosAndProfiles.XML, который
используется программой ТЕЛЕ, однако не нужно забывать, что программа работает с загруженными в
оперативную память данными, и если ваше приложение загрузит LogosAndProfiles.XML, то в памяти будет
два экземпляра этого файла – один будет загружен программой ТЕЛЕ, другой – вашей; и изменение
объектов или логотипов одной программой не приведет к автоматическому изменению их в другой
программе – нужно будет сначала сохранить измененный LogosAndProfiles.XML одной программой и
загрузить его другой. Функция EditLogotype редактирует логотип в том файле, который был загружен вашей
программой (не TELE). После завершения редактирования функция автоматически сохраняет изменения в
тот файл XML, который был в последний раз загружен функцией LoadLogosAndProfiles. Еще раз загружать
файл после редактирования не нужно.
Переменные
Возможность использования переменных значительно повышает возможности TELE2 API.
Аналогично переменным Alphapro, переменные TELE2 могут входить в состав строк, выводимых на ТВ,
причем их значения автоматически подставляются при выводе. Например, можно задать объект переднего
плана типа «static» (см. раздел «Типы Объектов»), и присвоить ему значение: «Сегодня %DATE, Время:
%TIME». Когда этот объект будет выведен на экран, вместо %DATE %TIME будут автоматически выведены
текущие дата и время. Причем время будет «идти», т.е. минуты и секунды будут автоматически меняться.
Как видно из этого примера, названия переменных должны быть написаны большими латинскими буквами и
перед ним должен стоять процент. Переменные могут быть созданы пользователем – все что для этого
нужно сделать – это присвоить переменной значение:
AssignValue(“MYVAR”, “какой-то текст”)
Чтобы получить значение переменной можно использовать функцию GetValue:
s=LogoApiObj.GetValue(“MYVAR”)
Помимо пользовательских переменных, есть «системные» переменные, значения которых автоматически
присваиваются системой TELE:
%TIME – время в формате HH:MM:SS
%TIMEHHMM – время в формате HH:MM
%DATE – дата, например «Вторник 3 октября 2006г»
%SHORTDATE – дата в формате DD/MM/YY
%THERMO – показания термометра
Как описывается в разделе «Типы объектов», любому объекту переднего плана присваивается по
умолчанию (если значение пустое) переменная, имя которой соответствует названию этого объекта.
Функции общего назначения
Sub Login Key as String
Эта функция должна быть выполнена в самом начале работы. Key – цифровая часть номера HASP ключа
ТЕЛЕ-Инфоканал.
Пример: LogoApiObj.Login(“334”) для ключа D334
Function ChooseTransition(transition as String) as String
Запускает диалог выбора типа перехода. Параметр transition задает выбарнный по-умолчанию переход.
Функция возвращает название выбранного перехода.
Function ConvertFile (src as String, tgt as String, options as String) as Interger
Осуществляет конвертацию файлов и последовательностей кадров.
Function GetVideoClipDuration (fn as String) as Interger
Возвращает длительность клипа.
Sub PreviewOn ()
Переводит произрыватель в режим Preview ON.
Sub PreviewOff ()
Переводит произрыватель в режим Preview OFF.
Функции работы с композициями переднего плана (логотипами)
Sub AssignValue Var as String, Val as String
Присваивает значение переменной ТЕЛЕ. В имени переменной знак процента не указывается
Пример: LogoApiObj.AssignValue (“VAR2”,”text text text”)
В данном примере переменной ТЕЛЕ с именем %VAR2 присваивается значение ”text text text”.
Имена переменных среды ТЕЛЕ могут встречаться в тексте обьектов типа static а также в качестве имени
файла картинки в обьекте типа logo. При изменении значения переменной %VAR2, обьекты, в тексте
которых встречается %VAR2 обновляются на экране с учетом нового значения переменной. Другой способ
изменения значения параметров обьектов – функция SendObjDirect, когда параметрам присваиваются
значения напрямую, а не опосредованно через переменные
Function GetValue(Name as String) as String
Возвращает значение переменной ТЕЛЕ
Пример: s=LogoApiObj.GetValue(“VAR2”)
Sub LoadLogosAndProfiles FileName as String
Загрузить настройки логотипов (композиций переднего плана) и профилей из файла (XML или более ранний
формат ТЕЛЕ 2.0)
Пример: LogoApiObj.LoadLogosAndProfiles(“c:\alphapro\LogosAndProfiles.XML”)
При этом в память загружаются все композиции, находящиеся в файле.
Sub EditLogotype Name as String
Запускает редактор логотипов для логотипа (композиции переднего плана) Name. При нажатии на Save в
редакторе логотипов, текущий набор композиций и логотипов сохраняется в файл, из которого он был
загружен (см. LoadLogosAndProfiles)
Пример: LogoApiObj.EditLogotype(“New Logo1”)
Function ChooseTransition(Transition as string) Name as String
Запускает редактор графических переходов. Переходы используются, например, при
появлении/исчезновении группы, а также в видео-блоках. Настройки перехода хранятся в строке вида:
"TransitionLen=4 TransitionName=”””reveal_right””” Transition=”””reveal””” TransitionSoftness=8"
У перехода есть 4 параметра: длина перехода TransitionLen (в кадрах), «мягкость» перехода
TransitionSoftness, тип перехода Transition и имя перехода TransitionName.
Функция возвращает строку, содержащую описание выбранного перехода.
Пример: s=LogoApiObj.ChooseTransition(“”);
Sub SendObjDirect Obj as String, Cmd as String
Обновляет часть параметров обьекта (команда ObjDirect используется для присвоения значения объектов
логотипов или профилей когда они уже отображаются на экране, чтобы сменить в реальном времени
текст/логотип/…)
Пример: LogoApiObj.SendObjDirect(“crawl1”,”addtext=””AAAAAAAAAAAAAAAAA”””)
Этот пример добавляет текст к окончанию бегущей строки crawl1 .
Пример: LogoApiObj.SendObjDirect(“static1”,”text=””NEWTEXT”””)
Присвоение текстового значения обьекту типа static
Пример: LogoApiObj.SendObjDirect(“logo1”,”logo=””c:\alphapro\face.logo”””)
Изменение картинки, отображаемой в обьекте logo1
Пример: LogoApiObj.SendObjDirect(“group”,”text=””off”””)
Присвоение значения off группе приводит к исчезновению группы с экрана вместе со всеми
содержащимися в ней обьектами.
Sub SendObjects
Подготавливает к проигрыванию все логотипы и профили, инициализируюет все обьекты. Эту команду
нужно вызвать заранее, до начала проигрывания, а также после каждого изменения, внесенного
EditLogotype
Sub SendPlayWithLogo(back as String, logo as String, dur as Integer, profile as String)
Запускает проигрывание видео-файла или картинки back (указывается полный путь к ней, например
c:\avi\test.avi, либо «clear», если картинка отстутсвует, а наложение логотипов производится на проходящий
сигнал), с логотипом logo профилем profile и длительностью dur (в кадрах). Значение (-1) для длительности
означает бесконечное проигрывание. Значение «clear» для имени файла обозначает наложение логотипов на
проходящий видеосигнал
Пример: LogoApiObj.SendPlayWithLogo(“clear”,”New
Logo1”,10000,”DCS Bars”)
Пример: LogoApiObj.SendPlayWithLogo(“c:\avi\test.avi”,”New
Logo2”,1000,””)
Sub SendPlayWithLogos(back as String, logos as String, dur as Integer, profile as String)
Работает также как SendPlayWithLogo, но в параметре logos можно указывать несколько логотипов через
зяпятую. В этом случае будет показана композиция логитипов. Следует слудить за тем, чтобы ни в каких
двух из этих логотипах не было одинаковых объектов.
Функции реализующие доступ к Alpha Pro
Sub AProAssignValue Name as String, Value as String
Присваивает значение переменной AlphaPro
Действие функции эквивалентно AssignValue интерфейса Alpha Pro (см. описание расширенной версии
Alpha Pro).
Пример: LogoApiObj.AProAssignValue.Login(“%VAR1”,”text text text”)
function AProGetValue(Name as string) as String
Возвращает значение переменной AlphaPro
Действие функции эквивалентно GetValue интерфейса Alpha Pro (см. описание расширенной версии Alpha
Pro).
Пример: s= LogoApiObj.AProGetValue(“%VAR1”)
Sub AProExecCommand CmdLine as String
Выполняет команду AlphaPro
Действие функции эквивалентно ExecCommand интерфейса Alpha Pro (см. описание расширенной версии
Alpha Pro).
function AProGetStatus as String
Возвращает статус AlphaPro
Действие функции эквивалентно GetStatus интерфейса Alpha Pro (см. описание расширенной версии Alpha
Pro).
Функции реализующие доступ к текстовым файлам (для случаев, если
другие функции работы с файлами не доступны, например в HTML)
Sub FileClose FileName as String
Закрывает файл, который был открыт для записи или чтения
Function FileGetLine(FileName as String) as String
Считывает строку из файла FileName. Если это первое обращение к этому файлу, он будет открыт.
Sub FileWriteLine FileName as String, line as String
Записать строку в файл FileName. Если это первое обращение к этому файлу, то он будет создан и открыт.
Function GetFilePath as String
Открыть диалог выбора файла
Функции для работы с INI-файлами
GetSectionName (n as integer, file as String)
Возвращает название секции под номером N
Function
Function
String
as String
GetSectionKeyByN (n as integer, section as String, file as String)
as
Возвращает название ключа под номером N в данной секции
GetNumSections (file as String)
Возвращает количество секций
Function
Function
String
as Integer
GetSectionLineByN (n as integer, section as String, file as String)
Возвращает строку по номеру в данной секции
Function GetSectionLineByName (key as String, section as String, file as
String) as String
Возвращает строку по названию ключа в данной секции
ParseLine (line as String, key as String)
Возвращает значение ключа в строке
Function
as String
Функции реализующие доступ к расписаниям TELE Scheduler
Sub AddSchedItem AfterTime as Integer, type as Integer,Name as String
Добавляет в расписание новый элемент:
AfterTime – время начала
Type – тип (0 - clip, 1 - block, 2 - anchor, 3 - empty (name в этом случае является длительностью)
Name - название
Sub DelSchedItem N as Integer
Удаляет строку из расписания номер N
Sub EditBlock Name as String
Запускает редактор блоков для блока Name
Sub EditClip Name as String
Запускает редактор событий для события Name
Sub FindSchedItem time as Integer, Name as String
Найти номер строки расписания по времени и названию
Sub PlayBlock Name as String
Запускает блок Name на проигрывание
Sub PlayClip Name as String
Запускает событие Name на проигрывание
Sub SetItemLogo n as Integer, Logo as String
Устанавливает логотип строки расписания
Sub SetItemProfile n as Integer, Profile as String
Устанавливает профиль строки расписания
Sub StartPlaybackFromItem SchedItem as Integer
Запускает проигрывание со строки расписания с номером SchedItem
Sub StartPlaybackFromTime Time as Integer
Запускает проигрывание расписания со времени Time
as
Sub StartSystemPlay
Запускает проигрывание по системному времени
Sub StopPlayback
Останавливает проигрывание расписания
Sub RegisterClip(name as String, path as String)
Добавляет клип в БД
Типы объектов, используемые в композициях переднего плана
Каждый объект имеет различные параметры, их набор зависит от типа объекта.
Параметры делятся на общие и постоянные. Значение постоянных параметров одинаково во всех логотипах,
где данный объект используется, т.е. оно хранится в самом объекте. Задать значение постоянного
постоянного параметра проще всего непосредственно в редакторе логотипов. Значение переменных
параметров может быть разным в разных логотипах, поскольку оно хранится в логотипе, и такие значения
можно менять при помощи функции AssignValue или SendObjDirect.
Разница между AssignValue и SendObjDirect состоит в том, что AssignValue присваивает значение
переменной, а SendObjDirect присваивает значение непосредственно параметру объекта. Работает это
следующим образом: если изначально параметр text (для текстовых объектов) или logo (для картинок)
пустой, т.е. в редакторе логотипов не задано никакого значения по умолчанию, то ему присваивается
переменная, название которой совпадает с названием объекта. Например, для объекта mystatic это будет
%MYSTATIC. Т.е. если мы в редакторе логотипов не задали значение text объекта mystatic, то ему будет
автоматически присвоена переменная %MYSTATIC. Если мы присвоим значение переменной %MYSTATIC
перед появлением объекта на экране, то он отобразится сразу со значением, которое было присвоено
переменной. Если в дальнейшем изменить значение переменной %MYSTATIC, то объект на экране
автоматически изменится (в случае static изменится текст на экране).
Однако, если изначально значение параметра не было пустым, изменить его можно будет уже
только при помощи команды SendObjDirect (или присвоить при помощи SendObjDirect переменную).
Аналогично, если мы уже изменили значение параметра при помощи SendObjDirect, даже если изначально в
редакторе логотипов оно было пустым, больше для этого объекта AssignValue работать не будет.
Таким образом, сказанное можно свести в таблицу:
AssignValue
Используется только для задания параметров text
или logo (для текстовых объектов – text, для
картинок – logo), для группы – “on” или “off”.
Удобно для задания начального значения,
которое будет сразу при появлении, но можно
использовать и когда объект уже на экране, если
только начальное значение, заданное в редакторе
логотипов пустое и не использовались команды
SendObjDirect для этого параметра объекта
Пример: LogoApiObj.AssignValue
(“STATIC1”,”text text text”)
SendObjDirect
Можно использовать для любых параметров объекта
Используется только если объект уже на экране
Пример:LogoApiObj.SendObjDirect(“static1”,”text=””
text text text”””)
общие параметры для всех объектов:
постоянные:
x,y,w,h – координаты
wait (0/1)
переменные :
style по умолчанию ("helios") – стиль текста
text
классы объектов:
clock
– аналоговые часы
постоянные параметры :
clock=путь к директории со стрелками
crawl – бегущая строка (с картинками)
переменные параметры: speed , text
допустимые последовательности в тексте - \picture \pause \speed
примеры:
LogoApiObj.SendObjDirect(“mycrawl”,”text=”””это текст
текст \speed(10)ускоренный текст””””)
\picture(C:\avi\pic.tga) pause(100) тоже
Добавление текста в конец строки:
LogoApiObj.SendObjDirect(“crawl1”,”addtext=””AAAAAAAAAAAAAAAAA”””)
Чтобы осуществить такое добавление только когда текущая строка уже пробежала, нужно:
перед каждой командой SendObjDirect с параметром addtext
(LogoApiObj.SendObjDirect(“crawl1”,”addtext=””AAAAAAAAAAAAAAAAA”””)) нужно присвоить значение 1
переменной состояния:
LogoApiObj.AssignValue (“crawl1_busy”,”1”)
использовать такой цикл для ожидания окончания текущей строки:
LogoApiObj.AssignValue (“crawl1_busy”,”1”)
LogoApiObj.SendObjDirect(“crawl1”,”addtext=””AAAAAAAAAAAAAAAAA”””)
Dim ss as string
While ss<>”0”
Ss=GetValue(“crawl1_busy")
…
Wend
по окончанию цикла можно еще раз
сделать LogoApiObj.AssignValue(“crawl1_busy”,”1”).
И снова послать SendObjDirect с параметром addtext
Gauge
– столбик переменной ширины/высоты (может используется для диаграмм)
постоянные параметры direction (1-горизонтальное, 2 - вертикальное), picture
переменные параметры: color, position
Значение position 1000 соответствуюет полностью запоненной шкале, 500 – половина шкалы
пример:
LogoApiObj.SendObjDirect(“gauge1”,”position=””500”” color=””FFFFFF”””)
logo
– картинка
переменные параметры:
Transition – тип перехода при появлении/исчезновении (reveal_right, reveal_left, crossfade, zoom,
fade, wipe)
TransitionLen – длительность перехода
TransitionName – название перехода (путь к картинке для wipe)
TransitionSoftness – «мягкость» перехода
noanim [0/1] - не воспринимать tga файл, как часть последовательности, даже если
имя заканчивается на цифру
noloop[0/1] - прокрутить анимацию один раз и остановиться на последнем кадре
logo="имя файла" – картинка
пример:
LogoApiObj.SendObjDirect(“logo1”,”logo=””c:\alphapro\ALPHAPRO.TGA”””)
Присваивает значение объекту типа «картинка», можно использовать TGA –файл или анимационный файл типа LOGO,
созданный в программе conv422. Внимание! TGA-файлы, если имя заканчивается на цифру, например test3.tga
рассматриваются, как кадры в анимационной последовательности.
roll
– текст (с картинками) бегущий вертикально
постоянные параметры : align="left/right/center"
переменные параметры:
text, speed,
autospeed (0/1/2) - режим скроллирования вертикального барабана, в завмсимости от
скорости добавления новых данных по addtext
vspacing – межстрочное расстояние
addvspacing,
style стиль текста
допустимые последовательности в тексте - \picture
примеры:
LogoApiObj.SendObjDirect(“myroll”,”text=”””это текст \picture(C:\avi\pic.tga) ””””)
LogoApiObj.SendObjDirect(“roll1”,”addtext=””AAAAAAAAAAAAAAAAA`”””)
Параметр addtext позволяет добавить текст в конце барабана. Не забудьте поставить в конце символ «обратная кавычка» он обозначает перевод строки
scrncap
– видеозахват с экрана
переменные параметры:
logo - имя файла для маски (Mask File Name)
srcx,srcy,srcw,srch – расположение окна
findflash=[0/1] - автоматически найти на десктопе Windows окно с классом Flash и
брать изображение оттуда
bright, contrast, gamma, softness
priority=[-1,0,1]
static
– статический текст
постоянные параметры:
align="left/right/center"
valign="top/bottom/center"
rotate= [0,1] – поворот на 90 градусов
переменные параметры:
vspacing (межстрочный интервал),
Transition – тип перехода при появлении/исчезновении (reveal_right, reveal_left, crossfade, zoom,
fade, wipe)
TransitionLen – длительность перехода
TransitionName – название перехода (путь к картинке для wipe)
TransitionSoftness – «мягкость» перехода
Style (стиль текста),
text
пример:
LogoApiObj.SendObjDirect(“mystatic”,”text=”””это текст””””)
допустимые последовательности в тексте - нет (только смена стиля)
window
– вывод видео в окне
постоянные параметры:
scale=[0/1] (масштабировать ли видео),
force444=[0/1] - режим при котором видеофайл отображается в окне на
фоне проходящего видео (картинка в картинке)
переменные параметры: logo - фоновая картинка, разрешение только 720х576 (720х480 для режима
NTSC)
group – группа (объединение объектов, которые появляются и исчезают вместе)
помимо функции логотипа, позволяет включенным в него объектам одновременно появляться и исчезать
вместе в ним, используя эффект (transition) , заданный для группы
постоянные параметры : нет
переменные параметры:
Transition – тип перехода при появлении/исчезновении (reveal_right, reveal_left, crossfade, zoom,
fade, wipe)
TransitionLen – длительность перехода
TransitionName – название перехода (путь к картинке для wipe)
TransitionSoftness – «мягкость» перехода
noanim [0/1] - не воспринимать tga файл, как часть последовательности, даже если
имя заканчивается на цифру
noloop[0/1] - прокрутить анимацию один раз и остановиться на последнем кадре
logo="имя файла" – фоновая картинка группы
text=”on”/”off” – показать или скрыть группу
пример:
LogoApiObj.SendObjDirect(“group1”,”text=””on”””)
выводит группу, вместе со всеми входящими в нее объектами на экран
LogoApiObj.SendObjDirect(“group1”,”text=””off”””)
убирает группу с экрана
Примеры
Пример последовательности команд для запуска видео-ролика с логотипом:
LogoApiObj=CreateObject("TELE.API")
LogoApiObj.Login(“334”)
LogoApiObj.LoadLogosAndProfiles(“c:\alphapro\LogosAndProfiles.XML”)
LogoApiObj.SendObjects
LogoApiObj.SendPlayWithLogo(“c:\avi\bol.avi”,”New Logo1”,10000,”DSC Bars”)
Пример последовательности команд для отображения проходящего видео с наложенным логотипом c
последующей модификацией содержимого обьекта static:
Dim LogoApiObj
Private Sub Form_Load()
LogoApiObj=CreateObject("TELE.API")
LogoApiObj.Login(“334”)
LogoApiObj.LoadLogosAndProfiles(“c:\alphapro\LogosAndProfiles.XML”)
LogoApiObj.SendObjects
LogoApiObj.SendPlayWithLogo(“clear”,”New Logo1”,-1,””)
End Sub
Private Sub Command1_Click()
LogoApiObj.SendObjDirect(“static1”,”text=”””+ Text1.Text)
End Sub