Protocol

Following is a list of API commands.

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=232|OK|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 ]

>> OK               - Authentication was successful.
>> CODE=<int>       - Failure code.
>> MSG=<str>        - Human readable string message.

[ Example ]

<< AUTH|USER=admin|PASS=admin
>> AUTH|OK|MSG=Successful

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

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

SITES

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 ]

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

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")

For example: "...|extrafield=somestuff|OS=Unix"

[ Returns ]

>> SITEID=<int>    - Site ID of created site.
>> OK              - The operation was successful.
>> 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 ]

[ 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]
>> END             - Final item was sent, end of command.

[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
>> SITELIST|SITEID=1|NAME=localhost|HOST=127.0.0.1|PORT=21|USER=mp3|PASS=mp3|PAS
SIVE=1|FXP_PASSIVE=2|CONTROL_TLS=2|DATA_TLS=2|optional_variable=roger moore
>> SITELIST|SITEID=0|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

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 ]

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

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")

For example:

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

[ Returns ]

>> SITEID=<int>    - Site ID of created site.
>> OK              - The operation was successful.
>> 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.
>> OK              - The operation was successful.
>> CODE=<int>      - Command return status CODE.
>> MSG=<str>       - Command return message.

[ Example ]

>> SITEDEL|SITEID=12
<< SITEDEL|CODE=0|OK|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.

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). These are in turn returned so that you can match the queue created with the appropriate SIDs.

[ 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.
>> NORTH_SID=<int>  - SID of the session, out of two.
>> SOUTH_SID=<int>  - SID of the session, out of two.

[ Example ]

>> queuenew|north_sid=1|south_sid=2
<< QUEUENEW|CODE=0|QID=1|NORTH_SID=1|SOUTH_SID=2|MSG=Queue created.
<< QUEUENEW|CODE=510|NORTH_SID=1|SOUTH_SID=2|MSG=SID 2 already belongs to QID 5

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.

[ Example ]

>> qadd|qid=1|src=north|fid=2
<< QADD|CODE=0|QID=1|ITEMS=1|@=0|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|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