From MP3tunes

Contents 1 LockerSync XML Interface 1.1 Summary 1.2 Concepts and Definitions 1.3 Getting Started 1.3.1 Access a running instance of the LockerSync GUI application through a TCP socket 1.3.2 Start the LockerSync XML Interface TCP server without the GUI application 1.3.3 Run the LockerSync XML Interface with direct I/O to stdin/stdout 1.4 Supported Commands 1.4.1 login 1.4.2 status 1.4.3 pause 1.4.4 resume 1.4.5 interrupt 1.4.6 tracks_up 1.4.7 tracks_down 1.4.8 sync_all 1.4.9 sync_up_directory 1.4.10 set_max_up_rate 1.4.11 exit 1.4.12 quit 1.5 Output 1.5.1 Message Types 1.5.1.1 command_ack 1.5.1.2 error 1.5.1.3 status 1.5.1.4 started 1.5.1.5 completed 1.5.1.6 actions_started 1.5.1.7 actions_paused 1.5.1.8 actions_resumed 1.5.1.9 actions_stopped 1.5.1.10 actions_completed 1.5.1.11 action_interrupted

LockerSync XML Interface

Summary

The LockerSync XML Interface is a method for third party applications to interact with the MP3tunes LockerSync application.

Concepts and Definitions

• Action: LockerSync's operations are broken down into distinct Action's, and most of the XML Interface deals with retrieving information about currently running Actions. For more info see: LockerSync Actions
• aId: Each action has a unique identifier called an 'aId' these identifiers are used in commands for the XML Interface
• SyncManager: The SyncManager manages the execution of Action's

Getting Started

There are three ways to make use of the LockerSync XML Interface from your application.

Access a running instance of the LockerSync GUI application through a TCP socket

Using this method it is possible to control/inspect the normal LockerSync GUI application.

To use:

1. Check 'Enable TCP/XML status interface' in LockerSync's Advanced Preferences tab and click OK.
2. When the TCP/XML interface is enabled, LockerSync will listen to connections on port 3145 by default.
3. Connect to localhost:3145 with telnet, or your application

Start the LockerSync XML Interface TCP server without the GUI application

Using this method, it is possible to start LockerSync without displaying the GUI. The status interface will listen on port 3145 as above.

To use:

1. Run common/lockersync/xml_tcp_server.py in your LockerSync directory
2. Connect to localhost:3145 with telnet, or your application

Run the LockerSync XML Interface with direct I/O to stdin/stdout

Using this method, LockerSync is started without displaying the GUI, instead of a tcp socket, the XML interface will accept input on stdin and produce output on stdout.

To use:

1. Run common/lockersync/xml_interface.py in your LockerSync directory
2. You may now interact with the XML interface manually

Supported Commands

Commands for the LockerSync XML Interface are simple one line statements. such as 'login username password' followed by a newline.

login

syntax: login [username] [password]

Logs into an MP3tunes Locker. If username and/or password are not specified, values from the LockerSync Config File will be used if available.

status

syntax: status [aId_1] [aId_2] ....

Retrieve status information for one or more actions. if no aId is specified, status for the top level ActionQueue will be retrieved.

Note that the command 'status' is implictly executed upon startup (or connection to) the XML Interface, outputing the status of the top level ActionQueue

pause

syntax: pause

Pause the SyncManager (i.e. pause any currently running actions)

resume

syntax: resume

Resume the SyncManager after a pause

interrupt

syntax: interrupt [aId]

Interrupt the action with the specified aId. If no aId is specified, and a sync is currently running, the sync action will be interrupted.

tracks_up

syntax: tracks_up

Sync up any tracks/playlists found on the local system that are not present in the current locker

tracks_down

syntax: tracks_down

Sync down any tracks/playlists found in the current locker that are not present on the local system.

sync_all

syntax: sync_all

Sync everything up not present in locker, then sync everything down not present on local system

sync_up_directory

syntax: sync_up_directory <directory>

Sync up all tracks/playlists found in specified directory not present in current locker

set_max_up_rate

syntax: set_max_up_rate <bytes_per_second>

Set the maximum speed that should be used for uploads. The change in throttling will take effect on the next upload request. Use a value of 0 for unlimited

exit

syntax: exit

Exit XML interface and close connection, leaves application running

quit

syntax: quit

Exit XML interface and quit the application entirely

Output

All output from the LockerSync XML Interface should be valid/well-formed XML with utf-8 encoding.

Output is comprised of distinct messages. Each message starts with an xml header, followed by a 'lockersync' element containing the body of the message.

An example message:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <completed>
        <action aId="420" parent_aId="419" type="IncrementalDiskScan" />
    </completed>
</ls:lockersync>

Message Types

The LockerSync XML Interface currently support X different message types. Each message type corresponds to the first child element of the lockersync element (i.e. 'completed' in the above example).

