ANN (Myth Protocol)

From MythTV Official Wiki
Jump to: navigation, search

Important Notes

  1. One variant of this command should always be the second command sent, after MYTH_PROTO_VERSION. Until the ANN command has successfully been sent, all other commands besides MYTH_PROTO_VERSION, ANN, and DONE will be silently ignored.
  2. Any ANN identifier sent other than the ones listed here with one to four arguments (i.e. "ANN foobar nonsense") will result in a response of "OK" from the backend.
  3. Of the identifiers listed here, only Playback and Monitor are intended for typical use. FileTransfer sends and received bulk data as coordinated by a coupled command connection. SlaveBackend and MediaServer receive commands from the backend, rather than send them to a backend.

ANN Playback or ANN Monitor

Arguments

Command arguments: <mode> <hostname> <eventmode>

List arguments: none

Examples

Command:

23      ANN Playback sycamore 0

Response:

2       OK

Description

Announces a Playback or Monitor connection to the backend.

A mode of Monitor is the same as Playback except that a Monitor client will not prevent the backend from shutting itself down.

If the client would like to receive broadcast events from the backend eventmode allows four settings:

  • 0 - No events
  • 1 - All events
  • 2 - No SYSTEM_EVENT messages
  • 3 - Only SYSTEM_EVENT messages

Returns

Successful response:
OK

Notes

While possible, it is easier not to have to deal with the locking and timeout issues of handling both outbound queries and inbound events on the same socket. MythTV's internal communications code behaves in the manner, dedicating a connection to receiving such unsolicited events and commands from the master backend.

ANN FileTransfer

Present in Protocol Versions

All?

Arguments

Command arguments: <mode> <hostname> <write> [<user_read_ahead> <retries>]

List arguments: <file> <storage group>

Examples

Command:

58      ANN FileTransfer sycamore 0[]:[]/2021_20060218193000.mpg.png[]:[]Default

Response:

25      OK[]:[]20[]:[]0[]:[]13987

Description

Announces a FileTransfer connection to the backend.

Recordings and channel icons are /<filename> and /channels/<filename>, respectively, in the Default group. All other files are paths relative to the storage group base.

Write can be 0 or 1, deciding whether a socket will be read or write.

The user_read_ahead and retries values are optional. user_read_ahead can be 1 or 0 and identifies that you want a read-ahead thread.

Once the ANN FileTransfer command has succeeded, data flow over the socket is regulated by QUERY_FILETRANSFER commands. The ANN FileTransfer socket may be used for this, if ANN Playback or ANN Monitor is sent.

Returns

Successful response:
OK[]:[]<socket number>[]:[]<file size>

The socket number must be saved for use in later commands. The file size is a 64 bit number.

ANN SlaveBackend

Present in Protocol Versions

All?

Arguments

Command arguments: <hostname> <IP address>

List arguments: [ ProgramInfo [ ProgramInfo ]...]

Examples

Command:

211     ANN SlaveBackend host 192.168.10.1[]:[]program details...

Response:

2       OK

Description

Announces a slave backend connection to the master backend.

The program details that are sent represent recordings managed by the slave that is connecting. Any number of programs can be sent, including zero.

Returns

Successful response:
OK

ANN MediaServer

Present in Protocol Versions

67+

Arguments

Command arguments: <hostname>

List arguments: none

Examples

Command:

20      ANN MediaServer host

Response:

2       OK

Description

Announces a media server connection to the master backend.

Returns

Successful response:
OK

Changelog

version changeset description
1 [3021] Initial version
20 [7739] 'RingBuffer' type removed, LiveTV now runs through 'FileTransfer's
22 [7883] Adds 'Monitor' mode
29 [9592] Adds 'usereadahead' <bool> and 'retries' <int> to 'FileTransfer' mode.
46 [21134] Allow writing to files over 'FileTransfer' mode
56 [23012] Add system events for 'Playback' and 'Monitor', 'eventmode' changed from <bool> to <int>
60 [26101] Alter 'FileTransfer' to accept a timeout (in ms) rather than a retry count
66 [v0.25pre-2052-g1508085]cgitgithub The file size is now returned as a single 64 bit number rather than two 32 bit numbers.
67 [v0.25pre-2603-gfb63a2e]cgitgithub Added the 'MediaServer' option.