FidoNet Technical Standards Committee (FTSC) Documents

http://ftsc.org/docs
Admin
The FTSC documents contain standards, proposals, and reference materials for FidoNet, a distributed...
Tokens:10,875
Snippets:28
Trust Score:4.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Binkp Session Frame Exchange Example

Illustrates a typical frame exchange during a simple Binkp session setup between two nodes, showing the sequence of commands like M_NUL, M_ADR, M_PWD, and M_OK.

```APIDOC
+----------------------------------------------------------------+
| Originating side               | Answering side                |
|--------------------------------+-------------------------------|
| M_NUL "SYS ..."                | M_NUL "SYS ..."               |
| M_NUL "ZYZ ..."                | M_NUL "ZYZ ..."               |
| M_NUL "LOC ..."                | M_NUL "LOC ..."               |
| M_NUL "VER ..."                | M_NUL "VER ..."               |
| M_NUL "OPT ..."                | M_NUL "OPT ..."               |
| M_ADR "1:1/1.1@fidonet"        | M_ADR "2:2/2.2@fidonet"       |
| M_PWD "password"               | (waiting for a password from  |
|                                | remote)                       |
|--------------------------------+-------------------------------|
| (waiting for password          | M_OK "secure"                 |
| acknowledgement)               |                               |
|--------------------------------+-------------------------------|
```

--------------------------------

### FTSC Session Setup - Originating Side

Details the state transitions and actions for the originating side during the FTSC session setup phase. It covers connection initiation, authentication, and progression to the file transfer stage.

```APIDOC
FTSC Session Setup - Originating Side (Table 1):

State S0 (ConnInit):
  Predicate(s): None
  Action(s): Attempt to establish connection.
  Next State: S1

State S1 (After ConnInit):
  Predicate(s): Connection established.
  Action(s): Send M_ADR frame, then send M_PWD frame.
  Next State: Awaiting Authentication Response

State Awaiting Authentication Response:
  Predicate(s): Reception of M_OK (success) or M_ERR (failure).
  Action(s) on M_OK: Proceed to file transfer stage.
  Action(s) on M_ERR: Close connection.
  Next State: File Transfer Stage or Connection Closed
```

--------------------------------

### Binkp Command Examples

Illustrates the frame structure for specific Binkp commands, M_OK and M_NUL, showing the placement of the command ID, data length (SIZE), and command arguments within the frame.

```APIDOC
Example: M_OK ""
  Frame Structure:
    +-+-------+--------+--------+
    |1|      0        1|       4|
    +-+-------+--------+--------+
     |                |        +----- command ID (M_OK)
     |                +-------- frame length (SIZE=1 for command ID)
     +- command frame flag (T bit = 1)

Example: M_NUL "TEST"
  Frame Structure:
    +-+-------+--------+--------+-------+--------+--------+--------+
    |1|      0        5|       0|   T        E        S       T    |
    +-+-------+--------+--------+-------+--------+--------+--------+
     |                |        +----- command ID (M_NUL)
     |                +-------- frame length (SIZE=5 for "TEST" + command ID)
     +- command frame flag (T bit = 1)
     +-------------------------+----- "Data string" (TEST)
```

--------------------------------

### FTCS Protocol Session Setup - Answering Side States

Defines the states, predicates, actions, and next states for the answering side of the FTCS protocol during session setup. This includes handling incoming connections, address frames, password verification, and error conditions.

```APIDOC
FTCS Protocol Session Setup - Answering Side

This section details the state transitions and actions for the answering side of the FTCS protocol during the session establishment phase.

**State R0: WaitConn**
  - **Description**: Waits for an incoming connection.
  - **Predicates**: Incoming connection established.
  - **Actions**: 
    - Send M_NUL frames with system info and capabilities (optional).
    - Send M_ADR frame with system addresses.
    - Set Timer.
  - **Next State**: R1
  - **Alternate Predicates**: Nothing happens.
  - **Alternate Actions**: Wait.
  - **Alternate Next State**: R0

**State R1: WaitAddr**
  - **Description**: Waits for an M_ADR frame from the remote.
  - **Predicates**: M_ADR frame received.
  - **Actions**: 
    - Check if a password exists for each of the remote addresses.
  - **Next State**: R2
  - **Alternate Predicates**: M_ERR frame received.
  - **Alternate Actions**: Report error, send M_ERR frame.
  - **Alternate Next State**: exit
  - **Alternate Predicates**: M_NUL frame received.
  - **Alternate Actions**: Ignore or parse, optionally log.
  - **Alternate Next State**: R1
  - **Alternate Predicates**: Other known frame received.
  - **Alternate Actions**: Report unexpected frame; send M_ERR frame.
  - **Alternate Next State**: exit
  - **Alternate Predicates**: Unknown frame received.
  - **Alternate Actions**: Ignore.
  - **Alternate Next State**: R1
  - **Alternate Predicates**: Nothing happens.
  - **Alternate Actions**: Wait.
  - **Alternate Next State**: R1
  - **Alternate Predicates**: Timer expired.
  - **Alternate Actions**: Report timeout.
  - **Alternate Next State**: exit

**State R2: IsPasswd**
  - **Description**: Verifies password match based on received addresses.
  - **Predicates**: Yes, we have a password.
  - **Actions**: 
    - Set Timer.
  - **Next State**: R3
  - **Alternate Predicates**: Yes, but we have several different passwords for different addresses of the remote.
  - **Alternate Actions**: Send M_ERR frame, Report inconsistent password settings.
  - **Alternate Next State**: exit
  - **Alternate Predicates**: No, there's no password.
  - **Alternate Actions**: Set Timer.
  - **Alternate Next State**: R3

**State R3: (Implicit)**
  - **Description**: Continues session setup based on password verification outcome.
  - **Actions**: (Details not fully provided in this snippet for R3 onwards, but implies proceeding to file transfer or disconnection based on password match success/failure).
```

