xxfi_negotiate callback Function

Purpose

The xxfi_negotiate callback function handles negotiation.

Syntax

#include <libmilter/mfapi.h>
#include <libmilter/mfdef.h>
sfsistat (*xxfi_negotiate)(
        SMFICTX *ctx, 
	unsigned long f0,
	unsigned long f1,
	unsigned long f2,
	unsigned long f3,
	unsigned long *pf0,
	unsigned long *pf1,
	unsigned long *pf2,
	unsigned long *pf3);

Description

The xxfi_negotiate callback function is called at the start of each simple mail transfer protocol (SMTP) connection and returns SMFIS_ALL_OPTS flag.

With this function, a milter parameter could dynamically determine and request operations and actions during startup. In previous versions, the actions (f0) were fixed in the flags field of the smfiDesc structure and the protocol steps (f1) were implicitly derived by checking whether a callback was defined. Due to the extensions in the new milter version, such a static selection would not work if a milter parameter requires new actions that are not available when talking to an older mail transfer agent (MTA). Hence, in the negotiation a callback can determine which operations are available and dynamically select those callback function which it needs and which are offered. If some operations are not available, the milter parameter might either fall back to an older mode or stop the session and ask the user to upgrade.

Protocol steps

(f1, *pf1)

SMFIP_RCPT_REJ: By setting this bit, a milter parameter can request that the MTA should also send RCPT commands that have been rejected because the user is unknown (or similar reasons), but not those function which have been rejected because of syntax errors. If a milter requests this protocol step, then it should check the macro {rcpt_mailer}: if that is set to error, then the recipient would be rejected by the MTA. Usually the macros {rcpt_host} and {rcpt_addr} would contain an enhanced status code and an error text in that case.
SMFIP_SKIP indicates that the MTA understand the SMFIS_SKIP return code.
SMFIP_NR_* indicates that the MTA understand the SMFIS_NOREPLY return code. There are flags for various protocol stages:
- SMFIP_NR_CONN: xxfi_connect callback Function
- SMFIP_NR_HELO: xxfi_helo callback Function
- SMFIP_NR_MAIL: xxfi_envfrom callback Function
- SMFIP_NR_RCPT: xxfi_envrcpt callback Function
- SMFIP_NR_DATA: xxfi_data callback Function
- SMFIP_NR_UNKN: xxfi_unknown callback Function
- SMFIP_NR_EOH: xxfi_eoh callback Function
- SMFIP_NR_BODY:xxfi_body callback Function
- SMFIP_NR_HDR: xxfi_header callback Function
The SMFIP_HDR_LEADSPC flag indicates that the MTA can send header values with leading space intact. If this protocol step is requested, the MTA would not add a leading space to headers when they are added, inserted, or changed.
The MTA can be instructed not to send information about various SMTP stages, these flags start with: SMFIP_NO*.
- SMFIP_NOCONNECT: xxfi_connect callback Function
- SMFIP_NOHELO: xxfi_header callback Function
- SMFIP_NOMAIL: xxfi_envfrom callback Function
- SMFIP_NORCPT: xxfi_envrcpt callback Function
- SMFIP_NOBODY: xxfi_body callback Function
- SMFIP_NOHDRS: xxfi_header callback Function
- SMFIP_NOEOH: xxfi_eoh callback Function
- SMFIP_NOUNKNOWN: xxfi_unknown callback Function
- SMFIP_NODATA: xxfi_data callback Function
For each of these xxfi_* callbacks that a milter parameter does not use, the corresponding flag should be set in
```
*pf1.
```

The available actions

(f0, *pf0)

are described in (xxfi_flags).

If a milter returns the SMFIS_CONTINUE flag, the milter sets the desired actions and protocol steps via the (output) parameters pf0 and pf1 (which correspond to f0 and f1, respectively). The (output) parameters pf2 and pf3 should be set to 0 for compatibility with future versions.

Arguments

Table 1. Arguments
Item	Description
`ctx`	The opaque context structure maintained in libmilter parameter.
`f0`	The actions offered by the MTA.
`f1`	The protocol steps offered by the MTA.
`f2`	For future extensions.
`f3`	For future extensions.
`pf0`	The actions requested by the milter
`pf1`	The protocol steps requested by the milter.
`pf2`	For future extensions.
`pf3`	For future extensions.

Return values

Table 2. Return Values
Item	Description
`SMFIS_ALL_OPTS`	If a milter just wants to inspect the available protocol steps and actions, then it can return the SMFIS_ALL_OPTS flag and the MTA would make all protocol steps and actions available to the milter. In this case, no values should be assigned to the output parameters `pf0` -`pf3` as they would be ignored.
`SMFIS_REJECT`	The milter startup fails and it would not be contacted again (for the current connection).
`SMFIS_CONTINUE`	Continue processing. In this case the milter parameter must set all output parameters `pf0` - `pf3`. See the following for an explanation how to set those output parameters.