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