com_ff(): Depreciate "n-" syntax.

This syntax was introduced long ago (pre git era) for no good reason.
This patch adjusts the documentation to not mention it any more.

The command handler is modified to use para_atoi32() instead of
sscanf(), with fallback code for the old syntax which also prints a
deprecation warning.

Clarify the documentation by explaining what happens in case the
argument is out of bounds.

diff --git a/command.c b/command.c
index 857d77f3e6477642b8e2651749e84afe095a1bd7..f8d679e7add601ed0e93489f38aa4d61318368d0 100644 (file)
--- a/command.c
+++ b/command.c
@@ -671,10 +671,22 @@ static int com_ff(struct command_context *cc, struct lls_parse_result *lpr)
                send_errctx(cc, errctx);
                return ret;
        }
-       if (!(ret = sscanf(lls_input(0, lpr), "%i%c", &i, &c)))
-               return -E_COMMAND_SYNTAX;
-       if (ret > 1 && c == '-')
-               i = -i;
+       ret = para_atoi32(lls_input(0, lpr), &i);
+       if (ret < 0) {
+               if (ret != -E_ATOI_JUNK_AT_END)
+                       return ret;
+               /*
+                * Compatibility code to keep the historic syntax (ff 30-)
+                * working. This can be removed after 0.7.0.
+                */
+               ret = sscanf(lls_input(0, lpr), "%i%c", &i, &c);
+               if (ret <= 0)
+                       return -E_COMMAND_SYNTAX;
+               if (ret > 1 && c == '-') {
+                       PARA_WARNING_LOG("use of obsolete syntax\n");
+                       i = -i;
+               }
+       }
        mutex_lock(mmd_mutex);
        ret = -E_NO_AUDIO_FILE;
        if (!mmd->afd.afhi.chunks_total || !mmd->afd.afhi.seconds_total)

diff --git a/m4/lls/server_cmd.suite.m4 b/m4/lls/server_cmd.suite.m4
index 079589d1f36eee98fb9a0c1252906b5d9b1e43a4..e69d1e2440ac4c7764d8b3909d86c5aba72c1d93 100644 (file)
--- a/m4/lls/server_cmd.suite.m4
+++ b/m4/lls/server_cmd.suite.m4
@@ -124,18 +124,18 @@ aux_info_prefix = Permissions:
                summary = enable verbose mode
 
 [subcommand ff]
-       purpose = jump N seconds forward or backward
-       synopsis = n[-]
+       purpose = jump forward or backward in the current audio file
+       synopsis = seconds
        aux_info = VSS_READ | VSS_WRITE
        [description]
-               This sets the 'R' (reposition request) bit of the vss status flags
-               which enqueues a request to jump n seconds forwards or backwards.
-
-               Example:
-
-                    para_client ff 30-
-
-               jumps 30 seconds backwards.
+               This enqueues a request to reposition the audio stream according to
+               the argument, which may be signed or unsigned integer. Negative values
+               correspond to backward jumps.
+
+               If a negative number is given whose absolute value exceeds the current
+               postition of the stream, a jump to the beginning of the audio file
+               is performed. If a positive amount of seconds is given which exceeds
+               the remaining time of the audio file, the next audio file is loaded.
 
        [/description]