# xxfi_negotiate

SYNOPSIS

    #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

Called When | Once, at the start of each SMTP connection.
Default Behavior | Return SMFIS_ALL_OPTS to change nothing.

ARGUMENTS

Argument | Description
--- | ---
ctx | the opaque context structure.
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.

SPECIAL RETURN VALUES

Return value | Description
--- | ---
SMFIS_ALL_OPTS | If a milter just wants to inspect the available protocol steps and actions, then it can return SMFIS_ALL_OPTS and the MTA will 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 will be ignored.
SMFIS_REJECT | Milter startup fails and it will not be contacted again (for the current connection).
SMFIS_CONTINUE | Continue processing. In this case the milter must set all output parameters `pf0` - `pf3`. See below for an explanation how to set those output parameters.

NOTES

This function allows a milter to 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 will not work if a milter requires new actions that are not available when talking to an older MTA. Hence in the negotiation callback a milter can determine which operations are available and dynamically select those which it needs and which are offered. If some operations are not available, the milter may either fall back to an older mode or abort the session and ask the user to upgrade.

Protocol steps (`f1`, `*pf1`):

- `SMFIP_RCPT_REJ`: By setting this bit, a milter 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 which have been rejected because of syntax errors etc. If a milter requests this protocol step, then it should check the macro `{rcpt_mailer}`: if that is set to `error`, then the recipient will be rejected by the MTA. Usually the macros `{rcpt_host}` and `{rcpt_addr}` will contain an enhanced status code and an error text in that case, respectively.
- `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()
  - `SMFIP_NR_HELO`: xxfi_helo()
  - `SMFIP_NR_MAIL`: xxfi_envfrom()
  - `SMFIP_NR_RCPT`: xxfi_envrcpt()
  - `SMFIP_NR_DATA`: xxfi_data()
  - `SMFIP_NR_UNKN`: xxfi_unknown()
  - `SMFIP_NR_EOH`: xxfi_eoh()
  - `SMFIP_NR_BODY`: xxfi_body()
  - `SMFIP_NR_HDR`: xxfi_header()
- `SMFIP_HDR_LEADSPC` indicates that the MTA can send header values with leading space intact. If this protocol step is requested, then the MTA will also 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()
  - `SMFIP_NOHELO`: xxfi_header()
  - `SMFIP_NOMAIL`: xxfi_envfrom()
  - `SMFIP_NORCPT`: xxfi_envrcpt()
  - `SMFIP_NOBODY`: xxfi_body()
  - `SMFIP_NOHDRS`: xxfi_header()
  - `SMFIP_NOEOH`: xxfi_eoh()
  - `SMFIP_NOUNKNOWN`: xxfi_unknown()
  - `SMFIP_NODATA`: xxfi_data()
  For each of these xxfi_* callbacks that a milter does not use the corresponding flag should be set in `*pf1`.

The available actions (`f0`, `*pf0`) are described elsewhere (xxfi_flags).

If a milter returns SMFIS_CONTINUE, then it must set 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.

Copyright (c) 2006 Sendmail, Inc. and its suppliers. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the LICENSE.