--------------------------------

### File Transfer Protocol Commands

This section details the commands used in a file transfer protocol, covering file metadata, acknowledgments, error reporting, and session management. It includes syntax, parameter descriptions, and usage examples for each command.

```APIDOC
M_OK 1
  Description: Reports to the remote about the session status (secure or non-secure).
  Arguments:
    - "non-secure": Report normal password unprotected session (e.g., empty password).
    - "secure": Report normal password protected session.
  Example:
    M_OK "secure"

M_FILE 3
  Description: Specifies parameters for the next file to be transmitted.
  Synopsis: M_FILE "<filename> <file_size> <unixtime> <file_offset>"
  Parameters:
    - filename: The name of the file.
    - file_size: Size of the file in bytes (decimal integer).
    - unixtime: Unix timestamp of the file (decimal integer).
    - file_offset: Transmission offset for the file (decimal integer).
  Implementation Notes:
    - Size, unixtime, and offset must be positive numbers or zero.
    - Mailer MUST check received string to prevent number overflow and skip file if overflow.
    - Data frames must carry data from this file consecutively until the next M_FILE command.
    - Transmission typically starts from offset 0, but M_GET command from remote forces transmission from a specified offset.
  Example:
    M_FILE "config.sys 125 2476327846 0"
    M_FILE "config.sys 125 2476327846 100" (answering to M_GET with offset 100)

M_EOB 5
  Description: End-of-Batch command, transmitted after all files have been sent.
  Arguments: Arguments MUST be ignored in the basic implementation.
  Example:
    M_EOB ""

M_GOT 6
  Description: File acknowledgment transmitted upon receiving the last data frame for a file.
  Synopsis: M_GOT "<filename> <size> <unixtime>"
  Parameters:
    - filename: The name of the successfully received file.
    - size: Size of the file in bytes (decimal integer).
    - unixtime: Unix timestamp of the file (decimal integer).
  Usage:
    - Argument values must match those sent in the corresponding M_FILE command.
    - Can be transmitted while receiving a file, potentially interpreted as a destructive file skip.
  Example:
    M_GOT "config.sys 125 2476327846"

M_ERR 7
  Description: Indicates a fatal error; the sending party SHOULD abort the session.
  Arguments: SHOULD contain an error explanation and may be logged by the remote.
  Common Errors:
    - "Bad address": Remote mailer passed a bad (restricted) address.
    - "Incorrect password": Remote side sent an incorrect password.
    - "<command>: cannot parse args": Illegal argument string for a command.
  Implementation Note:
    - Mailer MUST NOT abort a session without sending M_ERR or M_BSY.
    - After receiving M_ERR and session drop, mailer should wait before next poll to prevent continuous polling.
  Example:
    M_ERR "Incorrect password"

M_BSY 8
  Description: Transmitted when the system encounters a non-fatal error due to temporary lack of resources (e.g., incoming session limit exceeded).
  Arguments: SHOULD contain an explanation of the situation and may be logged by the remote.
  Usage:
    - Can be sent at any time during the session.
    - The side sending M_BSY is in a legal position to abort the session.
    - Mailer MUST be able to accept M_BSY at any time.
  Example:
    M_BSY "Incoming session limit exceeded"
```

--------------------------------

### Binkp Command Classification by Protocol Stage

Categorizes Binkp commands based on the stage of the protocol they are used in, distinguishing between session setup, file transfer, and commands applicable at any stage.

```APIDOC
Command Stages:

1. Session Setup Stage:
   - M_ADR: MUST be sent by both sides.
   - M_PWD: MUST NOT be sent by the Answering side.
   - M_OK: MUST NOT be sent by the Originating side.
   - These commands MUST NOT be sent during the file transfer stage.

2. File Transfer Stage:
   - M_FILE, M_GOT, M_GET, M_SKIP, M_EOB.
   - These commands MUST NOT be sent during the session setup stage.

3. Any Stage:
   - M_NUL, M_ERR, M_BSY.
   - These commands MAY be sent any time during the session.
```

