PMX_MESSAGE Methods

Many of the PMX_MESSAGE accessor methods return parts of the message. The returned data may be a copy of the original message data, or just a pointer and a length into the internal message buffer. For this reason, the returned data cannot be guaranteed to be '\0' terminated. The engine always treats all returned data as read only. It also calls the message's free() method on the returned data, just in case the implementation returns a copy that must be deallocated, which is the case for the default Perl implementation.

free()
void (*free)(PMX_MESSAGE m, char *chunk);
The chunk returned by the various message methods must be freed by the caller before the PMX_MESSAGE object is destroyed.
get_message_size()
PMX_ERROR (*get_message_size)(PMX_MESSAGE m, size_t *sz);
Returns the size of the raw message, in bytes.
get_message()
PMX_ERROR (*get_message)(PMX_MESSAGE m, size_t offset, size_t len,
                         const char **chunk, size_t *sz);
Returns a chunk of the raw message, starting at offset, of length len bytes. If len is zero, returns the rest of the message from offset. The chunk is returned in chunk, and the length of the string is returned in sz.
get_envelope_sender()
PMX_ERROR (*get_envelope_sender)(PMX_MESSAGE m, const char **sender,
                                 size_t *sz);
Returns the envelope sender.

The default implementation of the PMX_MESSAGE object does not maintain any envelope information.

enumerate_envelope_recipients()
int (*enumerate_envelope_recipients)(PMX_MESSAGE m, PMX_RCPT_CB cb,
     void *host);
Invokes the callback cb for each recipient named.
get_header_size()
PMX_ERROR (*get_header_size)(PMX_MESSAGE m, size_t *sz);
Returns the size of the RFC 822 header block, in bytes. Returns 0 if the raw header block is not available.
get_header()
PMX_ERROR (*get_header)(PMX_MESSAGE m, size_t offset, size_t len,
                        const char **chunk, size_t *sz);
Fetch a chunk of the raw RFC 822 header block, if available. If len is zero, returns the rest of the header block from offset.
enumerate_headers()
int (*enumerate_headers)(PMX_MESSAGE m, const char *header,
                         PMX_HEADER_CB cb, void *host);
Invokes the callback cb for each header named header. If header is NULL, invokes cb on every header.
get_body_size()
PMX_ERROR (*get_body_size)(PMX_MESSAGE m, size_t *sz);
Returns the size of the body in bytes.
get_body()
PMX_ERROR (*get_body)(PMX_MESSAGE m, size_t offset, size_t len,
                      const char **chunk, size_t *sz);
Returns a chunk of the raw body starting at offset with length len bytes. If len is zero, returns the rest of the body.
get_decoded_body()
PMX_ERROR (*get_decoded_body)(PMX_MESSAGE m, size_t offset, size_t len,
                              const char **chunk, size_t *sz);
Returns a chunk of the decoded body starting at offset with length len bytes. If len is zero, returns the rest of the decoded body.

The decoded body undoes base-64 and quoted-printable encodings.

enumerate_parts()
int (*enumerate_parts)(PMX_MESSAGE m, PMX_PART_CB cb, void *host);
Invokes the callback cb for each subpart of the message object. Each subpart is represented by its own PMX_MESSAGE object passed to the callback. The part object is only valid during the lifetime of the callback. It cannot be saved.
get_relay()
PMX_ERROR (*get_relay)(PMX_MESSAGE m, const char **ip, size_t *sz);
Returns the IP address of the connecting relay as a string. The default message implementation always returns PMX_ERR_NOATTR, which the engine interprets as a signal not to perform relay checks.
get_relay_hostname()
PMX_ERROR (*get_relay_hostname)(PMX_MESSAGE m, const char **hostname,
                                size_t *sz);
Returns the hostname of the connecting relay as a string, or the empty string (a size of zero) if the relay has no hostname. If implemented, the result of performing a reverse DNS lookup on the connecting relay's IP address (the one returned from the get_relay() method). The SDK treats this hostname as unforgable, thus suitable for whitelisting and blacklisting. The default message implementation always returns PMX_ERR_NOATTR, which the engine interprets as a signal not to perform hostname checks or its own DNS lookup.
get_helo()
PMX_ERROR (*get_helo)(PMX_MESSAGE m, const char **helo, size_t *sz);
Returns the SMTP HELO line from the SMTP transaction as a string.

The default message implementation always returns PMX_ERR_NOATTR, which the engine interprets as a signal not to perform helo checks.