Responses

A command returns OK on completion or ACK some error on failure. These denote the end of command execution.

Failure responses

The nature of the error can be gleaned from the information that follows the ACK. ACK lines are of the form:

ACK [error@command_listNum] {current_command} message_text\n

These responses are generated by a call to commandError. They contain four separate terms. Let's look at each of them:

  • error: numeric value of one of the ACK_ERROR constants defined in ack.h.

  • command_listNum: offset of the command that caused the error in a Command List. An error will always cause a command list to terminate at the command that causes the error.

  • current_command: name of the command, in a Command List, that was executing when the error occurred.

  • message_text: some (hopefully) informative text that describes the nature of the error.

Example 1.1. foo

An example might help. Consider the following sequence sent from the client to the server.

              command_list_begin
              volume 86
              play 10240
              status
              command_list_end
            

The server responds with: ACK [50@1] {play} song doesn't exist: "10240"

This tells us that the play command, which was the second in the list (the first or only command is numbered 0), failed with error 50. The number 50 translates to ACK_ERROR_NO_EXIST--the song doesn't exist. This is reiterated by the message text which also tells us which song doesn't exist.