Data Access APIs

The smfi_getsymval() API

You can use the smfi_getsymval() API to get the value of a Sendmail macro. The macros that are defined depend on when smfi_getsymval() is called. You can call smfi_getsymval() from any of the xxfi_* callbacks.

The declaration of smfi_getsymval() is as follows:

#include <libmilter/mfapi.h>
char* smfi_getsymval(
         SMFICTX *ctx,
         char *symname
);

Table 2-1 “The xxfi_flags Field Values” lists the Sendmail macros that you can use with the xxfi_* callbacks.

All macros specified with the xxfi_connect() and xxfi_helo() callbacks are active from the point they are received until the end of the connection. All macros specified with the callback xxfi_envfrom() are active from the point they are received until the end of the message. All macros specified with the callbacks xxfi_envrcpt() are active for each recipient.

You can use the confMILTER_MACROS_* options in the Sendmail .mc file to change the macro list. Depending on when Sendmail sets the macros, you can determine the scope of these macros.

Arguments

You must call smfi_getsymval() with the following argument:

Return Value

smfi_getsymval() returns the value of the given macro as a null-terminated string or a NULL value if the macro is not defined.

The smfi_getpriv() API

You can use the smfi_getpriv() API to get the connection-specific data pointer for a connection. You can call smfi_getpriv() in any of the xxfi_* callbacks.

The declaration of smfi_getpriv() is as follows:

#include <libmilter/mfapi.h>
void* smfi_getpriv(
          SMFICTX *ctx
);

Argument

You must call smfi_getpriv() with the argument ctx, which specifies an opaque context structure.

Return Value

smfi_getpriv() returns the private data pointer stored by an earlier call to the smfi_setpriv() API, or NULL if none has been set.

The smfi_setpriv() API

You can use smfi_setpriv() to set the private data pointer for a connection. You can call smfi_setpriv() in any of the xxfi_* callbacks.

The declaration of smfi_setpriv() is as follows:

#include <libmilter/mfapi.h>
int smfi_setpriv(
       SMFICTX *ctx,
       void *privatedata
);

Only one private data pointer is available per connection; multiple calls to smfi_setpriv() with different values result in loss of previous values. Before a filter terminates, it must release the private data and set the pointer to NULL.

Arguments

You must call smfi_setpriv() with the following arguments:

Return Values

smfi_setpriv() returns MI_FAILURE if ctx is an invalid context structure. smfi_setpriv() returns MI_SUCCESS on success.

The smfi_setreply() API

You can use the smfi_setreply() API to set the default SMTP error reply code. Only 4xx and 5xx replies are accepted. You can call smfi_setreply() from any of the xxfi_* callbacks other than the xxfi_connect() callback. smfi_setreply() directly sets the SMTP error reply code for a connection. If subsequent error occurs because of an action taken by the filter, analyze the error code to identify the problem.

The declaration of smfi_setreply() is as follows:

#include <libmilter/mfapi.h>
int smfi_setreply(
         SMFICTX *ctx,
         char *rcode,
         char *xcode,
         char *message
);

Following are some points to consider regarding smfi_setreply():

Arguments

You must call smfi_setreply() with the following arguments:

Return Value

smfi_setreply() fails because of the following reasons and returns MI_FAILURE:

smfi_setreply() returns MI_SUCCESS on success.

The smfi_setmlreply() API

You can use the smfi_setmlreply() API to set the default SMTP error reply code to a multi-line response. You can set only 4xx and 5xx reply codes.

You can call smfi_setmlreply() from any of the xxfi_* callbacks except the xxfi_connect() callback. smfi_setmlreply() directly sets the SMTP error reply code for a connection to the given lines after xcode. You must terminate the list of arguments that you pass to smfi_setmlreply() with a NULL value. The error code is used on subsequent error replies resulting from actions taken by the filter program.

The declaration of smfi_setmlreply() is as follows:

#include <libmilter/mfapi.h>
int smfi_setmlreply(
        SMFICTX *ctx,
        char *rcode,
        char *xcode,
        ...
);

Following are some points to consider regarding smfi_setmlreply():

Arguments

You must call smfi_setmlreply() with the following argument:

Return Values

smfi_setmlreply() fails because of the following reasons and returns MI_FAILURE:

smfi_setmlreply() returns MI_SUCCESS on success.