Chapter 2 Using the Protocol Level Plug-in API

This chapter describes using the Protocol Level Plug-in API to write protocol level plug-ins. The examples in this chapter come from the Anti-Relay Plug-in, a protocol level plug-in that allows you to prevent other sites from using your site to relay UBE on to other sites.

• Using Protocol Level Plug-in Functions
• Working with Plug-in Structures
• Using Macros

int PPModule_Init(ProtPlugSystem *pSys) 

ProtPlug *PPModule_NewProtPlug(PPSession *ps);

int ProtPlug_ProcessLine(ProtPlug *ppp, 
                         char *pszLine, 
                         char **ppszResp)

void ProtPlug_Delete(ProtPlug *ppp)

void PPModule_Exit(void); 

• The ProtPlugSystem Structure
• The PPSessionActions Structure

typedef struct ProtPlugSystemStruct 
{
     void  *(*PPRealloc)(void *pOld, int nSize);
                     /* all memory comes from here */ 
     PPMutex  *(*PPMutex_New)(void); 
     void  (*PPMutex_Lock)(PPMutex *pm); 
     void  (*PPMutex_Unlock)(PPMutex *pm);
     void  (*PPMutex_Delete)(PPMutex *pm);
     char  *(*PPGetIni)(char *pszKey, char *pszDefault,
                        char *pszResult, int nResultSize);
     void  (*PPLogPrintf)(char *pszFormat,...);
     struct in_addr (*PPGetHostByName)(char *pszName);
     char  *(*PPGetHostByAddr)(struct in_addr ina, char *pBuf,
                               int nBufSize);
} ProtPlugSystem;

• The PPRealloc function allocates, reallocates, and frees all memory used by the plug-in. All memory comes from this operation.
• The PPMutex functions handle the operations on the mutex synchronization object. For more information, see PPMutex.
• The PPGetIni function gets basic server configuration information, which consists of any configuration value stored in Directory Server or the local config.db. As one of its parameters, PPGetIni takes a configuration value name as a key. To see a list of possible key values, run configutil.
• The PPLogPrintf function allows the plug-in to write to the SMTP server log.
• The PPGetHostByName and PPGetHostByAddr functions provide basic name resolution functionality. PPGetHostByName returns the actual name of the host, for example, netscape.com. PPGetHostByAddr returns the IP address based on the display name.

#include <protplug.h>
typedef struct PPSessionActionsStruct
{
     int (*DeferLine)
         (PPSession *ps, char *pszLine, char **ppszResp);
     char *(*GetProperty)
         (PPSession *ps, char *pszKey, char *pszDefault);
} PPSessionActions;

• The DeferLine function passes control to the next plug-in the chain and allows the calling plug-in to see and act on the response.
• The GetProperty function retrieves information about the current session, which can include the client IP-address, the authentication state, and other values. The function uses a key that represents session-specific properties. For values, see Table 2.4.

• Passing Control to the Next Plug-in
• Retrieving Session-Specific Information

#define PPSESSION_DEFERLINE(p, l, r) \
        ((PPSessionActions *)(p))->DeferLine((p), (l), (r))

#define PPSESSION_GETPROPERTY(p, k, d) \
        (((PPSessionActions *)(p))->GetProperty((p), (k), (d)))