--------------------------------

### Binkp Protocol Identification

Defines the format for identifying the Binkp protocol version during session setup. It specifies the M_NUL frame content, including mailer identification and the protocol string, and outlines fallback behavior when identification strings are missing or incompatible.

```APIDOC
APIDOC:
  Protocol Identification String:
    In session setup stage, both sides send M_NUL frames.
    Format: M_NUL "VER mailer/version binkp/1.0"
    - mailer/version: Mailer identification string (free form, ASCII 32-126).
    - binkp/1.0: Protocol identification string (case-insensitive).

    Example:
      M_NUL "VER binkd/0.9.5a/FreeBSD binkp/1.0"

    Timing:
      Version identification frame SHOULD be sent and may be received before authentication ends.

    Fallback Rules:
    - If no protocol identification string is received, binkp/1.0 MUST be assumed.
    - Mailers with a protocol higher than binkp/1.0 MUST fallback to binkp/1.0 if they receive a binkp/1.0 version identification string or no identification string at all.
```

--------------------------------

### Password Handling Protocol States

Defines the state transitions and actions for password authentication. It details how the system responds to different frames (M_PWD, M_ERR, M_NUL) and conditions like password matching or timer expirations, guiding the system through states R3, R4, and R5.

```APIDOC
State: R3 (WaitPwd)
  - On M_PWD frame received:
    - If password matches or no password required: Transition to R4.
    - If password does not match: Transition to exit (Report password error, Send M_ERR frame).
  - On M_ERR frame received: Transition to exit (Report error).
  - On M_NUL frame received: Ignore or parse, optionally log. Transition to R1.
  - On Other known frame received: Report unexpected frame; send M_ERR frame. Transition to exit.
  - On Unknown frame received: Ignore. Transition to R3.
  - On Nothing happens: Wait. Transition to R3.
  - On Timer Expired: Report timeout. Transition to exit.

State: R4 (PwdAck)
  - On Yes, the password matches:
    - Send M_OK frame.
    - Report secure session.
    - Transition to R5.
  - On No password and got M_PWD "-" frame:
    - Send M_OK frame.
    - Report unsecure session.
    - Transition to R5.
  - On No, password does not match:
    - Report password error.
    - Send M_ERR.
    - Transition to exit.

State: R5 (Opts)
  - On We have more protocol extensions:
    - Send frames to negotiate protocol extensions.
    - Transition to T0.
```

--------------------------------

### FTSC Protocol Message Types

Defines common message types used within the FTSC protocol for communication between sides during session setup and file transfer. Includes status indicators and file transfer markers.

```APIDOC
FTSC Protocol Messages:

- M_OK: Acknowledgment of successful operation or authentication.
- M_ERR: Error indicator, signaling a failure in an operation or authentication.
- M_FILE "file_info": Indicates a file is being transferred, with associated metadata like filename, size, and checksum.
- M_EOB: End of Block marker, signifying the completion of a data block or file segment.
- M_GOT "file_info": Confirmation that a file has been received and processed.
- M_ADR: Address frame, typically sent by the originating side during session setup.
- M_PWD: Password frame, sent by the originating side for authentication.
- M_NUL "OPT ...": Null frame used to indicate optional protocol extensions.
```

--------------------------------

### Binkp Commands Specification

Defines the format and arguments for various Binkp protocol commands, including M_NUL for information exchange, M_ADR for address lists, M_PWD for session passwords, and M_OK for acknowledgments. Covers recommended usage and extensions.

```APIDOC
Binkp Commands:

Format: symbolic_command_name command_ID

M_NUL 0
  Purpose: Used for human-readable information, nodelist info, sysop name, and protocol extensions.
  Arguments: MAY contain human-readable information. Mailer MAY ignore/log arguments if options not supported.
  Recommended format for arguments:
    * M_NUL "OPT protocol options list" (space-separated list of supported options/extensions)
    * M_NUL "SYS system_name"
    * M_NUL "ZYZ sysop's_name"
    * M_NUL "LOC system_location"
    * M_NUL "NDL system_capabilities"
    * M_NUL "TIME date_time" (e.g., "Sun, 06 Nov 1994 08:49:37 GMT" [RFC822])
    * M_NUL "VER mailer_version protocol_version" (e.g., "binkp/1.0")
    * M_NUL "TRF netmail_bytes arcmail_bytes" (traffic prognosis in bytes)
  Other arguments used by some mailers:
    * M_NUL "PHN string" (phone number, IP address)
    * M_NUL "OPM string" (message for system operator)
    * M_NUL "FREQ" (indicate file request)

M_ADR 1
  Purpose: Lists 5D FTN addresses.
  Arguments: Space-separated list of 5D FTN addresses (e.g., "2:5047/13.1@fidonet 2:5047/0@fidonet").
  Address format: If point part is 0, ".0" may be omitted.
  Extension: Supports 4D, 3D, and 2D addresses. Mailers MAY append default domain/zone for compatibility.
  Recommendation: All implementations should send 5D addresses to avoid ambiguities.

M_PWD 2
  Purpose: Session password for authentication.
  Usage: Only Originating side MUST send this message. Answering side proceeds after successful authentication.
  Arguments: Case-sensitive password string (e.g., "pAsSwOrD").
  No Password: If no password is available, send M_PWD "-".

M_OK 4
  Purpose: Acknowledgement for a correct password.
```

