banner logo

Index of Methods

The optional string /zip can be appended to the requested method name to indicate that the response string should be compressed in ZLib stream format
General
/ping
Purpose:
Check that the server is available and determine information about it, such as the server version, server capabilities, security protocols in force, etc.
Parameters:
none
Example response:
<pingresponse result="NEED_PASSWORD" serverversion="0.98" serverrevision="25" serverosversionstring="Microsoft Windows NT 6.1.7601 Service Pack 1" serverosversion="6.1" servercapabilities="MCE,MUSIC,PICTURES,VIDEOS,RECORDEDTV,STREAM-HTTPLIVE,STREAM-MSWMSP"/>
Notes:
The result parameter can be one of two values: OK or NEED_PASSWORD
If NEED_PASSWORD is returned, the client must call the login64 method before attempting to make furhter API calls.

The Server Capabilities string is used to tell clients what features are supported on the server. This is a comma-delimited list that can include any of the ServerCapabilities values.

Client apps are expected to disabled unsupported features as appropriate.
xml/login64?un=USERNAME&pw=PASSWORD
Purpose:
Log into the server and obtain a security token string to use in future API calls this session.
Parameters:
un: The username of the user logging in, base64 encoded
pw: The password of the user logging in, base64 encoded
hashedpw: Optionally, an SHA256 hash of the password.
Example response:
<?xml version="1.0"?><loginresponse result="OK" token=8dsd9sd />
Notes:
You should store the token as a string value somewhere; it must be appended as a parameter to every other API method that you call - it is valid for 60 minutes, and will continue to be renewed each time you use it for another 60 minutes.

Specify parameters pw or hashedpw but not both.
xml/settings
Purpose:
Obtain the full list of settings from the server.
Parameters:
None.
Example response:
Notes:
The server settings can be used to provide enhanced client functionality by retrieving a user's preferred settings. Examples include:
  • Title for Main Menu
  • Default series recording options
  • EPG-related preferences

Some server settings, such as passwords, are redacted (usually with asterisks) for security purposes.
xml/showlog/
Purpose:
Obtain the debug log from the server
Parameters:
None.
Example response:
<log result="OK" contents="....debug log contents....">
Notes:
The user may disable remote log retrieval via the Remote Potato Server settings application. In such cases, this method will return this XML:
<log result="Error" contents="RemoteLoggingDisabled">
EPG - Channels and Programmes
xml/channels/all
Purpose:
Retrieve a full list of TV Channels from the server. This is returned as an array of TVService objects.
Parameters:
None.
Example response:
Notes:
xml/channels/setasfavorite/CHANNEL_ID
Purpose:
Add a TVService object to the list of favorite channels on the server.
Parameters:
CHANNEL_ID: The ID of a TVService object as previously retrieved from the server.
Example response:
An XML encoded string, containing the string OK or ERROR to indicate success or failure.
Notes:
If the TVService is already marked as a favorite on the server, the method is ignored but still returns OK.
xml/channels/unsetasfavorite/CHANNEL_ID
Purpose:
Remove a TVService object from the list of favorite channels on the server.
Parameters:
CHANNEL_ID: The ID of a TVService object as previously retrieved from the server.
Example response:
An XML encoded string, containing the string OK or ERROR to indicate success or failure.
Notes:
If the TVService is not marked as a favorite on the server, the method is ignored but still returns OK.
xml/programmes/byepgrequest OR
xml/programmes/nodescription/byepgrequest
Purpose:
Obtain a list of programmes from the EPG that match the specified requests.
POST object:
An array of EPGRequest objects.
Parameters:
programmetype=TVPROGRAMMETYPE: Optionally, this querystring key may be passed along with one of the TVProgrammeType values, to filter the returned list of programmes by type.
Response:
An array of TVProgramme objects.
Notes:
If the 'nodescription' variant of the method is used, all returned TVProgramme objects shall have a null 'Description' field. This is desirable if retrieving large lists of programmes in a limited bandwidth scenario. The client can then call the method /xml/programme/getinfo at a later time to retrieve the additional information for individual TV programmes.
xml/programme/getinfo/PROGRAMME_ID
Purpose:
Retrieve additional information about a given TVProgramme object.
Parameters:
PROGRAMME_ID: The ID of a known TVProgramme object on the server.
Response:
Notes:
Clients should use this method only when a user selects a TVProgramme for further inspection as it is a database-intensive operation on the server.
EPG - Scheduling
xml/recordings
Purpose:
Retrieve the list of scheduled recordings from the server.
Parameters:
None.
Response:
An RPRecordingsBlob object
xml/record/byrecordingrequest
Purpose:
Make a recording via Window Media Center on the server.
Post Object:
A RecordingRequest object.
Response:
A RecordingResult object.
Notes:
Client should check the recording result to see whether the request succeeeded. If it did, the client may wish to merge the returned list of Recordings and TVProgrammes into its database.
xml/cancelrequest/REQUEST_ID
Purpose:
Cancel a scheduled recording request on the server.
Parameters:
REQUEST_ID: The ID of a known RPRequest object on the server
Response:
One of the following strings:

