PMX_MESSAGE_WRITABLE Methods

The PMX_MESSAGE_WRITABLE interface can be used with messages returned from the engine's create_message() method. This interface is not required for basic SDK usage.

set_envelope_sender()
PMX_ERROR (*set_envelope_sender)(PMX_MESSAGE_WRITABLE m,
           const char *sender,
           size_t len);
Sets the message's envelope sender. The string is copied into the message object. The get_envelope_sender() method subsequently returns a pointer to the copied string.
add_envelope_recipient()
PMX_ERROR (*add_envelope_recipient)(PMX_MESSAGE_WRITABLE m,
           const char *recip,
           size_t len);
Adds an envelope recipient. The string is copied into the message object. The enumerate_envelope_recipients() method subsequently reports the copied string.
set_relay()
PMX_ERROR (*set_relay)(PMX_MESSAGE_WRITABLE m,
           const char *relay,
           size_t len);
Sets the relay IP address as a string. The string is copied into the message object. The get_relay() method subsequently returns a pointer to the copied string.
set_relay_hostname()
PMX_ERROR (*set_relay_hostname)(PMX_MESSAGE_WRITABLE m,
                                const char *hostname,
                                size_t len);
Sets the relay hostname as a string. The string is copied into the message object. The get_relay_hostname() method subsequently returns a pointer to the copied string.
set_helo()
PMX_ERROR (*set_helo)(PMX_MESSAGE_WRITABLE m, const char *helo, size_t len);
Sets the SMTP HELO string. The string is copied into the message object. The get_helo() method subsequently returns a pointer to the copied string.
append()
PMX_ERROR (*append)(PMX_MESSAGE_WRITABLE m, const char *data, size_t len);
Appends data to the message. This method is called internally by pmx_append_to_message() .
set_limit()
PMX_ERROR (*set_limit)(PMX_MESSAGE_WRITABLE m,
                       PMX_MESSAGE_LIMIT what,
                       size_t limit);
Sets internal limits in the message object. There are several limits to tweak:
PMX_MLIMIT_BYTES
The maximum number of bytes to allocate for raw MIME data. If more data than this is allocated, further calls to append() are silently ignored.

Default: 64KB

PMX_MLIMIT_PARTS
The maximum number of MIME parts to parse in the message object. If more MIME parts than this are encountered, MIME parsing is aborted. The value returned from enumerate_parts() never exceeds this limit.

Default: 128

PMX_MLIMIT_SIBLINGS
The maximum number of MIME sibling parts allowed anywhere in the MIME tree. If any part with more subparts than this is encountered, MIME parsing is aborted.

Default: 50

These parameters should not need modification as they are designed to limit the amount of work done by a high performance mail scanning application. The limits can be lowered further to increase scanning performance on large messages.
preload()
PMX_ERROR (*preload)(PMX_MESSAGE_WRITABLE, size_t maxbytes);
The preload() method forces the message object to parse at least maxbytes bytes from its input stream. If EOF or the watermark is found before maxbytes, the object stops reading. This can be used to guarantee that a certain amount of data is ready for the engine before calling scan_message(). In a multithreaded application, this may be more efficient, as the scanning thread will not block for IO.

The preload() method is incompatible with the append() method. Use it with the streaming input methods read_from_file() or read_from_func().

This method should not be called after any vtbl member functions have been invoked on the PMX_MESSAGE object.

read_from_file()
PMX_ERROR (*read_from_file)(PMX_MESSAGE_WRITABLE m, const char *file);
The read_from_file() method set the message to read MIME on demand from the specified file. The file is opened and remains open (using up a file descriptor) until the message is destroyed, the watermark is hit, or EOF is encountered.

The read_from_file() method is incompatible with the append() method. Use one or the other, but not both.

This method should not be called after any vtbl member functions have been invoked on the PMX_MESSAGE object.

read_from_func()
PMX_ERROR (*read_from_func)(PMX_MESSAGE_WRITABLE m, void *host, PMX_MESSAGE_READER, PMX_MESSAGE_READER_FREE);
The read_from_func() method sets the message to read MIME on demand from a callback function. The application provides a reader function that the message object will call whenever it needs more data. The reader callback is passed the opaque pointer provided to read_from_func() by the calling application. It is also passed a buffer; the size of the buffer, and, as an out parameter, the number of bytes stored in the buffer. The reader is expected to return PMX_MESSAGE_EOF when the stream is exhausted.

The free function is provided so that resources used by the host can be freed when the stream is exhausted. This is called when the message object is destroyed, the watermark is hit, or the reader returns EOF. The read_from_func() method is incompatible with the append() method. Use one or the other, but not both.

This method should not be called after any vtbl member functions have been invoked on the PMX_MESSAGE object.