Object Reference Manual (ver 4.7)
2014-06-03
: Brightsign Object Reference Manual (Ver 4.7) Object Reference Manual (ver 4.7) s
Open the PDF directly: View PDF 
.
Page Count: 284
| Download | |
| Open PDF In Browser | View PDF |
OBJECT REFERENCE MANUAL
Firmware Versions 4.7.x
•
BrightSign, LLC. 16795 Lark Ave., Suite 200 Los Gatos, CA 95032 | 408-852-9263 | www.brightsign.biz
TABLE OF CONTENTS
INTRODUCTION .................................................................................................................... 1
INTERFACES AND METHODS OVERVIEW ........................................................................2
Classes .............................................................................................................................................................................. 3
Object and Class Name Syntax ......................................................................................................................................... 3
Zones................................................................................................................................................................................. 3
Event Loops....................................................................................................................................................................... 4
BrightSign Object Library ................................................................................................................................................... 5
BRIGHTSCRIPT CORE OBJECTS .......................................................................................6
roArray ............................................................................................................................................................................... 6
roAssociativeArray ............................................................................................................................................................. 8
roBoolean ........................................................................................................................................................................ 10
roByteArray...................................................................................................................................................................... 11
roDouble, roIntrinsicDouble ............................................................................................................................................. 13
roFunction........................................................................................................................................................................ 14
roGlobal ........................................................................................................................................................................... 15
roInt, roFloat, roString ...................................................................................................................................................... 22
roList ................................................................................................................................................................................ 25
roRegex ........................................................................................................................................................................... 27
roXMLElement ................................................................................................................................................................. 29
roXMLList ........................................................................................................................................................................ 33
PRESENTATION AND WIDGET OBJECTS .......................................................................36
roAudioEventMx .............................................................................................................................................................. 36
roAudioOutput ................................................................................................................................................................. 37
roAudioPlayer .................................................................................................................................................................. 39
roAudioPlayerMx ............................................................................................................................................................. 46
roCanvasWidget .............................................................................................................................................................. 51
roClockWidget ................................................................................................................................................................. 56
roHtmlWidget ................................................................................................................................................................... 59
roImageBuffer .................................................................................................................................................................. 62
roImagePlayer ................................................................................................................................................................. 63
roImageWidget ................................................................................................................................................................ 67
roRectangle ..................................................................................................................................................................... 70
roShoutcastStream .......................................................................................................................................................... 71
roShoutcastStreamEvent ................................................................................................................................................. 72
roTextField....................................................................................................................................................................... 73
roTextWidget ................................................................................................................................................................... 76
roVideoEvent, roAudioEvent............................................................................................................................................ 79
roVideoInput .................................................................................................................................................................... 81
roVideoMode ................................................................................................................................................................... 83
roVideoPlayer .................................................................................................................................................................. 89
roTouchCalibrationEvent ................................................................................................................................................. 96
roTouchEvent .................................................................................................................................................................. 97
roTouchScreen ................................................................................................................................................................ 98
FILE OBJECTS .................................................................................................................104
roAppendFile ................................................................................................................................................................. 104
roCreateFile ................................................................................................................................................................... 106
roReadFile ..................................................................................................................................................................... 108
roReadWriteFile ............................................................................................................................................................. 110
HASHING AND STORAGE OBJECTS .............................................................................112
roBrightPackage ............................................................................................................................................................ 112
roDiskErrorEvent ........................................................................................................................................................... 115
roDiskMonitor ................................................................................................................................................................ 116
roHashGenerator ........................................................................................................................................................... 118
roRegistry ...................................................................................................................................................................... 119
roRegistrySection .......................................................................................................................................................... 120
roSqliteDatabase ........................................................................................................................................................... 122
roSqliteEvent ................................................................................................................................................................. 125
roSqliteStatement .......................................................................................................................................................... 126
roStorageAttached, roStorageDetached ........................................................................................................................ 133
roStorageHotplug .......................................................................................................................................................... 134
roStorageInfo ................................................................................................................................................................. 136
NETWORKING OBJECTS ................................................................................................138
roAssetCollection ........................................................................................................................................................... 138
roAssetFetcher .............................................................................................................................................................. 141
roAssetFetcherEvent ..................................................................................................................................................... 143
roAssetFetcherProgressEvent ....................................................................................................................................... 144
roAssetPool ................................................................................................................................................................... 145
roAssetPoolFiles ............................................................................................................................................................ 147
roAssetRealizer ............................................................................................................................................................. 149
roAssetRealizerEvent .................................................................................................................................................... 151
roDatagramSender, roDatagramReceiver, roDatagramSocket, roDatagramEvent ....................................................... 153
roHttpEvent.................................................................................................................................................................... 158
roHttpServer .................................................................................................................................................................. 160
roMediaStreamer ........................................................................................................................................................... 163
roMediaStreamerEvent .................................................................................................................................................. 165
roMimeStream ............................................................................................................................................................... 166
roMimeStreamEvent ...................................................................................................................................................... 167
roNetworkAdvertisement ............................................................................................................................................... 168
roNetworkAttached, roNetworkDetached....................................................................................................................... 170
roNetworkConfiguration ................................................................................................................................................. 171
roNetworkHotplug .......................................................................................................................................................... 178
roNetworkStatistics ........................................................................................................................................................ 179
roRssParser, roRssArticle ............................................................................................................................................. 181
roRtspStream ................................................................................................................................................................ 183
roRtspStreamEvent ....................................................................................................................................................... 184
roShoutcastStream ........................................................................................................................................................ 185
roShoutcastStreamEvent ............................................................................................................................................... 186
roSnmpAgent................................................................................................................................................................. 187
roSnmpEvent ................................................................................................................................................................. 188
roStreamByteEvent ....................................................................................................................................................... 189
roStreamConnectResultEvent ....................................................................................................................................... 190
roStreamEndEvent ........................................................................................................................................................ 191
roStreamLineEvent ........................................................................................................................................................ 192
roSyncManager ............................................................................................................................................................. 193
roSyncManagerEvent .................................................................................................................................................... 196
roSyncSpec ................................................................................................................................................................... 197
roTCPConnectEvent ...................................................................................................................................................... 199
roTCPServer.................................................................................................................................................................. 200
roTCPStream................................................................................................................................................................. 201
roUrlEvent...................................................................................................................................................................... 203
roUrlStream ................................................................................................................................................................... 207
roUrlTransfer ................................................................................................................................................................. 208
INPUT/OUTPUT OBJECTS ...............................................................................................215
roCecInterface ............................................................................................................................................................... 215
roCecRxFrameEvent, roCecTxCompleteEvent ............................................................................................................. 216
roChannelManager ........................................................................................................................................................ 218
roControlPort ................................................................................................................................................................. 226
roControlUp, roControlDown ......................................................................................................................................... 228
roGpioControlPort, roGpioButton ................................................................................................................................... 229
roIRRemote ................................................................................................................................................................... 231
roIRRemotePress .......................................................................................................................................................... 233
roKeyboard, roKeyboardPress ...................................................................................................................................... 235
roMessagePort .............................................................................................................................................................. 237
roSequenceMatcher ...................................................................................................................................................... 239
roSequenceMatchEvent ................................................................................................................................................ 242
roSerialPort.................................................................................................................................................................... 243
SYSTEM OBJECTS ..........................................................................................................246
roDeviceInfo .................................................................................................................................................................. 246
roResourceManager ...................................................................................................................................................... 249
roSystemLog ................................................................................................................................................................. 251
DATE AND TIME OBJECTS .............................................................................................253
roDateTime .................................................................................................................................................................... 253
roSystemTime ............................................................................................................................................................... 255
roTimer .......................................................................................................................................................................... 259
roTimerEvent ................................................................................................................................................................. 263
roTimeSpan ................................................................................................................................................................... 264
LEGACY OBJECTS ..........................................................................................................265
roSyncPool .................................................................................................................................................................... 265
roSyncPoolEvent ........................................................................................................................................................... 268
roSyncPoolFiles ............................................................................................................................................................. 269
roSyncPoolProgressEvent ............................................................................................................................................. 270
Change Log ......................................................................................................................271
4.4.x, 4.2.x, 3.10.x ......................................................................................................................................................... 271
4.6.x, 4.4.x, 3.10.x ......................................................................................................................................................... 272
4.7.x ............................................................................................................................................................................... 273
INTRODUCTION
We use BrightScript Objects (ROs) as the standardized way to expose functionality for our public SDKs. To publish a new
API, we create a new BrightScript Object. All BrightSign players use this library of objects.
This Object Reference Manual describes the BrightScript Object architecture in two main sections:
•
•
How to use BrightScript Objects (as a script writer)
How the initial objects are defined for BrightSign players
1
INTERFACES AND METHODS OVERVIEW
Every BrightScript Object consists of one or more "interfaces." An ro interface consists of one or more "methods." For
example, the roVideoPlayer object has two interfaces, ifMediaTransport and ifSetMessagePort. The interface
ifSetMessagePort has one method, SetPort.
Example:
p = CreateObject("roMessagePort")
video = CreateObject("roVideoPlayer")
gpio = CreateObject("roControlPort", "BrightSign")
gpio.SetPort(p)
video.SetPort(p)
This syntax makes use of a shortcut provided by the language: The interface name is optional, unless it is needed to
resolve name conflicts. For example:
gpio.SetPort(p)
is the same as
gpio.ifSetMessagePort.SetPort(p)
2
Note: The abstract interface ifSetMessagePort is exposed and implemented by both the roControlPort and the
roVideoPlayer objects. Once the SetPort method is called, these objects will send their events to the supplied message
port. This is discussed more in the Event Loops section below.
BrightScript Objects consist only of interfaces. Interfaces define only methods. There is no concept of a "property" or
variable at the object or interface level. These must be implemented as Set/Get methods in an interface.
Classes
A "class name" is used to create a BrightScript Object. For example:
video = CreateObject("roVideoPlayer")
The class name of the above BrightScript Object is roVideoPlayer.
Object and Class Name Syntax
Class names have the following characteristics:
•
•
•
•
Must start with an alphabetic character (a – z).
May consist of alphabetic characters, numbers, or the "_" (i.e. underscore) symbol.
Are not case sensitive.
May be of any reasonable length.
Zones
With the BrightSign Zones feature, you can divide the screen into rectangles and play different content in each rectangle.
3
A zone can contain video, images, audio, a clock, or text. There can be only one video zone per screen for all HD and AU
models. However, there can be multiple zones of other types on the screen. A text zone can contain simple text strings or
can be configured to display an RSS feed in a ticker type display.
To enable zone functionality, the following global function must be called in the script:
EnableZoneSupport(enable As Boolean) As Void
When zones are enabled, the image layer is always on top of the video layer. When zones are not enabled, the image
layer is hidden whenever video is played, and the video layer is hidden whenever images are played.
Event Loops
When writing anything more than a very simple script, an "event loop" will need to be created. Event loops typically have
this structure:
o
Wait for the event.
o Process the event.
o Return to step 1.
An event can be any number occurrences: a button that has been pressed, a timer that has been triggered, or a video that
has finished playing back.
By convention, BrightScript Object event scripting work as follows.
1. An object of the type roMessagePort is created in BrightScript by the user’s script.
2. Objects that can send events are instructed to send their events to this message port. You could set up multiple
message ports and have each event go to its own message port, but it is usually simpler to just create one
message port, and have all the events go to this one port. To instruct the object to send events to a specific port,
use the ifSetMessagePort interface.
4
3. The script waits for an event. The actual function to do this is ifMessagePort.WaitMessage, but if you are using
BrightScript, the built-in statement "WAIT" allows you to do this easily.
4. If multiple event types are possible, your script should determine which event the wait received, then process it.
The script then jumps back to the wait.
An event can be generated by any BrightScript Object. For example, the class roControlPort sends events of type
roControlDown and roControlUp. The roControlDown implements the ifInt Interface, which allows access to an integer. An
event loop needs to be aware of the possible events it can get and process them.
BrightSign Object Library
The following chapters specify each of the objects that can be used in BrightScript. A brief description, a list of interfaces,
and the member functions of the interfaces are provided for each object class.
While most BrightScript objects have self-contained sections in this chapter, some objects are grouped in the same
section if they are closely related or depend on one another to function correctly.
5
BRIGHTSCRIPT CORE OBJECTS
roArray
This object stores objects in a continuous array of memory locations. Since an roArray contains BrightScript components,
and there are object wrappers for most intrinsic data types, entries can either be different types or all of the same type.
Object creation:
CreateObject("roArray", size As Integer, resize As Boolean)
•
•
size: The initial number of elements allocated for an array.
resize: If true, the array will be resized larger to accommodate more elements if needed. If the array is large, this
process might take some time.
•
dim: This statement may be used instead of CreateObject to create a new array. Dim is sometimes advantageous
because it automatically creates array of array for multi-dimensional arrays.
Interfaces: ifArray, ifEnum, ifArrayGet, ifArraySet
The ifArray interface provides the following:
•
•
•
•
•
Peek() As Dynamic: Returns the last (highest index) array entry without removing it.
Pop() As Dynamic: Returns the last (highest index) entry and removes it from the array.
Push(a As Dynamic): Adds a new highest index entry to the end of the array
Shift() As Dynamic: Removes index zero from the array and shifts all other entries down by one unit.
Unshift(a As Dynamic): Adds a new index zero to the array and shifts all other entries up by one unit.
6
•
Delete(a As Integer) As Boolean: Deletes the indicated array entry and shifts all above entries down by
one unit.
•
•
•
Count() As Integer Returns the index of the highest entry in the array plus one (i.e. the length of the array).
Clear(): Deletes every entry in the array.
Append(a As Object): Appends one roArray to another. If the passed roArray contains entries that were never
set to a value, they are not appended.
Note: The two appended objects must be of the same type.
The ifEnum interface provides the following:
•
•
•
•
Reset(): Resets the position to the first element of enumeration.
Next() As Dynamic: Returns a typed value at the current position and increment position.
IsNext() As Boolean: Returns True if there is a next element.
IsEmpty() As Boolean: Returns True if there is not an exact statement.
The ifArrayGet interface provides the following:
•
GetEntry(a As Integer) As Dynamic: Returns an array entry of a given index. Entries start at zero. If an
entry that has not been set is fetched, Invalid is returned.
The ifArraySet interface provides the following:
•
SetEntry(a As Integer, b As Dynamic): Sets an entry of a given index to the passed type value.
7
roAssociativeArray
An associative array (also known as a map, dictionary, or hash table) that allows objects to be associated with string keys.
This object is created with no parameters:
CreateObject("roAssociativeArray")
Interfaces: ifEnum, ifAssociativeArray
The ifEnum interface provides the following:
•
•
•
•
Reset(): Resets the position to the first element of enumeration.
Next() As Dynamic: Returns the typed value at the current position and increment position.
IsNext() As Boolean: Returns True if there is a next element.
IsEmpty() As Boolean: Returns True if there is not a next element.
The ifAssociativeArray interface provides the following:
•
AddReplace(key As String, value As Object) As Void: Adds a new entry to the array, associating the
supplied object with the supplied string. Only one object may be associated with a string, so any existing object is
discarded.
•
Lookup(key As String) As Object: Looks for an object in the array associated with the specified string. If
there is no object associated with the string, then an object implementing ifInt and containing zero is returned.
•
DoesExist(key As String) As Boolean: Looks for an object in the array associated with the specified
string. If there is no associated object, then False is returned. If there is such an object, then True is returned.
•
Delete(key As String) As Boolean: Looks for an object in the array associated with the specified string. If
there is such an object, then it is deleted and True is returned. If not, then False is returned.
•
Clear As Void: Removes all objects from the associative array.
8
•
SetModeCaseSensitive(): Makes all subsequent actions case sensitive. All roAssociativeArray lookups
are case insensitive by default.
•
LookupCi(a As String) As Dynamic: Looks for an object in the array associated with the specified string.
This method functions similarly to Lookup(), with the exception that key comparisons are always case insensitive,
regardless of case mode.
•
Append(a As Object): Appends a second associative array to the first.
Example:
aa = CreateObject("roAssociativeArray")
aa.AddReplace("Bright", "Sign")
aa.AddReplace("TMOL", 42)
print aa.Lookup("TMOL")
print aa.Lookup("Bright")
The above script produces the following:
42
Sign
9
roBoolean
This is the object equivalent for the Boolean intrinsic type. It is useful in the following situations:
• When an object is needed instead of an intrinsic value. For example, if a Boolean is added to roList, it will be
automatically wrapped in an roBoolean object by the language interpreter. When a function that expects a
BrightScript component as a parameter is passed a Boolean, BrightScript automatically creates the equivalent
BrightScript component.
• When any object exposes the ifBoolean interface. That object can then be used in any expression that expects an
intrinsic value.
Interfaces: ifBoolean
The ifBoolean interface provides the following:
•
•
GetBoolean() As Boolean
SetBoolean(a As Boolean)
10
roByteArray
This object contains functions to convert strings to or from a byte array, as well as to or from ASCII hex or ASCII base 64.
Note that if you are converting a byte array to a string, and the byte array contains a zero, the string conversion will end at
that point.
roByteArray will automatically resize to become larger as needed. If you wish to disable this behavior, use the
SetResize() method. If an uninitialized index is read, Invalid is returned.
Since roByteArray supports the ifArray interface, it can be accessed with the array [] operator. The byte array is
always accessed as unsigned bytes while this interface is being used. This object also supports the ifEnum interface, and
so can be used with a "for each" statement.
Interfaces: ifByteArray, ifArray, ifArrayGet, ifEnum, ifArraySet
See roArray for a description of ifArray, ifArrayGet, ifEnum and ifArraySet.
The ifByteArray interface provides the following:
•
•
•
•
•
•
•
•
•
WriteFile(filename As String) As Boolean
WriteFile(filename As String, start_index As Integer, length As Integer) As Boolean
ReadFile(filename As String) As Boolean
ReadFile(filename As String, start_index As Integer, length As Integer) As Boolean
AppendFile(filename As String) As Boolean
SetResize(minimum_allocation_size As Integer, autoresize As Boolean)
ToHexString() As String
FromHexString(hexstring As String)
ToBase64String() As String
11
•
•
•
•
•
FromBase64String(base65string As String)
ToAsciiString() As String
FromAsciiString(a As String)
GetSignedByte(index As Integer) As Integer
GetSignedLong(index As Integer) As Integer: Retreives the integer located at the specified long-word
index of the byte array. Note that this method cannot accept a byte index as its parameter.
•
IsLittleEndianCPU() As Boolean
12
roDouble, roIntrinsicDouble
Interfaces: ifDouble
The ifDouble interface provides the following:
GetDouble() As Double
SetDouble(a As Double)
13
roFunction
Interfaces: ifFunction
•
•
GetSub() As Function
SetSub(value As Function)
14
roGlobal
This object provides a set of standard, module-scope functions that are stored in the global object. If one of these global
functions is referenced, the compiler directs the runtime to call the appropriate global object member.
Note: Global trigonometric functions accept and return values in radians, not degrees.
Interfaces: ifGlobal
The ifGlobal interface provides the following:
•
Sleep(milliseconds As Integer): Instructs the script to pause for a specified amount of time without
wasting CPU cycles. The sleep interval is specified in milliseconds.
•
asc(letter As String) As Integer: Returns the ASCII code for the first character of the specified string. A
null-string argument will cause an error.
•
chr(chr As Integer) As String: Returns a one-character string containing a character reflected by the
specified ASCII or control. For example, because quotation marks are normally used as string delimiters, you can
pass ASCII code 34 to this function to add quotes to a string.
•
•
len(target_string As String) As Integer: Returns the number of characters in a string.
str(value As Double) As String: Converts a specified float value to a string. This method also returns a
string equal to the character representation of a value. For example, if "A" is assigned a value of 58.5, then calling
str(A) will return "58.5" as a string.
•
•
strI(value As Integer) As String: Converts a specified integer value to a string. This method also
returns a string equal to the character representation of a value. For example, if "A" is assigned a value of 58.5,
then calling stri(A) will return "58" as a string.
val(target_string As String) As Double: Returns a number represented by the characters in the string
argument. This is the opposite of the str() function. For example, if "A" is assigned the string "58", and "B" is
assigned the string "5", then calling val(A+"."+B) will return the float value 58.5.
15
•
•
abs(x As Double) As Double: Returns the absoule vale of the argument x.
atn(x As Double) As Double: Returns the arctangent (in radians) of the argument x (i.e. Atn(x) returns "the
angle whose tangent is x"). To get the arctangent in degrees, multiply Atn(x) by 57.29578.
•
•
•
csng(x As Integer) As Float: Returns a single-percision float representation of the argument x.
cdbl(x As Integer) As Double: Returns a double-percision float representation of the argument x.
cint(x As Double) As Integer: Returns an integer representation of the argument x by rounding to the
nearest whole number.
•
cos(x As Double) As Double: Returns the cosine of the arugment x. The argument must be in radians. To
obtain the cosine of x when x is in degrees, use Cos(x*.01745329).
•
•
•
•
exp(x As Double) As Double: Returns the natural exponential of x. This is the inverse of the log() function.
fix(x As Double) As Integer: Returns a truncated representation of the argument x. All digits to the right of
the decimal point are removed so that the resultant value is an integer. For non-negative values of x, fix(x) is
equal to int(x). For negative values of x, fix(x) is equal to int(x)+1.
int(x As Double) As Integer: Returns an integer representation of the argument x using the largest whole
number that is not greater than the argument. For example, int(2.2) returns 2, while fix(-2.5) returns -3.
log(x As Double) As Double: Returns the natural logarithm of the argument x(i.e. loge(x)). This is the inverse
of the exp() function. To find the logarithm of a number to a base b, use the following formula:
logb(x) = loge(x)/loge(b).
•
sgn(x As Double) As Integer: Returns an integer representing how the float argument x is signed: -1 for
negative, 0 for zero, and 1 for positive.
•
sgnI(x As Integer) As Integer: Returns an integer representing how the integer argument x is signed: -1
for negative, 0 for zero, and 1 for positive.
•
sin(x As Double) As Double: Returns the sine of the argument x. The argument must be in radians. To
obtain the sine of x when x is in degrees, use sin(x*.01745329).
•
tan(x As Double) As Double: Returns the tangent of the argument x. The argument must be in radians. To
obtain the tangent of x when x is in degrees, use tan(x*.01745329).
16
•
sqr(x As Double) As Double: Returns the square root of the argument x. This function is the same as x^(1/2),
but calculates the result faster.
•
Left(target_string As String, n As Integer) As String: Returns the first n characters of the
specified string.
•
Right(target_string As String, n As Integer) As String: Returns the last n characters of the
specified string.
•
StringI(n As Integer, character As Integer) As String: Returns a string composed of a character
symbol repeated n times. The character symbol is passed to the method as an ASCII code integer.
•
String(n As Integer, character As String) As String: Returns a string composed of a character
symbol repeated n times. The character symbol is passed to the method as a string.
•
Mid(target_string As String, start_position As Integer, length As Integer) As String:
Returns a substring of the target string. The first integer passed to the method specifies the starting position of the
substring, and the second integer specifies the length of the substring. The start position of a string begins with 1.
•
instr(start_position As Integer, search_text As String, substring_to_find As String)
As Integer: Returns the position of a substring within a string. This function is case sensitive and returns 0 if the
specified substring is not found. The start position of a string begins with 1.
•
GetInterface(object As Object, ifname As String) As Interface: Returns a value of the type
"Interface". All objects have one or more interfaces. In most cases, you can skip interface specification when calling
an object component. This will not cause problems as long as the method names within a function are unique.
•
Wait(timeout As Integer, port As Object) As Object: Instructs the script to wait on an object that
has an ifMessagePort interface. This method will return the event object that was posted to the message port. If the
timeout is specified as zero, Wait() will wait indefinitely; otherwise, Wait() will return Invalid after the specified
number of milliseconds if no messages have been received.
•
•
ReadAsciiFile(file_path As String) As String: Reads the specified text file and returns it as a string.
WriteAsciiFile(file_path As String, buffer As String) As Boolean: Creates a text file at the
specified file path. The text of the file is passed as the second parameter. This method cannot be used to edit files:
A preexisting text file will be overwritten if it has the same name and directory path as the one being created.
17
Note: The roCreateFile object provides more flexibility if you need to create or edit files.
• ListDir(path As String) As Object: Returns an roList containing the contents of the specified directory
path. File names are converted to all lowercase.
•
MatchFiles(path As String, pattern_in As String) As Object: Takes a directory to look in (it can
be as simple as "." or "/") and a pattern to be matched and then returns an roList containing the results. Each listed
result contains only the part of the filename that is matched against the pattern, not the full path. The match is only
applied in the specified directory; you will get no results if the pattern contains a directory separator. The pattern is
case insensitive. It may contain the following special characters:
o ? -- Matches any single character.
o * -- Matches zero or more arbitrary characters.
o […]-- Matches any single character specified within the brackets. The closing bracket is treated as a
member of the character class if it immediately follows the opening bracket (i.e. "[]]" matches a single closed
bracket). Within this class, "-" can be used to specify a range unless it is the first or last character (e.g. "[ACf-h"] is equivalent to "[ABCfgh]"). A character class may be negated by specifying "^" as the first character.
To match a literal of this character, place it elsewhere in the class.
•
•
•
Note: The "?", "*", and "[" lose their function if preceded by a single "\", and a single"\" can be matched as "\\".
LCase(target_string As String) As String: Converts the specified string to all lower case.
UCase(target_string As String) As String: Converts the specified string to all upper case.
DeleteFile(file_path As String) As Boolean: Deletes the file at the specified file path. This method
returns False if the delete fails or if the file does not exist.
•
DeleteDirectory(diretory As String) As Boolean: Deletes the specified directory. This method will
recursively delete any files and directories that are necessary for removing the specified directory. This method
returns False if it fails to delete the directory, but it may still delete some of the nested files or directories.
•
CreateDirectory(directory As String) As Boolean: Creates the specified directory. Only one directory
can be created at a time. This method returns True upon success and False upon failure.
•
•
RebootSystem(): Causes a soft reboot.
ShutdownSystem()
18
•
•
UpTime(dummy As Integer) As Float: Returns the uptime of the system (in seconds) since the last reboot.
FormatDrive(drive As String, fs_type As String) As Boolean: Formats the specified drive using
one of the file systems listed below. This function returns True upon success and False upon failure:
o vfat (DOS/Windows file system): Readable and writable by Windows, Linux, and MacOS.
o ext2 (Linux file system): Writable by Linux and readable by Windows and MacOS with additional software.
o ext3 (Linux file system): Writable by Linux and readable by Windows and MacOS with additional software.
This file system uses journaling for additional reliability.
•
EjectDrive(drive As String) As Boolean: Ejects the specified drive (e.g. "SD:") and returns True if
successful. If the script is currently accessing files from the specified drive, the ejection process will fail.
•
CopyFile(source As String, destination As String) As Boolean: Copies the file at the specified
source file-path name to the specified destination file-path name. The function returns True if successful and False
in the event of failure.
•
MoveFile(a As String, b As String) As Boolean: Moves the specified source file to the specified
destination. The function returns True if successful and False in the event of failure.
Note: Both path names must be on the same drive.
• strtoi(target_string As String) As Integer: Converts the target string to an integer. Any non-integer
characters (including decimal points and spaces), and any numbers to the right of a non-integer character, will not
be part of the integer output.
•
•
•
•
•
•
rnd(a As Dynamic) As Dynamic
RunGarbageCollector() As Object
GetDefaultDrive() As String: Returns the current default drive complete with a trailing slash. When running
autorun.brs, the drive containing the autorun is designated as the current default.
SetDefaultDrive(a As String): Sets the current default drive, which does not need to include a trailing
slash. This function will not fail. However, if the specified default drive is non-existent, it will not be possible to
retrieve anything.
EnableZoneSupport(a As Boolean)
EnableAudioMixer(a As Boolean)
19
•
•
Pi() As Double: Returns the value of pi as a double-precision floating-point number.
ParseJson(JSON_string as String) As Object: Parses a string formatted according to the RFC4627
standard and returns an equivalent BrightScript object, which can consist of the following: Booleans, integers,
floating point numbers, strings, roArray objects, and roAssociativeArray objects. The ParseJson() method has
the following properties:
o Invalid will be returned if the string is not syntactically correct.
o Any roAssociativeArray objects that are returned will be case sensitive.
o An error will be returned if an roArray or roAssociativeArray is nested more than 256 levels deep.
Example: The following script demonstrates how to use ParseJson() to process a JSON object containing the titles and
URLs of a set of images.
JSON Script
{
"photos" : [
{
},
{
},
{
]
}
"title" : "View from the hotel",
"url" : "http://example.com/images/00012.jpg"
"title" : "Relaxing at the beach",
"url" : "http://example.com/images/00222.jpg"
"title" : "Flat tire",
"url" : "http://example.com/images/00314.jpg"
20
}
BrightScript
searchRequest = CreateObject("roUrlTransfer")
searchRequest.SetURL("http://api.example.com/services/rest/getPhotos")
response = ParseJson(searchRequest.GetToString())
For Each photo In response.photos
GetImage(photo.title, photo.url)
End For
21
roInt, roFloat, roString
The intrinsic types roInt32, roFloat, and roString have an object and interface equivalent. These are useful in the following
situations:
•
•
An object is needed instead of a typed value. For example, roList maintains a list of objects.
If any object exposes the ifInt, ifFloat, or ifString interfaces, that object can be used in any expression that expects
a typed value. For example, an roTouchEvent can be used as an integer whose value is the userid of the
roTouchEvent.
Note: If "o" is an roInt, then these statements have the following effects:
o print o: Prints o.GetInt()
o i%=o: Assigns the integer i% the value of o.GetInt()
o k=o: Presumably k is typeOmatic, so it becomes another reference to the roInt o
o o=5: This is NOT the same as o.SetInt(5). Instead it releases o, changes the type of o to roINT32 (o is
typeOmatic), and assigns it to 5.
When a function that expects a BrightScript Object as a parameter is passed an int, float, or string, BrightScript
automatically creates the equivalent object.
Interfaces: ifInt, ifIntOps, ifFloat, ifString, ifStringOps
roInt contains the ifInt interface, which provides the following:
•
•
GetInt() As Integer
SetInt(value As Integer) As Void
22
roInt also contains the ifIntOps interface, which provides the following:
•
ToStr() As String
roFloat contains the ifFloat interface, which provides the following:
•
•
GetFloat() As Float
SetFloat(value As Float) As Void
roString contains the ifString interface, which provides the following:
•
•
GetString() As String
SetString(value As String) As Void
roString also contains the ifStringOps interface, which provides the following:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
SetString(a As String, b As Integer)
AppendString(a As String, b As Integer)
Len() As Integer
GetEntityEncode() As String
Tokenize(a As String) As Object
Trim() As String
ToInt() As Integer
ToFloat() As Float
Left(a As Integer) As String
Right(a As Integer) As String
Mid(a As Integer) As String
Mid(a As Integer, b As Integer) As String
Instr(a As String) As Integer
Instr(a As Integer, b As String) As Integer
23
Example:
BrightScript>
BrightScript>
BrightScript>
555
BrightScript>
555
BrightScript>
500
o=CreateObject("roInt")
o.SetInt(555)
print o
print o.GetInt()
print o-55
Example:
BrightScript> list=CreateObject("roList")
BrightScript> list.AddTail(5)
BrightScript> print type(list.GetTail())
An integer value of "5" is converted to type roInt automatically because list.AddTail expects a BrightScript Object as its
parameter.
Example: Here the function ListDir returns an object roList of roStrings:
BrightScript> l=ListDir("/")
BrightScript> for i=1 to l.Count():print l.RemoveHead():next
test_movie_3.vob
test_movie_4.vob
test_movie_1.vob
test_movie_2.vob
24
roList
This object functions as a general-purpose, doubly linked list. It can be used as a container for arbitrary-length lists of
BrightSign Objects. The array operator [ ] can be used to access any element in an ordered list.
Interfaces: ifList, ifEnum, ifArray, ifArrayGet, ifArraySet
The ifList interface provides the following:
•
•
•
•
•
Count() As Integer: Returns the number of elements in the list.
ResetIndex() As Boolean: Resets the current index or position in the list to the head element.
AddTail(obj As Object) As Void: Adds a typed value to the tail of the list.
AddHead(obj As Object) As Void: Adds a typed value to the head of the list.
RemoveIndex() As Object: Removes an entry from the list at the current index or position and increments the
index or position in the list. It returns Invalid when the end of the list is reached.
•
GetIndex() As Object: Retrieves an entry from the list at the current index or position and increments the
index or position in the list. It returns Invalid when the end of the list is reached.
•
•
•
•
•
RemoveTail() As Object: Removes the entry at the tail of the list.
RemoveHead() As Object: Removes the entry at the head of the list.
GetTail() As Object: Retrieves the entry at the tail of the list and keeps the entry in the list.
GetHead() As Object: Retrieves the entry at the head of the list and keeps the entry in the list.
Clear(): Removes all elements from the list.
The ifEnum interface provides the following:
•
•
•
•
Reset(): Resets the position to the first element of enumeration.
Next() As Dynamic: Returns the typed value at the current position and increment position.
IsNext() As Boolean: Returns True if there is a next element.
IsEmpty() As Boolean: Returns True if there is not a next element.
25
The ifArray interface provides the following:
•
•
•
•
•
•
Peek() As Dynamic: Returns the last (highest index) array entry without removing it.
Pop() As Dynamic: Returns the last (highest index) entry and removes it from the array.
Push(a As Dynamic): Adds a new highest index entry to the end of the array
Shift() As Dynamic: Removes index zero from the array and shifts all other entries down by one unit.
Unshift(a As Dynamic): Adds a new index zero to the array and shifts all other entries up by one unit.
Delete(a As Integer) As Boolean: Deletes the indicated array entry and shifts all above entries down by
one unit.
•
•
•
Count() As Integer Returns the index of the highest entry in the array plus one (i.e. the length of the array).
Clear(): Deletes every entry in the array.
Append(a As Object): Appends one roArray to another. If the passed roArray contains entries that were never
set to a value, they are not appended.
Note: The two appended objects must be of the same type.
The ifArrayGet interface provides the following:
•
GetEntry(a As Integer) As Dynamic: Returns an array entry of a given index. Entries start at zero. If an
entry that has not been set is fetched, Invalid is returned.
The ifArraySet interface provides the following:
•
SetEntry(a As Integer, b As Dynamic): Sets an entry of a given index to the passed type value.
26
roRegex
This object allows the implementation of the regular-expression processing provided by the PCRE library.
This object is created with a string to represent the "matching-pattern" and a string to indicate flags that modify the
behavior of one or more matching operations:
CreateObject("roRegex", "[a-z]+", "i")
The match string (in the example above, "[a-z]+", which matches all lowercase letters) can include most Perl
compatible regular expressions found in the PCRE documentation.
This object supports any combination of the following behavior flags (in the example above, "i", which can be modified to
match both uppercase and lowercase letters):
•
•
•
•
"i": Case-insensitive match mode.
"m": Multiline mode. The start-line ("^") and end-line ("$") constructs match immediately before or after any
newline in the subject string. They also match at the absolute beginning or end of a string.
"s": Dot-all mode, which includes a newline in the ".*" regular expression. This modifier is equivalent to "/s" in
Perl.
"x": Extended mode, which ignores whitespace characters except when escaped or inside a character class. This
modifier is equivalent to "/x" in Perl.
Interfaces: ifRegex
The ifRegex interface provides the following:
•
IsMatch(a As String) As Boolean: Returns True if the string is consistent with the matching pattern.
27
•
Match(a As String) As roArray: Returns an roArray of matched substrings from the string. The entire
match is returned in the form array[0].This will be the only entry in the array if there are no parenthetical
substrings. If the matching pattern contains parenthetical substrings, the relevant substrings will be returned as an
array of length n+1, where array[0] is the entire match and each additional entry in the array is the match for
the corresponding parenthetical expression.
•
Replace(a As String, b As String) As String: Replaces the first occurrence of a match to the
matching pattern in the string with the subset. The subset may contain numbered back-references to parenthetical
substrings.
•
•
ReplaceAll(a As String, b As String) As String: Performs a global search and replace.
Split(a As String) As roList: Uses the matching pattern as a delimiter and splits the string on the
delimiter boundaries. The function returns an roList of strings that were separated by the matching pattern in the
original string.
28
roXMLElement
This object is used to contain an XML tree.
The roXMLElement object is created with no parameters:
CreateObject("roXMLElement")
The following examples illustrate how XML elements are parsed in BrightScript:
This is example text
Name = tag1
Attributes = Invalid
Body = roString containing "This is example text"
XML element.
EqualTo(other As roSyncSpec) As Boolean: Compares the contents of the roSyncSpec object with
another roSyncSpec object. This method compares the parsed contents of each sync spec rather than the XML
files themselves.
•
VerifySignature(signature as String, obfuscated_passphrase as String) As Boolean: Deobfuscates the passphrase and uses it to verify the signature of the sync spec. This method returns True upon
success and False upon failure.
•
•
•
FilterFiles(a As String, b As Object) As Object
FilesEqualTo(a As Object) As Boolean
GetAssets(a As String) As Object
198
roTCPConnectEvent
The event is posted when a new connection is made to an roTCPServer port. The normal response to receiving such an
event is to create a new roTCPStream object and pass the event to its AcceptFrom call.
Interfaces: ifUserData, ifSocketInfo, ifInternalGetTCPStream
The ifUserData interface provides the following:
•
•
SetUserData(a As Object)
GetUserData() As Object
The ifSocketInfo interface provides the following:
•
GetSourceAddress() As String: Returns the IP address of the remote end of the TCP connection.
199
roTCPServer
Interfaces: ifTCPServerInstance, ifUserData
The ifTCPServerInstance interface provides the following:
•
•
•
GetFailureReason() As String: Yields additional useful information if an roTCPServer method fails.
SetPort(port As Object): Sets the message port that will receive events from an roTCPServer instance.
BindToPort(port As Dynamic) As Boolean: Prepares to accept incoming TCP connections on the
specified port. Passing an integer to this method will specify a standard port number. This method can also accept
an index of integer interfaces contained within an associative array, which can contain the following members:
o -1: Any (this is the default value)
o 0: Ethernet
o 1: WiFi
o 2: Modem
o 32767: Loopback (i.e. TCP connections can only be established by internal sources)
The ifUserData interface provides the following:
•
SetUserData(a As Object): Supplies an object that will be provided by every event called by an roTCPServer
instance.
•
GetUserData() As Object
200
roTCPStream
Interfaces: ifStreamReceive, ifUserData, ifStreamSend, ifTCPStream
The ifStreamReceive interface provides the following:
•
•
•
•
SetLineEventPort(a As Object)
SetByteEventPort(a As Object)
SetReceiveEol(a As String)
SetMatcher(matcher As Object) As Boolean: Instructs the stream to use the specified matcher. This
object returns True if successful. Pass Invalid to this method to stop using the specified matcher.
The ifUserData interface provides the following:
•
SetUserData(a As Object): Supplies an object that will be provided by every event called by an
roTCPStream instance.
•
GetUserData() As Object
The ifStreamSend interface provides the following:
•
•
•
SetSendEol(eol_sequence As String) As Void: Sets the EOL sequence when writing to the stream.
SendByte(byte As Integer) As Void: Writes the specified byte to the stream.
SendLine(string As String) As Void: Writes the specified characters to the stream followed by the
current EOL sequence.
•
SendBlock(a As Dynamic) As Void: Writes the specified characters to the stream. This method can support
either a string or an roByteArray. If the block is a string, any null bytes will terminate the block.
•
Flush()
The ifTCPStream interface provides the following:
201
•
•
GetFailureReason() As String: Yields additional useful information if an roTCPStream method fails.
ConnectTo(a As String, b As Integer) As Boolean: Connects the stream to the specified host
(designated using a dotted quad) and port. The function returns True upon success.
•
Accept(a As Object) As Boolean: Accepts an incoming connection event. The function returns True upon
success.
•
AsyncConnectTo(a As String, b As Integer) As Boolean: Attempts to connect the stream to the
specified host (designated using a dotted quad) and port. The function returns False if this action is immediately
impossible (for example, when the specified host is not in the correct format). Otherwise, the function returns True
upon success. The connect proceeds in the background, and an roStreamConnectResultEvent is posted to the
associated message port when the connect attempt succeeds or fails.
202
roUrlEvent
Interfaces: ifInt, ifUserData, ifUrlEvent, ifString, ifSourceIdentity
The ifInt interface provides the following:
•
GetInt() As Integer: Returns the type of event. The following event types are currently defined: transfer
complete (1), transfer started (2). Headers are available for suitable protocols (though this is not currently
implemented).
The ifUserData interface provides the following:
•
•
SetUserData(a As Object)
GetUserData() As Object
The ifUrlEvent interface provides the following:
•
GetResponseCode() As Integer: Returns the protocol response code associated with an event. The following
codes indicate success:
o 200: Successful HTTP transfer
o 226: Successful FTP transfer
o 0: Successful local file transfer
For unexpected errors, the return value is negative. There are many possible negative errors from the CURL library,
but it is often best to look at the text version by calling GetFailureReason.
Here are some potential errors. Not all of them can be generated by a BrightSign player:
Status
Name
Description
-1
CURLE_UNSUPPORTED_PROTOCOL
-2
CURLE_FAILED_INIT
203
-3
-5
-6
-7
-8
CURLE_URL_MALFORMAT
CURLE_COULDNT_RESOLVE_PROXY
CURLE_COULDNT_RESOLVE_HOST
CURLE_COULDNT_CONNECT
CURLE_FTP_WEIRD_SERVER_REPLY
-9
CURLE_REMOTE_ACCESS_DENIED
-11
-13
-14
-15
-17
-18
-19
-21
-22
-23
-25
-26
-27
-28
-30
-31
-33
-34
-35
-36
-37
-38
-39
-41
CURLE_FTP_WEIRD_PASS_REPLY
CURLE_FTP_WEIRD_PASV_REPLY
CURLE_FTP_WEIRD_227_FORMAT
CURLE_FTP_CANT_GET_HOST
CURLE_FTP_COULDNT_SET_TYPE
CURLE_PARTIAL_FILE
CURLE_FTP_COULDNT_RETR_FILE
CURLE_QUOTE_ERROR
CURLE_HTTP_RETURNED_ERROR
CURLE_WRITE_ERROR
CURLE_UPLOAD_FAILED
CURLE_READ_ERROR
CURLE_OUT_OF_MEMORY
CURLE_OPERATION_TIMEDOUT
CURLE_FTP_PORT_FAILED
CURLE_FTP_COULDNT_USE_REST
CURLE_RANGE_ERROR
CURLE_HTTP_POST_ERROR
CURLE_SSL_CONNECT_ERROR
CURLE_BAD_DOWNLOAD_RESUME
CURLE_FILE_COULDNT_READ_FILE
CURLE_LDAP_CANNOT_BIND
CURLE_LDAP_SEARCH_FAILED
CURLE_FUNCTION_NOT_FOUND
A service was denied by the server due to lack of access.
When login fails, this is not returned.
Failed quote command
Failed upload command.
Could not open/read from file.
The timeout time was reached.
FTP PORT operation failed.
REST command failed.
RANGE command did not work.
Wrong when connecting with SSL.
Could not resume download.
204
-42
-43
-45
-47
-48
-49
-51
-52
-53
-54
-55
-56
-58
-59
-60
-61
-62
-63
-64
-65
-66
CURLE_ABORTED_BY_CALLBACK
CURLE_BAD_FUNCTION_ARGUMENT
CURLE_INTERFACE_FAILED
CURLE_TOO_MANY_REDIRECTS
CURLE_UNKNOWN_TELNET_OPTION
CURLE_TELNET_OPTION_SYNTAX
CURLE_PEER_FAILED_VERIFICATION
CURLE_GOT_NOTHING
CURLE_SSL_ENGINE_NOTFOUND
CURLE_SSL_ENGINE_SETFAILED
CURLE_SEND_ERROR,
CURLE_RECV_ERROR
CURLE_SSL_CERTPROBLEM
CURLE_SSL_CIPHER
CURLE_SSL_CACERT
CURLE_BAD_CONTENT_ENCODING
CURLE_LDAP_INVALID_URL
CURLE_FILESIZE_EXCEEDED,
CURLE_USE_SSL_FAILED,
CURLE_SEND_FAIL_REWIND,
CURLE_SSL_ENGINE_INITFAILED
-67
CURLE_LOGIN_DENIED
-68
-69
-70
-71
-72
-73
-74
-75
CURLE_TFTP_NOTFOUND
CURLE_TFTP_PERM
CURLE_REMOTE_DISK_FULL
CURLE_TFTP_ILLEGAL
CURLE_TFTP_UNKNOWNID
CURLE_REMOTE_FILE_EXISTS
CURLE_TFTP_NOSUCHUSER
CURLE_CONV_FAILED
CURLOPT_INTERFACE failed.
Catch endless re-direct loops.
User specified an unknown option.
Malformed telnet option.
Peer's certificate or fingerprint wasn't verified correctly.
When this is a specific error.
SSL crypto engine not found.
Cannot set SSL crypto engine as default.
Failed sending network data.
Failure in receiving network data.
Problem with the local certificate.
Could not use specified cipher.
Problem with the CA cert (path?)
Unrecognized transfer encoding.
Invalid LDAP URL.
Maximum file size exceeded.
Requested FTP SSL level failed.
Sending the data requires a rewind that failed.
Failed to initialize ENGINE.
User, password, or similar field was not accepted and login
failed .
File not found on server.
Permission problem on server.
Out of disk space on server.
Illegal TFTP operation.
Unknown transfer ID.
File already exists.
No such user.
Conversion failed.
205
-76
CURLE_CONV_REQD
-77
-78
CURLE_SSL_CACERT_BADFILE
CURLE_REMOTE_FILE_NOT_FOUND
-79
CURLE_SSH
-80
CURLE_SSL_SHUTDOWN_FAILED
Caller must register conversion callbacks using the following
URL_easy_setopt options:
CURLOPT_CONV_FROM_NETWORK_FUNCTION
CURLOPT_CONV_TO_NETWORK_FUNCTION
CURLOPT_CONV_FROM_UTF8_FUNCTION
Could not load CACERT file, missing or wrong format.
Remote file not found.
Error from the SSH layer (this is somewhat generic, so the
error message will be important when this occurs).
Failed to shut down the SSL connection.
•
•
•
GetObject() As Object
GetFailureReason As String: Returns a description of the failure that occurred.
GetSourceIdentity As Integer: Returns a unique number that can be matched with the value returned by
roUrlTransfer.GetIdentity to determine where this event came from.
•
GetResponseHeaders As roAssociativeArray: Returns an associative array containing all the headers
returned by the server for appropriate protocols (such as HTTP).
The ifString interface provides the following:
•
GetString As String: Returns the string associated with the event. For transfer-complete AsyncGetToString,
AsyncPostFromString, and AsyncPostFromFile requests, this will be the actual response body from the server,
truncated to 65,536 characters.
The ifSourceIdentity interface provides the following:
•
GetSourceIdentity As Integer: Returns a unique number that can be matched with the value returned
by roUrlTransfer.GetIdentity to determine where this event originated.
206
roUrlStream
This object allows playback of content from a URL; the current implementation is only designed to work from local NAS
storage.
This object is created with an associated roUrlTransfer object, as well as a number of other numeric parameters that
define buffer size, etc. The roUrlTransfer object defines the retrieval URL and is documented separately.
To use the final object to play back content, you must put the object into an associative array with the parameter name
"Url". This array can then be sent to roVideoPlayer.PlayFile() for playback.
Interfaces: ifUrlStream
The ifUrlStream interface provides the following:
•
•
•
•
GetUrl() As String
GetBufferSize() As Integer
GetRewindSize() As Integer
GetMinimumFill() As Integer
207
roUrlTransfer
This object is used for reading from and writing to remote servers through URLs.
Object Creation: roUrlTransfer is created with no parameters.
CreateObject("roUrlTransfer")
Interfaces: ifUserData, ifIdentity, ifSetMessagePort, ifGetMessagePort, ifUrlTransfer
The ifUserData interface provides the following:
•
•
SetUserData(user_data As Object): Associates an arbitrary object with the roUrlTransfer instance that is
provided via roUrlEvent.GetUserData() when an event is generated.
GetUserData() As Object: Retrieves the arbitrary object set using SetUserData().
The ifIdentity interface provides the following:
•
GetIdentity As Integer: Returns a unique number that can be used to identify whether events originated
from this object.
The ifSetMessagePort interface provides the following:
•
SetPort(port As ifMessagePort) As Void: Sets the message port to which events will be posted for
asynchronous requests.
The ifGetMessagePort interface provides the following:
•
GetPort() As Object
208
The ifUrlTransfer interface provides the following:
•
SetUrl(URL As String) As Boolean: Sets the URL for the transfer request. This function returns False on
failure. Use GetFailureReason to learn the reason for the failure.
Note
When using SetUrl to retrieve content from local storage, you do not need to specify the full file path:
SetUrl("file:/example.html"). If the content is located somewhere other than the current storage device, you
can specify it within the string itself. For example, you can use the following syntax to retrieve content from a storage
device inserted into the USB port when the current device is an SD card:
SetUrl("file:///USB1:/example.html").
•
AddHeader(name As String, value As String) As Boolean: Adds the specified HTTP header. This is
only valid for HTTP URLs. This function returns False on failure. Use GetFailureReason() to learn the reason
for the failure.
•
•
•
GetToString As String: Connects to the remote service as specified in the URL and returns the response
body as a string. This function cannot return until the exchange is complete, and it may block for a long time.
Having a single string return means that much of the information (headers, response codes) has been discarded. If
you need this information, you can use AsyncGetToString() instead.
Note: The size of the returned string is limited to 65,536 characters.
GetToFile(filename As String) As Integer: Connects to the remote service as specified in the URL and
writes the response body to the specified file. This function does not return until the exchange is complete and may
block for a long time. The response code from the server is returned. It is not possible to access any of the
response headers. If you need this information, use AsyncGetToFile() instead.
AsyncGetToString As Boolean: Begins a "get" request to a string asynchronously. Events will be sent to the
message port associated with the object. If False is returned, then the request could not be issued and no events
will be delivered.
209
•
AsyncGetToFile(filename As String) As Boolean: Begins a "get" request to a file asynchronously.
Events will be sent to the message port associated with the object. If False is returned, then the request could not
be issued and no events will be delivered.
•
Head() As Object: Synchronously perform an HTTP HEAD request and return the resulting response code and
headers through an roUrlEvent object. In the event of catastrophic failure (e.g. an asynchronous operation is
already active), a null object is returned.
•
AsyncHead() As Boolean: Begins an ansynchronous HTTP HEAD request. Events will be sent to the message
port associated with the object. If the request could not be issued, the method will return False and will not deliver
any events.
•
PostFromString(request As String) As Integer: Uses the HTTP POST method to post the supplied
string to the current URL and return the response code. Any response body is discarded.
•
PostFromFile(filename As String) As Integer: Uses the HTTP POST method to post the contents of
the file specified to the current URL and then return the response code. Any response body is discarded.
•
AsyncPostFromString(request As String) As Boolean: Uses the HTTP POST method to post the
supplied string to the current URL. Events of type roUrlEvent will be sent to the message port associated with the
object. A False return indicates that the request could not be issued and no events will be delivered.
•
AsyncPostFromFile(filename As String) As Boolean: Uses the HTTP POST method to post the
contents of the specified file to the current URL. Events of the type roUrlEvent will be sent to the message port
associated with the object A False return indicates that the request could not be issued and no events will be
delivered.
•
SetUserAndPassword(user As String, password As String) As Boolean: Enables HTTP
authentication using the specified user name and password. Note that HTTP basic authentication is deliberately
disabled due to it being inherently insecure. HTTP digest authentication is supported.
•
SetMinimumTransferRate(bytes_per_second As Integer, period_in_seconds As Integer) As
Boolean: Causes the transfer to be terminated if the rate drops below bytes_per_second when averaged
over period_in_seconds. Note that if the transfer is over the Internet, you may not want to set period_in_seconds
210
to a small number in case network problems cause temporary drops in performance. For large file transfers and a
small bytes_per_second limit, averaging over fifteen minutes or even longer might be appropriate.
•
GetFailureReason As String: May provide additional information if any of the roUrlTransfer methods indicate
failure.
•
•
SetHeaders(a As Object) As Boolean
AsyncGetToObject(type As String) As Boolean: Begins an asynchronious GET request and uses the
contents to create an object of the specified type. Events will be sent to the message port associated with the
object. If this method returns False, the request could not be issued and no events will be delievered.
•
•
AsyncCancel() As Boolean
EnableUnsafeAuthentication(enable As Boolean) As Boolean: Supports basic HTTP authentication if
True. HTTP authentication uses an insecure protocol, which might allow others to easily determine the password.
The roUrlTransfer object will still prefer the stronger digest HTTP if it is supported by the server. If this method is
False (which is the default setting), it will refuse to provide passwords via basic HTTP authentication, and any
requests requiring this authentication will fail.
•
EnableUnsafeProxyAuthentication(enable As Boolean) As Boolean: Supports basic HTTP
authentication against proxies if True (which, unlike EnableUnsafeAuthentication(), is the default setting).
HTTP authentication uses an insecure protocol, which might allow others to easily determine the password. If this
method is False, it will refuse to provide passwords via basic HTTP authentication, and any requests requiring this
authentication will fail.
•
•
•
•
•
EnableResume(a As Boolean) As Boolean
EnablePeerVerification(a As Boolean) As Boolean
EnableHostVerification(a As Boolean) As Boolean
SetCertificatesFile(a As String) As Boolean
EnableEncodings(a As Boolean) As Boolean: Communicates to the server that the system can accept
any encoding that the roUrlTransfer object is capable of decoding by itself. This currently includes "deflate" and
"gzip", which allow for transparent compression of responses. Clients of roUrlTransfer see only the decoded data
and are unaware of the encoding being used.
211
•
•
SetUserAndPassword(a As String, b As String) As Boolean
Head() As Object: Performs a synchronous HTTP HEAD request and returns the resulting response code and
headers through an roURLEvent object. In the event of catastrophic failure (e.g. an asynchronous operation is
already active), a null object is returned.
•
Escape(unescaped As String) As String: Converts the provided string to a URL-encoded string. All
characters that could be misinterpreted in a URL context are converted to the %XX form.
•
•
•
•
Unescape(a As String) As String
GetUrl() As String
SetProxy(a As String) As Boolean
SetTimeout(milliseconds As Integer) As Boolean: Terminates the transfer if the request takes longer
than the specified number milliseconds. Note that this includes the time taken by any name lookups, so setting this
value too low will cause undesirable results. Passing 0 to the method disables the timeout. This method returns
True upon success and False upon failure. In the event of failure, using the GetFailureReason() method may
provide more information. If the operation times out, the status return is -28.
•
•
SetUserAgent(a As String) As Boolean
PutFromString(a As String) As Integer: Uses the HTTP PUT method to write the supplied string to the
current URL and return the response code. Any response body is discarded; use roUrlTransfer.SyncMethod to
retrieve the response body.
•
PutFromFile(a As String) As Integer: Uses the HTTP PUT method to write the contents of the specified
file to the current URL and return the response code. Any response body is discarded; use
roUrlTransfer.SyncMethod to retrieve the response body.
•
AsyncPutFromString(a As String) As Boolean: Uses the HTTP PUT method to write the supplied string
to the current URL. Events of type roUrlEvent will be sent to the message port associated with the object. A False
return indicates that the request could not be issued and no events will be delivered. Any response body is
discarded; use roUrlTransfer.AsyncMethod to retrieve the response body.
•
AsyncPutFromFile(a As String) As Boolean : Uses the HTTP PUT method to write the contents of the
specified file to the current URL. Events of type roUrlEvent will be sent to the message port associated with the
212
object. A False return indicates that the request could not be issued and no events will be delivered. Any response
body is discarded; use roUrlTransfer.AsyncMethod to retrieve the response body.
•
Delete() As Object: Uses the HTTP DELETE method to delete the resource at the current URL and return the
response code. Any response body is discarded; use roUrlTransfer.SyncMethod to retrieve the response body.
•
AsyncDelete() As Boolean: Uses the HTTP DELETE method to delete the resource at the current URL.
Events of type roUrlEvent will be sent to the message port associated with the object. A False return indicates that
the request could not be issued and no events will be delivered. Any response body is discarded; use
roUrlTransfer.AsyncMethod to retrieve the response body.
•
•
ClearHeaders(): Removes all headers that would be supplied with an HTTP request.
AddHeaders(a As Object) As Boolean: Adds one or more headers to HTTP requests. Pass headers to this
object as an roAssociativeArray of name/value pairs. This method returns True upon success and False upon
failure. All headers that are added with this method will continue to be sent with HTTP requests until
ClearHeaders()is called.
•
•
•
•
SyncMethod(a As Object) As Object: Performs a synchronous HTTP method request using the specified
parameters. If the request is started successfully, then the method returns an roUrlEvent object containing the
results of the request. This method returns Invalid if the the request could not be started. In this case, the
GetFailureReason() method may provide more information.
SetRelativeLinkPrefix(prefix As String) As Boolean: Places the specified prefix in front of the URL
if the URL is relative. Use this method to easily make file:/// URLs drive agnostic.
BindToInterface(interface As Integer) As Boolean: Ensures that the request only goes out over the
specified network interface. By default, the request goes out over the most appropriate network interface (which
may depend on the routing metric configured via roNetworkConfiguration). Note that if both interfaces are on the
same layer 2 network, this method may not always work as expected due to the Linux weak host model. The
default behavior can be selected by passing -1 to the method. This method returns False upon failure. In this case,
the GetFailureReason() method may provide more information.
AsyncMethod(parameters As Object) As Boolean: Begins an asynchronous HTTP method request using
the specified parameters (see below). If the request is started successfully, the method returns True and and will
213
deliver an event. If the request could not be started, then the method returns False and will not deliver an event. If
this occurs, you may be able to use the GetFailureReason() method to get more information.
The parameters are sepecifed as an associatve array that may contain the following members:
Name
method
Type
String
Description
An HTTP method. Normal values include "HEAD", "GET", "POST", "PUT", and "DELETE".
Other values are supported; however, depending on server behavior, they may not work as
expected.
request_body_string
String
A string containing the request body.
request_body_file
String
The name of a file that contains the request body
response_body_string
Boolean
If specified and set to True, the response will be stored in a string and provided via the
roUrlEvent.GetString() method.
response_body_file
String
The name of the file that will contain the response body. The body is written to a temporary file
and then renamed to the specified filename if successful.
response_body_resume_file
String
The name of the file that will contain the response body. For a GET request, a RANGE header
is sent based on the current size of the file, which is written in place rather than using a
temporary file.
response_body_object
String
Uses the response body to create an object of the specified type. See the entry for
AsyncGetToObject() for supported object types.
214
INPUT/OUTPUT OBJECTS
roCecInterface
This object provides access to the HDMI CEC channel.
Object Creation: roCecInterface is created with no parameters.
CreateObject("roCecInterface")
Interfaces: IfCecInterface, ifSetMessagePort
The IfCecInterface interface provides the following:
•
SendRawMessage(packet As Object) As Void: Sends a message on the CEC bus. The frame data should
be provided as an roByteArray, with the destination address in the low 4 bits of the first octet. The high 4 bits of the
first octet should be supplied as zero; they will be replaced with the source address.
The ifSetMessagePort interface provides the following:
•
SetPort(a As Object)
215
roCecRxFrameEvent, roCecTxCompleteEvent
If an roMessagePort is attached to an roCecInterface instance, it will receive events of type roCecRxFrameEvent and/or
roCecTxCompleteEvent.
roCecRxFrameEvent
Interfaces: ifCecRxFrameEvent
The ifCecRxFrameEvent interface provides the following;
•
GetByteArray() As Object: Returns the message data as an roByteArray.
roCecTxFrameEvent
Interfaces: ifCecTxCompleteEvent
The ifCecTxCompleteEvent interface provides the following:
•
GetStatusByte() As Integer
The currently defined status codes are described below:
0x00
Transmission successful
0x80
Unable to send, CEC hardware powered down
0x81
Internal CEC error
0x82
Unable to send, CEC line jammed
0x83
Arbitration error
216
0x84
Bit-timing error
0x85
Destination address not acknowledged
0x86
Data byte not acknowledged
217
roChannelManager
You can use this object to manage RF channel scanning and tuning. The roVideoPlayer method also has channel
scanning capabilities.
Object Creation: roChannelManager is created with no parameters.
CreateObject("roChannelManager")
Interfaces: ifUserData, ifMessagePort, ifSetMessagePort, ifChannelManager,
The ifUserData interface provides the following:
•
•
SetUserData(a As Object)
GetUserData() As Object
The ifMessagePort interface provides the following:
•
SetPort(a As Object)
The ifSetMessagePort interface provides the following:
•
SetPort(a As Object)
The ifChannelManager interface provides both a Synchronous and Asynchronous API:
Synchronous API
• Scan(parameters As roAssociativeArray) As Boolean: Performs a channel scan on the RF input for
both ATSC and QAM frequencies and builds a channel map based on what it finds. The roChannelManager object
stores a list of all channels that are obtained using the CreateChannelDescriptor() method (described below).
The list is cleared on each call to Scan() by default, but this behavior can be overridden.
218
Each channel takes approximately one second to scan; you can limit the scope of the channel scan with the
following parameters:
o ["ChannelMap"] = "ATSC" or "QAM": Limits the frequency scan to either QAM or ATSC.
o ["ModulationType"] = "QAM64" or "QAM256": Limits the modulation type of the scan to QAM64 or
QAM256.
o ["FirstRfChannel"] = Integer and/or ["LastRfChannel"] = Integer: Limits the scan to the
•
•
specified range of channels. The high end of the channel range is an optional parameter.
o ["ChannelStore"] = "DISCARD ALL" or "MERGE": Controls how the script handles previous channel
scan information. The default setting is DISCARD ALL, which clears all channel data prior to scanning. On
the other hand, MERGE overwrites the data only for channels specified in the scan.
GetChannelCount() As Integer: Returns the number of found channels.
ClearChannelData() As Boolean: Clears all stored channel scanning data, including that which persists in
the registry. This method also cancels any AsyncScan() calls that are currently running.
•
•
GetCurrentSnr() As Integer: Returns the SNR (in centibels) of the currently tuned channel.
ExporttoXML() As String: Serializes the contents of RF channels into XML. You can write the XML to a file
that can be used at a later point on the same or other units. See below for an example of XML output.
•
ImportFromXML(a As String) As Boolean: Retrieves the RF channel contents stored as XML. The
formatting of the XML is controlled using version tags.
Example
2
42
219
7
0
1
1
42
7
0
1
2
•
EnableScanDebug(filename As String) As Boolean: Allows all scan debugging to be written to a text file.
By default, there is no debug output from a scan. You can close the debug file by passing an empty string.
Example
c=CreateObject("roChannelManager")
c.EnableScanDebug("tmp:/scandebug.txt")
v = CreateObject("roVideoPlayer")
aa = CreateObject("roAssociativeArray")
aa["RfChannel"] = 12
aa["VirtualChannel"] = "24.1"
print v.PlayFile(aa)
220
c.EnableScanDebug("")
•
CreateChannelDescriptor(a As Object) As Object: Creates an associative array that can either be
passed to the roVideoPlayer.PlayFile method (to tune to a channel) or parsed for metadata. The generated channel
object can be based on one of the following:
o Index:
["ChannelIndex"] = 0
o Virtual channel number as a string in an associative array:
["VirtualChannel"] = "12.1"
o Channel name as a string:
["ChannelName"] = "KCBS"
Note: Channels are sorted internally by virtual channel, so you could use a ChannelIndex script to implement
standard channel up/down behavior.
These are the entries generated in the array:
o VirtualChannel
o ChannelName
o CentreFrequency
o ModulationType
o VideoPid
o VideoCodec
o AudioPid
221
o
o
o
o
o
AudioCodec
SpectralInversion
ChannelMap
FirstRfChannel
LastRfChannel
The last three entries in this array allow you to use the same roArray as a parameter for Scan() and PlayFile().
The first and last RF channel values are set to the same value so that only one RF channel will be scanned. This
kind of scan can be performed at the same time as playing the channel because it doesn’t require retuning.
Example
c=CreateObject("roChannelManager")
aa=CreateObject("roAssociativeArray")
aa["ChannelMap"] = "QAM"
aa["FirstRfChannel"] = 10
aa["LastRfChannel"] = 15
c.Scan(aa)
cinfo = CreateObject("roAssociativeArray")
cinfo["ChannelIndex"] = 0
desc = c.CreateChannelDescriptor(cinfo)
print desc
v = CreateObject("roVideoPlayer")
v.PlayFile(desc)
c.Scan(desc)
222
Asynchronous API
• AsyncScan(parameters As roAssociativeArray) As Boolean: Begins a channel scan on the RF input
and returns the results immediately. Otherwise, the behavior and parameters of this method are identical to
Scan(). When completed or cancelled, AsyncScan() generates an roChannelManagerEvent, which supports
ifUserData and outputs two types of event:
o 0 – Scan Complete: Generated upon the completion of a scan. No extra data is supplied.
o 1 – Scan Progress: Generated upon every tune that is performed during the scan. GetData() returns the
percentage complete of the scan.
•
CancelScan() As Boolean: Cancels any asynchronous scans that are currently running. This method does
not generate an roChannelManagerEvent.
Synchronous Example
c = CreateObject("roChannelManager")
' Scan the channels
aa = CreateObject("roAssociativeArray")
aa["ChannelMap"] = "ATSC"
aa["FirstRfChannel"] = 12
aa["LastRfChannel"] = 50
c.Scan(aa)
' Start at the first channel
index = 0
cinfo = CreateObject("roAssociativeArray")
cinfo["ChannelIndex"] = index
desc = c.CreateChannelDescriptor(cinfo)
223
' Play the first channel
v = CreateObject("roVideoPlayer")
v.PlayFile(desc)
' Play the second channel
index = index + 1
cinfo["ChannelIndex"] = index
desc = c.CreateChannelDescriptor(cinfo)
v.PlayFile(desc)
Asynchronous Example
c = CreateObject("roChannelManager")
p = CreateObject("roMessagePort")
c.SetPort(p)
' Scan the channels
aa = CreateObject("roAssociativeArray")
aa["ChannelMap"] = "ATSC"
aa["FirstRfChannel"] = 12
aa["LastRfChannel"] = 50
c.AsyncScan(aa)
loop:
msg = Wait(2000,p)
if msg = 0 then goto scan_complete
224
goto loop
scan_complete:
' Start at the first channel
index = 0
cinfo = CreateObject("roAssociativeArray")
cinfo["ChannelIndex"] = index
desc = c.CreateChannelDescriptor(cinfo)
' Play the first channel
v = CreateObject("roVideoPlayer")
v.PlayFile(desc)
' Rescan the current channel, and update the
desc["ChannelStore"] = MERGE
c.Scan(desc)
225
roControlPort
This object is an improved version of roGpioControlPort. It provides support for the IO port of the BP200 and BP900 USB
botton boards as well as the on-board I/O port and side buttons on the BrightSign player. It also supports button-up events.
The object is used to configure output levels on the I/O connector and monitor inputs. Typically, LEDs and buttons are
attached to the I/O connector on the BrightSign player or the BrightSign Expansion Module.
Object creation:
CreateObject("roControlPort", name as String)
For name, use one of the following:
•
BrightSign to specify the onboard DA-15 connector (on HD210, HD410, HD1010w, HD1020, XD1030, and
XD1230) and side buttons (i.e. SVC button and reset button).
•
Expander-GPIO to specify the DB-25 connector on the BrightSign Expansion Module. If no BrightSign Expansion
module is attached, then object creation will fail and Invalid will be returned.
•
Expander-DIP to specify the eight DIP switches on the BrightSign Expansion Module. If no BrightSign Expansion
module is attached, then object creation will fail and Invalid will be returned.
Note: Hot-plugging the BrightSign Expansion Module is not supported.
Interfaces: ifControlPort, ifSetMessagePort
The ifControlPort interface provides the following:
•
GetVersion() as String: Returns the version number of the firmware (either the main BrightSign firmware or
the BrightSign Expansion Module firmware) responsible for the control port.
226
•
EnableOutput(pin as Integer) as Boolean: Marks the specified pin as an output. If an Invalid pin number
is passed, False will be returned. If successful, the function returns True. The pin will be driven high or low
depending on the current output state of the pin.
•
EnableInput(pin as Integer) as Boolean: Marks the specified pin as an input. If an Invalid pin number is
passed, False will be returned. If successful, the function returns True. The pin will be tri-stated and can be driven
high or low externally.
•
GetWholeState as Integer: Returns the state of all the inputs attached to the control port as bits in an integer.
The individual pins can be checked using binary operations, although it is normally easier to call IsInputActive
instead.
•
IsInputActive(pin as Integer) as Boolean: Returns the state of the specified input pin. If the pin is not
configured as an input, then the result is undefined.
•
SetWholeState(state as Integer): Specifies the desired state of all outputs attached to the control port as
bits in an integer. The individual pins can be set using binary operations, although it is normally easier to call
SetOutputState instead.
•
SetOutputState(pin as Integer, level as Boolean): Specifies the desired state of the specified
output pin. If the pin is not configured as an output, the resulting level is undefined.
•
GetIdentity() as Integer: Returns the identity value that can be used to associate roControlUp and
roControlDown events with this control port.
The ifSetMessagePort interface provides the following:
•
SetPort(port as Object): Requests that all events raised on this control port be posted to the specified
message port.
227
roControlUp, roControlDown
These objects are posted by the control port to the configured message port when inputs change state. The roControlUp
and roControlDown objects are not normally created directly.
An roControlDown event is posted when the input level goes from high to low. An roControlUp event is posted when the
input level goes from low to high.
Interfaces: ifInt, ifSourceIdentity
The ifInt interface provides the following:
•
GetInt() as Integer: Retrieves the pin number associated with the event.
The ifSourceIdentity interface provides the following:
•
GetSourceIdentity() as Integer: Retrieves the identity value that can be used to associate events with the
source roControlPort instance.
228
roGpioControlPort, roGpioButton
Note: New scripts should use roControlPort instead of roGpioControlPort.
roGpioControlPort
This object is used to control and wait for events on the BrightSign generic DB15 control port. Typically, LEDs or buttons
are connected to the DB15 / DB25 port. Turning on a GPIO output changes the voltage on the GPIO port to 3.3V. Turning
off a GPIO output changes the voltage on the GPIO port to 0V.
The GPIO ports are bidirectional and must be programmed as either inputs or outputs. The IDs range from 0–7. The
SetWholeState() method will overwrite any prior output settings. The SetOutputState() takes an output ID (1, 2, or
6, for example). The SetWholeState() method takes a mask (for example, SetWholeState(2^1 + 2^2 ) will set
IDs 1 and 2).
Interfaces: ifSetMessagePort, ifGpioControlPort
The ifSetMessagePort interface provides the following:
•
SetPort(obj As Object) As Void
The ifGpioControlPort interface provides the following:
•
•
•
•
•
•
IsInputActive(input_id As Integer) As Boolean
GetWholeState() As Integer
SetOutputState(output_id As Integer, onState As Boolean) As Void
SetWholeState(on_state As Integer) As Void
EnableInput(input_id As Integer) As Boolean
EnableOutput(output_id As Integer) As Boolean
229
roGpioButton
Interfaces: ifInt, ifIntOps
The ifInt interface contains the input ID listed above and provides the following:
•
•
GetInt() As Integer
SetInt(a As Integer)
The ifIntOps interface provide the following:
•
ToStr() As String
230
roIRRemote
This component supports receiving and transmitting arbitrary Infrared remote control codes using the NEC and PHC
(Pronto Hex Code) protocols. The best way to determine the required send values is to capture the codes received by
roIRRemote when the remote buttons of the device are pressed and then send the same codes.
NEC codes are expressed in 24 bits:
• Bits 0-7: Button code
• Bits 8-23: Manufacturer code
Note: If the manufacturer code is zero, then the code is considered to be intended for the Roku SoundBridge remote
control.
Interfaces: ifSetMessagePort, ifIRRemote.
The ifSetMessagePort interface provides the following:
•
SetPort(message_port_object As Object) As Void
The ifIRRemote interface provides the following:
•
Send(protocol as String, code as Integer) As Boolean: Sends the specified code using the IR
blaster. The system currently supports two IR transmission protocols: "NEC" and "PHC" (Pronto Hex Code). This
method returns True if the code was successfully transmitted, but there is no way to determine from BrightScript if
the controlled device actually received it.
Raw captures of Pronto Hex commands will likely not work with the inbuilt IR blaster on XD players, though they should
work with Iguanaworks IR transceivers. This is a result of the trailing off periods, which are too long to be ecoded properly.
Changing the off periods to all zeros ("0000") will fix this issue.
231
Example: The following example sends an "ON" command to a Panasonic television using a single string of Pronto Hex
Code. You can also provide Pronto Hex Code as an roArray of hex values, which results in less work for the script engine.
ir = CreateObject("roIRRemote")
pronto_hex_Panasonic_on_str = " 0000 0071 0000 0032 0080 003F 0010 0010 0010 0030
0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010
0010 0010 0010 0010 0010 0030 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010
0010 0010 0010 0010 0010 0010 0010 0030 0010 0010 0010 0010 0010 0010 0010 0010 0010 0010
0010 0010 0010 0010 0010 0010 0010 0010 0010 0030 0010 0030 0010 0030 0010 0030 0010 0030
0010 0010 0010 0010 0010 0010 0010 0030 0010 0030 0010 0030 0010 0030 0010 0030 0010 0010
0010 0030 0010 0000"
ir.Send("PHC", pronto_hex_lg_on_str)
232
roIRRemotePress
Messages are generated upon key presses from the Roku Soundbridge remote.
Interfaces: ifInt, ifIntOps
The ifInt interface contains keycode and provides the following:
•
•
GetInt() As Integer
SetInt(a As Integer)
The ifIntOps interface provides the following:
•
ToStr() As String
For the Roku SoundBridge remote control, the Integer returned can have one of the following values:
West
0
East
1
North
2
South
3
Select
4
Exit
5
Power
6
Menu
7
Search
8
Play
9
Next
Previous
Pause
10
11
12
233
Add
Shuffle
Repeat
Volume up
Volume down
Brightness
13
14
15
16
17
18
234
roKeyboard, roKeyboardPress
roKeyboard
This object is used to wait for events from a USB keyboard.
Interfaces: ifSetMessagePort
The ifSetMessagePort interface provides the following:
•
SetPort(As Object) As Void
roKeyboardPress
This object is a keyboard event resulting from the user pressing a key on a USB keyboard. The int value is equivalent to
the ASCII code of the key that was pressed.
Interfaces: ifInt, ifIntOps
The ifInt interface contains the ASCII value of key presses and provides the following:
•
•
GetInt() As Integer
SetInt(a As Integer)
The ifIntOps interface provides the following:
•
ToStr() As String
235
The rotINT32 returned can have one of the following values:
Letter Keys
Number
Keys
Function
Keys
Misc Keys
Special Keys
A - 97
R - 114
0 - 48
F1 - 32826
Del - 127
"-" 45
: 58
B - 98
S - 115
1 - 49
F2 - 32827
Backspace - 8
"=" 61
" 34
C - 99
T - 116
2 - 50
F3 - 32828
Tab - 9
\ 92
< 60
D - 100
U - 117
3 - 51
F4 - 32829
Enter - 13
` 96
> 62
E - 101
V - 118
4 - 52
F5 - 32830
Print Scrn - 32838
[ 91
? 63
F - 102
W - 119
5 - 53
F6 - 32831
Scrl Lock - 32839
] 93
! 33
G - 103
X - 120
6 - 54
F7 - 32832
Pause/Brk - 32840
; 59
@ 64
H - 104
Y - 121
7 - 55
F8 - 32833
INS - 32841
" ' " 39
# 35
I - 105
Z - 122
8 - 56
F9 - 32834
Home - 32842
, 44
$ 36
9 - 57
F11 - 32836
Page Up - 32843
. 46
% 37
F12 - 32837
Page Down - 32846
/ 47
^ 94
L - 108
End - 32845
_ 95
& 38
M - 109
Caps - 32811
"+" 43
* 42
N - 110
Left Arrow - 32848
O - 111
J - 106
K - 107
| 124
( 40
Right Arrow - 32847
~ 126
) 41
P - 112
Up Arrow - 32850
{ 123
Q - 113
Down Arrow - 32849
} 125
236
roMessagePort
A message port is the destination where messages (events) are sent. See the Event Loops section for more details. You
do not call these functions directly when using BrightScript. Instead, use the "Wait" BrightScript statement (see the
BrightScript Reference Guide for more details).
Interfaces: ifMessagePort, ifEnum
The ifMessagePort interface provides the following:
•
•
•
•
•
GetMessage() As Object
WaitMessage(timeout As Integer) As Object
PostMessage(msg As Object) As Void
PeekMessage() As Object
SetWatchdogTimeout(seconds As Integer) As Integer: Enables a watchdog timeout on the
roMessagePort instance. The watchdog on roMessagePort is disabled by default. Passing a positive integer to this
method instructs the watchdog to crash and reboot the player if GetMessage() or WaitMessage() does not
return after the specified number of seconds. Passing zero to this method disables the watchdog again.
Note: The watchdog timeout will not trigger while waiting on the BrightScript debugger prompt.
• DeferWatchdog(a As Integer): Defers the watchdog timeout set by the SetWatchdogTimeout() method.
Passing an integer to this method defers the timeout for the specified number of seconds.
DeferWatchdog(): Defers the watchdog timeout by the amount of seconds set in the SetWatchdogTimeout()
method.
Note: Calls to either DeferWatchdog() method cannot cause the watchdog to trigger earlier than it already will. For
example, calling DeferWatchdog(100) followed by DeferWatchdog(10) will still cause the watchdog to trigger
•
after 100 seconds.
237
The ifEnum interface provides the following:
•
•
•
•
Reset(): Resets the position to the first element of enumeration.
Next() As Dynamic: Returns the typed value at the current position and increment position.
IsNext() As Boolean: Returns True if there is a next element.
IsEmpty() As Boolean: Returns True if there is not a next element.
238
roSequenceMatcher
This object is used to send roSequenceMatchEvent events when the specified byte sequence patterns are matched.
Once a pattern has been matched and the event has been posted, all contributing bytes are discarded. As a result, if one
pattern is a prefix of another pattern, then the second, longer pattern will never be matched by the object.
Interfaces: ifStreamReceiveObserver, ifSequenceMatcher
The ifSequenceMatcher interface provides the following:
•
SetMessagePort(a As Object): Specifies the message port where roSequenceMatchEvent objects will be
posted.
•
Add(pattern As Object, user_data As Object) As Boolean: Adds a pattern to be matched by the
roSequenceMatcher object instance. The pattern should be specified as an object that is convertible to a byte
sequence (e.g. roByteArray, roString). For the user data, pass the object that should be returned if the specified
pattern is matched.
Example
Function FromHex(hex as String) as Object
bytes = CreateObject("roByteArray")
bytes.FromHexString(hex)
return bytes
End Function
Sub Main()
serial = CreateObject("roSerialPort", 1, 115200)
mp = CreateObject("roMessagePort")
239
button1_seq = FromHex("080a01040001e000")
button2_seq = FromHex("080e01040001e000")
matcher = CreateObject("roSequenceMatcher")
matcher.SetMessagePort(mp)
matcher.Add(button1_seq, { name: "button1" })
matcher.Add(button2_seq, { name: "button2" })
matcher.Add("flibbet", { name: "flibbet" })
matcher.Add("flobbet", { name: "flobbet" })
if not serial.SetMatcher(matcher) then
stop
end if
finished = false
while not finished
ev = mp.WaitMessage(10000)
if ev = invalid then
finished = true
else if type(ev) = "roSequenceMatchEvent" then
print "Got button: "; ev.GetUserData().name
else
print "Unexpected event: "; type(ev)
end if
end while
End Sub
240
241
roSequenceMatchEvent
This object is generated whenever roSequenceMatcher matches a specified byte sequence pattern.
Interfaces: ifUserData
The ifUserData interface provides the following:
•
•
SetUserData(user_data As Object): Sets the user data that will be returned when events are raised.
GetUserData() As Object: Returns the user data that has previously been set via roSequenceMatcher.Add()
roSequenceMatchEvent.SetUserData(). It will return Invalid if no data has been set.
242
roSerialPort
This object controls the RS232 serial port, allowing you to receive input and send responses.
roSerialPort sends the following event types:
•
roStreamLineEvent: The line event is generated whenever the end of line string set using SetEol is found and
contains a String for the whole line. This object implements the ifString and ifUserData interfaces.
•
roStreamByteEvent: The byte event is generated on every byte received. This object implements the ifInt and
ifUserData interfaces.
Interfaces: ifStreamSend, ifStreamReceive, ifSerialControl, ifUserData
The ifStreamSend interface provides the following:
•
•
•
SetSendEol(eol_sequence As String) As Void: Sets the EOL sequence when writing to the stream.
SendByte(byte As Integer) As Void: Writes the specified byte to the stream.
SendLine(string As String) As Void: Writes the specified characters to the stream followed by the
current EOL sequence.
•
SendBlock(a As Dynamic) As Void: Writes the specified characters to the stream. This method can support
either a string or an roByteArray. If the block is a string, any null bytes will terminate the block.
•
Flush()
The ifStreamReceive interface provides the following:
•
•
•
•
SetLineEventPort(port As Object) As Void
SetByteEventPort(port As Object) As Void
SetReceiveEol(a As String)
SetMatcher(matcher As Object) As Boolean: Instructs the stream to use the specified matcher. This
object returns True if successful. Pass Invalid to this method to stop using the specified matcher.
243
The ifSerialControl interface provides the following:
•
SetBaudRate(baud_rate As Integer) As Boolean: Sets the baud rate of the device. The supported baud
rates are as follows: 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600,
115200, 230400.
•
SetMode(mode As String) As Boolean: Sets the serial mode in "8N1" syntax. The first character is the
number of data bits. It can be either 5, 6, 7, or 8. The second number is the parity. It can be "N"one, "O"dd, or
"E"ven. The third is the number of stop bits. It can be 1 or 2.
•
SetEcho(enable As Boolean) As Boolean: Enables or disables serial echo. It returns True on success and
False on failure.
•
•
SetEol(a As String)
SetInverted(inverted As Boolean) As Boolean: Inverts the signals on the player serial port. This allows
the player to communicate with most PCs that use -12v to 12v signaling. Passing True to the method enables
inversion, whereas passing False disables it.
•
SendBreak(duration_in_ms As Integer) as Boolean: Sends a serial break or sets the serial break
condition. This method returns True upon success and False upon failure.
a. duration_in_ms = -1: Sends a continuous break.
b. duration_in_ms = 0: Clears the break state.
c. duration_in_ms >= 100: Sets the break condition for the specified period of milliseconds (note that this
integer is only accurate to the tenth of a second).
The ifUserData interface provides the following:
•
•
SetUserData(user_data As Object): Sets the user data that will be returned when events are raised.
GetUserData() As Object: Returns the user data that has previously been set via SetUserData. It will return
Invalid if no data has been set.
Example: This code waits for a serial event and echoes the input received on the serial port to the shell.
244
serial = CreateObject("roSerialPort", 0, 9600)
p = CreateObject("roMessagePort")
serial.SetLineEventPort(p)
serial_only:
msg = Wait(0,p) ' Wait forever for a message.
if(type(msg) <> "roStreamLineEvent") goto serial_only 'Accept serial messages only.
serial.SendLine(msg) ' Echo the message back to serial.
245
SYSTEM OBJECTS
roDeviceInfo
This object provides information about the device hardware, firmware, and features.
Interfaces: ifDeviceInfo
The ifDeviceInfo interface provides the following:
•
GetModel() As String: Returns the model name for the BrightSign device running the script as a string (for
example, "HD1020" or "XD230").
•
GetVersion() As String: Returns the version number of the BrightSign firmware running on the device (for
example, "4.0.13").
•
GetVersionNumber() As Integer: Returns the version number of the BrightSign firmware running on the
device in the more comparable numeric form of (major*65536 + minor*256 + build).
•
GetBootVersion() As String: Returns the version number of the BrightSign boot firmware, also known as
"safe mode", as a string (for example, "1.0.4").
•
GetBootVersionNumber() As Integer: Returns the version number of the BrightSign boot firmware, also
known as "safe mode," in the more comparable numeric form of (major*65536 + minor*256 + build).
•
GetDeviceUptime() As Integer: Returns the number of seconds that the device has been running since the
last power cycle or reboot.
•
GetDeviceUniqueId() As String: Returns an identifier that, if not an empty string, is unique to the unit
running the script.
•
GetFamily() As String: Returns a single string that indicates the family to which the device belongs. A device
family is a set of models that are all capable of running the same firmware.
•
GetDeviceLifetime() As Integer
246
•
HasFeature(feature As String) As Boolean: Returns True if the player feature, which
is passed as a case-insensitive string parameter, is present on the current device
and firmware. These are the possible features that can be queried from the script:
Note: If you pass a parameter other than one of those listed below, it may return False even if the feature is
available on the hardware and firmware.
o "brightscript1": BrightScript Version 1
o "brightscript2": BrightScript Version 2
o "networking": Any form of networking capability; there may be no network currently available.
o "hdmi"
o "component video"
o "vga"
o
o
o
o
o
o
o
o
o
o
o
o
o
"audio1": The first audio output
"audio2": A second audio output
"audio3": A third audio output
"ethernet"
"usb"
"rs232"
"5v serial"
"gpio connector"
"gpio12 button"
"reset button"
"rtc"
"registry"
"nand storage"
o "sd": SD or SDHC
o "sdhc": SDHC only
247
Example:
di = CreateObject("roDeviceInfo")
print di.GetModel()
print di.GetVersion(), di.GetVersionNumber()
print di.GetBootVersion(), di.GetBootVersionNumber()
print di.GetDeviceUptime(), di.GetDeviceBootCount()
On a particular system, this generates:
HD1010
3.2.41
3.2.28
14353
197161
197148
3129
248
roResourceManager
The roResourceManager is used for managing strings in multiple languages.
Object creation:
CreateObject("roResourceManager", filename As String): filename is the name of the file that contains all
of the localized resource strings required by the user. This file must be in UTF-8 format.
Interfaces: ifResourceManager
The interface ifResourceManager provides the following:
•
SetLanguage(language_identifier As String) As Boolean: Instructs the roResourceManager object
to use the specified language. False is returned if there are no resources associated with the specified language.
•
GetResource(resource_identifier As String) As String: Returns the resource string in the current
language for a given resource identifier.
•
•
GetFailureReason() As String: Yields additional useful information if a function return indicates an error.
GetLanguage() As String
At present, roResourceManager is primarily used for localizing the roClockWidget. The resource file passed in during
creation has the following format for each string entry:
[RESOURCE_IDENTIFIER_NAME_GOES_HERE]
eng "Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec"
ger "Jan|Feb|Mär|Apr|Mai|Jun|Jul|Aug|Sep|Okt|Nov|Dez"
spa "Ene|Feb|Mar|Abr|May|Jun|Jul|Ago|Sep|Oct|Nov|Dic"
fre "Jan|Fév|Mar|Avr|Mai|Jun|Jul|Aou|Sep|Oct|Nov|Déc"
249
ita "Gen|Feb|Mar|Apr|Mag|Giu|Lug|Ago|Set|Ott|Nov|Dic"
dut "Jan|Feb|Mar|Apr|Mei|Jun|Jul|Aug|Sep|Okt|Nov|Dec"
swe "Jan|Feb|Mar|Apr|Maj|Jun|Jul|Aug|Sep|Okt|Nov|Dec"
The name in square brackets is the resource identifier. Each line after it is a language identifier followed by the resource
string. Multiple roResourceManager objects can be created. A default "resources.txt" file, which contains a range of
internationalization for the clock widget, is available from the BrightSign website.
250
roSystemLog
This object enables the application to receive events that are intended for reporting errors and trends, rather than for
triggering a response to a user action.
roSystemLog requires specific design patterns in your BrightScript application:
•
•
•
•
Use one roMessagePort throughout the application (instead of creating a new roMessagePort for each screen).
Create one roSystemLog instance at startup that remains for the entire lifetime of the application.
Pass the global roMessagePort mentioned above to SetMessagePort() on the roSystemLog component.
Enable the desired log types using EnableType().
This object is created with no parameters:
CreateObject("roSystemLog")
Interfaces: ifStreamSend, ifSystemLog
The ifStreamSend interface provides the following:
•
•
•
SetSendEol(eol_sequence As String) As Void: Sets the EOL sequence when writing to the stream.
SendByte(byte As Integer) As Void: Writes the specified byte to the stream.
SendLine(string As String) As Void: Writes the specified characters to the stream followed by the
current EOL sequence.
•
SendBlock(a As Dynamic) As Void: Writes the specified characters to the stream. This method can support
either a string or an roByteArray. If the block is a string, any null bytes will terminate the block.
•
Flush()
251
The ifSystemLog interface provides the following:
•
ReadLog() As Object
252
DATE AND TIME OBJECTS
roDateTime
roDateTime represents an instant in time. See roSystemTime and roTimer for other objects with timing functionality.
Interfaces: ifDateTime, ifString
The ifDateTime interface provides the following:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
GetDayOfWeek() As Integer
GetDay() As Integer
GetMonth() As Integer
GetYear() As Integer
GetHour() As Integer
GetMinute() As Integer
GetSecond() As Integer
GetMillisecond() As Integer
SetDay(day As Integer) As Void
SetMonth(month As Integer) As Void
SetYear(year As Integer) As Void
SetHour(hour As Integer) As Void
SetMinute(minute As Integer) As Void
SetSecond(second As Integer) As Void
SetMillisecond(millisecond As Integer) As Void
AddSeconds(seconds As Integer) As Void
SubtractSeconds(seconds As Integer) As Void
253
•
•
•
AddMilliseconds(milliseconds As Integer) As Void
SubtractMilliseconds(milliseconds As Integer) As Void
Normalize() As Boolean: Checks that all the fields supplied are correct. This function fails if the values are out
of bounds.
•
ToIsoString() As String: Returns the current roDateTime value as an ISO-8601 basic formatted string.
Hyphens for date and colons for time are omitted, and a comma is used to separate seconds from milliseconds:
For example, the ISO-8601 standard "2014-05-29T12:30:00.100" would be formatted as "20140529T123000,100".
•
FromIsoString(date-time As String) As Boolean: Sets the value of the roDateTime object using an
ISO-8601 basic formatted string. Hyphens for date and colons for time are omitted, and either a period or comma
can be used to separate seconds from milliseconds: The ISO-8601 standard "2014-05-29T12:30:00.100" could, for
example, be formatted as either "20140529T123000,100" or "20140529T123000.100". This method will return
False (indicating that it has not affected changes to the roDateTime object) if the string is formatted incorrectly or if
the date passed is outside the range of January 1, 1970 and December 31, 2100.
•
ToSecondsSinceEpoch() As Integer: Returns the number of seconds that have elapsed since midnight on
January 1, 1970, as represented by the roDateTime instance (not the system time).
•
FromSecondsSinceEpoch(seconds As Integer) As Boolean: Populates the roDateTime instance with
the specified number of seconds since midnight on January 1, 1970.
•
GetString() As String
The ifString interface provides the following:
•
GetString() As String
A new object is, at the time of its creation, represented by zero seconds. When used via the ifString interface, ifDateTime
will always use the sortable date format "YYYY-MM-DD hh:mm:ss".
254
roSystemTime
roSystemTime provides the ability to read and write the time stored in the RTC. This object supports getting and setting
the time and time zone. See roDateTime and roTimer for other objects with timing functionality.
Interfaces: ifSystemTime.
The ifSystemTime interface provides the following:
•
•
•
•
•
•
•
•
GetLocalDateTime() As Object
GetUtcDateTime() As Object
GetZoneDateTime(timezone_name As String) As Object
SetLocalDateTime(localDateTime As roDateTime) As Boolean
SetUtcDateTime(utcDateTime As roDateTime) As Boolean
GetTimeZone() As String
SetTimeZone(zone_name As String) As Boolean
IsValid() As Boolean: Returns True if the system time is set to something valid. It can be set from the RTC or
NTP.
Dates up to 1 January, 2038 are supported.
The following are the supported time zones:
•
•
•
•
•
•
EST: US Eastern Time
CST: US Central Time
MST: US Mountain Time
PST: US Pacific Time
AKST: Alaska Time
HST: Hawaii-Aleutian Time with no Daylight Savings (Hawaii)
255
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
HST1: Hawaii-Aleutian Time with Daylight Saving
MST1: US MT without Daylight Saving Time (Arizona)
EST1: US ET without Daylight Saving Time (East Indiana)
AST: Atlantic Time
CST2: Mexico (Mexico City)
MST2: Mexico (Chihuahua)
PST2: Mexico (Tijuana)
BRT: Brazil Time (Sao Paulo)
NST: Newfoundland Time
AZOT: Azores Time
GMTBST: London/Dublin Time
WET: Western European Time
CET: Central European Time
EET: Eastern European Time
MSK: Moscow Time
SAMT: Delta Time Zone (Samara)
YEKT: Echo Time Zone (Yekaterinburg)
IST: Indian Standard Time
NPT: Nepal Time
OMST: Foxtrot Time Zone (Omsk)
JST: Japanese Standard Time
CXT: Christmas Island Time (Australia)
AWST: Australian Western Time
AWST1: Australian Western Time without Daylight Saving Time
ACST: Australian Central Standard Time (CST) with Daylight Saving Time
ACST1: Darwin, Australia/Darwin, and Australian Central Standard Time (CST) without Daylight Saving Time
AEST: Australian Eastern Time with Daylight Saving Time
256
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
AEST1: Australian Eastern Time without Daylight Saving Time (Brisbane)
NFT: Norfolk (Island) Time (Australia)
NZST: New Zealand Time (Auckland)
CHAST: , Fiji Time, , Fiji, Pacific/Fiji, Yankee Time Zone (Fiji)
SST: X-ray Time Zone (Pago Pago)
GMT: Greenwich Mean Time
GMT-1: 1 hour behind Greenwich Mean Time
GMT-2: 2 hours behind Greenwich Mean Time
GMT-3: 3 hours behind Greenwich Mean Time
GMT-3:30: 3.5 hours behind Greenwich Mean Time
GMT-4: 4 hours behind Greenwich Mean Time
GMT-4:30: 4.5 hours behind Greenwich Mean Time
GMT-5: 5 hours behind Greenwich Mean Time
GMT-6: 6 hours behind Greenwich Mean Time
GMT-7: 7 hours behind Greenwich Mean Time
GMT-8: 8 hours behind Greenwich Mean Time
GMT-9: 9 hours behind Greenwich Mean Time
GMT-9:30: 9.5 hours behind Greenwich Mean Time
GMT-10: 10 hours behind Greenwich Mean Time
GMT-11: 11 hours behind Greenwich Mean Time
GMT-12: 12 hours behind Greenwich Mean Time
GMT-13: 13 hours behind Greenwich Mean Time
GMT-14: 14 hours behind Greenwich Mean Time
GMT+1: 1 hour ahead of Greenwich Mean Time
GMT+2: 2 hours ahead of Greenwich Mean Time
GMT+3: 3 hours ahead of Greenwich Mean Time
GMT+3:30: 3.5 hours ahead of Greenwich Mean Time
257
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
GMT+4: 4 hours ahead of Greenwich Mean Time
GMT+4:30: 4.5 hours ahead of Greenwich Mean Time
GMT+5: 5 hours ahead of Greenwich Mean Time
GMT+5:30: 5.5 hours ahead of Greenwich Mean Time
GMT+6: 6 hours ahead of Greenwich Mean Time
GMT+6:30: 6.5 hours ahead of Greenwich Mean Time
GMT+7: 7 hours ahead of Greenwich Mean Time
GMT+7:30: 7.5 hours ahead of Greenwich Mean Time
GMT+8: 8 hours ahead of Greenwich Mean Time
GMT+8:30: 8.5 hours ahead of Greenwich Mean Time
GMT+9: 9 hours ahead of Greenwich Mean Time
GMT+9:30: 9.5 hours ahead of Greenwich Mean Time
GMT+10: 10 hours ahead of Greenwich Mean Time
GMT+10:30: 10.5 hours ahead of Greenwich Mean Time
GMT+11: 11 hours ahead of Greenwich Mean Time
GMT+11:30: 11.5 hours ahead of Greenwich Mean Time
GMT+12: 12 hours ahead of Greenwich Mean Time
GMT+12:30: 12.5 hours ahead of Greenwich Mean Time
GMT+13: 13 hours ahead of Greenwich Mean Time
GMT+14: 14 hours ahead of Greenwich Mean Time
258
roTimer
See roDateTime and roSystemTime for other objects with timing functionality.
Interfaces: ifTimer, ifIdentity, ifSetMessagePort
The ifTimer interface provides the following:
• SetTime(hour As Integer, minute As Integer, second As Integer, millisecond As Integer)
As Void
•
•
•
•
•
•
•
SetDate(year As Integer, month As Integer, day As Integer) As Void
SetDayOfWeek(day_of_week As Integer) As Void: Sets the time when you wish the event to trigger. In
general, if a value is -1, then it is a wildcard and will cause the event to trigger every time the rest of the specification
matches. If there are no wildcards, then the timer will trigger only once when the specified date/time occurs. It is
possible, using a combination of day and day_of_week, to specify invalid combinations that will never occur. If
specifications include any wildcard, then the second and millisecond specifications must be zero. Events will be raised
at most once per minute near the whole minute.
SetDateTime(As ifDateTime) As Void: Sets the time when you wish the event to trigger from an roDateTime
object. It is not possible to set wildcards using this method.
Start() As Boolean: Starts the timer based on the current values specified using the above functions.
Stop(): Stops the timer.
SetTime(a As Integer, b As Integer, c As Integer)
SetElapsed(seconds As Integer, milliseconds As Integer): Configures a timer to trigger once the
specified time period has elapsed. Unlike the absolute timer methods above, changes to the system clock will not
affect the period of the SetElapsed() timer.
The ifIdentity interface provides the following:
• GetIdentity() As Integer
259
•
SetIdentity(a As Integer)
The ifSetSetMessagePort interface provides the following:
•
SetPort(a As Object)
Example: This code uses SetElapsed() to create a timer that triggers every 30 seconds.
Sub Main()
mp = CreateObject("roMessagePort")
timer = CreateObject("roTimer")
timer.SetPort(mp)
timer.SetElapsed(30, 0)
print "Start at "; Uptime(0)
timer.Start()
while true
ev = mp.WaitMessage(0)
if type(ev) = "roTimerEvent" then
print "Timer event received at "; Uptime(0)
timer.Start()
else
print "Another event arrived: "; type(ev)
end if
end while
End Sub
260
Example: This code creates a timer that triggers every minute using wildcards in the timer spec.
st=CreateObject("roSystemTime")
timer=CreateObject("roTimer")
mp=CreateObject("roMessagePort")
timer.SetPort(mp)
timer.SetDate(-1, -1, -1)
timer.SetTime(-1, -1, 0, 0)
timer.Start()
while true
ev = Wait(0, mp)
if (type(ev) = "roTimerEvent") then
print "timer event received"
else
print "unexpected event received"
endif
endwhile
Example: This code creates a timer that triggers once at a specific date/time.
timer=CreateObject("roTimer")
mp=CreateObject("roMessagePort")
timer.SetPort(mp)
timer.SetDate(2008, 11, 1)
261
timer.SetTime(0, 0, 0, 0)
timer.Start()
while true
ev = Wait(0, mp)
if (type(ev) = "roTimerEvent") then
print "timer event received"
else
print "unexpected event received"
endif
endwhile
262
roTimerEvent
Interfaces: ifSourceIdentity
The ifSourceIdentity interface provides the following.
•
•
GetSourceIdentity() As Integer
SetSourceIdentity(a As Integer)
263
roTimeSpan
This object provides an interface to a simple timer for tracking the duration of activities. It is useful for tracking how long an
action has taken or whether a specified time has elapsed from a starting event.
Interfaces: ifTimeSpan
The ifTimeSpan interface provides the following:
•
•
•
•
Mark()
TotalMilliseconds() As Integer
TotalSeconds() As Integer
GetSecondsToISO8601Date(a As String) As Integer
264
LEGACY OBJECTS
roSyncPool
We recommend using roAssetPool instead.
Object Creation:
CreateObject("roSyncPool", pool_path As String)
Example:
pool = CreateObject ("roSyncPool", "SD:/pool")
Interfaces: ifSyncPool, ifIdentity, ifMessagePort, ifUserData
The ifSyncPool interface provides the following:
•
ValidateFiles(sync_spec As roSyncSpec, directory As String, options_array As
roAssociativeArray) As Object: Validates the files in the specified directory against the hashes in the
specified sync spec. Files that are not in the sync spec are ignored. The options array can currently contain the
following optional parameters:
o DelteCorrupt (Boolean): Automatically delete files that do not match the sync spec. The method will return
an associative array that maps each fileneame to an explanation of why it is corrupt. The array only contains
corrupt files, so the success is reported by the method returning an empty associative array.
•
•
GetFailureReason() As String
AsyncDownload(a As Object) As Boolean
265
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
AsyncCancel() As Boolean
Realize(a As Object, b As String) As Object
ProtectFiles(a As Object, b As Integer) As Boolean
ReserveMegabytes(a As Integer) As Boolean
GetPoolSizeInMegabytes() As Integer
EstimateRealizedSizeInMegabytes(a As Object, b As String) As Integer
IsReady(a As Object) As Boolean
Validate(a As Object, b As Object) As Boolean
EnablePeerVerification(a As Boolean)
EnableHostVerification(a As Boolean)
SetCertificatesFile(a As String)
SetUserAndPassword(a As String, b As String) As Boolean
AddHeader(a As String, b As String)
SetHeaders(a As Object) As Boolean
SetMinimumTransferRate(a As Integer, b As Integer) As Boolean
AsyncSuggestCache(a As Object) As Boolean
SetProxy(a As String) As Boolean
SetFileProgressIntervalSeconds(a As Integer) As Boolean
QueryFiles(a As Object) As Object
SetFileRetryCount(a As Integer) As Boolean
SetRelativeLinkPrefix(prefix As String) As Boolean
BindToInterface(interface As Integer) As Boolean
EnableUnsafeAuthentication(a As Boolean)
EnableUnsafeProxyAuthentication(enable As Boolean) As Boolean
SetMaximumPoolSizeMegabytes(maximum_size As Integer) As Boolean
266
The ifIdentity interface provides the following:
•
GetIdentity() As Integer
The ifMessagePort interface provides the following:
•
SetPort(a As Object)
The ifUserData interface provides the following:
•
•
SetUserData(a As Object)
GetUserData () As Object
267
roSyncPoolEvent
We recommend using roAssetFetcherEvent instead.
Interfaces: ifSourceIdentity, ifSyncPoolEvent, ifUserData
The ifSourceIdentity interface provides the following:
•
GetSourceIdentity() As Integer
The ifSyncPoolEvent interface provides the following
•
•
•
•
•
GetEvent() As Integer
GetName() As String
GetResponseCode() As Integer
GetFailureReason() As String
GetFileIndex() As Integer
The ifUserData interface provides the following:
•
•
SetUserData(a As Object)
GetUserData() As Object
268
roSyncPoolFiles
We recommend using roAssetPoolFiles instead.
Interfaces: ifSyncPoolFiles
The ifSyncPoolFiles interface provides the following:
•
•
•
GetFailureReason() As String
GetPoolFilePath(a As String) As String
GetPoolFileInfo(a As String) As Object
269
roSyncPoolProgressEvent
We recommend using roAssetFetcherProgressEvent instead.
Interfaces: ifSourceIdentity, ifSyncPoolProgressEvent, ifUserData
The ifSourceIdentity interface provides the following:
•
GetSourceIdentity() As Integer
The ifSyncPoolProgressEvent interface provides the following:
•
•
•
•
•
•
GetFileName() As String
GetFileIndex() As Integer
GetFileCount() As Integer
GetCurrentFileTransferredMegabytes() As Integer
GetCurrentFileSizeMegabytes() As Integer
GetCurrentFilePercentage() As Float
The ifUserData interface provides the following:
•
•
SetUserData(a As Object)
GetUserData() As Object
270
CHANGE LOG
4.4.x, 4.2.x, 3.10.x
March 1, 2013
6.1 Added entries for roDatagramSocket [implemented in version 4.4.47], roXMLElement, roAudioPlayerMx, and
roAudioEventMx.
6.2 Added entry for roChannelManager [implemented in version 4.4.51].
6.3 Added entries for the ifUserData interface [implemented in version 4.4.47] in the roDatagramSender and
roDatagramReceiver section.
6.4 Added a description of the SetBackgroundColor() method in the roVideoOutput entry.
6.5 Added a description and listed the possible parameters for HasFeature() in the roDeviceInfo entry.
6.6 Added object creation parameters for roAssetPool and roSyncPool (as well as a more comprehensive introduction
for roAssetPool)
6.7 Revised description of the GetResponseCode() method in the roUrlEvent entry.
6.8 Changed the formatting of all example scripts to make them easier to distinguish from definitions and other
explanatory language.
March 14, 2013
2.1 Added a description of the JoinMulticastGroup()method [implemented in version 4.4.62] to the
roDatagramSocket entry.
2.2 Added a description of the EnableScanDebug()method [implemented in version 4.4.62] to the roChannelManager
entry.
March 27, 2013
3.1 Added descriptions of SetAppCacheDir() and SetAppCacheSize() methods [implemented in version 4.4.71] to
the roHtmlWidget entry.
271
3.2 Revised roVideoPlayer entry to include information about new channel scanning functionality.
April 8, 2013
4.1 Removed uses of "CF:" (compact flash) and "ATA:" directories from example scripts in favor of "SD:"
4.2 Added description of GetEdidIdentity() [implemented in 4.4.73] to the roVideoMode entry.
4.6.x, 4.4.x, 3.10.x
April 29, 2013
1.1 Revised listing and description of Australian time zones in the roSystemTime entry.
1.2 Added description of ifSerialPort.SendBreak() [implemented in 4.6.14] to the roSerialPort entry.
June 11, 2013
2.1 Added a description of the GetDiagnosticInfo() method [implemented in version 4.5.11] to the roTouchScreen
entry.
2.2 Added a description of the AddGetFromString() method [implemented in version 4.6.14] to the roHttpServer entry.
July 11, 2013
3.1 Added descriptions for all instances of ifStreamSend.SendBlock().
3.2 Added descriptions of EnableUnsafeProxyAuthentication() to the roUrlTransfer and roAssetFetcher entries.
3.3 Added a description of EnableUnsafeAuthentication() to the roAssetFetcher entry.
July 17, 2013
4.1 Expanded object creation entry for roAssetCollection.
4.2 Added a description of objection creation parameters for the roAssetPoolFiles, roAssetFetcher and roAssetRealizer
entries.
272
July 22, 2013
5.1 Added descriptions of the ProtectAssets() and UnprotectAssets() methods to the roAssetPool entry.
5.2 Added a full description of methods and their parameters to the roAssetPoolFiles entry.
5.3 Added a full description of methods and their parameters to the roAssetRealizer entry.
August 16, 2013
6.1 Removed the description of ReadLog() from the entry for roSystemLog.
6.2 Added the following method descriptions to the roUrlTransfer entry: ClearHeaders(), AddHeaders(),
PutFromString(), PutFromFile(), AsyncPutFromString(), AsyncPutFromFile(), Delete(),
AsyncDelete().
4.7.x
August 8, 2013
1.1 Added entires for the roDiskMonitor and roDiskErrorEvent objects.
September 10, 2013
2.1 Added a description for the roGlobal.EjectDrive() method.
2.2 Added descriptions of the roHdmiInputChanged event object, as well as the GetHdmiInputStatus() method, to
the roVideoMode entry.
October 1, 2013
3.1 Added descriptions for the roAudioPlayer.SetAudioDelay() and roAudioPlayer.SetVideoDelay() methods (this applies
to roVideoPlayer as well). Added a description for the related roAudioOutput.SetAudioDelay() method as well.
3.2 Added an entry and comprehensive description for roNetworkStatistics.
3.3 Added an entry for the roMediaStreamer and roMediaStreamerEvent objects.
3.4 Expanded the entry for roIRRemote to include support for the Pronto Hex Code (PHC) protocol.
273
3.5
3.6
3.7
3.8
3.9
3.10
3.11
3.12
3.13
3.14
3.15
Included additional explanation and an example for roStorageHotplug.
Added descriptions for the roVideoPlayer.AdjustVideoColor() and roVideoMode.AdjustGraphicsColor() methods.
Added descriptions for roVideoMode.GetVideoResX / GetVideoResY and roVideoMode.GetOutputResX /
GetOutputResY. Also revised description of roVideoMode.GetResX / GetResY.
Updated and corrected the list of supported baud rates for roSerialPort.SetBaudRate() and
roTouchScreen.SetBaudRate() methods.
Added a description for the roSerialPort.SetInverted method.
Added descriptions for the roDateTime.ToSecondsSinceEpoch and roDateTime.FromSecondsSinceEpoch methods.
Added a description for the roNetworkConfiguration.SetInboundShaperRate() method.
Added an example script to the roNetworkAdvertisement entry.
Expanded description for roUrlTransfer.SetTimeout().
Revised the descriptions for the ro*File.Flush() and ro*File.AsyncFlush() methods.
Added a description for the roSyncPool.ValidateFiles() method.
October 17, 2013
4.1 Revised the description of alpha values in roTextWidget to reflect the fact that they affect both text and canvas color
in 4.7.
October 25, 2013
5.1 Revised the roMediaStreamer entry to reflect new functionality.
5.2 Added a description of the SetMaximumPoolSizeMegabytes() method to the roAssetPool and roSyncPool
5.3
5.4
5.5
entries.
Added the ifUserData interface to the roAssetRealizer object.
Added entries for the new SetWatchdogTimout() and DeferWatchdog() methods in the roMessagePort
section.
Added entry for new roTimer.SetElapsed() method, as well as an example showing how to use roTimer.SetElapsed().
274
November 18, 2013
6.1 Added descriptions for most roGlobal methods.
6.2 Expanded the description of the roNetworkConfiguration.SetHostName() method.
December 12, 2013
7.1 Added a description for the roNetworkConfiguration.SetupDWS() method.
January 28, 2014
8.1 Added a description for the roHtmlWidget.SetUserAgent() method. Also added an example of the standard useragent string reported by WebKit.
8.2 Added a list of standard URL syntax iterations that can be used with roNetworkConfiguration. SetTimeServer().
8.3 Added descriptions for the roSequenceMatcher and roSequenceMatchEvent objects.
8.4 Add a description of the SetMatcher() method to the roTCPStream and roSerialPort objects.
February 13, 2014
9.1 Added an entry for the new roTCPConnectEvent.GetSourceAddress() method (implemented in 4.7.144).
9.2 Revised the description for roTCPServer.BindToPort to reflect new functionality (implemented in 4.7.144).
9.3 Added entries and descriptions for the new roSyncManager and roSyncManagerEvent objects.
9.4 Added a description for the UserString parameter that can be passed to roAudioPlayerMx.
9.5 Added a description for the roAudioEventMx object.
March 9, 2014
10.1 Added documentation for the roSqliteDatabase, roSqliteEvent, and roSqliteStatement objects.
10.2 Revised the roRssParser script example so that the call to roTextWidget.EnableForegroundColor() includes an alpha
value.
10.3 Added more descriptive parameters to several roHtmlWidget methods.
275
March 25, 2014
11.1 Added documentation for the new roVideoMode.Screenshot() method.
11.2 Clarified some of the information in the entry for roImagePlayer.
11.3 Added more descriptive parameter names to several roHtmlWidget methods.
April 10, 2014
12.1 Revised the interface listings for roNetworkConfiguration and added the ifMessagePort and ifUserData interfaces.
12.2 Split the roReadFile, roWriteFile, roReadWriteFile, roAppendFile section into different sections for each object, and
created a new "File Objects" chapter specifically for these objects. Added object descriptions to object entry.
12.3 Added additional information to the roCecRxFrameEvent and roCecTxCompleteEvent entry (including a description
for the objects.
12.4 Modernized some of the information in the roDeviceInfo entry.
12.5 Updated several method entries for roVideoMode. Also added an entry for the SaveEdids() method.
May 12, 2014
13.1 Revised example scripts in the roImageWidget entry so that they actually use roImageWidget objects.
13.2 Made the parameters of some roRegex methods more specific.
13.3 Added descriptions for the PreloadFile(), DisplayFile(), and SetTransitionTime() methods in the
13.4
13.5
13.6
roImagePlayer entry.
Added entires for the Hide() and Show() methods in the roImagePlayer entry.
Added return types and descriptions to ifSendStream methods for roTextField, roSerialPort, roSystemLog, and
roTCPStream.
Added descriptions for ifWidget methods in the roClockWidget entry.
May 29, 2014
14.1 Removed legacy information involving mouse cursor bitmaps from the roTouchScreen entry. Added a more
thorough and up-to-date description for the SetCursorBitmap() method.
276
14.2
14.3
14.4
14.5
14.6
Added a deprication notice to the SetTempDirectory() method in the entry for roSqliteDatabase.
Added descriptions for most roSyncSpec methods.
Added descriptions for the ToIsoString() and FromIsoString() methods in the roDateTime entry.
Added the default transition duration to the description of roImagePlayer.SetTransitionDuration().
Changed the supported interface in the roSyncManager entry from ifCecInterface to ifSyncManager.
277
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : Yes Tagged PDF : Yes XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:08:04 Modify Date : 2014:05:29 14:57:03-07:00 Create Date : 2014:05:29 14:55:07-07:00 Metadata Date : 2014:05:29 14:57:03-07:00 Creator Tool : Acrobat PDFMaker 9.1 for Word Document ID : uuid:e47ba860-96d9-40f8-83a7-354ac9d1df09 Instance ID : uuid:1914bdfe-c8ac-4a11-80fa-e7d7ca39fa39 Format : application/pdf Title : Creator : Producer : Adobe PDF Library 9.0 Page Layout : OneColumn Page Count : 284 Author :EXIF Metadata provided by EXIF.tools