Extra Site: Difference between revisions

From Lundman Wiki
No edit summary
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
== 2011 Holiday ==
Documentation for FXP.One API commands and protocol. This documentation file is maintained at
http://www.lundman.net/wiki/index.php?title=Protocol and exported to other formats. This documentation is purposly maintained rigorously as to aid all client developers of FXP.One.


=== Europe ===


[[Image:euro2.jpg|right|thumb|400px|actual route driven]]
== Connecting ==
[[Image:euro1.jpg|right|thumb|400px|roadmap part 1]]


Seeing countries [http://wikitravel.org/en/Switzerland Switzerland], (Germany), [http://wikitravel.org/en/Austria Austria], [http://wikitravel.org/en/Slovenia Slovenia], Italy Venice


It would be my guess that we sleep in: Zurich, Innsbruck, Salzburg, Graz, Ljubljanja/Bled, Venice
=== WELCOME ===
But Innsbruck->Salzburg is short, and Ljubljanja->Venice long.


Jul 14 - Jul 28
When you connect to the FXP.One server, you should receive a greeting
string, similar to:


Distances:
>> WELCOME|name=FXP.Oned|version=0.1|build=18|SSL=optional
{| border="1" align="center" style="color:green;background-color:#ffffcc;"
|'''From'''
|'''To'''
|'''Distance'''
|-
|Zurich
|Neuschwanstein
|228km
|-
|Neuschwanstein
|Innsbruck
|88km
|-
|Innsbruck
|Salzburg
|158km
|-
|Salzburg
|Graz
|276km
|-
|Graz
|Maribo
|50km
|-
|Maribo
|Ljubljanja
|118km
|-
|Ljubljanja
|Bled
|46km
|-
|Ljubljanja
|Postojna
|40km
|-
|Postonja
|Tieste
|37km
|-
|Tieste
|Venice
|142km
|-
|}


Pay special attention to the SSL flag here, since if it is enforced,
and you attempt plain text authentication (which will fail) you are
exposing the user and password.


=== To Organise ===
The "version" is the server version and build
The "protocol" is the protocol version, which you can check to be of
the same Major type as your application knows.


* <s>Book flights Tokyo-Zurich</s>. Done
The "SSL" field can be "disabled", "optional", and "forced".
* <s>Book place to stay for lundman-4 in Zurich on night of 15th-16th.</s> Olympia Hotel.
* <s>Book car Switzerland</s> Done, 7 seater Zurich Town 16/7 09:00 to Venice Centre 21/7 18:00.
* Axel and Marissa arriving at 9.45am on Saturday 16 on flight BA0710
* Fly out of Venice 17:30 Thu, 21 Jul Marco Polo (VCE), 19:30 Thu 21 Jul Schiphol,  21:00 Thu 21 Jul Schiphol -> 23:00 Thu, 21 Jul Stockholm Arlanda Terminal 5
* Book place to stay Arlanda Thu 21st.
* Book Sweden car Arlanda 22/7 to 26th. We fly out at: 14.30 from Arlanda (TG961).




=== SSL ===


Things to do in '''Switzerland''':
Initiate SSL challenge. This is sent by clients requesting the
remainder of the session to be in SSL. This requires that FXP.One
engine's WELCOME message is either "forced" or "optional".


* [http://wikitravel.org/en/Zurich Zurich]
** Zurich Zoo,
** Rhine Falls,
** Tram-Museum,
** Hallenbad Altstetten (waterpark),
** Urania Observatory ,
** [http://www.pilatus.com/content-n12-sE.html Summer Toboggan]
** Innertkirchen
** Swiss Vapeur Parc
** Aquabasilea Waterpark


Camping supplies shop in Uster which is on our way out of Zurich http://www.aventura-travel.ch/11901/index.html
[ Minimal Required Fields]


Things to do in '''Germany''':
[ Optional Arguments ]


* [http://en.wikipedia.org/wiki/Neuschwanstein_Castle Neuschwanstein Castle]
[ Returns ]
* [http://en.wikipedia.org/wiki/Kehlsteinhaus Eagle's Nest]
* Black Forest
>> CODE=<int>      - Command return status CODE.
>> OK              - Initiation request accepted, start SSL phase.
>> MSG              - Human-readable message string
 
[ Example ]
<< SSL 
>> SSL|CODE=0|Msg=Attempting SSL negotiations.
 
 
=== AUTH ===
 
Send USER and PASS for authentication. This requires a valid user and
password pair already registered on FXP.One. If FXP.One was started
with no user database files, it will create one with the account user
"admin" and password "admin".
 
 
[ Minimal Required Fields]
>> USER=<str>      - USER name
>> PASS=<str>      - PASSWORD
 
[ Optional Arguments ]
 
[ Returns ]
>> CODE=<int>      - Failure code.
>> MSG=<str>        - Human readable string message.
 
[ Example ]
<< AUTH|USER=admin|PASS=admin
>> AUTH|CODE=0|MSG=Successful
>> AUTH|CODE=502|MSG=Login incorrect
>> AUTH|CODE=503|MSG=Secure channel enforced.
 
 
== SITES ==
 
For SITE structure definition, see [[Site_Definition]]
http://www.lundman.net/wiki/index.php/Site_Definition
 
=== SITEADD ===
 
Add a new site to the system.
 
[ Minimal required fields ]
>> NAME=<str>      - Name of site. Not used by engine, need not be unique. 
>> HOST=<str>      - Hostname of remote FTP server
>> USER=<str>      - User name for authentication on remote FTP server
>> PASS=<str>      - and password
 
[ Optional Arguments ]
>> PORT=<int>      - Optional PORT of remote FTP server. Default 21.
>> PASSIVE=<yna>  - Use passive for directory listings? [See YNA type]
>> FXP_PASSIVE=yna - Can this remote FTP only take PASV, or PORT?
>> CONTROL_TLS=yna - Attempt SSL/TLS on Control channel?
>> DATA_TLS=<yna>  - Attempt SSL/TLS on Data channel? Site needs CCSN feat
>> IFACE=<ip>      - Optional IP to bind() to.
>> IPORT=<int>    - Optional PORT to bind() to.
>> DESIRED_TYPE=yna- Binary or Ascii mode transfers. [See YNA type]
                    - AUTO and engine will set Binary for transfers.
>> RESUME=<yna>    - Attempt to Resume before Overwrite.
>> RESUME_LAST=yna - Re-queue items needed resume last in the queue.
>> PRET=<yna>      - Send the extended Pre-Transfer command before transfer[1]
>> FSKIPLIST=<str> - File skip list [2]
>> DSKIPLIST=<str> - Directory skip list [2]
>> FPASSLIST=<str> - File pass list [3]
>> DPASSLIST=<str> - Directory pass list [3]
>> FSKIPEMPTY=<yna>- Skip empty files
>> DSKIPEMPTY=<yna>- Skip empty directories
>> FMOVEFIRST=<str>- Pattern file matches to force queue at top
>> DMOVEFIRST=<str>- Pattern directory matches to force queue at top
 
[1] AUTO means it will use this feature if it is reported by the
remote FTPD in the FEAT/features command reply.
 
[2] Uses fnmatch(3) syntax pattern matching. Most file globbal you can
do on the command line, including "*?[]", but excluding "{}". String
consists of slash separated patterns. eg "*.dat/*readme.txt*".
 
All skiplists, passlists and movefirst are processed on the DESTINATION site.
 
[3] Opposite to skiplist. The default is for passlist to be empty,
which is the equivalent of "*". A syntax like "*ENGLISH*" would ensure
only entries which matched string would be queued, and others are
dropped. Uses same pattern syntax as skiplist.
 
[ Extended Optional Arguments ]
As a special feature to the clients connecting to the FXP.One engine,
we also allow for storing of own, arbitrary, key/value pairs. As long
as the "key" is not the same as any of the above keys, or that of the
predefined reserved keys. (eg. "TYPE", "END")
>> <str>=<str>    - Store extra client information.
 
For example:
 
"...|extrafield=somestuff|OS=Unix"
 
[ Returns ]
>> SITEID=<int>    - Site ID of created site.
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>        - Command return message.
 
[ Example ]
>> SITEADD|NAME=local|host=localhost|port=56688|user=mp3|pass=mp3|passive=1|fxp_passive=2|control_TLS=2|data_TLS=2|extrafield=somestuff|OS=Unix
<< SITEADD|CODE=0|SITEID=12|Msg=Added successfully.
 
[ Caveat ]
It is recommended that all clients that wish to store information
in the site database, to prefix their key values with a unique string,
perhaps the name of the application. For example:
lundfxp_sitecmd_1=SITE WHO
lundfxp_lastlogin=015368281
 
=== SITELIST ===
 
Lists all defined sites.
 
[ Minimal Required Fields]
 
[ Optional Arguments ]
>> SHORT          - Send only short list (siteid + name)
>> SITEID=<int>    - Send only specified siteid. Sends no BEGIN/END keys.
 
[ Returns ]
>> SITEID=<int>    - Site ID being displayed.
>> NAME=<str>      - Name of site. Not used by engine, need not be unique.
>> HOST=<str>      - Hostname of remote FTP server
>> USER=<str>      - User name for authentication on remote FTP server
>> PASS=<str>      - and password
>> PORT=<int>      - Optional PORT of remote FTP server. [1]
>> PASSIVE=<yna>  - Use passive for directory listings? [See YNA type]
>> FXP_PASSIVE=yna - Can this remote FTP only take PASV, or PORT?
>> CONTROL_TLS=yna - Attempt SSL/TLS on Control channel?
>> DATA_TLS=<yna>  - Attempt SSL/TLS on Data channel? Site needs CCSN feat
>> IFACE=<ip>      - Optional IP to bind() to. [1]
>> IPORT=<int>    - Optional PORT to bind() to. [1]
>> DESIRED_TYPE=yna- Binary or Ascii mode transfers. [1]
>> RESUME=<yna>    - Attempt to Resume before Overwrite. [1]
>> RESUME_LAST=yna - Re-queue items needed resume last in the queue. [1]
>> PRET=<yna>      - Send the extended Pre-Transfer command before transfer[1]
>> FSKIPLIST=<str> - File skip list [1]
>> DSKIPLIST=<str> - Directory skip list [1]
>> FPASSLIST=<str> - File pass list [1]
>> DPASSLIST=<str> - Directory pass list [1]
>> FSKIPEMPTY=<yna>- Skip empty files [1]
>> DSKIPEMPTY=<yna>- Skip empty directories [1]
>> FMOVEFIRST=<str>- Pattern file matches to force queue at top [1]
>> DMOVEFIRST=<str>- Pattern directory matches to force queue at top [1]
>> BEGIN          - First item sent,  start of list.
>> END            - Final item was sent, end of list.
 
[1] This information is only sent if the current value differs from
the default "AUTO" type. Or, in the case of strings, where the string
is defined (not-empty).
 
[ Example ]
<< SITELIST|BEGIN
>> SITELIST|SITEID=2|NAME=localhost|HOST=127.0.0.1|PORT=21|USER=mp3|PASS=mp3|PASSIVE=1|FXP_PASSIVE=2|CONTROL_TLS=2|DATA_TLS=2|optional_variable=roger moore
>> SITELIST|SITEID=1|NAME=localhost2|HOST=127.0.0.1|PORT=56688|USER=mp3|PASS=mp3|PASSIVE=1|FXP_PASSIVE=2|CONTROL_TLS=2|DATA_TLS=2
>> SITELIST|END
 
<< SITELIST|SHORT
>> SITELIST|BEGIN
>> SITELIST|SITEID=1|NAME=localhost
>> SITELIST|END
 
<< SITELIST|SITEID=2
>> SITELIST|SITEID=2|NAME=localhost|HOST=127.0.0.1|PORT=21|USER=mp3|PASS=mp3|PASSIVE=1|FXP_PASSIVE=2|CONTROL_TLS=2|DATA_TLS=2|optional_variable=roger moore
 
=== SITEMOD ===
 
Modify an existing site's key/value pairs.  Specify as many items as
desired to be changed. Items not specified in the command are left as
they are. To delete a key/pair, send the key with an empty value
field. For example "key=".


Things to do in '''Austria''':
[ Minimal required fields ]
>> SITEID=<int>    - Site ID of created site.


* [http://wikitravel.org/en/Innsbruck Innsbruck]
[ Optional Arguments ]
** Hungerburg / Nordpark Cable Railways (tram/cable car)
** The Botanical Gardens of Innsbruck
>> NAME=<str>      - Name of site. Not used by engine, need not be unique. 
** Swarovski Crystal Worlds
>> HOST=<str>      - Hostname of remote FTP server
** Go Kart Bahn
>> USER=<str>      - User name for authentication on remote FTP server
** Happy Hopp, indoor childrens playpark
>> PASS=<str>      - and password
* [http://wikitravel.org/en/Salzburg_%28city%29 Salzburg]
>> PORT=<int>      - Optional PORT of remote FTP server. Default 21.
** Salzburg Fortress (Festung Hohensalzburg) (castle/cablecar)
>> IFACE=<ip>      - Optional IP to bind() to.
** Salt mine tours, there seem to be a few, this one includes train in mine and slides and raft ride http://www.salzburg.info/en/sights/excursions/salt_mines_hallein.htm
>> IPORT=<int>    - Optional PORT to bind() to.
** Haus der Natur (Science Museum)
>> DESIRED_TYPE=yna- Binary or Ascii mode transfers. [See YNA type]
** Wasserspiele Hellbrunn (water fountain park)
                    - AUTO and engine will set Binary for transfers.
** Untersberg mountain (cable car)
>> RESUME=<yna>    - Attempt to Resume before Overwrite.
** Mozartplatz / Mozart's Birthplace / Mozart Residence
>> RESUME_LAST=yna - Re-queue items needed resume last in the queue.
** Gerlospass (road)
>> PRET=<yna>      - Send the extended Pre-Transfer command before transfer[1]
** Water Wonder World at Krimml, Austria
>> FSKIPLIST=<str> - File skip list [2]
** Grottenbahn Fairytale World in Linz - this sounds good but looks a bit shoddy..
>> DSKIPLIST=<str> - Directory skip list [2]
''Accommodation ideas''
>> FPASSLIST=<str> - File pass list [3]
Salzburg camping [http://www.eurocampings.co.uk/en/europe/austria/salzburg/campsite-mauterndorf-111964/]
>> DPASSLIST=<str> - Directory pass list [3]
* [http://wikitravel.org/en/Graz Graz]
>> FSKIPEMPTY=<yna>- Skip empty files
** Armory (Landeszeughaus) (Museum The richest building in the world when it comes to armor and weapons from the late 15th century)
>> DSKIPEMPTY=<yna>- Skip empty directories
** Arnold Schwarzenegger Stadium
>> FMOVEFIRST=<str>- Pattern file matches to force queue at top
** Island in the Mur
>> DMOVEFIRST=<str>- Pattern directory matches to force queue at top


''Accommodation ideas''
[1] AUTO means it will use this feature if it is reported by the
Innsbruck camping [http://www.camping-stigger.at/camping]
remote FTPD in the FEAT/features command reply.
Bled camping with nice cabins [http://www.camping-bled.com/en-glamping.html]


Things to do in '''Slovenia''':
[2] Uses fnmatch(3) syntax pattern matching. Most file globbal you can
do on the command line, including "*?[]", but excluding "{}". String
consists of slash separated patterns. eg "*.dat/*readme.txt*".


* [http://wikitravel.org/en/Bled Bled] - impossibly romantic mountain lake complete with castle and island (Near Ljubanja)
[3] Opposite to skiplist. The default is for passlist to be empty,
** Summer tobogganing in Bled http://www.bled.si/en/default.asp?id=2300
which is the equivalent of "*". A syntax like "*ENGLISH*" would ensure
** [http://www.bled.si/en/default.asp?id=466 Vintgar Gorge] (TC recommended highly)
only entries which matched string would be queued, and others are
** Emerald River Adventure
dropped. Uses same pattern syntax as skiplist.
** Hot air ballooning "the direction of the flight depends on the wind" http://freeweb.siol.net/bubalo/
* [http://wikitravel.org/en/Postojna Postojna] - Site of the gigantic Postojna caves  (On the way from Ljubanja)
* [http://wikitravel.org/en/Maribor Maribor]
** [http://www.pohorje.org/en/mariborsko-pohorje-summer/ pohorje]
* [http://wikitravel.org/en/Ljubljana Ljubljana]
** Triple Bridge (Tromostovje)
** Dragon Bridge (Zmajski Most)


[ Extended Optional Arguments ]
   
   
Things to do in '''Italy''':
As a special feature to the clients connecting to the FXP.One engine,
we also allow for storing of own, arbitrary, key/value pairs. As long
as the "key" is not the same as any of the above keys, or that of the
predefined reserved keys. (eg. "TYPE", "END")
>> <str>=<str>    - Store extra client information.


* [http://wikitravel.org/en/Trieste Trieste]
For example:
** Grotta Gigante
** Tram
"...|extrafield=somestuff|OS=Unix"
** Aqua Splash Water Park in Lignano Sabbiadoro
* [http://wikitravel.org/en/Venice Venice]
** Dolomites
** Do 3,000 years of history in one afternoon!
** Aqualandia Water Park at Lido di Jesolo
** Gommapiuma Kids Park in Lido di Jesolo


'''Part 2 in [http://wikitravel.org/en/Sweden Sweden]'''
[ Returns ]
>> SITEID=<int>    - Site ID of created site.
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>      - Command return message.


Things to do in '''Sweden''':
[ Example ]
>> SITEMOD|SITEID=1|fskiplist=*ENGLISH*,*COMPLETE*|fskipempty=YES
<< SITEMOD|CODE=0|SITEID=1|Msg=Modified successfully.


* [http://wikitravel.org/en/Stockholm Stockholm]
[ Caveat ]
** [http://vasamuseet.se/en/ Vasa] Vasa ship museum
** [http://www.gronalund.com/sv/Attraktioner/ Grönalund]
It is recommended that all clients that wish to store information
** Gamla Stan
in the site database, to prefix their key values with a unique string,
** Gallivant Productions (Vikings)
perhaps the name of the application. For example:
** ABBA the Museum
* [http://maps.google.com/maps?ll=59.732783,19.072351&spn=0.016137,0.066047&t=h&z=15&lci=com.panoramio.all Koholma] (Jorgen)
lundfxp_sitecmd_1=SITE WHO
* [http://www.kaffeokackel.se/tl_files/kaffeokackel/bilder_innehall/stuga2.jpg Cabin by lake]
lundfxp_lastlogin=015368281


Accommodation 75metres from Skavsta airport http://www.connecthotel.se/default.asp?id=2asjem32vl
=== SITEDEL ===


----
Delete an existing site.


=== Singapore options ===
[ Minimal required fields ]
>> SITEID=<int>    - Site ID of created site.


Singapore snow city - http://www.snowcity.com.sg/snowcity2/index.php
[ Optional Arguments ]
http://www.singaporeforkids.com/things_see_do.php


Sentosa http://www.sentosa.com.sg/en/
[ Extended Optional Arguments ]
Festive hotel within the resort seems very family friendly http://www.rwsentosa.com/language/en-US/Hotels/FestiveHotel


http://www.birdpark.com.sg/
[ Returns ]
>> SITEID=<int>    - Site ID of created site.
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>      - Command return message.


http://www.nightsafari.com.sg/
[ Example ]
>> SITEDEL|SITEID=12
<< SITEDEL|CODE=0|MSG=Site deleted.


[ Caveat ]
Sites aren't actually deleted, just not saved to disk. This means
active sessions using said siteid created before the SITEDEL command
was issued will continue to work.


Proposed trip to Shanghai and Hong Kong.
Shanghai - maglev train


20 hour train from Shanghai to Hong Kong
http://www.seat61.com/China.htm#How_to_read_a_Chinese_train_ticket


Hong Kong - Disneyland, Disneyland hotel?
== SESSIONS ==
http://park.hongkongdisneyland.com/hkdl/en_US/hotels/landing?name=HongKongDisneylandHotelLandingPage


Great wall of China - Bedaling
A session refer to a site connection. The API will ask for a new
Taking the train to the Great Wall of China...
session to a specific site (specified with SITEID) and a session will
For the first 20 minutes, the train negotiates the Beijing suburbs, then it accelerates to around 80mph for a brief sprint to its first station stop.  After stopping briefly at this station, the train starts climbing at slow speed into the mountains to Badaling.  You start to see parts of the Great Wall as soon as you leave the station stop, so have your camera ready!  The train reverses direction at the stop before Badaling, so don't be surprised when this happens. 2 hours at the wall is plenty, so taking the 09:33 from Beijing out and the 15:22 from Badaling back, or the 13:19 out and 19:40 back all work fine. If you want to return earlier, there are also regular buses back to Beijing.
be created. If the connection is lost or closed, _the session is
closed_. The API will have to request a new session if so desired.


=== America ===
=== SESSIONNEW ===


Proposed trip to Canada USA in Summer 2011. We are staying in Waupoos Island, and need to stop in Toronto, and Boston.
Request a new session to site, returning a SID to session.


Since we are in the area, we might as well stop by Niagara Falls. According to Google it is only 4 hours from Boston to New York City. So it would seem prudent to get NYC over with.
[ Minimal Required Fields]
>> SITEID=<int>    - Which remote server to connect to, from SITELIST.


Proposed route:
[ Optional Arguments ]
>> LOG=1            - Normal login is silent. With LOG the API received
                      all verbose messages.


  [http://maps.google.com/maps/ms?hl=en&ie=UTF8&t=h&msa=0&msid=110604077924445277589.00048b26bb0a29bc54770&z=6 Google]
  [ Returns ]
>> SID=<int>      - Value of the new SID for all future commands with
                    sessions
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>      - Command return message.


Areas of interest, and possible sleep overs.
[ Example ]
>> sessionnew|siteid=0
<< SESSIONNEW|SITEID=0|SID=1
<< IDLE|SID=1


Niagara Falls
=== SESSIONFREE ===
NYC: Time Square
NYC: Central Park
NYC: Nat.History Museum
NYC: Statue of Liberty, don't care to go to Liberty Island, but at least see it from afar. Can you see it from Jersey turnpike?
Letchworth national park
Dorian Lake theme park


Six Flags Great Adventure, Jackson, New Jersey- Just an 80-minute drive from Manhattan sits the largest theme park in the world. Six Flags Great Adventure features 12 monster roller coasters and includes a Wild Safari. There is also Six  Flags Hurricane Harbor right next door (the largest water park in the Northeast). New Jersey Transit also provides bus service from the Port Authority Bus Terminal in Manhattan when the park is open (May-October).  
Release a session, and disconnect from remote host.


  Jersey Shore, New Jersey- The Jersey Shore starts just a few miles south of New York City. It stretches for almost 130 miles, and along it are private and public beaches. There are numerous activities along the Jersey Shore. A convenient train ride on the NJ Transit trains from Penn Station will get you to several of the towns on the Jersey Shore, including Manasquan and Point Pleasant Beach.  
  [ Minimal Required Fields]
>> SID=<int>        - SID of the session to close.


  Long Island— When you travel to NYC in the summer, a great idea is to check out Long Island. With its beautiful long white sanded beaches you can have it all: the big city and the summer holiday. Many New Yorkers do that every Friday, Saturday and Sunday if it is hot. Take the Long Island Rail Road from Penn Station to Long Beach ($6.75 one way), and from there go south to the beach itself. Take a day trip on the Hampton Jitney from various stops in NYC to the East End, where Long Island wine country is on the North Fork and The Hamptons are on the South Fork.
  [ Optional Arguments ]


[ Returns ]
>> SID=<int>        - SID of the session closed.
>> CODE=<int>        - Command return status CODE.
>> MSG=<str>        - Command return message.


  NYC: Grand Central Station?
  [ Example ]
  NYC: Central Zoo
   
  NYC: The Cloisters
  >> SESSIONFREE|SID=1
<< SESSIONFREE|CODE=0|SID=1|MSG=Success


Canada
=== ASYNC ===
Toronto - Medieval times restaurant
http://www.medievaltimes.com/toronto.aspx


[http://www.localsknow.ca/?sortby=popular locals know]
Is not a command but client need to be aware that there are messages that
come in at any time.
 
<< CONNECT|SID=1
Send once a session has successfully logged in and is ready to answer
queries. Initially it was thought that IDLE would be enough, but
clients will generally want to auto-trigger some commands upon
connection establish, so we provide this event.
 
<< IDLE|SID=1       
Site is idle, ready for more commands. Informative only as you can
always issue commands, they will be queued.
 
<< DISCONNECT|SID=1|CODE=429|MSG=Undefined error: 0
The session was disconnected. Any further references to the SID (in
this case "1") will result in an error.
 
<< LOG|SID=1|MSG=
You can request a SESSIONNEW to be logged (LOG), or, most of the
commands take an option "LOG" to specify that logging is desired
during the execution of said command. This means the engine will
forward all messages from the remote FTPD to the client. For example:
 
>> CWD|SID=2|path=/requests
<< CWD|SID=2|CODE=0|MSG=250 CWD command successful.
>> CWD|SID=2|path=requests|LOG
<< CWD|SID=2|CODE=-1|MSG=250-REQUESTS ADMIN: roger
<< CWD|SID=2|CODE=-1|MSG=250-
<< CWD|SID=2|CODE=-1|MSG=250-RULES: Please use format of REQ- and FILLED- 
<< CWD|SID=2|CODE=-1|MSG=250-      and please do not dump single files into 
<< CWD|SID=2|CODE=-1|MSG=250-    root as it just make the folder look untidy!
<< CWD|SID=2|CODE=-1|MSG=250-Available space: 14676.22 MB.
<< CWD|SID=2|CODE=0|MSG=250 CWD command successful.
 
 
 
== FTP COMMANDS ==
 
=== DIRLIST ===
 
Request a directory listing from remote server/session.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
 
[ Optional Arguments ]
// Optional: PATH, ARGS, RAW, CACHEOK, LOG
>> PATH=<str>        - Additional path element [1]
>> ARGS=<str>        - Additional list options [2]
>> RAW=<int>        - Include entire list line in FID reply.(unparsed)
>> CACHEOK          - If cache is populated, avoid remote server
>> LOG              - Send all strings with dirlist, like SESSIONNEW
 
[1] Warning. It is not recommended that you use this to supply
different paths as the internal cache engine will get mighty confused.
[2] Some "ls"/LIST options will break the internal parser. For
example, "-1" would remove the long listing style.
 
[ Returns ]
>> SID=<int>        - SID the dirlist reply is from.
>> FID=<int>        - File ID of this item. For QADD.
>> NAME=<str>        - Name of Directory OR File
>> DATE=<time>      - FID's date/time stamp. In seconds since 1970.
>> SIZE=<int>        - Size of Directory OR File
>> USER=<str>        - Owner of entry
>> GROUP=<str>      - Group of entry
>> PERM=<str>        - Permissions string. TODO - add octal as well.
>> FTYPE=<str>      - Type. "Directory", "File".
>> ITEMS=<int>      - Number of items in the list.
>> BEGIN            - First item sent,  start of list.
>> END              - Final item was sent, end of list.
 
[ Example ]
>> dirlist|sid=1
<< DIRLIST|SID=1|BEGIN|items=2
<<  DIRLIST|SID=1|FID=0|NAME=giana_sounds|DATE=1057590000|SIZE=512|USER=nobody|GROUP=nobody|PERM=drwxrwxrwx|type=directory
<< DIRLIST|SID=1|FID=1|NAME=debug_main.gba|DATE=1057590000|SIZE=417520|USER=nobody|GROUP=nobody|PERM=-rwxr-xr-x|type=file
<< DIRLIST|SID=1|END
<< IDLE|SID=1
>> dirlist|sid=1|RAW
<< DIRLIST|SID=1|BEGIN|items=1
<< DIRLIST|SID=1|FID=0|NAME=giana_sounds|DATE=1057590000|SIZE=512|USER=nobody|GROUP=nobody|PERM=drwxrwxrwx|type=directory|RAW=drwxrwxrwx++1+nobody++nobody+++++512+Jul++8++2003+giana_sounds
<< DIRLIST|SID=1|END
<< IDLE|SID=1
 
=== QUOTE ===
 
Send RAW FTP commands to the remote server without FXP.One's
involvement. Typically used for SITE commands.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
>> MSG=<str>        - RAW Command to execute.
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE. (If FTP reply < 300) code=0
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[ Example ]
>> QUOTE|SID=1|MSG=SITE uptime
<< QUOTE|SID=1|CODE=0|MSG=200 Uptime: 2d, 1h, 52m, 50s.
<< IDLE|SID=1
>> QUOTE|SID=1|LOG|MSG=SITE WHO
<< QUOTE|SID=1|CODE=-1|OK|MSG=200- [ WHO ]
<< QUOTE|SID=1|CODE=-1|OK|MSG=Total users online:  1              Total active data:  0   
<< QUOTE|SID=1|CODE=0|MSG=200 WHO command successful.
 
=== CWD ===
 
Change the Current Working Directory of the remote server.
ie. "cd files/"
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
>> PATH=<str>      - New desired directory. or:
>> FID=<int>        - or: FID of directory.
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[ Example ]
>> CWD|SID=1|PATH=Giana_Sisters_GBA
<< CWD|SID=1|CODE=0|MSG=250 CWD command successful.
 
=== PWD ===
 
Return the Current Working Directory path.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE.
>> PATH=<str>      - The parsed current PATH.    [1]
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[1] Warning, PATH is only returned if FXP.One successfully managed to
parse out the path from the reply. Some FTPD send non-standard
replies. If you find one of these, send me an example output string
and I can fix the parser.
 
[ Example ]
>> PWD|SID=1
<< PWD|SID=1|CODE=0|PATH=/Giana_Sisters_GBA/|MSG=257 "/Giana_Sisters_GBA/" is current directory.
 
=== SIZE ===
 
Return the size of a file on the remote server. Not this will give
errors on directories on most FTPDs.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
>> PATH=<str>      - Name of File.  or:
>> FID=<int>        - or: FID of file.
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE.
>> SIZE=<int>      - The size of the file.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[ Example ]
>> SIZE|SID=1|PATH=giana2k.xm.zip
<< SIZE|SID=1|CODE=0|SIZE=287688|MSG=213 287688
 
=== DELE ===
 
Delete a single file on the remote server. You can either issue by
name (relative path, or absolute path), or optionally use FID as
returned by DIRLIST.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
>> PATH=<str>      - Name of File.  or:
>> FID=<int>        - or: FID of file.
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[ Example ]
>> DELE|SID=1|PATH=delete_this.bin
<< DELE|SID=1|CODE=0|MSG=213 DELE command successful.
 
=== MKD ===
 
Create a new directory on the remote server.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
>> PATH=<str>      - Name of Directory.
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[ Example ]
>> MKD|SID=1|PATH=New Folder
<< MKD|SID=1|CODE=0|MSG=213 MKD command successful.
 
=== RMD ===
 
Delete a single directory on the remote server. You can either issue by
name (relative path, or absolute path), or optionally use FID as
returned by DIRLIST.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
>> PATH=<str>      - Name of Directory.  or:
>> FID=<int>        - or: FID of directory.
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[ Example ]
>> RMD|SID=1|PATH=delete_this_dir
<< RMD|SID=1|CODE=0|MSG=213 RMD command successful.
 
=== SITE ===
 
Send a SITE command to the remote server.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
>> CMD=<str>        - Command and arguments to send.
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[ Example ]
>> SITE|SID=1|CMD=WHO
<< SITE|SID=1|CODE=0|MSG=200 Command Successful.
 
=== REN ===
 
Rename a file or directory. Supply the originating name by either
passing FROM or a valid FID, as well as the resulting TO name.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
>> FROM=<str>      - Source name. or:
>> FID=<int>        - or: FID of entry.
>> TO=<str>        - Destination name.
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[ Example ]
>> REN|SID=1|FROM=oldfilename.bin|TO=newfilename.bin
<< REN|SID=1|CODE=0|MSG=250 RNTO command successful.
 
=== MDTM ===
 
Return the date and time of a file. (But not directories, according to
FTP RFC). The return data is in the format of yyyyMMddHHmmSS. For
example, "213 19970205115719". You can either issue by name (relative
path, or absolute path), or optionally use FID as returned by DIRLIST.
 
[ Minimal Required Fields]
>> SID=<int>        - SID of the session
>> PATH=<str>      - Name of Directory.  or:
>> FID=<int>        - or: FID of directory.
 
[ Optional Arguments ]
>> LOG              - Send all strings with command, like SESSIONNEW
 
[ Returns ]
>> SID=<int>        - SID of the session
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)
 
[ Example ]
>> MDTM|SID=1|PATH=somefile.bin
<< MDTM|SID=1|CODE=0|MSG=213 19970205115719
 
 
 
== QUEUES ==
 
=== QUEUENEW ===
 
Create a new QUEUE by associating two SIDs with it. These are
currently named NORTH and SOUTH as a means to refer to either one
uniquely without implying direction of transfer. (source and
destination does not work)
 
[ Minimal Required Fields]
>> NORTH_SID=<int>  - SID of the session, out of two.
>> SOUTH_SID=<int>  - SID of the session, out of two.
 
[ Optional Arguments ]
[ Returns ]
>> QID=<int>        - Queue ID for queue operations.
 
[ Example ]
>> queuenew|north_sid=1|south_sid=2
<< QUEUENEW|CODE=0|QID=1|MSG=Queue created.
 
=== QADD ===
 
Add a new items to a specified queue. This is quite a versatile
command which looks to take many arguments. As a command it has four
parts to it. Except for special QTYPE values, see below.
 
# The source information. The easiest way here is to use the FID option, if you have previously done a DIRLIST command. This will take the required source information from the directory cache. If FID is not used, or you wish to override information from the FID, you can specify the source information manually. The name of the item can either be specified by SRCDIR+SRCNAME OR SRCPATH. (SRCPATH = SRCDIR/SRCNAME). The extra SRC options, like SRCSIZE, and SRCREST are optional. Both are used for Resume purposes, as well as finally CPS calculations.
# The destination information. This is copied from the source. However, you can optionally override any of this. For example specifying a different DSTNAME would transfer and rename the file at the same time. The PATH is made up the same way as source, specify one of the two in: (DSTPATH = DSTDIR/DSTNAME)
# Queue position. This can be omitted for default queue positioning. However if the specific position is desired, you can use @=<int|FIRST|LAST> to specify Nth position, FIRST position or LAST position in the queue.
# Optional modifiers. The default behaviour of a SITE is to always RESUME unless specified otherwise using the "resume" option to the site definition. The default for a queue item is also to resume. You can override this default for THIS queue item by specifying "OVERWRITE" or "RESUME". The latter is useful if the site's default has been changed to OVERWRITE. You can also specify QTYPE for this addition, either due to manual queuing, or to override the FID type. If you get it wrong, the queue processing will also get it wrong.
 
Alternatively, you can use QTYPE to set non transfer type items. At
this time, there is only type "STOP". If you issue QTYPE=STOP there is
no need to send information for 1), 2) or 4). Part 3) is optional.
There is currently a bug where you have to specify SRC= field with the
STOP item. It makes no difference as to which SRC you pick.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
>> SRC=<str>        - Specify which SID is the source. Either "NORTH"
                      or "SOUTH".
EITHER:
>> FID=<int>        - File ID to use as source
OR:
>> SRCPATH=<str>    - Full path of the source file
OR:
>> SRCNAME=<str>    - Name of source file.
>> SRCDIR=<str>    - Directory path containing source file.
OR:
>> QTYPE=STOP      - Insert a soft stop item
 
[ Optional Arguments ]
>> SRCNAME=<str>    - Name of source file
>> SRCDIR=<str>    - Directory path containing source file
>> SRCPATH=<str>    - Full path, ie, SRCDIR/SRCNAME in one.
>> SRCSIZE=<int>    - Size of the queue item.
>> SRCREST=<int>    - Restart point of queue item (files only).
>> DSTNAME=<str>    - Name of destination file, OR obtained from source
>> DSTDIR=<str>    - Directory path containing destination file, OR
                      obtained from source
>> DSTPATH=<str>    - Full path, ie, DSTDIR/DSTNAME in one. OR
                      obtained from source.
>> DSTSIZE=<int>    - Size of the queue item.
>> DSTREST=<int>    - Restart point of queue item (files only).
>> QTYPE=<str>      - Type of queue item. Either "directory",
                      "file" or "stop". [1]
>> RESUME          - Resume file if possible.
>> OVERWRITE        - Do not resume, overwrite destination
>> @=<int|str>      - Queue position, int or FIRST/LAST strings.
 
[1] More types will come. The default type is "file".
 
[ Returns ]
>> QID=<int>        - Queue ID
>> CODE=<int>      - Command return status CODE.
>> ITEMS=<int>      - Number of items in the queue
>> MSG=<str>        - Command return message.
>> @=<int>          - Position in the queue item was inserted.
>> SRCPATH=<str>    - Original source path used (to identify QADD reply, and use "@")
>> DSTPATH=<str>    - Original destination path used (to identify QADD reply, and use "@")
>> FID=<int>        - If QADD was called with FID=, the QADD reply will also contain FID.
 
[ Example ]
>> qadd|qid=1|src=north|fid=2
<< QADD|CODE=0|QID=1|ITEMS=1|@=0|SRCPATH=/test/srcfile.bin|DSTPATH=/dump/srcfile.bin|FID=2|Msg=Added successfully.
>> QADD|QID=123|SRC=SOUTH|SRCPATH=/archive/thesis/bilingual.pdf|DSTPATH=/old/ducoments/obsolete.pdf|SRCSIZE=43523|OVERWRITE|QTYPE=file
<< QADD|CODE=0|QID=123|ITEMS=906|@=55|SRCPATH=/archive/thesis/bilingual.pdf|DSTPATH=/old/ducoments/obsolete.pdf|Msg=Added successfully.
 
What is the default queue position when QADD is called, or during file
transfers? When the API queues items, they will always be placed LAST
unless otherwise specified.
 
As a default, files are added after all the (top) files, but before
the first directory. Directories are added after all files, but before
the first directory. (yes, it's the same). Which the exception of if
the name matches "fmovefirst" or "dmovefirst", then it is inserted
with "FIRST" position.
 
This means, when it is expanding a directory, the queue ends up like:
 
FIRST
    files that match fmovefirst
    all other files
    directories.
LAST
 
=== QLIST ===
 
List all queues on the engine, and their current states.
 
[ Minimal Required Fields]
 
[ Optional Arguments ]
 
[ Returns ]
>> QID=<int>        - Queue ID
>> NORTH=<str>      - Name of the North site
>> SOUTH=<str>      - Name of the South site
>> ITEMS=<int>      - Number of queue items
>> STATUS=<str>    - Current processing state
>> ERRORS=<int>    - Number of items in the error queue.
>> KB/s=<int>      - Transfer speed of last completed transfer.
>> SUBSCRIBED      - Sent if client is subscribed to events from this queue.
>> BEGIN            - First item sent,  start of list.
>> END              - Final item was sent, end of list.
 
[ Example ]
>> qlist
<< QLIST|BEGIN
<< QLIST|QID=20|NORTH=ftp1|SOUTH=ds|ITEMS=1|STATUS=PROCESSING|ERRORS=0|SUBSCRIBED|KB/s=0.00
<< QLIST|END
 
=== QGET ===
 
Get the contents of a specific queue, all its queue items.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
 
[ Optional Arguments ]
 
[ Returns ]
>> QID=<int>        - Queue ID
>> @=<int>          - Position in the queue of item.
>> FTYPE=<str>      - Item type, directory/file.
>> SRC=<str>        - Source SID is "NORTH" or "SOUTH".
>> SRCPATH=<str>    - Full path of source
>> SRCSIZE=<int>    - Source size, if known.
>> SRCREST=<int>    - Source restart point.
>> DSTPATH=<str>    - Full path of destination
>> DSTSIZE=<int>    - Destination size, if known.
>> DSTREST=<int>    - Destination restart point.
>> ITEMS=<int>      - Number of items in the list.
>> BEGIN            - First item sent,  start of list.
>> END              - Final item was sent, end of list.
 
[ Example ]
>> qget|qid=1
<< QGET|QID=1|ITEMS=1|BEGIN
<< QGET|QID=1|@=0|FTYPE=FILE|SRC=NORTH|SRCPATH=/Giana_Sisters_GBA//gfx_blocks.txt|
        SRCSIZE=9328|SRCREST=0|DSTPATH=/tmp//gfx_blocks.txt|DSTSIZE=0|DSTREST=0
<< QGET|QID=1|END
 
=== QERR ===
 
Get the contents of a specific error queue, all its queue items.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
 
[ Optional Arguments ]
 
[ Returns ]
>> QID=<int>        - Queue ID
>> QTYPE=<str>      - Item type, directory/file.
>> SRC=<NORTH|SOUTH>- This item's source site is North or South.
>> SRCPATH=<str>    - Full path of source
>> DSTPATH=<str>    - Full path of destination
>> SERR_<int>=<str> - Source errors, incrementing, and the reason string
>> DERR_<int>=<str> - Destination errors, incrementing, and the reason string
>> BEGIN            - First item sent,  start of list.
>> END              - Final item was sent, end of list.
 
[ Example ]
>> QERR|QID=1|BEGIN|ITEMS=1
<< QERR|QID=1|QTYPE=FILE|SRC=NORTH|SRCPATH=/Giana_Sisters_GBA//gfx_blocks.txt|DSTPATH=/tmp/tmp//gfx_blocks.txt|DERR_0=553 gfx_blocks.txt: Can't open for writing
<< QERR|QID=1|END
 
=== QDEL ===
 
Delete an item in the queue. If a client wishes to delete multiple
items, it is advised that the client pre-sorts the items list, and
send it with highest queue position first, in descending order. It is
an error to attempt to delete queue item at first position (@=0) if
the queue is active.
 
Please be aware that since deleting a queue item early in the list,
will affect queue items in a later position. That is to say, if you
intend to delete items 1,4,8 from the queue, and you issue 3 QDEL
commands "blindly" in the same order (1,4,8), the net effect will be
that queue items 1,5,10 are actually deleted. When queue item 1 is
deleted, item at position 4 is now 3, and item 5 is at position 4.
 
Either the clients need to be aware of the re-numbering and compensate
for later commands,
OR,
much easier is to sort the list in descending order before issuing the
QDEL commands. Ie, send QDEL commands in the order 8,4,1.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
>> @=<int>          - Queue position of item to delete.
 
[ Optional Arguments ]
 
[ Returns ]
>> QID=<int>        - Queue ID
>> CODE=<int>      - Command return status CODE.
>> ITEMS=<int>      - Number of items in the queue
>> MSG=<str>        - Command return message.
>> @=<int>          - Position in the queue of item.
 
[ Example ]
>> qdel|qid=1|@=53
<< QDEL|QID=1|CODE=0|@=53|ITEMS=0
 
=== QMOVE ===
 
Move an item in the queue from one position to a new position. It is
an error to move a queue item from, or to, the first position (@=0)
when a queue is active.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
>> FROM=<int>      - Queue position of item to move
>> TO=<str|int>    - New position, either <int> Nth place, or string
                      placement like in QADD. ("FIRST"/"LAST")
 
[ Optional Arguments ]
 
[ Returns ]
>> QID=<int>        - Queue ID
>> CODE=<int>      - Command return status CODE.
>> ITEMS=<int>      - Number of items in the queue
>> MSG=<str>        - Command return message.
>> @=<int>          - Position where item was inserted.
>> FROM=<int>      - Position where item was originally from.
 
[ Example ]
>> qmove|qid=1|from=0|to=last
<< QMOVE|QID=1|@=23|FROM=0|CODE=0|ITEMS=3|MSG=Moved
 
=== QGRAB ===
 
QGRAB lets a client take control of an idle queue, and the queue's
sessions, if any. This is currently the only way to gain access to
sessions given away with the "GO" command. If the queue had any
connected sessions, the client should receive appropriate CONNECT
messages.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue id in question
 
[ Optional Arguments ]
 
[ Returns ]
>> QID=<int>        - Queue id
>> ITEMS=<int>      - Current number of items in queue
>> NORTH_SID=<int>  - Session ID of North site, if connected.
>> SOUTH_SID=<int>  - Session ID of South site, if connected.
>> NORTH_SITEID=int - Site ID of North site, for future SESSIONNEW
>> SOUTH_SITEID=int - Site ID of South site, for future SESSIONNEW
>> NORTH_NAME=<str> - Site name of North site
>> SOUTH_NAME=<str> - Site name of South site
>> CODE=<int>      - Command return status CODE.
 
As well as potential async commands.
 
[ Example ]
 
>> qgrab|qid=1
<< CONNECT|SID=34
<< IDLE|SID=34
<< CONNECT|SID=35
<< IDLE|SID=35
<< QGRAB|QID=1|CODE=0|ITEMS=0|NORTH_SID=34|SOUTH_SID=35|NORTH_SITEID=0|SOUTH_SITEID=4|NORTH_NAME=localhost|SOUTH_NAME=distro_site
 
=== QCOMPARE ===
 
Compare the two directories in the session cache against each other,
sending back list of FIDs that would be queued by FXP.One. This gives
GUIs an easy way to show which items would be queued, and processed in
a given set of directories. The compare function uses all the logic,
including skiplists, passlists, movefirst and skipempty. It compares
file sizes to ignore those of the same size, but highlights the side
with the smaller size should they differ.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
 
[ Optional Arguments ]
 
[ Returns ]
>> QID=<int>        - Queue ID
>> NORTH_FID=<int,> - Comma separated list of FIDs for the NORTH site.
>> SOUTH_FID=<int,> - Comma separated list of FIDs for the NORTH site.
>> BEGIN            - First item sent,  start of list.
>> END              - Final item was sent, end of list.
 
[ Example ]
>> qcompare|qid=1
<< QCOMPARE|QID=1|BEGIN
<< QCOMPARE|QID=1|NORTH_FID=1,3,4,5,6,7,8,10,13,15,16,17,18,19,21,22,23,24,25,26,28,29,31,33,35,36,37,38
,39,40,41,42,43,44,45,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,69,70,71,72,73,
74,75,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,99,100,101,102,103,104,105,
107,108,109,110,111,112,113,115,116,117,118
<< QCOMPARE|QID=1|NORTH_FID=119,120,121,122,123,124,125,126,127,128,129,130,132,133,134,135,136,137,
138,139,140,141,142,144,145,146,147,148,149
<< QCOMPARE|QID=1|SOUTH_FID=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,20,21,22,23,24,25,26,27,28,
29,30,31,32,34,35,36,37,38,39,40,41,42,43,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,
64,65,66,67,68,69,70,71,72,73,74,75,77,78,79,80,81,82,84,85,87,88,89,90,91,92,93,95,96,97,98,99,100,
101,102,104,105,106,107,109
<< QCOMPARE|QID=1|SOUTH_FID=110,113,114,115
<< QCOMPARE|QID=1|END|MSG=Completed comparison.
 
=== QUEUEFREE ===
 
Release an existing queue, release its sessions, and queue items.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
 
[ Optional Arguments ]
 
[ Returns ]
>> QID=<int>        - Queue ID
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>        - Command return message.
 
[ Example ]
>> QUEUEFREE|QID=1
<< QUEUEFREE|CODE=0|QID=1|Msg=Queue released.
 
=== GO ===
 
Issue "GO" to a queue. Request FXP.One engine to start processing the
queue and its items. The client loses ownership of the two SIDS at the
issue of the "GO" command.  You may no longer issue commands directory
to the SIDs. Once a queue is idle, either from the QC|EMPTY message,
or after issuing the STOP command, the client can issue the "QGRAB"
command to receive controls of the SIDs, if still existing.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
 
[ Optional Arguments ]
>> SUBSCRIBE        - Subscribe to queue status (QS) and queue changes (QC) 
 
[ Returns ]
>> QID=<int>        - Queue ID
>> CODE=<int>      - Command return status CODE if failed.
>> MSG=<str>        - Command return message.
 
[ Example ]
>> GO|QID=1
<< GO|QID=1|CODE=0|MSG=Queue processing started.
 
 
=== STOP ===
 
Issue "STOP" to a queue. Request FXP.One engine to attempt to stop processing the
queue and its items. There are currently three types on STOP levels, the default is
"SOFT", which will stop once the current transfer is complete. "HARD" which will attempt to send the FTP command 'ABOR' to both FTPDs to gracefully interrupt the current transfer. (local client might need ABOR support added) Finally, the "DROP" method which will log out of both FTPDs and hence forcing the transfer to stop. Once the queue processing has stopped, the FXP.One engine will issue a "QC|IDLE" command, after which the client can issue QGRAB.
 
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
 
[ Optional Arguments ]
>> HARD            - Send FTP 'ABOR' to FTP daemons
>> DROP            - Drop connections to FTP daemons to cancel transfers. 
 
[ Returns ]
>> QID=<int>        - Queue ID
>> CODE=<int>      - Command return status CODE if failed.
>> MSG=<str>        - Command return message.
 
[ Example ]
>> STOP|QID=1
<< STOP|QID=1|CODE=0|MSG=Stop initiated, please wait..
<< QC|QID=1|IDLE|MSG=Stop command successful.
 
=== QC ===
 
This is a receive-only command, sent by the FXP.One engine when there
is a Queue-Change. It is only sent if the client requested to
SUBSCRIBE to a queue, either using the "GO" command, or the "QGET"
 
[ Minimal Required Fields]
 
[ Optional Arguments ]
 
[ Returns ]
>> MOVE            - Item has moved to a new position. Comes with
                      FROM= and TO= keys.
>> REMOVE          - Remove items from queue. All items with higher
                      position are decremented by one. Uses @.
>> INSERT          - New item inserted into queue. Uses @, SRCPATH,
  DSTPATH, QTYPE, SRCSIZE.
>> EMPTY            - Empty queue, processing stops.
>> IDLE            - Queue moved into IDLE state, either from QTYPE=STOP or
                      in response to a STOP command.
 
[ Example ]
<< QC|QID=1|REMOVE|@=0
<< QC|QID=1|MOVE|FROM=0|TO=18
<< QC|QID=1|INSERT|@=0|SRCPATH=/testfile.dat|DSTPATH=/tmp/testing.bin|QTYPE=FILE|SRCSIZE=29734
 
=== QS ===
 
This is a receive-only command, sent by the FXP.One engine when there
is Queue-Status information to relay. Client can safely ignore this
command as it does not reflect on any queue changes. It is merely
meant as a way for clients to be able to track progress of a queue
being processed. It is only sent if the client requested to
SUBSCRIBE to a queue, either using the "GO" command, or the "QGET"
(Not yet implemented).
All QS messages are related to the item at the top of the queue. So
"@=0" is implied.
 
[ Minimal Required Fields]
 
[ Optional Arguments ]
 
[ Returns ]
>> START            - Started processing the item at the top of queue.
      SRCPATH=<str>  - Included for human readability.
>> SRCCWD=<str>    - Changed to new directory on source
>> DSTCWD=<str>    - Changed to new directory on destination
>> MKD=<str>        - Created new directory on destination
>> XFRACT          - File transfer has started (received 150)
      SECURE=<yes/no>- Was Secure Data negotiations successful.
      REST=<int>    - Are we resuming this file
      SIZE=<int>    - Final source size (from SIZE command)
>> XFREND          - File transfer finished (successfully, 226).
      TIME=<int>    - Duration of transfer [1]
      KB/s=<int>    - Estimated speed of transfer [1]
>> FAILED          - Attempted transfer failed
      SERR=<str>    - Error reasons (source failed)
      DERR=<str>    - Error reasons (destination failed)
      COUNT=<int>    - This failure count.
 
[1] Please be aware that we can only measure the time difference
between the 150 FTP message, and the 226 FTP message as received by
FXP.One. This may not reflect the actual time taken for the transfer,
subsequently the KB/s computation is based on said time, and will most
likely only be an estimate. The shorter the duration of a file
transfer is, the more inaccurate the speed computation will be.
 
[ Example ]
<< QS|QID=1|MSG=Processing directory|SRCPATH=/Giana_Sisters_GBA//giana_sounds|DSTPATH=/tmp/tmp//giana_sounds
<< QS|QID=1|SRCCWD=/Giana_Sisters_GBA/
<< QS|QID=1|START|@=0|SRCPATH=/Giana_Sisters_GBA//giana_sounds/might_be_game_sounds.pcm
<< QS|QID=1|SRCCWD=/Giana_Sisters_GBA/giana_sounds/
<< QS|QID=1|DSTMKD=/tmp/tmp//giana_sounds
<< QS|QID=1|MSG=Transfer started|SECURE=YES|REST=0|SIZE=29734
<< QS|QID=1|MSG=Transfer complete|TIME=0.00|KB/s=0.00
 
[ Log of a complete session ]
>> GO|QID=1|SUBSCRIBE
<< QS|QID=1|MSG=Processing directory|SRCPATH=/Giana_Sisters_GBA//giana_sounds|DSTPATH=/tmp/tmp//giana_sounds
<< QS|QID=1|SRCCWD=/Giana_Sisters_GBA/
<< QC|QID=1|REMOVE|@=0
<< QC|QID=1|INSERT|@=0|SRCPATH=/Giana_Sisters_GBA/giana_sounds//might_be_game_sounds.pcm|DSTPATH=/tmp/tmp//giana_sounds/might_be_game_sounds.pcm|QTYPE=FILE|SRCSIZE=29734
<< QS|QID=1|START|@=0|SRCNAME=might_be_game_sounds.pcm
<< QS|QID=1|SRCCWD=/Giana_Sisters_GBA/giana_sounds/
<< QS|QID=1|MKD=/tmp/tmp//giana_sounds
<< QS|QID=1|MSG=Transfer started|SECURE=YES|REST=0|SIZE=29734
<< QS|QID=1|MSG=Transfer complete|TIME=0.00|KB/s=0.00
<< QC|QID=1|REMOVE|@=0
 
=== SUBSCRIBE ===
 
Request to receive the QS and QC commands from a processing queue. A
client may subscribe to as many queues as it wants, including those
not started by itself.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
 
[ Optional Arguments ]
>> TOGGLE          - If already subscribed, issue un-subscribe instead.
 
[ Returns ]
>> QID=<int>        - Queue ID
>> MSG=<str>        - Command return message.
>> UNSUBSCRIBED    - If issued TOGGLE the result was to be un-subscribed.
 
[ Example ]
>> SUBSCRIBE|QID=1|TOGGLE
<< SUBSCRIBE|QID=1|CODE=0|MSG=Subscribed
 
=== UNSUBSCRIBE ===
 
Stop being subscribed to a queue.
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
 
[ Optional Arguments ]
 
[ Returns ]
>> QID=<int>        - Queue ID
>> MSG=<str>        - Command return message.
 
[ Example ]
>> UNSUBSCRIBE|QID=1
<< UNSUBSCRIBE|QID=1|CODE=0|MSG=Unsubscribed
 
 
=== QCLONE (v1.7) ===
 
Take a created queue (idle or active) and make an exact copy of the queue. If source queue is active, connect both sides and start processing. Some clients refer to this as "add another thread".
 
[ Minimal Required Fields]
>> QID=<int>        - Queue ID
 
[ Optional Arguments ]
>> START=<yna>      - Start processing (Y), do not start processing (N), or copy source (A). Default is (A).
>> SUBSCRIBE        - Also subscribe to queue processing notices.
 
[ Returns ]
>> QID=<int>        - Source Queue ID, same as given.
>> NEWQID=<int>        - Newly created clone Queue ID
>> MSG=<str>        - Command return message.
 
[ Example ]
>> QCLONE|QID=123
<< QCLONE|QID=123|NEWQID=124|CODE=0|MSG=Queue 124 processing started.
 
In reality, it is a little more verbose, here is an actual example:
>> QCLONE|QID=1
<< SESSIONNEW|SITEID=15|CODE=0|SID=3
<< SESSIONNEW|SITEID=16|CODE=0|SID=4
<< QUEUENEW|CODE=0|QID=2|NORTH_SID=3|SOUTH_SID=4|MSG=Queue created.
<< QCLONE|CODE=0|QID=1|NEW_QID=2|Msg=Cloned and created queue
<< CONNECT|SID=3|SSL
<< IDLE|SID=3
<< CONNECT|SID=4|SSL
<< IDLE|SID=4
<< GO|QID=2|CODE=0|MSG=Queue processing started.
 
== ADMINISTRATIVE COMMANDS ==
 
=== QUIT ===
 
Disconnect from the FXP.One engine. The client can also just close the connection without worry.
 
[ Minimal Required Fields]
 
[ Optional Arguments ]
 
[ Returns ]
>> Will disconnect on you, how rude.
 
[ Example ]
>> QUIT
<< Connection closed by remote host.
 
=== HELP ===
 
Display available commands at this privilege level.
 
[ Minimal Required Fields]
 
[ Optional Arguments ]
 
[ Returns ]
>> MSG=<str>        - Command return message.
>> CODE=<int>      - Command return status CODE.
 
[ Example ]
>> HELP
<< HELP|CODE=0|Msg= QUIT HELP WHO SHUTDOWN SITEADD SITELIST SITEMOD SITEDEL SESSIONNEW SESSIONFREE
        DIRLIST QUEUENEW QADD QLIST QGET QERR QGRAB QDEL QMOVE QCOMPARE QUEUEFREE GO STOP CWD PWD
        SIZE DELE MKD RMD SITE REN MDTM QUOTE SUBSCRIBE UNSUBSCRIBE.
 
=== WHO ===
 
Display a list of users connected to this FXP.One engine.
 
[ Minimal Required Fields]
 
[ Optional Arguments ]
 
[ Returns ]
>> NAME=<str>      - User name of login session
>> HOST=<ip>        - IP address of login session
>> PORT=<port>      - Remote port number
>> SSL=<yes|no>    - Is connection encrypted
>> CLIENTS=<int>    - Number of items in the queue
>> BEGIN            - First item sent,  start of list.
>> END              - Final item was sent, end of list.
 
[ Example ]
>> WHO
<< WHO|BEGIN|CLIENTS=3
<< WHO|NAME=admin|HOST=127.0.0.1|PORT=58597|SSL=yes
<< WHO|NAME=admin|HOST=220.150.239.57|PORT=1135|SSL=yes
<< WHO|NAME=admin|HOST=127.0.0.1|PORT=58540|SSL=no
<< WHO|END|Msg=Command Completed.
 
=== SETPASS ===
 
Change the login password on the FXP.One engine. This is strongly encouraged.
 
[ Minimal Required Fields]
>> OLD=<str>        - Old/current password of this login session.
>> NEW=<str>        - New/future password for this login session.
 
[ Optional Arguments ]
 
[ Returns ]
>> MSG=<str>        - Command return message.
>> CODE=<int>      - Command return status CODE.
 
[ Example ]
>> SETPASS|OLD=admin|NEW=newpass
<< SETPASS|CODE=0|MSG=New password has been set.
<< SETPASS|CODE=1502|MSG=Login incorrect
 
=== SHUTDOWN ===
 
Shutdown the FXP.One engine have it completely exit.
 
[ Minimal Required Fields]
 
[ Optional Arguments ]
>> LASTCLIENT      - Only shutdown if THIS client is the last one.
 
[ Returns ]
>> Might disconnect on you, how rude.
 
[ Example ]
>> SHUTDOWN
<< SHUTDOWN|CODE=0
<< Connection closed by remote host.

Latest revision as of 05:34, 24 February 2018

Documentation for FXP.One API commands and protocol. This documentation file is maintained at http://www.lundman.net/wiki/index.php?title=Protocol and exported to other formats. This documentation is purposly maintained rigorously as to aid all client developers of FXP.One.


Connecting

WELCOME

When you connect to the FXP.One server, you should receive a greeting string, similar to: 

>> WELCOME|name=FXP.Oned|version=0.1|build=18|SSL=optional

Pay special attention to the SSL flag here, since if it is enforced, and you attempt plain text authentication (which will fail) you are exposing the user and password.

The "version" is the server version and build The "protocol" is the protocol version, which you can check to be of the same Major type as your application knows.

The "SSL" field can be "disabled", "optional", and "forced".


SSL

Initiate SSL challenge. This is sent by clients requesting the remainder of the session to be in SSL. This requires that FXP.One engine's WELCOME message is either "forced" or "optional". 


[ Minimal Required Fields]

[ Optional Arguments ]

[ Returns ]

>> CODE=<int>       - Command return status CODE.
>> OK               - Initiation request accepted, start SSL phase.
>> MSG              - Human-readable message string

[ Example ]

<< SSL   
>> SSL|CODE=0|Msg=Attempting SSL negotiations.


AUTH

Send USER and PASS for authentication. This requires a valid user and password pair already registered on FXP.One. If FXP.One was started with no user database files, it will create one with the account user "admin" and password "admin". 


[ Minimal Required Fields]

>> USER=<str>       - USER name
>> PASS=<str>       - PASSWORD

[ Optional Arguments ]

[ Returns ]

>> CODE=<int>       - Failure code.
>> MSG=<str>        - Human readable string message.

[ Example ]

<< AUTH|USER=admin|PASS=admin
>> AUTH|CODE=0|MSG=Successful

>> AUTH|CODE=502|MSG=Login incorrect

>> AUTH|CODE=503|MSG=Secure channel enforced.


SITES

For SITE structure definition, see Site_Definition http://www.lundman.net/wiki/index.php/Site_Definition

SITEADD

Add a new site to the system. 

[ Minimal required fields ]

>> NAME=<str>      - Name of site. Not used by engine, need not be unique.  
>> HOST=<str>      - Hostname of remote FTP server
>> USER=<str>      - User name for authentication on remote FTP server
>> PASS=<str>      - and password

[ Optional Arguments ]

>> PORT=<int>      - Optional PORT of remote FTP server. Default 21.
>> PASSIVE=<yna>   - Use passive for directory listings? [See YNA type]
>> FXP_PASSIVE=yna - Can this remote FTP only take PASV, or PORT? 
>> CONTROL_TLS=yna - Attempt SSL/TLS on Control channel?
>> DATA_TLS=<yna>  - Attempt SSL/TLS on Data channel? Site needs CCSN feat
>> IFACE=<ip>      - Optional IP to bind() to.
>> IPORT=<int>     - Optional PORT to bind() to.
>> DESIRED_TYPE=yna- Binary or Ascii mode transfers. [See YNA type]
                   - AUTO and engine will set Binary for transfers.
>> RESUME=<yna>    - Attempt to Resume before Overwrite. 
>> RESUME_LAST=yna - Re-queue items needed resume last in the queue.
>> PRET=<yna>      - Send the extended Pre-Transfer command before transfer[1]
>> FSKIPLIST=<str> - File skip list [2]
>> DSKIPLIST=<str> - Directory skip list [2]
>> FPASSLIST=<str> - File pass list [3]
>> DPASSLIST=<str> - Directory pass list [3]
>> FSKIPEMPTY=<yna>- Skip empty files
>> DSKIPEMPTY=<yna>- Skip empty directories
>> FMOVEFIRST=<str>- Pattern file matches to force queue at top
>> DMOVEFIRST=<str>- Pattern directory matches to force queue at top

[1] AUTO means it will use this feature if it is reported by the remote FTPD in the FEAT/features command reply.

[2] Uses fnmatch(3) syntax pattern matching. Most file globbal you can do on the command line, including "*?[]", but excluding "{}". String consists of slash separated patterns. eg "*.dat/*readme.txt*".

All skiplists, passlists and movefirst are processed on the DESTINATION site.

[3] Opposite to skiplist. The default is for passlist to be empty, which is the equivalent of "*". A syntax like "*ENGLISH*" would ensure only entries which matched string would be queued, and others are dropped. Uses same pattern syntax as skiplist. 

[ Extended Optional Arguments ]

As a special feature to the clients connecting to the FXP.One engine,
we also allow for storing of own, arbitrary, key/value pairs. As long
as the "key" is not the same as any of the above keys, or that of the
predefined reserved keys. (eg. "TYPE", "END")

>> <str>=<str>     - Store extra client information.

For example: 

"...|extrafield=somestuff|OS=Unix"

[ Returns ]

>> SITEID=<int>     - Site ID of created site.
>> CODE=<int>       - Command return status CODE.
>> MSG=<str>        - Command return message.

[ Example ]

>> SITEADD|NAME=local|host=localhost|port=56688|user=mp3|pass=mp3|passive=1|fxp_passive=2|control_TLS=2|data_TLS=2|extrafield=somestuff|OS=Unix
<< SITEADD|CODE=0|SITEID=12|Msg=Added successfully.

[ Caveat ]

It is recommended that all clients that wish to store information
in the site database, to prefix their key values with a unique string,
perhaps the name of the application. For example:

lundfxp_sitecmd_1=SITE WHO
lundfxp_lastlogin=015368281

SITELIST

Lists all defined sites. 

[ Minimal Required Fields]


[ Optional Arguments ]
>> SHORT           - Send only short list (siteid + name)
>> SITEID=<int>    - Send only specified siteid. Sends no BEGIN/END keys.

[ Returns ]

>> SITEID=<int>    - Site ID being displayed.
>> NAME=<str>      - Name of site. Not used by engine, need not be unique.  
>> HOST=<str>      - Hostname of remote FTP server
>> USER=<str>      - User name for authentication on remote FTP server
>> PASS=<str>      - and password
>> PORT=<int>      - Optional PORT of remote FTP server. [1]
>> PASSIVE=<yna>   - Use passive for directory listings? [See YNA type]
>> FXP_PASSIVE=yna - Can this remote FTP only take PASV, or PORT? 
>> CONTROL_TLS=yna - Attempt SSL/TLS on Control channel?
>> DATA_TLS=<yna>  - Attempt SSL/TLS on Data channel? Site needs CCSN feat
>> IFACE=<ip>      - Optional IP to bind() to. [1]
>> IPORT=<int>     - Optional PORT to bind() to. [1]
>> DESIRED_TYPE=yna- Binary or Ascii mode transfers. [1]
>> RESUME=<yna>    - Attempt to Resume before Overwrite. [1]
>> RESUME_LAST=yna - Re-queue items needed resume last in the queue. [1]
>> PRET=<yna>      - Send the extended Pre-Transfer command before transfer[1]
>> FSKIPLIST=<str> - File skip list [1]
>> DSKIPLIST=<str> - Directory skip list [1]
>> FPASSLIST=<str> - File pass list [1]
>> DPASSLIST=<str> - Directory pass list [1]
>> FSKIPEMPTY=<yna>- Skip empty files [1]
>> DSKIPEMPTY=<yna>- Skip empty directories [1]
>> FMOVEFIRST=<str>- Pattern file matches to force queue at top [1]
>> DMOVEFIRST=<str>- Pattern directory matches to force queue at top [1]
>> BEGIN           - First item sent,   start of list.
>> END             - Final item was sent, end of list.

[1] This information is only sent if the current value differs from the default "AUTO" type. Or, in the case of strings, where the string is defined (not-empty). 

[ Example ]

<< SITELIST|BEGIN
>> SITELIST|SITEID=2|NAME=localhost|HOST=127.0.0.1|PORT=21|USER=mp3|PASS=mp3|PASSIVE=1|FXP_PASSIVE=2|CONTROL_TLS=2|DATA_TLS=2|optional_variable=roger moore
>> SITELIST|SITEID=1|NAME=localhost2|HOST=127.0.0.1|PORT=56688|USER=mp3|PASS=mp3|PASSIVE=1|FXP_PASSIVE=2|CONTROL_TLS=2|DATA_TLS=2
>> SITELIST|END

<< SITELIST|SHORT
>> SITELIST|BEGIN
>> SITELIST|SITEID=1|NAME=localhost
>> SITELIST|END

<< SITELIST|SITEID=2
>> SITELIST|SITEID=2|NAME=localhost|HOST=127.0.0.1|PORT=21|USER=mp3|PASS=mp3|PASSIVE=1|FXP_PASSIVE=2|CONTROL_TLS=2|DATA_TLS=2|optional_variable=roger moore

SITEMOD

Modify an existing site's key/value pairs. Specify as many items as desired to be changed. Items not specified in the command are left as they are. To delete a key/pair, send the key with an empty value field. For example "key=". 

[ Minimal required fields ]

>> SITEID=<int>    - Site ID of created site.

[ Optional Arguments ]

>> NAME=<str>      - Name of site. Not used by engine, need not be unique.  
>> HOST=<str>      - Hostname of remote FTP server
>> USER=<str>      - User name for authentication on remote FTP server
>> PASS=<str>      - and password
>> PORT=<int>      - Optional PORT of remote FTP server. Default 21.
>> IFACE=<ip>      - Optional IP to bind() to.
>> IPORT=<int>     - Optional PORT to bind() to.
>> DESIRED_TYPE=yna- Binary or Ascii mode transfers. [See YNA type]
                   - AUTO and engine will set Binary for transfers.
>> RESUME=<yna>    - Attempt to Resume before Overwrite. 
>> RESUME_LAST=yna - Re-queue items needed resume last in the queue.
>> PRET=<yna>      - Send the extended Pre-Transfer command before transfer[1]
>> FSKIPLIST=<str> - File skip list [2]
>> DSKIPLIST=<str> - Directory skip list [2]
>> FPASSLIST=<str> - File pass list [3]
>> DPASSLIST=<str> - Directory pass list [3]
>> FSKIPEMPTY=<yna>- Skip empty files
>> DSKIPEMPTY=<yna>- Skip empty directories
>> FMOVEFIRST=<str>- Pattern file matches to force queue at top
>> DMOVEFIRST=<str>- Pattern directory matches to force queue at top

[1] AUTO means it will use this feature if it is reported by the remote FTPD in the FEAT/features command reply.

[2] Uses fnmatch(3) syntax pattern matching. Most file globbal you can do on the command line, including "*?[]", but excluding "{}". String consists of slash separated patterns. eg "*.dat/*readme.txt*".

[3] Opposite to skiplist. The default is for passlist to be empty, which is the equivalent of "*". A syntax like "*ENGLISH*" would ensure only entries which matched string would be queued, and others are dropped. Uses same pattern syntax as skiplist. 

[ Extended Optional Arguments ]

As a special feature to the clients connecting to the FXP.One engine,
we also allow for storing of own, arbitrary, key/value pairs. As long
as the "key" is not the same as any of the above keys, or that of the
predefined reserved keys. (eg. "TYPE", "END")

>> <str>=<str>     - Store extra client information.

For example:

"...|extrafield=somestuff|OS=Unix"

[ Returns ]

>> SITEID=<int>    - Site ID of created site.
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>       - Command return message.

[ Example ]

>> SITEMOD|SITEID=1|fskiplist=*ENGLISH*,*COMPLETE*|fskipempty=YES
<< SITEMOD|CODE=0|SITEID=1|Msg=Modified successfully.

[ Caveat ]

It is recommended that all clients that wish to store information
in the site database, to prefix their key values with a unique string,
perhaps the name of the application. For example:

lundfxp_sitecmd_1=SITE WHO
lundfxp_lastlogin=015368281

SITEDEL

Delete an existing site. 

[ Minimal required fields ]

>> SITEID=<int>    - Site ID of created site.

[ Optional Arguments ]

[ Extended Optional Arguments ]

[ Returns ]

>> SITEID=<int>    - Site ID of created site.
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>       - Command return message.

[ Example ]

>> SITEDEL|SITEID=12
<< SITEDEL|CODE=0|MSG=Site deleted.

[ Caveat ]

Sites aren't actually deleted, just not saved to disk. This means
active sessions using said siteid created before the SITEDEL command
was issued will continue to work.


SESSIONS

A session refer to a site connection. The API will ask for a new session to a specific site (specified with SITEID) and a session will be created. If the connection is lost or closed, _the session is closed_. The API will have to request a new session if so desired.

SESSIONNEW

Request a new session to site, returning a SID to session. 

[ Minimal Required Fields]

>> SITEID=<int>    - Which remote server to connect to, from SITELIST.

[ Optional Arguments ]

>> LOG=1             - Normal login is silent. With LOG the API received
                     all verbose messages.

[ Returns ]

>> SID=<int>       - Value of the new SID for all future commands with
                    sessions
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>       - Command return message.

[ Example ]

>> sessionnew|siteid=0
<< SESSIONNEW|SITEID=0|SID=1
<< IDLE|SID=1

SESSIONFREE

Release a session, and disconnect from remote host. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session to close.

[ Optional Arguments ]

[ Returns ]

>> SID=<int>         - SID of the session closed.
>> CODE=<int>        - Command return status CODE.
>> MSG=<str>         - Command return message.

[ Example ]

>> SESSIONFREE|SID=1
<< SESSIONFREE|CODE=0|SID=1|MSG=Success

ASYNC

Is not a command but client need to be aware that there are messages that come in at any time. 

<< CONNECT|SID=1

Send once a session has successfully logged in and is ready to answer
queries. Initially it was thought that IDLE would be enough, but
clients will generally want to auto-trigger some commands upon
connection establish, so we provide this event.

<< IDLE|SID=1        

Site is idle, ready for more commands. Informative only as you can
always issue commands, they will be queued.

<< DISCONNECT|SID=1|CODE=429|MSG=Undefined error: 0

The session was disconnected. Any further references to the SID (in
this case "1") will result in an error. 

<< LOG|SID=1|MSG=

You can request a SESSIONNEW to be logged (LOG), or, most of the
commands take an option "LOG" to specify that logging is desired
during the execution of said command. This means the engine will
forward all messages from the remote FTPD to the client. For example:

>> CWD|SID=2|path=/requests
<< CWD|SID=2|CODE=0|MSG=250 CWD command successful.

>> CWD|SID=2|path=requests|LOG
<< CWD|SID=2|CODE=-1|MSG=250-REQUESTS ADMIN: roger
<< CWD|SID=2|CODE=-1|MSG=250- 
<< CWD|SID=2|CODE=-1|MSG=250-RULES: Please use format of REQ- and FILLED-  
<< CWD|SID=2|CODE=-1|MSG=250-       and please do not dump single files into  
<< CWD|SID=2|CODE=-1|MSG=250-     root as it just make the folder look untidy!
<< CWD|SID=2|CODE=-1|MSG=250-Available space: 14676.22 MB.
<< CWD|SID=2|CODE=0|MSG=250 CWD command successful.


FTP COMMANDS

DIRLIST

Request a directory listing from remote server/session. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session

[ Optional Arguments ]

// Optional: PATH, ARGS, RAW, CACHEOK, LOG
>> PATH=<str>        - Additional path element [1]
>> ARGS=<str>        - Additional list options [2]
>> RAW=<int>         - Include entire list line in FID reply.(unparsed)
>> CACHEOK           - If cache is populated, avoid remote server
>> LOG               - Send all strings with dirlist, like SESSIONNEW

[1] Warning. It is not recommended that you use this to supply different paths as the internal cache engine will get mighty confused. [2] Some "ls"/LIST options will break the internal parser. For example, "-1" would remove the long listing style. 

[ Returns ] 

>> SID=<int>         - SID the dirlist reply is from.
>> FID=<int>         - File ID of this item. For QADD.
>> NAME=<str>        - Name of Directory OR File 
>> DATE=
[ Example ]

>> dirlist|sid=1
<< DIRLIST|SID=1|BEGIN|items=2
<<  DIRLIST|SID=1|FID=0|NAME=giana_sounds|DATE=1057590000|SIZE=512|USER=nobody|GROUP=nobody|PERM=drwxrwxrwx|type=directory
<< DIRLIST|SID=1|FID=1|NAME=debug_main.gba|DATE=1057590000|SIZE=417520|USER=nobody|GROUP=nobody|PERM=-rwxr-xr-x|type=file
<< DIRLIST|SID=1|END
<< IDLE|SID=1

>> dirlist|sid=1|RAW
<< DIRLIST|SID=1|BEGIN|items=1
<< DIRLIST|SID=1|FID=0|NAME=giana_sounds|DATE=1057590000|SIZE=512|USER=nobody|GROUP=nobody|PERM=drwxrwxrwx|type=directory|RAW=drwxrwxrwx++1+nobody++nobody+++++512+Jul++8++2003+giana_sounds
<< DIRLIST|SID=1|END
<< IDLE|SID=1

QUOTE

Send RAW FTP commands to the remote server without FXP.One's involvement. Typically used for SITE commands. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session
>> MSG=<str>        - RAW Command to execute.

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE. (If FTP reply < 300) code=0
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[ Example ]

>> QUOTE|SID=1|MSG=SITE uptime
<< QUOTE|SID=1|CODE=0|MSG=200 Uptime: 2d, 1h, 52m, 50s.
<< IDLE|SID=1

>> QUOTE|SID=1|LOG|MSG=SITE WHO
<< QUOTE|SID=1|CODE=-1|OK|MSG=200- [ WHO ]
<< QUOTE|SID=1|CODE=-1|OK|MSG=Total users online:   1              Total active data:   0     
<< QUOTE|SID=1|CODE=0|MSG=200 WHO command successful.

CWD

Change the Current Working Directory of the remote server. ie. "cd files/" 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session
>> PATH=<str>       - New desired directory. or:
>> FID=<int>        - or: FID of directory.

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[ Example ]

>> CWD|SID=1|PATH=Giana_Sisters_GBA
<< CWD|SID=1|CODE=0|MSG=250 CWD command successful.

PWD

Return the Current Working Directory path. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE.
>> PATH=<str>       - The parsed current PATH.    [1]
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[1] Warning, PATH is only returned if FXP.One successfully managed to parse out the path from the reply. Some FTPD send non-standard replies. If you find one of these, send me an example output string and I can fix the parser. 

[ Example ]

>> PWD|SID=1
<< PWD|SID=1|CODE=0|PATH=/Giana_Sisters_GBA/|MSG=257 "/Giana_Sisters_GBA/" is current directory.

SIZE

Return the size of a file on the remote server. Not this will give errors on directories on most FTPDs. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session
>> PATH=<str>       - Name of File.  or:
>> FID=<int>        - or: FID of file.

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE.
>> SIZE=<int>       - The size of the file.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[ Example ]

>> SIZE|SID=1|PATH=giana2k.xm.zip
<< SIZE|SID=1|CODE=0|SIZE=287688|MSG=213 287688

DELE

Delete a single file on the remote server. You can either issue by name (relative path, or absolute path), or optionally use FID as returned by DIRLIST. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session
>> PATH=<str>       - Name of File.  or:
>> FID=<int>        - or: FID of file.

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[ Example ]

>> DELE|SID=1|PATH=delete_this.bin
<< DELE|SID=1|CODE=0|MSG=213 DELE command successful.

MKD

Create a new directory on the remote server. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session
>> PATH=<str>       - Name of Directory.

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[ Example ]

>> MKD|SID=1|PATH=New Folder
<< MKD|SID=1|CODE=0|MSG=213 MKD command successful.

RMD

Delete a single directory on the remote server. You can either issue by name (relative path, or absolute path), or optionally use FID as returned by DIRLIST. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session
>> PATH=<str>       - Name of Directory.  or:
>> FID=<int>        - or: FID of directory.

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[ Example ]

>> RMD|SID=1|PATH=delete_this_dir
<< RMD|SID=1|CODE=0|MSG=213 RMD command successful.

SITE

Send a SITE command to the remote server. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session
>> CMD=<str>        - Command and arguments to send.

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[ Example ]

>> SITE|SID=1|CMD=WHO
<< SITE|SID=1|CODE=0|MSG=200 Command Successful.

REN

Rename a file or directory. Supply the originating name by either passing FROM or a valid FID, as well as the resulting TO name. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session
>> FROM=<str>       - Source name. or:
>> FID=<int>        - or: FID of entry.
>> TO=<str>         - Destination name.

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[ Example ]

>> REN|SID=1|FROM=oldfilename.bin|TO=newfilename.bin
<< REN|SID=1|CODE=0|MSG=250 RNTO command successful.

MDTM

Return the date and time of a file. (But not directories, according to FTP RFC). The return data is in the format of yyyyMMddHHmmSS. For example, "213 19970205115719". You can either issue by name (relative path, or absolute path), or optionally use FID as returned by DIRLIST. 

[ Minimal Required Fields]

>> SID=<int>        - SID of the session
>> PATH=<str>       - Name of Directory.  or:
>> FID=<int>        - or: FID of directory.

[ Optional Arguments ]

>> LOG              - Send all strings with command, like SESSIONNEW

[ Returns ]

>> SID=<int>        - SID of the session
>> CODE=<int>       - Command return status CODE.
>> MSG=<str>        - Command return message. (Only final message
                      unless you issue LOG)

[ Example ]

>> MDTM|SID=1|PATH=somefile.bin
<< MDTM|SID=1|CODE=0|MSG=213 19970205115719


QUEUES

QUEUENEW

Create a new QUEUE by associating two SIDs with it. These are currently named NORTH and SOUTH as a means to refer to either one uniquely without implying direction of transfer. (source and destination does not work) 

[ Minimal Required Fields]

>> NORTH_SID=<int>  - SID of the session, out of two.
>> SOUTH_SID=<int>  - SID of the session, out of two.

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue ID for queue operations.

[ Example ]

>> queuenew|north_sid=1|south_sid=2
<< QUEUENEW|CODE=0|QID=1|MSG=Queue created.

QADD

Add a new items to a specified queue. This is quite a versatile command which looks to take many arguments. As a command it has four parts to it. Except for special QTYPE values, see below.

  1. The source information. The easiest way here is to use the FID option, if you have previously done a DIRLIST command. This will take the required source information from the directory cache. If FID is not used, or you wish to override information from the FID, you can specify the source information manually. The name of the item can either be specified by SRCDIR+SRCNAME OR SRCPATH. (SRCPATH = SRCDIR/SRCNAME). The extra SRC options, like SRCSIZE, and SRCREST are optional. Both are used for Resume purposes, as well as finally CPS calculations.
  2. The destination information. This is copied from the source. However, you can optionally override any of this. For example specifying a different DSTNAME would transfer and rename the file at the same time. The PATH is made up the same way as source, specify one of the two in: (DSTPATH = DSTDIR/DSTNAME)
  3. Queue position. This can be omitted for default queue positioning. However if the specific position is desired, you can use @=<int|FIRST|LAST> to specify Nth position, FIRST position or LAST position in the queue.
  4. Optional modifiers. The default behaviour of a SITE is to always RESUME unless specified otherwise using the "resume" option to the site definition. The default for a queue item is also to resume. You can override this default for THIS queue item by specifying "OVERWRITE" or "RESUME". The latter is useful if the site's default has been changed to OVERWRITE. You can also specify QTYPE for this addition, either due to manual queuing, or to override the FID type. If you get it wrong, the queue processing will also get it wrong.

Alternatively, you can use QTYPE to set non transfer type items. At this time, there is only type "STOP". If you issue QTYPE=STOP there is no need to send information for 1), 2) or 4). Part 3) is optional. There is currently a bug where you have to specify SRC= field with the STOP item. It makes no difference as to which SRC you pick. 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID 
>> SRC=<str>        - Specify which SID is the source. Either "NORTH"
                      or "SOUTH".
EITHER:
>> FID=<int>        - File ID to use as source
OR:
>> SRCPATH=<str>    - Full path of the source file
OR:
>> SRCNAME=<str>    - Name of source file.
>> SRCDIR=<str>     - Directory path containing source file.
OR:
>> QTYPE=STOP       - Insert a soft stop item

[ Optional Arguments ]

>> SRCNAME=<str>    - Name of source file
>> SRCDIR=<str>     - Directory path containing source file
>> SRCPATH=<str>    - Full path, ie, SRCDIR/SRCNAME in one.
>> SRCSIZE=<int>    - Size of the queue item.
>> SRCREST=<int>    - Restart point of queue item (files only).
>> DSTNAME=<str>    - Name of destination file, OR obtained from source
>> DSTDIR=<str>     - Directory path containing destination file, OR
                      obtained from source
>> DSTPATH=<str>    - Full path, ie, DSTDIR/DSTNAME in one. OR
                      obtained from source.
>> DSTSIZE=<int>    - Size of the queue item. 
>> DSTREST=<int>    - Restart point of queue item (files only).
>> QTYPE=<str>      - Type of queue item. Either "directory",
                      "file" or "stop". [1]
>> RESUME           - Resume file if possible.
>> OVERWRITE        - Do not resume, overwrite destination
>> @=<int|str>      - Queue position, int or FIRST/LAST strings.

[1] More types will come. The default type is "file". 

[ Returns ]

>> QID=<int>        - Queue ID
>> CODE=<int>       - Command return status CODE.
>> ITEMS=<int>      - Number of items in the queue
>> MSG=<str>        - Command return message.
>> @=<int>          - Position in the queue item was inserted.
>> SRCPATH=<str>    - Original source path used (to identify QADD reply, and use "@")
>> DSTPATH=<str>    - Original destination path used (to identify QADD reply, and use "@")
>> FID=<int>        - If QADD was called with FID=, the QADD reply will also contain FID.

[ Example ]

>> qadd|qid=1|src=north|fid=2
<< QADD|CODE=0|QID=1|ITEMS=1|@=0|SRCPATH=/test/srcfile.bin|DSTPATH=/dump/srcfile.bin|FID=2|Msg=Added successfully.

>> QADD|QID=123|SRC=SOUTH|SRCPATH=/archive/thesis/bilingual.pdf|DSTPATH=/old/ducoments/obsolete.pdf|SRCSIZE=43523|OVERWRITE|QTYPE=file
<< QADD|CODE=0|QID=123|ITEMS=906|@=55|SRCPATH=/archive/thesis/bilingual.pdf|DSTPATH=/old/ducoments/obsolete.pdf|Msg=Added successfully.

What is the default queue position when QADD is called, or during file transfers? When the API queues items, they will always be placed LAST unless otherwise specified.

As a default, files are added after all the (top) files, but before the first directory. Directories are added after all files, but before the first directory. (yes, it's the same). Which the exception of if the name matches "fmovefirst" or "dmovefirst", then it is inserted with "FIRST" position.

This means, when it is expanding a directory, the queue ends up like: 

FIRST
    files that match fmovefirst
    all other files
    directories.
LAST

QLIST

List all queues on the engine, and their current states. 

[ Minimal Required Fields]

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue ID
>> NORTH=<str>      - Name of the North site
>> SOUTH=<str>      - Name of the South site
>> ITEMS=<int>      - Number of queue items
>> STATUS=<str>     - Current processing state
>> ERRORS=<int>     - Number of items in the error queue.
>> KB/s=<int>       - Transfer speed of last completed transfer.
>> SUBSCRIBED       - Sent if client is subscribed to events from this queue.
>> BEGIN            - First item sent,   start of list.
>> END              - Final item was sent, end of list.

[ Example ]

>> qlist
<< QLIST|BEGIN
<< QLIST|QID=20|NORTH=ftp1|SOUTH=ds|ITEMS=1|STATUS=PROCESSING|ERRORS=0|SUBSCRIBED|KB/s=0.00
<< QLIST|END

QGET

Get the contents of a specific queue, all its queue items. 

[ Minimal Required Fields] 

>> QID=<int>        - Queue ID 

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue ID
>> @=<int>          - Position in the queue of item.
>> FTYPE=<str>      - Item type, directory/file.
>> SRC=<str>        - Source SID is "NORTH" or "SOUTH".
>> SRCPATH=<str>    - Full path of source
>> SRCSIZE=<int>    - Source size, if known.
>> SRCREST=<int>    - Source restart point.
>> DSTPATH=<str>    - Full path of destination
>> DSTSIZE=<int>    - Destination size, if known.
>> DSTREST=<int>    - Destination restart point.
>> ITEMS=<int>      - Number of items in the list.
>> BEGIN            - First item sent,   start of list.
>> END              - Final item was sent, end of list.

[ Example ]

>> qget|qid=1
<< QGET|QID=1|ITEMS=1|BEGIN
<< QGET|QID=1|@=0|FTYPE=FILE|SRC=NORTH|SRCPATH=/Giana_Sisters_GBA//gfx_blocks.txt|
        SRCSIZE=9328|SRCREST=0|DSTPATH=/tmp//gfx_blocks.txt|DSTSIZE=0|DSTREST=0
<< QGET|QID=1|END

QERR

Get the contents of a specific error queue, all its queue items. 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID 

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue ID
>> QTYPE=<str>      - Item type, directory/file.
>> SRC=<NORTH|SOUTH>- This item's source site is North or South.
>> SRCPATH=<str>    - Full path of source
>> DSTPATH=<str>    - Full path of destination
>> SERR_<int>=<str> - Source errors, incrementing, and the reason string
>> DERR_<int>=<str> - Destination errors, incrementing, and the reason string
>> BEGIN            - First item sent,   start of list.
>> END              - Final item was sent, end of list.

[ Example ]

>> QERR|QID=1|BEGIN|ITEMS=1
<< QERR|QID=1|QTYPE=FILE|SRC=NORTH|SRCPATH=/Giana_Sisters_GBA//gfx_blocks.txt|DSTPATH=/tmp/tmp//gfx_blocks.txt|DERR_0=553 gfx_blocks.txt: Can't open for writing
<< QERR|QID=1|END

QDEL

Delete an item in the queue. If a client wishes to delete multiple items, it is advised that the client pre-sorts the items list, and send it with highest queue position first, in descending order. It is an error to attempt to delete queue item at first position (@=0) if the queue is active.

Please be aware that since deleting a queue item early in the list, will affect queue items in a later position. That is to say, if you intend to delete items 1,4,8 from the queue, and you issue 3 QDEL commands "blindly" in the same order (1,4,8), the net effect will be that queue items 1,5,10 are actually deleted. When queue item 1 is deleted, item at position 4 is now 3, and item 5 is at position 4.

Either the clients need to be aware of the re-numbering and compensate for later commands, OR, much easier is to sort the list in descending order before issuing the QDEL commands. Ie, send QDEL commands in the order 8,4,1. 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID 
>> @=<int>          - Queue position of item to delete.

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue ID
>> CODE=<int>       - Command return status CODE.
>> ITEMS=<int>      - Number of items in the queue
>> MSG=<str>        - Command return message.
>> @=<int>          - Position in the queue of item.

[ Example ]

>> qdel|qid=1|@=53
<< QDEL|QID=1|CODE=0|@=53|ITEMS=0

QMOVE

Move an item in the queue from one position to a new position. It is an error to move a queue item from, or to, the first position (@=0) when a queue is active. 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID 
>> FROM=<int>       - Queue position of item to move
>> TO=<str|int>     - New position, either <int> Nth place, or string
                      placement like in QADD. ("FIRST"/"LAST")

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue ID
>> CODE=<int>       - Command return status CODE.
>> ITEMS=<int>      - Number of items in the queue
>> MSG=<str>        - Command return message.
>> @=<int>          - Position where item was inserted.
>> FROM=<int>       - Position where item was originally from.

[ Example ]

>> qmove|qid=1|from=0|to=last
<< QMOVE|QID=1|@=23|FROM=0|CODE=0|ITEMS=3|MSG=Moved

QGRAB

QGRAB lets a client take control of an idle queue, and the queue's sessions, if any. This is currently the only way to gain access to sessions given away with the "GO" command. If the queue had any connected sessions, the client should receive appropriate CONNECT messages. 

[ Minimal Required Fields]

>> QID=<int>        - Queue id in question

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue id
>> ITEMS=<int>      - Current number of items in queue
>> NORTH_SID=<int>  - Session ID of North site, if connected.
>> SOUTH_SID=<int>  - Session ID of South site, if connected.
>> NORTH_SITEID=int - Site ID of North site, for future SESSIONNEW
>> SOUTH_SITEID=int - Site ID of South site, for future SESSIONNEW
>> NORTH_NAME=<str> - Site name of North site
>> SOUTH_NAME=<str> - Site name of South site
>> CODE=<int>       - Command return status CODE.

As well as potential async commands. 

[ Example ]
 
>> qgrab|qid=1
<< CONNECT|SID=34
<< IDLE|SID=34
<< CONNECT|SID=35
<< IDLE|SID=35
<< QGRAB|QID=1|CODE=0|ITEMS=0|NORTH_SID=34|SOUTH_SID=35|NORTH_SITEID=0|SOUTH_SITEID=4|NORTH_NAME=localhost|SOUTH_NAME=distro_site

QCOMPARE

Compare the two directories in the session cache against each other, sending back list of FIDs that would be queued by FXP.One. This gives GUIs an easy way to show which items would be queued, and processed in a given set of directories. The compare function uses all the logic, including skiplists, passlists, movefirst and skipempty. It compares file sizes to ignore those of the same size, but highlights the side with the smaller size should they differ. 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID 

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue ID
>> NORTH_FID=<int,> - Comma separated list of FIDs for the NORTH site.
>> SOUTH_FID=<int,> - Comma separated list of FIDs for the NORTH site.
>> BEGIN            - First item sent,   start of list.
>> END              - Final item was sent, end of list.

[ Example ]

>> qcompare|qid=1
<< QCOMPARE|QID=1|BEGIN
<< QCOMPARE|QID=1|NORTH_FID=1,3,4,5,6,7,8,10,13,15,16,17,18,19,21,22,23,24,25,26,28,29,31,33,35,36,37,38
,39,40,41,42,43,44,45,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,69,70,71,72,73,
74,75,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,99,100,101,102,103,104,105,
107,108,109,110,111,112,113,115,116,117,118
<< QCOMPARE|QID=1|NORTH_FID=119,120,121,122,123,124,125,126,127,128,129,130,132,133,134,135,136,137,
138,139,140,141,142,144,145,146,147,148,149
<< QCOMPARE|QID=1|SOUTH_FID=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,20,21,22,23,24,25,26,27,28,
29,30,31,32,34,35,36,37,38,39,40,41,42,43,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,
64,65,66,67,68,69,70,71,72,73,74,75,77,78,79,80,81,82,84,85,87,88,89,90,91,92,93,95,96,97,98,99,100,
101,102,104,105,106,107,109
<< QCOMPARE|QID=1|SOUTH_FID=110,113,114,115
<< QCOMPARE|QID=1|END|MSG=Completed comparison.

QUEUEFREE

Release an existing queue, release its sessions, and queue items. 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue ID
>> CODE=<int>       - Command return status CODE.
>> MSG=<str>        - Command return message.

[ Example ]

>> QUEUEFREE|QID=1
<< QUEUEFREE|CODE=0|QID=1|Msg=Queue released.

GO

Issue "GO" to a queue. Request FXP.One engine to start processing the queue and its items. The client loses ownership of the two SIDS at the issue of the "GO" command. You may no longer issue commands directory to the SIDs. Once a queue is idle, either from the QC|EMPTY message, or after issuing the STOP command, the client can issue the "QGRAB" command to receive controls of the SIDs, if still existing. 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID

[ Optional Arguments ]

>> SUBSCRIBE        - Subscribe to queue status (QS) and queue changes (QC)  

[ Returns ]

>> QID=<int>        - Queue ID
>> CODE=<int>       - Command return status CODE if failed.
>> MSG=<str>        - Command return message.

[ Example ]

>> GO|QID=1
<< GO|QID=1|CODE=0|MSG=Queue processing started.


STOP

Issue "STOP" to a queue. Request FXP.One engine to attempt to stop processing the queue and its items. There are currently three types on STOP levels, the default is "SOFT", which will stop once the current transfer is complete. "HARD" which will attempt to send the FTP command 'ABOR' to both FTPDs to gracefully interrupt the current transfer. (local client might need ABOR support added) Finally, the "DROP" method which will log out of both FTPDs and hence forcing the transfer to stop. Once the queue processing has stopped, the FXP.One engine will issue a "QC|IDLE" command, after which the client can issue QGRAB. 


[ Minimal Required Fields]

>> QID=<int>        - Queue ID

[ Optional Arguments ]

>> HARD             - Send FTP 'ABOR' to FTP daemons
>> DROP             - Drop connections to FTP daemons to cancel transfers.  

[ Returns ]

>> QID=<int>        - Queue ID
>> CODE=<int>       - Command return status CODE if failed.
>> MSG=<str>        - Command return message.

[ Example ]

>> STOP|QID=1
<< STOP|QID=1|CODE=0|MSG=Stop initiated, please wait..
<< QC|QID=1|IDLE|MSG=Stop command successful.

QC

This is a receive-only command, sent by the FXP.One engine when there is a Queue-Change. It is only sent if the client requested to SUBSCRIBE to a queue, either using the "GO" command, or the "QGET" 

[ Minimal Required Fields]

[ Optional Arguments ]

[ Returns ]

>> MOVE             - Item has moved to a new position. Comes with
                      FROM= and TO= keys. 
>> REMOVE           - Remove items from queue. All items with higher
                      position are decremented by one. Uses @.
>> INSERT           - New item inserted into queue. Uses @, SRCPATH,
					  DSTPATH, QTYPE, SRCSIZE.
>> EMPTY            - Empty queue, processing stops.

>> IDLE             - Queue moved into IDLE state, either from QTYPE=STOP or
                      in response to a STOP command. 

[ Example ]

<< QC|QID=1|REMOVE|@=0
<< QC|QID=1|MOVE|FROM=0|TO=18
<< QC|QID=1|INSERT|@=0|SRCPATH=/testfile.dat|DSTPATH=/tmp/testing.bin|QTYPE=FILE|SRCSIZE=29734

QS

This is a receive-only command, sent by the FXP.One engine when there is Queue-Status information to relay. Client can safely ignore this command as it does not reflect on any queue changes. It is merely meant as a way for clients to be able to track progress of a queue being processed. It is only sent if the client requested to SUBSCRIBE to a queue, either using the "GO" command, or the "QGET" (Not yet implemented). All QS messages are related to the item at the top of the queue. So "@=0" is implied. 

[ Minimal Required Fields]

[ Optional Arguments ]

[ Returns ]

>> START            - Started processing the item at the top of queue.
     SRCPATH=<str>  - Included for human readability.
>> SRCCWD=<str>     - Changed to new directory on source
>> DSTCWD=<str>     - Changed to new directory on destination
>> MKD=<str>        - Created new directory on destination
>> XFRACT           - File transfer has started (received 150)
     SECURE=<yes/no>- Was Secure Data negotiations successful.
     REST=<int>     - Are we resuming this file
     SIZE=<int>     - Final source size (from SIZE command)
>> XFREND           - File transfer finished (successfully, 226).
     TIME=<int>     - Duration of transfer [1]
     KB/s=<int>     - Estimated speed of transfer [1]
>> FAILED           - Attempted transfer failed
     SERR=<str>     - Error reasons (source failed)
     DERR=<str>     - Error reasons (destination failed)
     COUNT=<int>    - This failure count.

[1] Please be aware that we can only measure the time difference between the 150 FTP message, and the 226 FTP message as received by FXP.One. This may not reflect the actual time taken for the transfer, subsequently the KB/s computation is based on said time, and will most likely only be an estimate. The shorter the duration of a file transfer is, the more inaccurate the speed computation will be. 

[ Example ]

<< QS|QID=1|MSG=Processing directory|SRCPATH=/Giana_Sisters_GBA//giana_sounds|DSTPATH=/tmp/tmp//giana_sounds
<< QS|QID=1|SRCCWD=/Giana_Sisters_GBA/
<< QS|QID=1|START|@=0|SRCPATH=/Giana_Sisters_GBA//giana_sounds/might_be_game_sounds.pcm
<< QS|QID=1|SRCCWD=/Giana_Sisters_GBA/giana_sounds/
<< QS|QID=1|DSTMKD=/tmp/tmp//giana_sounds
<< QS|QID=1|MSG=Transfer started|SECURE=YES|REST=0|SIZE=29734
<< QS|QID=1|MSG=Transfer complete|TIME=0.00|KB/s=0.00

[ Log of a complete session ]

>> GO|QID=1|SUBSCRIBE
<< QS|QID=1|MSG=Processing directory|SRCPATH=/Giana_Sisters_GBA//giana_sounds|DSTPATH=/tmp/tmp//giana_sounds
<< QS|QID=1|SRCCWD=/Giana_Sisters_GBA/
<< QC|QID=1|REMOVE|@=0
<< QC|QID=1|INSERT|@=0|SRCPATH=/Giana_Sisters_GBA/giana_sounds//might_be_game_sounds.pcm|DSTPATH=/tmp/tmp//giana_sounds/might_be_game_sounds.pcm|QTYPE=FILE|SRCSIZE=29734
<< QS|QID=1|START|@=0|SRCNAME=might_be_game_sounds.pcm
<< QS|QID=1|SRCCWD=/Giana_Sisters_GBA/giana_sounds/
<< QS|QID=1|MKD=/tmp/tmp//giana_sounds
<< QS|QID=1|MSG=Transfer started|SECURE=YES|REST=0|SIZE=29734
<< QS|QID=1|MSG=Transfer complete|TIME=0.00|KB/s=0.00
<< QC|QID=1|REMOVE|@=0

SUBSCRIBE

Request to receive the QS and QC commands from a processing queue. A client may subscribe to as many queues as it wants, including those not started by itself. 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID

[ Optional Arguments ]

>> TOGGLE           - If already subscribed, issue un-subscribe instead.

[ Returns ]

>> QID=<int>        - Queue ID
>> MSG=<str>        - Command return message.
>> UNSUBSCRIBED     - If issued TOGGLE the result was to be un-subscribed.

[ Example ]

>> SUBSCRIBE|QID=1|TOGGLE
<< SUBSCRIBE|QID=1|CODE=0|MSG=Subscribed

UNSUBSCRIBE

Stop being subscribed to a queue. 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID

[ Optional Arguments ]

[ Returns ]

>> QID=<int>        - Queue ID
>> MSG=<str>        - Command return message.

[ Example ]

>> UNSUBSCRIBE|QID=1
<< UNSUBSCRIBE|QID=1|CODE=0|MSG=Unsubscribed


QCLONE (v1.7)

Take a created queue (idle or active) and make an exact copy of the queue. If source queue is active, connect both sides and start processing. Some clients refer to this as "add another thread". 

[ Minimal Required Fields]

>> QID=<int>        - Queue ID

[ Optional Arguments ]

>> START=<yna>      - Start processing (Y), do not start processing (N), or copy source (A). Default is (A). 
>> SUBSCRIBE        - Also subscribe to queue processing notices.

[ Returns ]

>> QID=<int>        - Source Queue ID, same as given.
>> NEWQID=<int>        - Newly created clone Queue ID
>> MSG=<str>        - Command return message.

[ Example ]

>> QCLONE|QID=123
<< QCLONE|QID=123|NEWQID=124|CODE=0|MSG=Queue 124 processing started.

In reality, it is a little more verbose, here is an actual example:
>> QCLONE|QID=1 
<< SESSIONNEW|SITEID=15|CODE=0|SID=3
<< SESSIONNEW|SITEID=16|CODE=0|SID=4
<< QUEUENEW|CODE=0|QID=2|NORTH_SID=3|SOUTH_SID=4|MSG=Queue created.
<< QCLONE|CODE=0|QID=1|NEW_QID=2|Msg=Cloned and created queue
<< CONNECT|SID=3|SSL
<< IDLE|SID=3
<< CONNECT|SID=4|SSL
<< IDLE|SID=4
<< GO|QID=2|CODE=0|MSG=Queue processing started.

ADMINISTRATIVE COMMANDS

QUIT

Disconnect from the FXP.One engine. The client can also just close the connection without worry. 

[ Minimal Required Fields]

[ Optional Arguments ]

[ Returns ]

>> Will disconnect on you, how rude.

[ Example ]

>> QUIT
<< Connection closed by remote host.

HELP

Display available commands at this privilege level. 

[ Minimal Required Fields]

[ Optional Arguments ]

[ Returns ]

>> MSG=<str>        - Command return message.
>> CODE=<int>       - Command return status CODE.


[ Example ]

>> HELP
<< HELP|CODE=0|Msg= QUIT HELP WHO SHUTDOWN SITEADD SITELIST SITEMOD SITEDEL SESSIONNEW SESSIONFREE
        DIRLIST QUEUENEW QADD QLIST QGET QERR QGRAB QDEL QMOVE QCOMPARE QUEUEFREE GO STOP CWD PWD
        SIZE DELE MKD RMD SITE REN MDTM QUOTE SUBSCRIBE UNSUBSCRIBE.

WHO

Display a list of users connected to this FXP.One engine. 

[ Minimal Required Fields]

[ Optional Arguments ]

[ Returns ]

>> NAME=<str>       - User name of login session
>> HOST=<ip>        - IP address of login session
>> PORT=<port>      - Remote port number
>> SSL=<yes|no>     - Is connection encrypted
>> CLIENTS=<int>    - Number of items in the queue
>> BEGIN            - First item sent,   start of list.
>> END              - Final item was sent, end of list.

[ Example ]

>> WHO
<< WHO|BEGIN|CLIENTS=3
<< WHO|NAME=admin|HOST=127.0.0.1|PORT=58597|SSL=yes
<< WHO|NAME=admin|HOST=220.150.239.57|PORT=1135|SSL=yes
<< WHO|NAME=admin|HOST=127.0.0.1|PORT=58540|SSL=no
<< WHO|END|Msg=Command Completed.

SETPASS

Change the login password on the FXP.One engine. This is strongly encouraged. 

[ Minimal Required Fields]
>> OLD=<str>        - Old/current password of this login session.
>> NEW=<str>        - New/future password for this login session.

[ Optional Arguments ]

[ Returns ]

>> MSG=<str>        - Command return message.
>> CODE=<int>       - Command return status CODE.

[ Example ]

>> SETPASS|OLD=admin|NEW=newpass
<< SETPASS|CODE=0|MSG=New password has been set.

<< SETPASS|CODE=1502|MSG=Login incorrect

SHUTDOWN

Shutdown the FXP.One engine have it completely exit. 

[ Minimal Required Fields]

[ Optional Arguments ]

>> LASTCLIENT       - Only shutdown if THIS client is the last one.

[ Returns ]

>> Might disconnect on you, how rude.

[ Example ]

>> SHUTDOWN
<< SHUTDOWN|CODE=0
<< Connection closed by remote host.
Retrieved from "http://lundman.net/wiki/index.php?title=Extra_Site&oldid=4706"