--------------------------------

### Binkp Protocol Extensions Indication

Describes how to indicate supported protocol extensions using M_NUL frames. It covers the format for listing extensions and the expected behavior when multiple extension frames are received, emphasizing backward compatibility.

```APIDOC
APIDOC:
  Protocol Extensions:
    Indication Method: Sides indicate supported protocol extensions by sending M_NUL frames.
    Format: M_NUL "OPT list_of_extensions"
    - list_of_extensions: A space-separated list of supported protocol extensions.

    Handling Multiple Frames:
    - Whenever multiple M_NUL "OPT ..." frames are received during the session, they SHOULD augment the current list of extensions rather than replace it, unless specifically stated otherwise for a particular option.

    Usage:
    - Mailer SHOULD NOT use any extension unless exactly sure that this extension is supported by the remote.
    - Mailer SHOULD use M_NUL "OPT ..." to indicate supported options.
    - Other methods for indicating supported extensions are allowed as long as they provide full backwards compatibility.

    Recommended Extensions (at time of writing):
    - None-reliable mode (NR).
    - Challenge-Response Authentication Mechanism (CRAM).
```

--------------------------------

### Binkp Receive Logic State Transitions

Illustrates the logic for handling incoming frames and data during Binkp reception. It maps received frame types and data conditions to specific actions and subsequent states, including error handling and acknowledgment.

```APIDOC
Receive Logic Table
+-----------------+-----------------+-----------------+--------+--------+
|                 |                 | M_SKIP          | Queue     |        |
|                 |                 |-----------------+----------+--------|
|                 |                 | Got M_NUL       | Log/parse/| RxEOB  |OK      |
|                 |                 |                 | ignore    |        |        |
|                 |                 |-----------------+----------+--------|
|                 |                 | Got other       | Report    | RxDone |Failure |
|                 |                 | known frame     | unexpected|        |        |
|                 |                 | or data frame   | frame     |        |        |
|                 |                 |-----------------+----------+--------|
|                 |                 | Got unknown     | ignore    | RxEOB  |OK      |
|                 |                 | frame           |          |        |        |
|-----------------+-----------------+-----------------+----------+--------|
| RxDone          | none            | none            | none      | RxDone |OK      |
+-----------------+-----------------+-----------------+----------+--------+
```

--------------------------------

### File Transfer Protocol States

Describes the state machine for the file transfer stage, managed by Receive Routine (RxState) and Transmit Routine (TxState). It covers initialization, data transfer, and session completion, including states like RxWaitF, RxAccF, RxReceD, RxWriteD, RxEOB, RxDone for receiving and TxGNF, TxTryR, TxReadS, TxWLA, TxDone for transmitting.

```APIDOC
RxState := { RxWaitF | RxAccF | RxReceD | RxWriteD | RxEOB | RxDone }
TxState := { TxGNF | TxTryR | TxReadS | TxWLA | TxDone }

State: T0 (InitTransfer)
  - Predicate(s): none
  - Action(s):
    - Set Timer
    - Set RxState to RxWaitF
    - Set TxState to TxGNF
  - Next: T1

State: T1 (Switch)
  - Predicate(s):
    - RxState is RxDone and TxState is TxDone:
      - Action(s): Report session complete.
      - Next: exit
    - Data Available in Input Buffer:
      - Action(s): call Receive routine.
      - Next: T2
    - Free space exists in output buffer:
      - Action(s): call Transmit routine.
      - Next: T3
    - Nothing happens:
      - Action(s): Wait.
      - Next: T1
    - Timer Expired:
      - Action(s): Report Timeout.
      - Next: exit

State: T2 (Receive)
  - Predicate(s): Receive routine
  - Action(s):
    - Set Timer
  - Next: T1
```

--------------------------------

### Binkp Transmit Routine State Machine

Defines the state transitions for the Binkp transmit routine. It details the states, predicates, conditions, actions, next states, and return values for managing file transmission, including opening files, sending data blocks, and handling end-of-batch conditions.

