--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2007/05/24 14:04:18 1200 +++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2007/05/24 14:22:39 1201 @@ -145,7 +145,7 @@
-This Internet-Draft will expire on November 17, 2007.
+This Internet-Draft will expire on November 25, 2007.
@@ -430,6 +430,8 @@
Changing the description of instrument
6.8.20.
Finding instruments
+ 6.8.21.
+Getting job status information
7.
Command Syntax
8.
@@ -476,7 +478,9 @@
Number of database instruments changed
8.21.
Database instrument information changed
- 8.22.
+ 8.22.
+Database job status information changed
+ 8.23.
Miscellaneous and debugging events
9.
Security Considerations
@@ -7916,7 +7920,7 @@
-ADD DB_INSTRUMENTS [<mode>] <db_dir> <file_path> [<instr_index>] +
ADD DB_INSTRUMENTS [NON_MODAL] [<mode>] <db_dir> <file_path> [<instr_index>]
@@ -7938,6 +7942,17 @@
+"RECURSIVE" - +
+++ +All instruments will be processed, including those + in the subdirectories, and the respective subdirectory + tree structure will be recreated in the instruments + database +
+"NON_RECURSIVE" -
@@ -7960,20 +7975,15 @@-not supplied - -
--- -The subdirectory tree structure will be recreated - in the instruments database and all instruments will be - processed and added to the respective subdirectory - in the instruments database. -
-
+
The difference between regular and NON_MODAL versions of the command + is that the regular command returns when the scanning is finished + while NON_MODAL version returns immediately and a background process is launched. + The GET DB_INSTRUMENTS_JOB INFO (Getting job status information) + command can be used to monitor the scanning progress. +
Possible Answers:
@@ -7982,7 +7992,18 @@
"OK" -
-+ + +on success +
on success when NON_MODAL is not supplied +
+
"OK[<job-id>]" - +
++@@ -8783,6 +8804,102 @@on success when NON_MODAL is supplied, where <job-id> + is a numerical ID used to obtain status information about the job progress. + See GET DB_INSTRUMENTS_JOB INFO (Getting job status information) +
+
TOC |
The front-end can ask for the current status of a + particular database instruments job by sending the following command: +
++
++GET DB_INSTRUMENTS_JOB INFO <job-id> +
+
+ +
+Where <job-id> should be replaced by the numerical ID + of the job the front-end is interested in. +
+Possible Answers: +
++
++LinuxSampler will answer by sending a <CRLF> separated list. + Each answer line begins with the settings category name + followed by a colon and then a space character <SP> and finally + the info character string to that setting category. At the + moment the following categories are defined: +
++
+++ + +FILES_TOTAL - +
+++ + +The total number of files scheduled for scanning +
+FILES_SCANNED - +
+++ + +The current number of scanned files +
+SCANNING - +
+++ + +The absolute path name of the file which is currently + being scanned +
+STATUS - +
+++ + +An integer value between 0 and 100 indicating the + scanning progress percentage of the file which is + currently being scanned +
+
+ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET DB_INSTRUMENTS_JOB INFO 2" +
+S: "FILES_TOTAL: 12" +
+"FILES_SCANNED: 7" +
+"SCANNING: /home/me/gigs/Bosendorfer 290.gig" +
+"STATUS: 42" +
+"." +
+
+ +
TOC |
/ DB_INSTRUMENT_DIRECTORY SP pathname
-/ DB_INSTRUMENTS SP FLAT SP pathname SP pathname +
/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname + +
+/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
-/ DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP pathname +
/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname + +
+/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
/ DB_INSTRUMENTS SP pathname SP pathname @@ -8997,6 +9120,9 @@
/ DB_INSTRUMENT_INFO
+/ DB_INSTRUMENTS_JOB_INFO + +
/ MISCELLANEOUS
@@ -9069,6 +9195,9 @@/ DB_INSTRUMENT_INFO
+/ DB_INSTRUMENTS_JOB_INFO + +
/ MISCELLANEOUS
@@ -9252,6 +9381,9 @@/ DB_INSTRUMENT SP INFO SP pathname
+/ DB_INSTRUMENTS_JOB SP INFO SP number + +
/ VOLUME
@@ -9843,6 +9975,21 @@+
scan_mode = +
++RECURSIVE + +
+/ NON_RECURSIVE + +
+/ FLAT + +
+
+ +
TOC |
TOC |
Client may want to be notified when the status of particular database + instruments job is changed by issuing the following command: +
++
++SUBSCRIBE DB_INSTRUMENTS_JOB_INFO +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:DB_INSTRUMENTS_JOB_INFO:<job-id>" +
+
+ +
+where <job-id> will be replaced by the numerical ID of the job, + which status is changed. The front-end will have to send the respective + command to actually get the status info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+TOC |
Client may want to be notified of miscellaneous and debugging events occurring at