Application messages

Application messages are accepted by the static OSC address /ITL.

Application management

ITLMsg

  • quit: requests the client application to quit.

  • scenes: creates a set of scenes. Arguments is a list of scene names.

  • rootPath: rootPath of an INScore application is the default path where the application reads or writes a file when a relative path is used for this file. The default value is the user home directory. Sending the rootPath message without parameter resets the application path to its default value.

  • preprocess: evaluates the input file script and print the result to the log window.

  • mouse: hide or show the mouse pointer.

  • defaultShow: changes the default show status for new objects. The default defaultShow value is 1.

  • load: loads a file previously saved using the save message (see section common). Note that the load operation appends the new objects to the existing scene. When necessary, it is the sender responsibility to clear the scene before loading a file. URL are supported for the file path (see section filebasedrsrc);

  • read: read a buffer that is expected to contain a valid inscore script.

  • require: check that the current INScore version number is equal or greater to the number given as argument. The version number is given as a float value. A message is associated to the require message, which is triggered when the check fails. See section interaction for more details.

  • compatibility: preserve INScore previous behavior. The argument corresponds to a version number, INScore will preserve the corresponding behavior (objects scaling, default size, etc.).

  • errorAddress: set the OSC address of error messages. Default is error: (which is not a valid OSC address but preserved for compatibility reasons).

  • rate: changes the time task rate. Note that null values are ignored. The default rate value is 10.

  • time: sets the application current time. The time is expressed in milliseconds.

  • ticks: sets the application current ticks count. The ticks count indicates the number of time tasks performed by the application.

  • hello: query the host IP number. The message is intended for ITL applications discovery. Answer to the query has the following format: IP inPort outPort errPort where IP is sent as a string and port numbers as integer values.

  • forwardingMsg: application support message forwading and filtering. See section Forwarding.

Example when sending the message:

/ITL hello;

the application will answer with the following message:

/ITL 192.168.0.5  7000 7001 7002

when it runs on a host which IP address is 192.168.0.5 using the default port numbers.

Ports management

ITLPortsMsg

Changes the UDP port numbers:

  • port defines the listening port number,
  • outport defines the port used to send replies to queries,
  • errport defines the port used to send error messages.

The int32 parameter should be a positive value in the range [1024-49150]. The default port, outport and errport values are 7000, 7001 and 7002.

Note: Error messages are sent as a single string.

System support

ITLSystem
  • browse open the file given as parameter using the system default browser. The message supports URLs that can be of type http:// , https:// or file:// . It supports also direct reference to a local file (e.g. myfile.html) that is translated into file:// url using the application rootPath.

Application level queries

The application supports the get messages for its parameters (see section getsect). In addition, it provides the following messages to query version numbers or IP address.

ITLRequest
  • version: version number request.
  • guido-version: Guido engine version number request.
  • musicxml-version: MusicXML and Guido converter version numbers request. Returns "not available" when the library is not found.
  • IP: the host IP address.
  • scount: gives the count of scenes.

Example Querying INScore version:

/ITL get version;

will give the following as output:

/ITL version 1.34

Application static nodes

The application level provides the static nodes stats, debug, log and ssl, available at /ITL/stats /ITL/debug, /ITL/log and /ITL/ssl.

The 'stats' nodes

ITLStats
  • get gives the count of handled messages at OSC and UDP levels: the UDP count indicates the count of messages received from the network, the OSC count includes the UDP count and the messages received internally.
  • reset resets the counters to zero. Note that querying the stats node increments at least the OSC the counter.

Example Answer to a get message addressed to /ITL/stats

/ITL/stats osc 15 udp 10

The 'debug' nodes

The debug node is used to activate debugging information.

ITLdebug
  • switch the debug mode ON or OFF. The parameter is interpreted as a boolean value. When in debug mode, INScore sends verbose messages to the OSC error port for every message that can't be correctly handled. Debugging is ON by default.

Example Error messages generated on error port in debug mode:

error:  incorrect OSC address: /ITL/stat
error:  incorrect parameters: /ITL/scene/foo unknown 0.1
error:  incorrect parameters: /ITL/scene/foo x "incorrectType"

The 'log' nodes

The log node controls a console window that display all the messages sent to the OSC error port. Typical content is given by the example above.

ITLLog
  • show show or hides the console. The parameter is a boolean value.
  • clear clear the console window.
  • foreground put the console window to front.
  • wrap control line wrapping of the console. The parameter is a boolean value.
  • write write the arg list formatted as a string to the log window.
  • save save the current log content to a file. The parameter is a file name. When expressed as a relative path, the file is saved under the current application root path.

  • level set the log level. Expected values are:

  • 0 : no log

  • 1 : log errors (default value)

  • 2 : log errors and output of get messages

  • scale scales the log window content. Default value is 1.0.

The 'plugins' nodes

The plugins node controls the search path for plugins. See section plugins for more information on plugins and search strategies.

ITLPlugin
  • path add folder as a user path. The system will look for plugins in this folder first.
  • reset clear the current user path.

The 'ssl' node

The ssl node is provided to manage certificates for encrypted communication with remote hosts. See section SSL for more details and section Forwarding for communication scheme.