OK
TV is not configured
Invalid Request ID
This series or keyword recording no longer exists.
Error - could not cancel recording request: [ERROR INFO]
FAILED
Notes:
The response to this method is NOT in XML format; instead a UTF8 string is returned. The author of Remote Potato is aware that this is reasonably poor form.

To establish whether this method was successful, test whether the string 'OK' is returned. Any different string response can be directly displayed to the user as an error.
xml/cancelrecording/RECORDING_ID
Purpose:
Cancel a scheduled recording on the server.
Parameters:
RECORDING_ID: The ID of a known RPRecording object on the server
Response:
One of the following strings:

OK
TV is not configured
Invalid Request ID
This recording no longer exists.
Error - could not cancel recording: [ERROR INFO]
FAILED
Notes:
If the recording to be cancelled is part of a 'OneTime' recording request, the corresponding parent request will also be cancelled.

The response to this method is NOT in XML format; instead a UTF8 string is returned. To establish whether this method was successful, test whether the string 'OK' is returned. Any different string response can be directly displayed to the user as an error.
Previously Recorded TV
xml/recordedtv
Purpose:
Retrieve a list of files from the recorded TV folder(s) on the server.
Parameters:
None.
Response:
An array of TVProgramme objects.
Notes:
All TVProgramme objects returned will have the property 'IsGeneratedFromFile' set to TRUE.

The properties of returned TVProgramme objects are extracted from the metadata contained within the .WTV or .DVR-MS files.
/rectvthumbnail64?filename=FILENAME64
Purpose:
Retrieve a thumbnail representing a previously recorded TV show.
Parameters:
FILENAME64: The filename of the recorded TV show, represented as a base64, URL-encoded string.
Response:
A JPEG image representing the thumbnail for the show.
Notes:
This method returns an error if the requested file does not fall within a Remote Potato shared media library.
xml/sendremotekey/REMOTECOMMAND
Purpose:
Simulates an infra-red remote control keypress on the server.
Parameters:
REMOTECOMMAND: One of the RemoteCommand string constants.
Response:
An XML encoded string that is either OK or HELPER_NOT_RUNNING
Notes:
For the key press to be correctly recognised, the server must be running Windows Media Center, and it must be the current foreground application. (i.e. the window is in focus)
Streaming - HTTP Live Streaming
xml/mediastream/probe/byfilename
Purpose:
Retrieve details (before streaming) about an AV file - number of streams, type of codecs, etc.
Post Object:
A String representing the full path to the file, on the server.
Response:
An ArrayOfAVStream object, i.e. an array of AVStream objects, representing the valid streams found within the file
Notes:
Clients can use this method to investigate more about an AV file before presenting streaming options to the user - for example, how many streams are in the file, what type of codecs are contained within the streams, etc.

In cases where more than one audio stream exists, a client might want to display a choice for the user to select which audio track should be streamed. This selection can then be incorporated into the MediaStreamingRequest when streaming is activated, to ensure that the appropriate audio track is played.
xml/mediastream/start/bymediastreamingrequest
Purpose:
Begin an HTTP Live Streaming session on the server, using the requested file and streaming parameters. (quality, bitrate, etc.)
Post Object:
A MediaStreamingRequest object that specifies which file is to be streamed, and various preferences as to quality, size, etc.
Response:
A MediaStreamingResult object that indicates success or failure, and provides the necessary connection information for the client to begin retrieving the stream.
Notes:
Clients should call this method to initiate streaming, then read the response carefully to get the necessary information used to consume the stream.
xml/mediastream/stop/STREAMER_ID
Purpose:
Stop an HTTP Live Streaming session on the server.
Parameters:
STREAMER_ID: The ID of the stream to be stopped.
Response:
The response should be discarded.
Notes:
This method works, but is not necessary to implement streaming since encoding of an HTTP Live Stream will stop of its own accord if the stream is not accessed within a pre-defined Timeout period.