command_ack

A command_ack message is sent whenever the XML Interface has received a command. This does not necessarily indicate that the command is valid, or has been processed, only that it has been successfully received. The command_ack element's text will be the text of the command received. For example if I used the command: 'login demo@mp3tunes.com demo' The following output would be generated:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <command_ack>login demo@mp3tunes.com demo</command_ack>
</ls:lockersync>

error

An error message indicates that LockerSync has encountered an error. The first child element of the error element is a detailed XML representation of the error encountered. See [[LockerSync Errors] for more information. Example:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <error>
        <MalformedCommand>
            <command>login</command>
            <message>Username and/or password not specified</message>
        </MalformedCommand>
    </error>
</ls:lockersync>

status

A status message is usually the result of a 'status' command. The first child element of a status message should be a detailed XML representation of an Action containing status information. Below is an example status message displaying the status of the top level ActionQueue with TuneWatch enabled.

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
  <status>
    <action aId="1" type="ActionQueue">
      <started>True</started>
      <completed>False</completed>
      <units_complete>18</units_complete>
      <units_total>60</units_total>
      <units_per_second>0.00245396737197</units_per_second>
      <running_time>7335.06099296</running_time>
      <time_remaining>17115.1423848</time_remaining>
      <current_action>
        <action aId="11" parent_aId="1" type="FolderWatcher">
          <started>True</started>
          <completed>False</completed>
          <units_complete>18</units_complete>
          <units_total>60</units_total>
          <units_per_second>0.00256085751258</units_per_second>
          <running_time>7028.89570117</running_time>
          <time_remaining>16400.7567596</time_remaining>
          <current_action>
            <action aId="466" parent_aId="11" type="WatchFoldersWait">
              <started>True</started>
              <completed>False</completed>
              <units_complete>18</units_complete>
              <units_total>60</units_total>
              <units_per_second>0.963117734102</units_per_second>
              <running_time>18.6893379688</running_time>
              <time_remaining>43.6085158984</time_remaining>
            </action>
          </current_action>
          <remaining_actions>
            <action aId="467" parent_aId="11" type="ScanWatchFolders">
              <started>False</started>
              <completed>False</completed>
              <units_complete>0</units_complete>
              <units_total>0</units_total>
              <units_per_second>0</units_per_second>
              <running_time>0</running_time>
              <time_remaining>0.0</time_remaining>
            </action>
          </remaining_actions>
        </action>
      </current_action>
    </action>
  </status>
</ls:lockersync>

started

A started message indicates that an Action has started executing. The first child element of a started message should be a brief XML representation of the Action that was started. Below is an example started message for a TuneWatch scan:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <started>
        <action aId="473" parent_aId="11" type="ScanWatchFolders" />
    </started>
</ls:lockersync>

completed

A completed message indicates that an Action has finished executing. The first child element of a completed message should be a brief XML representation of the Action that completed. Below is an example completed message for a TuneWatch scan:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <completed>
        <action aId="473" parent_aId="11" type="ScanWatchFolders" />
    </completed>
</ls:lockersync>

actions_started

An actions_started message indicates that the SyncManager has just started executing actions. actions_started elements do not have any child elements. Example:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <actions_started />
</ls:lockersync>

actions_paused

An actions_paused message indicates that the SyncManager has paused execution of actions (usually due to a user initiated pause, or the result of the pause command). actions_paused elements do not have any child elements. Example:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <actions_paused />
</ls:lockersync>

actions_resumed

An actions_resumed message indicates that the SyncManager has resumed execution of actions after a pause. actions_resumed elements do not have any child elements. Example:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <actions_resumed />
</ls:lockersync>

actions_stopped

An actions_stopped message indicates that the SyncManager has halted execution of actions before all actions were completed. Normally in response to an error. actions_stopped elements do not have any child elements. Example:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <actions_stopped />
</ls:lockersync>

actions_completed

An actions_completed message indicates that the SyncManager has successfully executed all queued actions. Note that if TuneWatch is enabled, this should never happen (as new actions are continually added to the queue for background scanning). actions_completed elements do not have any child elements. Example:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <actions_stopped />
</ls:lockersync>

action_interrupted

An action_interrupted message indicates that an action was interrupted before completion (usually due to a user stopping a sync, a sync interrupting tunewatch actions, or the interrupt command). The first child element of an action_interrupted element is a brief XML representation of the interrupted action. action_interrupted elements may also have an 'exception' child element designating the type of interruption. Example:

<?xml version='1.0' encoding='utf-8'?>
<ls:lockersync xmlns:ls="http://mp3tunes.com/api/lockersync/">
    <action_interrupted>
        <action aId="11" parent_aId="1" type="FolderWatcher" />
        <exception>InterruptAction</exception>
    </action_interrupted>
</ls:lockersync>