```APIDOC
Table 5: Transmit Routine
+-----------------+-----------------+-----------------+-----------------+-------+--------+
| TxState         | Predicate(s)    | Condition(s)    | Actions(s)      | Next  | Return |
|-----------------+-----------------+-----------------+-----------------+-------+--------|
| TxGNF           | Open next file  | File opened OK  | Send M_FILE     | TxTryR|continue|
|                 | from outgoing   |                 | Report          |       |        |
|                 | queue           |                 | sending file    |       |        |
|                 |                 |-----------------+-----------------+-------+--------|
|                 |                 | Failed to open  | Report          | TxDone|Failure |
|                 |                 | file            | failure         |       |        |
|                 |                 |-----------------+-----------------+-------+--------|
|                 |                 | No more files   | Send M_EOB      | TxWLA |continue|
|                 |                 |                 | Report end      |       |        |
|                 |                 |                 | of batch        |       |        |
|-----------------+-----------------+-----------------+-----------------+-------+--------|
| TxTryR          | Check TheQueue  | TheQueue is     | none            | TxReadS|continue|
|                 |                 | empty           |                 |       |        |
|                 |                 |-----------------+-----------------+-------+--------|
|                 |                 | TheQueue is     | call ProcessTheQueue|continue|
|                 |                 | not empty       |                 |       |        |
|-----------------+-----------------+-----------------+-----------------+-------+--------|
| TxReadS         | Read data block | Read failed     | Report Error    | TxDone|Failure |
|                 | from file       |-----------------+-----------------+-------+--------|
|                 |                 | Read OK,        | Send data       | TxGNF |OK      |
|                 |                 | Reached EOF     | block frame     |       |        |
|                 |                 |                 | Close           |       |        |
|                 |                 |                 | current file    |       |        |
|                 |                 |                 | Add current     |       |        |
|                 |                 |                 | file to         |       |        |
|                 |                 |                 | PendingFiles    |       |        |
|                 |                 |-----------------+-----------------+-------+--------|
|                 |                 | Read OK, not    | Send data       | TxTryR|OK      |
|                 |                 | reached EOF     | block frame     |       |        |
|-----------------+-----------------+-----------------+-----------------+-------+--------|
| TxWLA           | Check TheQueue  | TheQueue is     | none            | TxDone|OK      |
|                 |                 | empty and       |                 |       |        |
|                 |                 | RxState >=      |                 |       |        |
|                 |                 | RxEOB           |                 |       |        |
|                 |                 |-----------------+-----------------+-------+--------|
|                 |                 | TheQueue is     | none            | TxWLA |OK      |
|                 |                 | not empty       |                 |       |        |
+-----------------+-----------------+-----------------+-----------------+-------+--------+
```

--------------------------------

### Binkp M_GET Command

The M_GET command is a request to resend files, sent only after receiving an M_FILE command. It specifies the file to be resent by its filename, size in bytes, unixtime, and transmission offset. If a previous session was aborted, M_GET is used to continue receiving an incomplete file.

```APIDOC
M_GET <filename>; <size>; <unixtime>; <offset>

Example: M_GET "config.sys 125 2476327846 100"

Mailer reacts by discarding transmission in progress, performing seek() to the specified offset, and proceeding with transmission starting with an appropriate M_FILE command.
```

--------------------------------

### ftsc File Transfer Protocol Commands

Defines the core commands used in the ftsc file transfer protocol for managing file transfers, including requesting files, acknowledging receipt, and skipping files. These commands dictate the flow of data and state management between sender and receiver.

```APIDOC
M_GET command:
  - Description: Sent by the remote to request a specific file.
  - Parameters:
    - requested file: The name of the file being requested.
    - Requested pos: The offset within the file the remote is interested in.
  - Behavior:
    - If requested file is not in KnownFiles list: Report unknown file.
    - If requested file is in KnownFiles list and Requested pos is FileSize: Close and finalize file. Report remote refused file. Remove file from PendingFiles. Set TxState to TxGNF.
    - If requested file is in KnownFiles list and Requested pos is less than FileSize: Set file pointer to requested pos. Report remote requested offset. Set TxState to TxGNF.
    - If requested file is in KnownFiles list and Requested pos is greater than FileSize: Ignore frame.
  - Related Commands: M_GOT, M_SKIP
```

```APIDOC
M_GOT command:
  - Description: Sent by the remote to acknowledge receipt of file data or completion.
  - Parameters:
    - file: The file identifier.
  - Behavior:
    - If file is currently transmitting: Close and finalize file. Report Remote refused file. Remove file from PendingFiles. Set TxState to TxGNF.
    - If file is not currently transmitting and File is in PendingFiles list: Finalize file. Report file has been sent. Remove file from PendingFiles.
    - If file is not currently transmitting and File is not in PendingFiles: Ignore frame.
  - Related Commands: M_GET, M_SKIP
```

```APIDOC
M_SKIP command:
  - Description: Sent by the remote to indicate it will accept a file later or skip it for the current session.
  - Parameters:
    - file: The file identifier.
  - Behavior:
    - If file is currently transmitting: Close file (do not finalize). Report remote will accept this file later. Remove file from PendingFiles. Set TxState to TxGNF.
    - If file is not currently transmitting: Report remote will accept this file.
  - Related Commands: M_GET, M_GOT
```

