RokuECP: Interact with Roku devices using ECP. More...

Data Structures
struct	RokuDevice
	Information about a Roku Device. More...

struct	RokuTVChannel
	Information about a TV channel on a Roku device. More...

struct	RokuTVProgram
	Information about a TV program on a Roku device. More...

struct	RokuExtTVChannel
	Extended information about a TV channel. More...

struct	RokuApp
	Information about a Roku channel (app). More...

struct	RokuAppIcon
	A Roku channel (app) icon. More...

struct	RokuSearchParams
	Information about a Roku search to be performed. More...

struct	RokuAppLaunchParams
	Parameters for Roku app launch command. More...

Functions
int	findRokuDevices (const char interface, size_t maxDevices, size_t urlStringSize, char deviceList[])
	Find Roku devices on the network using SSDP.

int	getRokuDevice (const char url, RokuDevice device)
	Get information about a Roku Device from its ECP URL.

int	rokuSendKey (const RokuDevice device, const char key)
	Send a keypress to a Roku Device, emulating the press of a button on a Roku Remote.

int	getRokuTVChannels (const RokuDevice *device, int maxChannels, RokuTVChannel channelList[])
	Get a list of TV channels accessible from a given Roku device.

int	getActiveRokuTVChannel (const RokuDevice device, RokuExtTVChannel channel)
	Get either the current or last active TV channel on a given Roku device.

int	launchRokuTVChannel (const RokuDevice device, const RokuTVChannel channel)
	Launch a given Live TV channel on a given Roku device.

int	getRokuApps (const RokuDevice *device, int maxApps, RokuApp appList[])
	Get a list of apps on a given Roku device.

int	getActiveRokuApp (const RokuDevice device, RokuApp app)
	Get the current active app on a given Roku device.

int	launchRokuApp (const RokuDevice device, const RokuAppLaunchParams params)
	Launch a given app on a given Roku device.

int	getRokuAppIcon (const RokuDevice device, const RokuApp app, RokuAppIcon *icon)
	Get a given app's icon.

int	sendCustomRokuInput (const RokuDevice device, size_t params, const char names[], const char *values[])
	Send custom input to the currently active app on a given Roku device.

int	rokuSearch (const RokuDevice device, const char keyword, const RokuSearchParams *params)
	Run search for a movie, TV show, person, or app.

int	rokuTypeString (const RokuDevice device, const wchar_t string)
	Send Unicode string to Roku device as a series of keyboard keypresses.

Detailed Description

RokuECP: Interact with Roku devices using ECP.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Function Documentation

◆ findRokuDevices()

int findRokuDevices	(	const char *	interface,
		size_t	maxDevices,
		size_t	urlStringSize,
		char *	deviceList[]
	)

Find Roku devices on the network using SSDP.

Parameters

interface	Name of network interface to search on. Set NULL to auto-select the primary interface.
maxDevices	Maximum number of devices to look for
urlStringSize	Size of destination URL strings (recommended 30)
deviceList	Array (of size maxDevices) of strings (size urlStringSize), which will be updated to contain the ECP URLs of found Roku Devices. Remaining elements, if any, will be made empty strings.

Returns: Number of devices found within five seconds, or a negated gssdp error code

◆ getActiveRokuApp()

int getActiveRokuApp	(	const RokuDevice *	device,
		RokuApp *	app
	)

Get the current active app on a given Roku device.

Parameters

device	Pointer to RokuDevice to list the active app of
app	Pointer to RokuApp to store info about the current active app (Home if no app is active)

Returns: libsoup error code for active-app request, or one of the following error codes: -1 if XML parsing failed, -2 if app element is empty, -3 if the device has ECP disabled.

◆ getActiveRokuTVChannel()

int getActiveRokuTVChannel	(	const RokuDevice *	device,
		RokuExtTVChannel *	channel
	)

Get either the current or last active TV channel on a given Roku device.

Note: This does not work if the device is in Limited mode.

Parameters

device	Pointer to RokuDevice to list the active channel of
channel	Pointer to RokuExtTVChannel to store info about the current or last active TV channel

Returns: libsoup error code for tv-active-channel request, or one of the following error codes: -1 if XML parsing failed, -2 if channel element is empty, -3 if the device is not a TV, -4 if the device is in Limited mode, -5 if the device has ECP disabled.

◆ getRokuAppIcon()

int getRokuAppIcon	(	const RokuDevice *	device,
		const RokuApp *	app,
		RokuAppIcon *	icon
	)

Get a given app's icon.

Note: This does not work if the device is in Limited mode.

Parameters

device	Pointer to RokuDevice on which the app is installed
app	Pointer to RokuApp to get the icon of
icon	Pointer to RokuAppIcon to store the app icon

Returns: libsoup error code for active-app request, or -1 if the device is in Limited mode, or -2 if the device has ECP disabled.

◆ getRokuApps()

int getRokuApps	(	const RokuDevice *	device,
		int	maxApps,
		RokuApp	appList[]
	)

Get a list of apps on a given Roku device.

Note: This does not work if the device is in Limited mode.

Parameters

