Appendix J: Using the SendMessage Utility

= Appendix J: Using the SendMessage Utility =

When SageTV is installed, SendMessage.exe (version 2.2) is also placed in your SageTV directory. If that file is not in your SageTV directory it may be downloaded from the attachment to this forum post: http://forums.sagetv.com/forums/showthread.php?p=125680&postcount=1

'''This utility was created by a SageTV user and is provided by SageTV “as-is”. Use of this utility is not supported by SageTV’s technical support. If you need help using this utility, please go to our discussion forum at forums.sagetv.com/forums.'''

The SendMessage utility can be used to send commands to SageTV as Windows messages, using the command event numbers. See: Sending Commands via Windows Messages. While SageTV itself can also do this with its -event parameter, SendMessage has a few advantages:

1.      The SendMessage exe file is smaller than the SageTV exe file, so it will load and run faster.

2.      Unlike the -event parameter, the SendMessage utility is capable of sending multiple commands each time the program is run, making it easier to ‘batch process’ a series of commands.

3.      SendMessage can be used to send messages to any Windows program.

Usage
If SendMessage is run without any parameters, it will display a dialog with a brief outline of its usage instructions. The utility uses the following command line format:

'''SendMessage WindowClass WindowName MsgID wParam lParam … '''

The above-referenced Sending Commands via Windows Messages section lists the values to be used for each of those parameters in order to send command event numbers to SageTV or SageTVClient. To send multiple messages, simply send another series of those five parameters after the first five.

In addition to those parameters, default values for each parameter can be defined when you wish to send multiple messages: once a default value is set, that value can be skipped in the list of parameters for additional messages to be sent. To define default values, use the following options. Note that the values are not case sensitive (-c is the same as –C):

-C WindowClass – Define the window class name to receive multiple messages.

-N WindowName – Define the name of the window to receive multiple messages.

-M MsgID – The Windows message number to be sent; decimal value.

-W wParam – The message’s wParam value to be sent; decimal value.

-L lParam – The message’s lParam value to be sent; decimal value.

-D DelayTime – Time, in milliseconds, to delay between each message sent. This parameter is not usually needed, but was added in case such a delay was ever desired.

Any parameters that contain spaces, perhaps the WindowClass or WindowName of some application, can be enclosed in quotes, such as: -C “Window Class”.

Example Use
To show how the parameters might be put into use to control SageTV, let’s take a look at a common desire: to have SageTV go directly to a menu that currently has no direct-access command. The Plugin Manager’s All Available Plugins menu is one such location. The following series of commands will go to that location from anywhere within SageTV:

Home – Event number 28; go to the Main Menu.

Page Down – Event number 56; Page Down to make sure the bottom menu item is highlighted.

Up – Event number 4; arrow Up to the Setup menu item.

Right – Event number 3; arrow into the Setup submenu.

Page Up – Event number 55; Page Up to make sure the top submenu item is highlighted.

Down, Down – Event number 5; arrow Down to the''' SageTV Plugins''' menu item.

Right – Event number 3; arrow into the SageTV Plugins submenu.

Page Up – Event number 55; Page Up to make sure the top submenu item is highlighted.

Select – Event number 20; Select the All Available Plugins submenu item to go to that menu.

Putting all the above options together, SendMessage can be used as follows to issue this series of commands for SageTV:

'''SendMessage.exe -C SageApp -N SageWin -m 1258 -W 0 42 28 56 4 3 55 5 5 3 55 20 '''

In this example, SageApp is the name of the window class receiving the message; SageWin is the name of the window to receive the message; 1258 is the message ID number; 0 is the wParam value; and “42 28 56 4 3 55 5 5 3 55 20” is the series of command event numbers to send to SageTV.

Note: To control SageTVClient, use SageClientApp instead of SageApp.