Loading...
Searching...
No Matches
rokuecp.h File Reference

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

Go to the source code of this file.

## 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.

Copyright 2025 Ben Westover me@be.nosp@m.nthe.nosp@m.techg.nosp@m.uy.n.nosp@m.et

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.