--------------------------------

### Binkp Frame Structure and Notation

Defines the general structure of Binkp frames, including the SIZE field for data length, command ID, and the notation used for symbolic command representation. It specifies how commands are encoded within frames.

```APIDOC
Binkp Frame Structure:
  - Frame consists of a header and a DATA part.
  - Header includes 15 bits for SIZE (length of DATA part in octets).
  - Total frame length = SIZE + 2.
  - SIZE range: 0 to 32767 octets. SIZE 0 is obsolete.
  - First octet of DATA part is the command ID (0-127).
  - Other octets in DATA part carry command arguments.

Command Notation:
  - Symbolic names (M_XXX) are used to refer to commands.
  - Format: M_XXX "Data string"
  - Encoding:
    - First octet of DATA: Numeric command ID for M_XXX.
    - "Data string": Copied into DATA area starting at the second octet.
    - SIZE field: Set to length of "Data string" + 1 (for command ID octet).
    - T bit (part of header): Should be set to 1 for command frames.
```

--------------------------------

### Receive Routine State Machine

Details the states, predicates, conditions, actions, and next states for the Receive Routine during file transfer. It handles incoming frames, processes specific frame types like M_GET, M_GOT, M_SKIP, M_ERR, and M_EOB, and manages file reception states.

```APIDOC
Receive Routine State Machine:

RxState | Predicate(s) | Condition(s) | Actions(s) | Next | Return
--------|--------------|--------------|------------|--------|--------
RxWaitF | Get a frame from Input Buffer | Haven't got a complete frame yet | none | RxWaitF | OK
        |              | Got Data frame | ignore | RxWaitF | OK
        |              | Got M_ERR | Report Error | RxDone | Failure
        |              | Got M_GET / M_GOT / M_SKIP | Add frame to TheQueue | RxWaitF | OK
        |              | Got M_NUL | Log/parse/ignore | RxWaitF | OK
        |              | Got M_EOB | Report End of Batch | RxEOB | OK
        |              | Got M_FILE | none | RxAccF | continue
        |              | Got other known frame | Report unexpected frame | RxDone | Failure
        |              | Got unknown frame | ignore | RxWaitF | OK
RxAccF  | Decide how to accept Incoming File | Accept from beginning | Report receiving file | RxReceD | OK
        |              | Accept from offset (we do already have a part of file) | Send M_GET Report receiving file, requested offest | RxReceD | OK
        |              | Accept later (or failed to create file) | Send M_SKIP Report we will accept | RxWaitF | OK
```

--------------------------------

### ftsc ProcessTheQueue Routine Logic

Details the decision-making process for the ProcessTheQueue routine, which handles actions based on received messages (predicates) and specific conditions related to file transfer states and remote requests. This logic governs how the system responds to various file transfer scenarios.

```APIDOC
ProcessTheQueue Routine:
  - Purpose: To manage file transfer states and actions based on incoming messages and conditions.
  - Predicates and Actions:
    - Predicate: M_GET received
      - Condition: requested file is not in the KnownFiles list
      - Action: Report unknown file
    - Predicate: M_GET received for a known file
      - Condition: Requested pos is FileSize
      - Action: Close and finalize file. Report that remote refused file being transmitted. Remove file from the PendingFiles list. Set TxState to TxGNF.
      - Condition: Requested pos is less than FileSize
      - Action: Set file pointer to requested pos. Report that remote requested offset. Set TxState to TxGNF.
      - Condition: Requested pos is greater than FileSize
      - Action: Ignore frame.
    - Predicate: M_GOT file that is currently transmitting
      - Action: Close and finalize file. Report Remote refused file being transmitted. Remove file from the PendingFiles list. Set TxState to TxGNF.
    - Predicate: M_GOT file that is not currently transmitting
      - Condition: File is in PendingFiles list
      - Action: Finalize file. Report file has been sent. Remove file from the PendingFiles list.
      - Condition: File is not in PendingFiles
      - Action: Ignore frame.
    - Predicate: M_SKIP file that is currently transmitting
      - Action: Close file (do not finalize, will send later). Report remote will accept this file later. Remove file from the PendingFiles list. Set TxState to TxGNF.
    - Predicate: M_SKIP file that is not currently transmitting
      - Action: Report remote will accept this file.
  - Dependencies: KnownFiles list, PendingFiles list, TxState, FileSize, RxState, RxEOB.
```

--------------------------------

### Transmit Routine State Machine

Details the states, predicates, conditions, actions, and next states for the Transmit Routine during file transfer. It handles transmitting frames, processing queue items, and managing transmission states.

