This function scans an SMTP message from a buffer. A scan result block is allocated for the scan and a handle representing the scan result block is returned. The application can then use this handle to retrieve the scan results using the get...() functions. When the application is finished it MUST release the scan result block with a call to closeScan().

The message buffer is expected to contain the raw SMTP data for the message with the local Received: header at the top. The message should not be broken into MIME segments before it is scanned by SNFMulti. This is important because Message Sniffer examines the entire message as well as how the message was assembled by the originating system. Any additional processing is both unnecessary and may remove subtle defects and artifacts that will help Message Sniffer classify the message.

If the message is particularly large, it is acceptable to scan only the first 32K bytes of the message. This means that if the calling application wants to scan a large incoming message before it has received all of the DATA during the SMTP connection then it can scan the first 32K of the message and potentially reject the remainder based on the scan result.

When the application is finished with the results from this scan it must release the scan result block with a call to closeScan(). Scan result blocks are allocated as needed and then recycled in order to improve performance. If the application fails to close the scan result blocks then the DLL will continue to allocate additional blocks until there is no more RAM.

The entire scan is performed before this function returns. After that the scanning thread is no longer considered to be active. The resulting scan result buffer may be accessed as often as needed to gather results data from this scan without impacting any other scan operations.

Any number of scan...() operations may be active concurrently up to the limits of the platform.

Parameters

The scanBuffer() function accepts two additional parameters that are passed on to the logging system to aid in debugging.

The Name parameter is a null terminated string containing an identifier for the message being scanned. This can be any name that can be used later to identify this particular message in the log files such as a serial number, unique hash, or the message-id. For example, when the scanFile() function is called this parameter is filled in with the path to the file that was scanned.

The Setup parameter is an integer representing the number of milliseconds spent so far setting up the message to be scanned. This can be any useful metric - but generally it should represent how much time the system has spent working on preparing and evaluating the message so far. For example, when the scanFile() function is called this value is automatically established with the amount of time spent opening and reading the message file.

IMPORTANT: SNF expects to identify the source IP for the message by searching Received: headers in the message. The application must ensure that the local Received: header is present as the first Received: header in the message in order for this search to be accurate. If necessary the calling application can simulate the local received header using the following minimal form:

Received: from connecting.mta.example.com [12.34.56.78] by this.scanning.system

where connecting.mta.example.com is the optional reverse DNS resolved for the connecting MTA; 12.34.56.78 is the IP of the connecting MTA; and by this.scanning.system is an optional reference to the calling application.

Bfr = a pointer to the buffer that is to be scanned.

Length = the length of the message buffer in bytes.

Name = a message identifier as a null terminated string.

Setup = the time in milliseconds already spent setting up this message for scanning.

returns a handle to the scan result block upon success otherwise an error code:

snf_ERROR_NO_HANDLE - There was a problem allocating a scan result block.

snf_ERROR_SCAN_FAILED - There was a problem performing the scan.

In general a result > 0 indicates a valid scan handle and a result <= 0 indicates an error. NOTE that the scan may have failed even if you get a valid handle. The scan result code you retrieve from get...() may indicate an error. See Result Codes for details.