POP3 Reader Input Adapter

Introduction

Note

This adapter uses the WinPcap libraries for Windows to tap into the IP packet stream. Before using this adapter with real-time data, you must install and configure these libraries on the system that will host the adapter.

Download and install the latest WinPcap MSI from http://www.winpcap.org. Use all the default settings for the installation. This adapter is not supported on Mac OS X or Linux.

The TIBCO StreamBase® Input Adapter for IP/POP3 reads Internet Protocol packets, either from the IP stack of a running system or from an archived capture file, and emits a tuple for each e-mail message found in the TCP data stream.

Dedicated tuple fields hold the source and destination addresses, and the POP3 headers (From, To, Subject, and so on). The body of the message is shown in nested tuples body1, body2, and so on, having the dedicated fields (ContentType, ContentTransferEncoding and Content). Attachments are shown in nested tuples Attachment1, Attachment2, and so on, having the dedicated fields (ContentType, ContentTransferEncoding, ContentDisposition and Content). Each nested tuple denotes one attachment.

This adapter supports three multipart subtypes of the MIME standard’s Content-Type header (Mixed, Alternative and Related) and does not support seven subtypes (Message, Digest, Report, Signed, Encrypted, Form Data, Mixed-Replace (Experimental) and Byteranges).

When reading IP traffic on a running system, a filter string can be configured to limit the IP traffic being read.

Properties

Property	Description
Data Source	Select Realtime Data or Capture File to read POP3 traffic from the IP stack of a running system or from an archived capture file, respectively.
Capture File Name	The fully-qualified name of the capture file holding the IP packets to process. The capture file must be on a WinPcap-compatibile format. The property is ignored when Data Source is set to Realtime Data.
TCP Port Number	The well-known TCP port number of the POP3 server, which defaults to 110.
Capture Filter String	A WinPcap-compatible filter string that can be used to limit the IP traffic being read.
Number of Body Fields	Specifies the number of Body fields to use, with a default value of 3. All message portions of the body are shown in nested tuples. If the e-mail has no attachments, the body is shown in the field Body1 and the remaining configured fields are null. If the mail has attachments inline, the message is shown in the configured fields (Body2, Body3). The message is shown in the nested tuple field Content.
Number of Attachments	Specifies the number of Attachment fields to use, with a default value of 3. Any attachments of the incoming e-mail are shown in nested tuples. If the e-mail has no attachments, then all the configured nested tuples are shown as null. Any attachment containing an unsupported header is ignored. The body of the attachment is shown in the nested tuple field Content.
Log Level	Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.
Schema (schema)	The schema to output, which includes the following fields that the adapter automatically creates. The user can override the length of any string field by adding that field in the Edit Schema tab: Date (string): The date and time the e-mail message was sent. From (string): Contents of the From header. To (string): Contents of the To header. Subject (string): Contents of the Subject header. Return-Path (string): Contents of the Return-Path header. Received (string): Contents of the Received header. Reply-To (string): Contents of the Reply-To header. Message-ID (string): Contents of the Message-ID header. User-Agent (string): Contents of the User-Agent header. MIME-Version (string): Contents of the MIME-Version header. TruncatedFields (string): A comma-separated list of field names above that were truncated. For example, if the Subject field is set to 128, and an e-mail message with a longer subject is processed, the subject is truncated and this field includes the string Subject. Note that this field is itself truncated if it is not large enough to hold all the field names that were truncated for a specific message.

Typechecking and Error Handling

Typechecking fails in the following circumstances:

Schema fields are entered that are not in the Edit Schema tab listed above, or are of a data type other than string or blob.
The Number of Attachments is less than zero or null.
The Number of Body Fields is less than zero or null.

A tuple is emitted only when a complete e-mail message is detected in the TCP stream. If one or more IP packets are missing such that the TCP stream cannot be reconstructed, no tuple is emitted for the corresponding e-mail message.

Suspend and Resume Behavior

When suspended, the adapter stops processing IP packets. Note that doing so may cause the WinPcap libraries to discard IP packets, resulting in lost tuples when the adapter is eventually resumed.