```APIDOC
Transmit Routine State Machine:

TxState | Predicate(s) | Condition(s) | Actions(s) | Next | Return
--------|--------------|--------------|------------|--------|--------
TxWaitF | Get a frame from TheQueue | TheQueue is empty | none | TxWaitF | OK
        |              | Got M_GET / M_GOT / M_SKIP | Transmit frame | TxWaitF | OK
        |              | Got M_ERR | Report Error | TxDone | Failure
        |              | Got M_EOB | Transmit M_EOB | TxEOB | OK
        |              | Got M_FILE | Transmit M_FILE | TxAccF | continue
        |              | Got other known frame | Report unexpected frame | TxDone | Failure
        |              | Got unknown frame | ignore | TxWaitF | OK
TxAccF  | Decide how to accept Incoming File | Accept from beginning | Transmit M_GET | TxReceD | OK
        |              | Accept from offset | Transmit M_GET | TxReceD | OK
        |              | Accept later | Transmit M_SKIP | TxWaitF | OK
```

--------------------------------

### FTSC Basic Authentication Scheme

Describes the mandatory Basic Authentication Scheme for FTSC, including its requirements, limitations, and the exchange of password information for verification.

```APIDOC
FTSC Basic Authentication Scheme:

Purpose: Authenticates the originating side to the answering side.

Mechanism:
  1. Originating side sends M_PWD frame containing a password.
  2. Answering side verifies the password against presented addresses.
  3. Answering side responds with M_OK (acknowledgement) or M_ERR (rejection).

Limitations:
  - Password must be the same for all presented addresses if multiple are sent.
  - Passwords are sent in cleartext over the network.
  - Verification is performed only by the Answering side; Originating side cannot verify Answering side.

Extensions for Improvement:
  - CRAM extension for secure password transmission.
  - 'IP address restriction' extension for Answering side verification.
```

--------------------------------

### ftsc Protocol State Machine

Defines the state transitions and actions within the ftsc communication protocol. It maps received frame types and internal conditions to specific system responses, including state changes and error handling. This table serves as a comprehensive reference for the protocol's behavior.

```APIDOC
State: RxReceD (Receive Data)
  Action/Condition: Get a frame from Input Buffer
    Sub-condition: Didn't got a complete frame yet
      Outcome: none
      Next State: RxReceD
      Status: OK
    Sub-condition: Got Data frame
      Outcome: Add frame to The Queue
      Next State: RxWriteD
      Status: continue
    Sub-condition: Got M_ERR
      Outcome: Report Error
      Next State: RxDone
      Status: Failure
    Sub-condition: Got M_GET / M_GOT / M_SKIP
      Outcome: Add frame to The Queue
      Next State: RxReceD
      Status: OK
    Sub-condition: Got M_NUL
      Outcome: Log/parse/ignore
      Next State: RxReceD
      Status: OK
    Sub-condition: Got M_FILE
      Outcome: Report partially received file
      Next State: RxAccF
      Status: Continue
    Sub-condition: Got other known frame
      Outcome: Report unexpected frame
      Next State: RxDone
      Status: Failure
    Sub-condition: Got unknown frame
      Outcome: ignore
      Next State: RxReceD
      Status: OK

State: RxWriteD (Write Data)
  Action/Condition: Write data to file
    Sub-condition: Write Failed
      Outcome: Report error
      Next State: RxDone
      Status: Failure
    Sub-condition: File Pos > Reported
      Outcome: Report write beyond EOF
      Next State: RxDone
      Status: Failure
    Sub-condition: File Pos = Reported
      Outcome: Close File, Send M_GOT Report File Received
      Next State: RxWaitF
      Status: OK
    Sub-condition: File Pos < Reported
      Outcome: none
      Next State: RxReceD
      Status: OK

State: RxEOB (End of Buffer)
  Action/Condition: Get a frame from Input Buffer
    Sub-condition: PendingFiles list is empty
      Outcome: none
      Next State: RxDone
      Status: OK
    Sub-condition: Didn't get a complete frame yet or TxState is not TxDone
      Outcome: none
      Next State: RxEOB
      Status: OK
    Sub-condition: Got M_ERR
      Outcome: Report Error
      Next State: RxDone
      Status: Failure
    Sub-condition: Got M_GET / M_GOT / M_SKIP
      Outcome: Add frame to The Queue
      Next State: RxEOB
      Status: OK

State: Refuse (delete on remote)
  Action/Condition: Send M_GOT Report we do not accept file
    Outcome: later, not in current session
    Next State: RxWaitF
    Status: OK
```

--------------------------------

### Binkp M_BSY Command

The M_BSY command is used by a server to indicate it is busy or to suggest a retry interval. It can include an optional explanation. The format 'RETRY NNNN: <explanation>' specifies the retry interval in seconds.

```APIDOC
M_BSY "<explanation>"

Recommended extension:
M_BSY "RETRY NNNN: <explanation>"
M_BSY "RETRY NNNN"

where NNNN is the interval in seconds (decimal string, any positive number) and <explanation> is an arbitrary string containing the explanation of the matter (optional).
```

--------------------------------

