How do I integrate my application with RR ?

guino · 09-23-2006, 08:38 PM

Well, as you probably already know, RR is open source, so there are various choices on adding or modifying the way things interface and work with RR.

Those are the most usual ways of interfacing anything with RR:

1.Direct altering the sources

The source code is release with the software, so feel free to dig in and pitch in. However, there are a few guidelines for this type of work.. Most importantly: Any changes/additions to the code should be limited to fixes and/or features that are used by most people. This is merely an attempt to keep things light enough for most people. Though, when a major feature requires little code, it should not be an issue to merge it as long as it doesn't interfere with existing features.

The source code is fairly well commented so should not be very hard to understand, but to keep it that way, it is highly suggested that you place good comments on any changes/additions to the code. For instance:

'MYNEWFEATURE SUPPORT -- BY MYNAME
...
<CODE>
...
'END OF MYNEWFEATURE

This will help you locate and submit the changes once you're done. All that I need to merge the changes into the main sources is a TXT file with the Changes you made (To/From style is recommended, but not required).

2.Extension Plugins

This is a method for those who wish to extend functionality or modify the behavior of existing commands without having to re-compile or understand RR's source code. This method is described in THIS thread. While the example is provided in VB6 source code, it should be possible to replicate the same COM/ActiveX interface from any language that supports such objects.

3.COM/ActiveX SDK Method

This method is being introduced in the Octber'06 release and basically allows for any software to interface with RR with a very basic COM interface. There are two public creatable Objects from RR available for use by any application running within the same machine. This is the preferred/suggested method for interfacing with RR. You can access those with code similar to:

Set SDK = CreateObject("RoadRunner.SDK")

and

Set GPS = CreateObject("RoadRunner.GPS")

3.1 The SDK Object:

The SDK interface allows any application to execute commands and retrieve any information available from RR. It basically consists of those Functions:

3.1.1 SDK.Execute:

Similar to executing button codes on .skin files:
SDK.Execute "PLAY" -- Play/Pause current song
SDK.Execute "LOAD;AUDIO_PLAYER.SKIN" -- loads the audio player
SDK.Execute "LOAD;AUDIO_PLAYER.SKIN", True -- same but waits till it's finished executing before returning

3.1.2 SDK.GetInfo:

Similar to label codes in .skin files (also includes optional format field):
MYVAR = SDK.GetInfo("TRACKNAME") -- Retrieves trackname
MYVAR = SDK.GetInfo("=$RRVARIABLE$") -- Retrives variable from RR
MYVAR = SDK.GetInfo("TEMP1", "C2F") -- Retrieves Temp1 in Farenheit format

3.1.3 SDK.GetInd:

Returns the state of any indicator codes -- note that for "activexx" codes it assumes the current screen for indication OR you can provide the screen you'd like to get such status from. This method return string types ("True", "False" or a Path to an image file used by indicator)

MYIND = SDK.GetInd("SHUFFLE")
MYIND = SDK.GetInd("ACTIVEPL", "audio_browser.skin")

3.1.4 SDK Mixer Information:

NLINES = SDK.MixerCount -- Retrieves the number of audio lines available (integer)
LINENAME = SDK.MixerName(0) -- Retrieves the name for first audio line (String)
LINEVOL = SDK.MixerVol(0) -- Retrieves the volume for first audio line (long integer)

3.2 GPS Object:

The GPS interface allows any application to poll both parsed and raw NMEA data from the GPS configured in RR.
This is done by simply reading a few properties:

LOCK = GPS.Valid -- Is the information on the GPS Valid ? True/False (Has a lock)
LAT = GPS.Lat -- Parsed GPS Latitude (double)
LON = GPS.Lon -- Parsed GPS Longitude (double)
HDG = GPS.Hdg -- Parsed GPS Heading (double)
ALT = GPS.Alt -- Parsed GPS Altitude (double)
SPD = GPS.Speed -- Parsed GPS Speed (double)
SATS = GPS.Sats -- Parsed GPS number of sattelites in use (integer)
N = GPS.Clients -- Number of Applications connected to GPS, including caller (integer)
GPRMC = GPS.NMEA("$GPRMC") -- Most recent $GPRMC nmea message (works with all $XXXXX messages)

It is also possible to close/open the GPS port for internal use, though you should be mindful of other application using the GPS (including RR) -- thus why the number of clients connected to the GPS.

GPS.ClosePort -- Closes GPS Port (so it is available for other applications outside RR)
GPS.OpenPort -- Re-Opens GPS Port (after being closed by ClosePort)

The Open/Closed functions should be used with most caution. The GPS information is also available from RR when the GPS port is not set but FD or MM is running with propper settings.

4.Windows Messaging API

This was the first method of integration available in RR. I would hope for it to become obsolete, but there's no reason to ever stop support for it. This basically uses the SendMessage Windows API call with the WM_COPYDATA inteface to exchange messages between applications. This requires window hooking and processing of messages (very typical for C++). There's an example of how to do this within the Sources package of RR (SDK Examples).

5.Keyboard Method

Any application that can simulate keyboard presses can interface with RR either by sending key presses to execute commands defined in KeyTBL.INI. This method is NOT recommended if the application simulating keypresses is not able to direct the key presses to specific windows (i.e. only send to application on focus). Another way to do this is to have the commands you wish to execute simply typed out to RR's window between quotes ("PLAY" etc).. Girder is an example of application that handles this interface VERY WELL -- In fact, the RR.GML file for remote contro works on this interface.