device	Pointer to RokuDevice to list the apps on
maxApps	Maximum number of apps to list
appList	Array (of size maxApps) of RokuApps which will be updated to contain listed apps

Returns: Number of apps found, or one of the following error codes: -1 if the GET request failed, -2 if XML parsing failed, -3 if app list is empty, -4 if the device is in Limited mode, -5 if the device has ECP disabled.

◆ getRokuDevice()

int getRokuDevice	(	const char *	url,
		RokuDevice *	device
	)

Get information about a Roku Device from its ECP URL.

Parameters

url	The Roku Device's ECP URL (like "http://192.168.1.162:8060/")
device	RokuDevice pointer to store device info in

Returns: libsoup error code for device-info request, or one of the following error codes: -1 if XML parsing failed, -2 if the device info is empty, -3 if the device has ECP disabled.

◆ getRokuTVChannels()

int getRokuTVChannels	(	const RokuDevice *	device,
		int	maxChannels,
		RokuTVChannel	channelList[]
	)

Get a list of TV channels accessible from a given Roku device.

Note: This does not work if the device is in Limited mode.

Parameters

device	Pointer to RokuDevice to list the channels of
maxChannels	Maximum number of channels to list
channelList	Array (of size maxChannels) of RokuTVChannels which will be updated to contain listed channels

Returns: Number of channels found, or one of the following error codes: -1 if the GET request failed, -2 if XML parsing failed, -3 if channel list is empty, -4 if the device is not a TV, -5 if the device is in Limited mode, -6 if the device has ECP disabled.

◆ launchRokuApp()

int launchRokuApp	(	const RokuDevice *	device,
		const RokuAppLaunchParams *	params
	)

Launch a given app on a given Roku device.

Parameters

device	Pointer to RokuDevice to launch the app on
params	App ID and optional parameters to launch with

Returns: libsoup error code for launch request, or -1 if the device has ECP disabled.

◆ launchRokuTVChannel()

int launchRokuTVChannel	(	const RokuDevice *	device,
		const RokuTVChannel *	channel
	)

Launch a given Live TV channel on a given Roku device.

Parameters

device	Pointer to RokuDevice to launch channel on
channel	Pointer to RokuTVChannel to launch

Returns: libsoup error code for launch request, or -1 if the device has ECP disabled, or -2 if the device is not a TV.

◆ rokuSearch()

int rokuSearch	(	const RokuDevice *	device,
		const char *	keyword,
		const RokuSearchParams *	params
	)

Run search for a movie, TV show, person, or app.

Either display the results or auto-launch the first one.

Note: This does not work if the device is in Limited mode; it will return -1.

Parameters

device	Pointer to RokuDevice to run the search on
keyword	Movie/show title, app name, person name, or other keyword to be searched
params	Pointer to RokuSearchParams describing the parameters of the search

Returns: libsoup error code for search request, or -1 if device does not support searches, or -2 if keyword is empty.

◆ rokuSendKey()

int rokuSendKey	(	const RokuDevice *	device,
		const char *	key
	)

Send a keypress to a Roku Device, emulating the press of a button on a Roku Remote.

Note: This does not work if the device is in Limited mode.

Parameters

device	Pointer to RokuDevice to send the keypress to
key	The key code to send to the Roku. Accepted keys are listed at https://developer.roku.com/docs/developer-program/dev-tools/external-control-api.md#keypress-key-values.

Returns: libsoup error code for keypress request, or one of the following error codes: -1 if the selected key isn't valid for that device type, -2 if the device is in Limited mode, -3 if the device has ECP disabled.

◆ rokuTypeString()

int rokuTypeString	(	const RokuDevice *	device,
		const wchar_t *	string
	)

Send Unicode string to Roku device as a series of keyboard keypresses.

Note: This does not work if the device is in Limited mode.; This function depends on locale. Many special characters will fail to send if the standard C locale is used.

Parameters

device	Pointer to RokuDevice to send the string to
string	Wide Unicode string to send

Returns: libsoup error code for the last keypress request, or -1 if the device is in Limited mode, or -2 if the device has ECP disabled.

◆ sendCustomRokuInput()

int sendCustomRokuInput	(	const RokuDevice *	device,
		size_t	params,
		const char *	names[],
		const char *	values[]
	)

Send custom input to the currently active app on a given Roku device.

Parameters

device	Pointer to RokuDevice to send input to
params	Number of parameters to send
names	Array (size params) of strings with the names of the parameters
values	Array (size params) of strings with the values of the parameters

Returns: libsoup error code for input request, or -1 if the device is in limited mode, or -2 if the device has ECP disabled.

Data Structures

Functions

Detailed Description

Function Documentation

◆ findRokuDevices()

◆ getActiveRokuApp()

◆ getActiveRokuTVChannel()

◆ getRokuAppIcon()

◆ getRokuApps()

◆ getRokuDevice()

◆ getRokuTVChannels()

◆ launchRokuApp()

◆ launchRokuTVChannel()

◆ rokuSearch()

◆ rokuSendKey()

◆ rokuTypeString()

◆ sendCustomRokuInput()