However, a good client may call this method if absolutely certain that the stream will not be required again in the immediate future. Doing so will limit the CPU load on the server and free up disk space by allowing cleanup of temporary files created during streaming.
Streaming - MS-WMSP (older)
xml/stream/start
Purpose:
Begin streaming a named file via MS-WMSP streaming.
Post Object: Response:
A WTVStreamingVideoResult object indicating the result of the streaming request and more information about the stream. (e.g. streaming port number, etc.)
Notes:
When attempting to stream a TV Programme, a client should first check the 'IsDRMProtected' flag - if this is set to TRUE then streaming will fail.

A client should check the returned object to find out whether the streaming request was successful. If so, the client should wait a few seconds and then consume the streaming by connecting to the server on the Port specified in the WTVStreamingVideoResult object that was returned.
Pictures, Videos & File Browsing
xml/filebrowse/dir
Purpose:
Retrieve folders and files within a known directory on the server
Post Object: Response:
A FileBrowseResult object containing the result of the file browse request and, if appropriate, details of the folders and files retrieved.
Notes:
The folder requested must be a folder that is shared on the Remote Potato server else the method may fail.
xml/deletefile64/FILE_PATH
Purpose:
Delete a media file from the server.
Parameters:
FILE_PATH: a base64, URL-encoded representation of the file path.
Response:
...
Notes:
This method returns an error if the requested file does not fall within a Remote Potato shared media library.
/xml/getfilethumbnail64?filename=FILENAME&size=SIZE
Purpose:
Retrieve the thumbnail associated with a file on the server.
Parameters:
FILENAME: A filename that has been base 64 encoded, and then URL encoded.
SIZE: One of the ThumbnailSizes values.
Response:
A JPG file representing the requested thumbnail, or an HTTP 404 response code if any error occurred, including (but not limited to) file not found.
Notes:
The thumbnail requested must be a folder that is shared on the Remote Potato server else the method may fail.
xml/picture/thumbnailzip
Purpose:
Retrieve all thumbnails within a specified directory, represented as a zip archive.
Post Object:
A FileBrowseRequest object pointing to the required folder on the server
Response:
A zip file containing a JPG thumbnail for each file within the requested folder.
Notes:
The folder requested must be a folder that is shared on the Remote Potato server else the method may fail.
Music
xml/music/framework
Parameters:
None

xml/music/songs/artist/ARTIST_ID
Parameters: ARTIST_ID

xml/music/songs/album/ALBUM_ID
Parameters: ALBUM_ID

xml/music/songs/genre/GENRE_ID
Parameters: GENRE_ID

xml/music/songs/all
Parameters: None

xml/music/songs/checkexists/SONG_ID
Parameters
SONG_ID


/musicalbumthumbnail64?id=ID&size=SIZE
Parameters
ID: a base 64 string encoded ID of the album
SIZE: Small, Medium, Large or ExtraLarge

/musicsongthumbnail64?id=ID&size=SIZE
Parameters
ID: a base 64 string encoded ID of the song
SIZE: Small, Medium, Large or ExtraLarge
Deprecated Methods
xml/login?un=USERNAME&pw=PASSWORD
Purpose:
Deprecated, please use the login64 method which provides greater security.
xml/stream/stop
Purpose:
This method has been obsoleted - MS-WMSP streams stop of their own accord, either upon TimeOut (no clients connected) or after all clients have disconnected.
xml/deletefile/FILE_PATH
Purpose:
This method is deprecated as non-ASCII characters within a URL are unsupported, please use /deletefile64
/rectvthumbnail?filename=...
Purpose:
This method is deprecated as non-ASCII characters within a URL are unsupported, please use /rectvthumbnail64