Talk:V600-TCP Interface
From Newsbin
Notes:
Contents |
Goal
Remote Control Application for Newsbin Version 6+
Has to have basic features to be useful, but shouldn't be expected to completely control every aspect of Newsbin. People who need that could just use a Remote Desktop app.
Feature Set
In addition to (or modification of) currently available commands:
- Authentication
- Perform an Internet Search from device
- Send an NZB from the device to Newsbin for processing
- Status information (Download speed, Number files in download list, etc)
- Request a list of subscribed groups
- Request a page of posts from a group, optionally with filter
- Request a page of posts from the search tab, optionally with filter
- Request a page of files in the download list
- Request details about a post
- Request download of a post
- Request details of a file in the download list.
- Pause/Resume a post in the download list
- Request manual unrar of a post in the download list.
Communication
Basic client/server communication follows guidelines set by RFC 3977 - NNTP The following information is partially excerpted from the RFC and edited.
The character set for all commands is UTF-8 RFC 3629.
When a TCP connection is established, Newsbin, now acting as a server, sends a greeting.
200 Newsbin Server
The client and server then exchange commands and responses (respectively) until the connection is closed or aborted.
quit 200 Disconnecting
Commands consist of a keyword, which may be followed by one or more arguments. A CRLF pair terminates all commands. Multiple commands are not permitted on the same line. Keywords and arguments are separated by one or more space or TAB characters.
Keywords are case insensitive; the case of keywords for commands are ignored by the server.
Each response starts with a three-digit response code that is sufficient to distinguish all responses. Certain valid responses are defined to be multi-line; for all others, the response is contained in a single line. The initial line of the response MUST NOT exceed 512 octets, which includes the response code and the terminating CRLF pair; an extension MAY specify a greater maximum for commands that it defines, but not for any other command. Single-line responses consist of an initial line only. Multi-line responses consist of an initial line followed by a multi-line data block.
Should there be an inactivity timeout? If so, how long?
Feature Details
Here are details about how each feature is envisioned to work with suggestions for what TCP command would be invoked to provide the function.
Authentication
Description: Ability to authenticate the user at the beginning of a TCP session.
TCP Command: AUTH <Key> <password>
Returns: 200 OK | 400 Failed
Key has to match the key used to register Newsbin. Password is set in Newsbin under Options/Security Options
Search
Description: Ability to initiate either a local or Internet Search query from the client.
TCP Command: SEARCH <keyword> <internet|local> <min size> <max size> <age> <search source>
Send NZB
Description: Ability to send an NZB file from the client to Newsbin for processing. Needs to be able to handle both text NZB format and binary data if it is a .zip or .gz.
TCP Command: NZB <NZB Data>
Returns: 200 OK | 400 Failed [reason]
Status
Description: Provides status information about what Newsbin is currently doing. Information includes:
- Current download speed
- Bytes queued for download
- Estimated time to download queue
- Bandwidth Limit on/off status
- Pause on/off status
- Available disk space
TCP Command: Status
Returns: 200 speed\tbytesqueued\testtime\tbwonoff\tpauseonoff\tdiskspace
To be discussed - Format needs to be defined.
Request a list of subscribed groups
Description : Request a list of GoG's/groups as setup in NewsBin Pro.
Command: GROUPS
Returns: 200 groupname\ngroupname\ngroupname...
Request a page of posts from a group, with filter
Description: Request a list of posts for a group optionally filtered
Command: GRLIST groupname pagesize page filter
Returns: 200 totalpages\npostid\tsubject\tstatus\tnumberoffiles\tnumberofpars\tsize\tdate\tfrom\tgroup\n....
Request details about a post
Description: Request a list of details of a post
Command: GRDETAILS postid
Returns: 200 partid\tsubject\tstatus\tsize\tdate\tfrom\tgroup\n....
Request download of a post
Description: Requests downloading of a post from group list
Command: GRDOWNLOAD postid
Returns: 200 OK | 400 Failed [reason]
Security
Newsbin will accept a single TCP connection with SSL encryption. Client will have to authenticate before any other commands will be processed, similar to NNTP. Authentication consists of the Newsbin Key and a password. The key must match the key used to register Newsbin. The password is set under the current Options/Security Options configuration screen.
Notes
- Support for V6+ only. No backward support to V5
- iPhone is first. Then iPad and Android devices.