### Binkp M_SKIP Command

The M_SKIP command is a non-destructive skip that indicates the remote should postpone sending a specific file until the next session. It requires the filename, size, and unixtime of the file to be skipped.

```APIDOC
M_SKIP "<filename> <size> <unixtime>"

Example: M_SKIP "config.sys 125 2476327846"
```

--------------------------------

### Binkp File Naming and Escaping Rules

Specifies rules for file naming within the Binkp protocol, emphasizing characters that must be escaped. It defines the structure for plain characters, safe characters, and hexadecimal escaped sequences.

```APIDOC
File Naming Conventions:

Characters considered unsafe and MUST be escaped include space and backslash (\).
Example: file name "abcd e.0f@" must be transmitted as "abcd\x20e.0f@".

Grammar:
  filename = *pchar
  pchar    = plain | escaped
  plain    = alpha | digit | safe
  safe     = "!" | "\"" | "#" | "$" | "%" | "&" | "'" | "(" | ")" |
             "*" | "+" | "," | "-" | "." | "/" | ":" | ";" | "<" |
             "=" | ">" | "?" | "@" | "[" | "]" | "^" | "_" | "`" |
             "{" | "|" | "}" | "~"
  alpha    = "A" | "B" | ... | "Z" | "a" | "b" | ... | "z"
  digit    = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
  escaped  = "\x" HEX HEX
  HEX      = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" |
             "c" | "d" | "e" | "f"

Note: The protocol does not impose limitations on file name length beyond the Binkp frame, but practical limits may exist due to OS compatibility. Maximum length can't exceed 32751 bytes.
```

--------------------------------

### Binkp Session Termination Conditions

Outlines the conditions under which a Binkp session can be terminated. It details fatal errors, non-fatal errors, and the criteria for a successfully completed session, including the role of acknowledgements and end-of-block signals.

```APIDOC
APIDOC:
  Session Termination:
    A session may be terminated in any of the following cases:

    1. Fatal Error:
       - If transmitted or received M_ERR.
       - Session should be deemed aborted due to a fatal error.

    2. Non-Fatal Error:
       - If transmitted or received M_BSY.
       - Session should be deemed aborted due to non-fatal error (e.g., temporary lack of resources).

    3. Successful Completion:
       - All files have been sent.
       - M_EOB has been received from the remote side (no more files for us).
       - Acknowledgements for all sent files have been received.
       - All files re-requested by M_GET have been received.
       - Session should be deemed successfully completed.

    Termination Mechanism:
    - Session termination is not a protocol stage.
    - Mailer may terminate a session at any time by issuing a disconnect (shutdown) command to the underlying transport layer, provided any of the three conditions above are met.
    - Mailer MUST take proper steps for graceful shutdown of the transport layer, ensuring all data is transmitted and received before disconnection.
```

--------------------------------

### Binkp Frame Format Specification

Defines the structure of Binkp frames, including the header format, frame type, and data size. It details the mapping of an octet stream or datagram stream into Binkp frames, specifically for TCP/IP socket connections.

```APIDOC
Binkp Frame Structure:

  7 6543210 76543210
 +-+-+-------+--------+--- ................ ---+
 |T|      SIZE      |          DATA          |
 +-+-+-------+--------+--- ................ ---+
 |<-   2 octets   ->|<- up to 32767 octets ->|
    (frame header)          (frame data)

Frame Header:
  - T (1 bit): Frame Type
    - 0: Indicates a data frame.
    - 1: Indicates a command frame.
  - SIZE (15 bits): Specifies the size of the DATA field in octets. Maximum value is 32767.

Frame Data:
  - DATA: Contains the actual protocol command or data payload, with a maximum size of 32767 octets.
```

--------------------------------

### Binkp Command Argument Escaping

Details the methods for escaping special characters, particularly non-ASCII characters and reserved symbols like whitespace and backslash, within Binkp command arguments to ensure data integrity.

```APIDOC
Escaping Illegal Characters:
  - Form: \x followed by two hexadecimal digits (e.g., \x20 for space).
  - Example: whitespace (' ') escaped as '\x20'; pipe ('|') escaped as '\x7c'.
  - Backslash ('\') MUST always be escaped as '\\' to prevent uncertainty.

  - Older method (FSP-1011.003): Two hexadecimal digits preceded by a backslash (e.g., '\20' for space).
  - Compatibility: Mailers SHOULD decode '\20' into space in file names.

Non-ASCII Characters:
  - Mailers SHOULD use only ASCII characters [32...126] in symbol strings.
  - Other characters MAY be used only in M_NUL command arguments in plain form.
  - Recommendation: Use isprint() function (ISO C).

File Name Issues:
  - File names MUST NOT include whitespace (ASCII 20 hex).
  - If a filename contains space, it MUST be escaped.
  - File names SHOULD NOT include symbols other than alphanumeric and safe characters.
```
Tokens:
Raw