Metadata2 filter functions

Updated by Bryan Jones

Scope

This document describes the Lua functions available in *metadata2*. For other information regarding Lua versions and libraries included please see the document What Lua libraries and what version of Lua do your Streaming products use?

The entries, in no particular order, are;

split

Split a string using a specified separator string.

items=split(sep,string)

Example:

items=split("~","a~bc")

          print(items[1]) -- a

          print(items[2]) -- bc

join

Combine multiple strings into one with an optional separator between them.

result=join(sep,string1,string2,...)

Example:

result=join("~","a","bc")

          print(result) -- a~bc

time_msec

Returns the UTC time in milliseconds since the epoch (midnight Jan 1, 1970). This is the same value as returned by the C time() function but with millisecond accuracy; an integer-divide of the result by 1,000 should give you the same value as the one returned by the time() function.

ms=time_msec()

time_ticks

Returns the UTC time in 100-nanosecond “ticks”, as used by the Windows FILETIME functions. If you integer-divide the result by 10,000 you get the same value as returned by time_msec().

ticks=time_ticks()

time_ticks_unique

Both time_msec() and time_ticks() could return the same value if called very closely together. The time_ticks_unique() function guarantees that each call will return a new value by incrementing the tick count by 1, if needed. Since integer-dividing the result by 10,000 gets you the time_msec() result, this might be the best function to use to guarantee message ordering.

ticks=time_ticks_unique()

WriteString

Write string parameters to the connected socket.

WriteString(item1,item2,...)

Example:

WriteString("abc",123) -- writes "abc123" to the socket

WriteByte

Write an ASCII byte to the connected socket.

WriteByte(number)

Example:

WriteByte(32) -- write a space character

LogInfo, console

Write a log message to the application log file. The message will be prefixed with "Lua: ".

LogInfo(item1,item2,...) -- or use console()

          console(item1,item2,...)

SetField

Set the value of a metadata field. Any old values for the named field are replaced. The fields accumulate into a metadata packet. This packet is sent along when the SendMetadata() function is called.

SetField(fieldName,fieldValue) -- fieldName and fieldValue are strings

GetField

Get the value of a metadata field. A blank string is returned if the field doesn't exist.

fieldValue=GetField(fieldName)

FieldExists

Returns true if the specified field exists (i.e. has been previously set), or false otherwise.

boolean=FieldExists(fieldName)

SendMetadata

Sends the current metadata packet, with all the accumulated fields, for further processing.

SendMetadata()

SendMetaDataServer

This is here for backwards compatibility with metadata1. It sends a special metadata packet for further processing.

SendMetaDataServer(serverName,serverUrl,genre)

          

          -- this has the same effect as:

          

          SetField("metadataFunctionName","SendMetaDataServer")

          SetField("metadataStreamServerName",serverName)

          SetField("metadataStreamServerUrl",serverUrl)

          SetField("metadataStreamGenre",genre)

          SendMetadata()

SendMetaDataSong

This is here for backwards compatibility with metadata1. It sends a special metadata packet for further processing.

SendMetaDataSong(songTitle,songUrl)

          

          -- this has the same effect as:

          

          SetField("metadataFunctionName","SendMetaDataSong")

          SetField("metadataTitleArtist",songTitle)

          SetField("metadataSongUrl",songUrl)

          SendMetadata()

SetCodePage

Sets the input code page for international character processing. Janis Timma has more information on this setting.

SetCodePage(numberOrString)

UseCharacterParser

Tells the upstream processor to use character-at-a-time parsing. This means that OnCharacter() function will be called for each character received.

UseCharacterParser()

UseLineParser

Tells the upstream processor to use line-at-a-time parsing. The OnLineReceived() function is called when a full line has been received.

UseXmlParser()

Enables the XML parser.

UseXmlParser()

OnCharacterData

This Lua function gets called when a character is received.

function OnCharacterReceived(asciiValueOfChar) 

          	-- code goes here

          end

OnLineReceived

This Lua function gets called when a line of data is received. The function is only called if UseLineParser() was called at the start of the Lua filter.

function OnLineReceived(lineData,fullLine)

              -- code goes here

          end

The fullLine parameter will be true if an entire line was received. If fullLine is false, that means that the line is very long and that lineData contains only part of the line.

OnElementStart, OnElementEnd, OnCharacterData, OnComment, OnCdataStart, OnCdataEnd

These Lua functions are called when the XML parser is used.

GetDataTimeoutMinutes

This Lua function specifies how long to wait for data to arrive before a data timeout is triggered.

function GetDataTimeoutMinutes()

              return 1 -- specify the number of minutes to wait for data

          end

Once the data timeout timer expires, the application will call the OnDataTimeout() function. If this function returns true, then the application continues to wait for data. If OnDataTimeout() returns false, then the connection will be closed and reopened.

OnDataTimeout

This Lua function is called after the filter did not receive data for the interval specified by the GetDataTimeoutMinutes() function. If OnDataTimeout() returns true the application will continue to wait for data. If it returns false, the application will close and reopen the connection.

How did we do?