Documentation: agents/messages.php

class Messages - Process inbound mail messages

This script is triggered through the hook 'tick'. It scans one or more POP3 accounts and processes received messages.

* Mail accounts that are scanned are configured in agents/configure.php. Account information is stored in agents/parameters.include.php.

* Messages are transferred to the YACS server and deleted from the mail server. The number of fetched messages per tick is capped.

* Only associates and explicitly given mail boxes can use to send messages. Following keywords can also be used to enable 'any_member', 'any_subscriber', and 'anyone. Opening the door can be useful to catch error messages, but use this feature cautiously because of spammers.

* Security can be enforced through pattern matching on a per-queue basis. Useful to check that only a given mailing list server is using your e-mail address.

* Messages are parsed to break content into article components if any: introduction, source, section, categories, author.

* Messages tagged with either a article:123 or section:456 label are posted as comments of the referenced anchor. This feature is useful to capture thread information by e-mail. For example, support teams can label their e-mail messages to customers, to have these messages automatically recorded at the right place in the database.

* Articles can be auto-publish if the queue has been configured for that, if the target section is enabled for that, or if the server has been configured to work in Wiki-mode.

* Any mail message successfully processed is submitted to modules hooked to the id 'inbound_mail', and to any specific ids listed into the configuration field 'processing hooks'.

Message components are put in $context['mail_body'] and $context['mail_headers'] for further processing by included modules. Also, queue attributes are provided into $context['mail_queue'].

This design allows for generic hooks, bound on id 'inbound_mail', to process every input message. Also, particular mail processors can be defined on specific ids, and used only on selected mail queues.

Possible use of e-mail processing:

blogging - send a structured message and that's it - sender appears in the list of community members

importing data - subscribe to mailing lists and that's it - first application is to fetch and process security bulletins

asynchronous RPC - reporting to a central server for example

error catching - to identify invalid e-mail recipient addresses on newsletter sending

One application (suggested by Antoine) is to dispatch security bulletins collected by e-mail. A single agents/messages_dispatch_hook.php script is enough to achieve this. On mail reception, this script will extract keywords from mail body, and look for user profiles having one or more of these keywords in the 'interests' field. Then the script forwards the incoming message to each matching user, using the e-mail address mentioned in user profiles.

This script is hooked on id 'messages_dispatch' and, therefore, will be triggered only on queues having this id into their hook list.

Another application is to automatically disable invalid e-mail addresses. agents/messages_feedback_hook.php will be hooked on id 'messages_feedback'.

YACS parses input queues and uses regular expressions to locate weblog attributes. Following tags are allowed into a textual entity to be posted as a page:

* 'anchor' - the anchor for this post. Example: <anchor>section:234</anchor>.

* 'author' - the nick name or user id of the author. Example: <author>Alfred</author>.

* 'blogid' - an alias for 'section'

* 'categories' - a comma-separated list of categories for this post. Example: <categories>PHP, MySQL, Apache, interesting subjects</categories>.

* 'introduction' - text to be used as blog excerpt. Example: <introduction>Hello World</introduction>.

* 'section' - the id or the nick name of the section to be used Example: <section>news</section>.

* 'source' - reference link for this blog entry Example: <source>http://www.yetanothercommunitysystem.com/yacs/index.php</source>.

* 'title' - the title to use for this entry Example: <title>What'up doc?</title>.

Following parameters are used while processing inbound messages:

debug_messages - if set to Yes, then processed messages will be saved

for debugging purpose.

mail_queues[] - An array of mail accounts to poll.

Each entry has a name, and following attributes: server network address, account name, account password, default section, security match, processing options, processing hooks, prefix boundary, suffix boundary.

Following options may be used to change the behaviour of this script:

auto_publish to force the automatic publishing of articles received from this queue.

no_reply to not send a feed-back message. Useful when capturing data from mailing lists,

to avoid bouncing messages.

These parameters are set in agents/configure.php, and saved in agents/parameters.include.php.

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com

Testeurs:

Guillaume Perez

Reste à faire:

should be able to decode UTF-8 from YACS newsletters (dobliu)
strip HTML (dobliu)

decode() - Transform text back to its original format

function decode($text, $method)

$text - string the encoded text
$method - string the encoded method
returns the transformed string

According to RFC2045:

Three transformations are currently defined: identity, the "quoted- printable" encoding, and the "base64" encoding. The domains are "binary", "8bit" and "7bit".

The Content-Transfer-Encoding values "7bit", "8bit", and "binary" all mean that the identity (i.e. NO) encoding transformation has been performed. As such, they serve simply as indicators of the domain of the body data, and provide useful information about the sort of encoding that might be needed for transmission in a given transport system.

The quoted-printable and base64 encodings transform their input from an arbitrary domain into material in the "7bit" range, thus making it safe to carry over restricted transports.

Voir aussi:

MIME Extensions part one

parse_headers() - Unfold and decode message headers

function parse_headers($text)

$text - string some raw text
returns an array of decoded headers ('name' => $name, 'value' => $value)

Headers names and fields have to match RFC822 specification:

Once a field has been unfolded, it may be viewed as being com- posed of a field-name followed by a colon (":"), followed by a field-body, and terminated by a carriage-return/line-feed. The field-name must be composed of printable ASCII characters (i.e., characters that have values between 33. and 126., decimal, except colon). The field-body may be composed of any ASCII characters, except CR or LF. (While CR and/or LF may be present in the actual text, they are removed by the action of unfolding the field.)

Also, headers are supposed to be decoded according to RFC2047, more or less.

Voir aussi:

process_entity() - Process one entity

function process_entity($message_headers, $entity, $anchor=NULL)

$message_headers - array message headers
$entity - string the entity to be processed
$anchor=NULL - string the main anchor to attach found items

This function may process either the global message, or any embedded entity.

According to RFC 2046, the processing depends on content type.

The five discrete top-level media types are:

* text -- textual information. The subtype "plain" in particular indicates plain text containing no formatting commands or directives of any sort. Plain text is intended to be displayed "as-is". YACS attemps to create a page out of provided text.

* image -- image data. "Image" requires a display device (such as a graphical display, a graphics printer, or a FAX machine) to view the information. YACS stores the image entity in the file system, and creates an article to reference it.

* audio -- audio data. "Audio" requires an audio output device (such as a speaker or a telephone) to "display" the contents. YACS stores the audio entity in the file system, and creates an article to reference it.

* video -- video data. "Video" requires the capability to display moving images, typically including specialized hardware and software. YACS stores the video entity in the file system, and creates an article to reference it.

* application -- some other kind of data, typically either uninterpreted binary data or information to be processed by an application. YACS stores the entity in the file system, and creates an article to reference it.

* multipart -- data consisting of multiple entities of independent data types. YACS separate entities, attempts to locate an article, and attach all other entities to it.

* message -- an encapsulated message. A body of media type "message" is itself all or a portion of some kind of message object. YACS processes only sub types 'message/rfc822' and 'message/delivery-status', as plain text.

Voir aussi:

process_queue() - Process all messages from one mailbox

function process_queue($queue)

$queue - array of mailbox attributes ($server, $account, $password)
returns the number of processed messages

submit_container() - Create a page to host some other entity

function submit_container($message_headers, $type)

$message_headers - array of message attributes
$type - string the type of the attached entity
returns the anchor of created page, or NULL on error

This function is called when a message contains only binary entities. It is aiming to create a fake page to either embed posted images or to reference attached files.

submit_file() - Create an attached file

function submit_file($message_headers, $entity_headers, $content, $anchor)

$message_headers - array of message attributes
$entity_headers - array of entity attributes (e.g., 'Content-Disposition')
$content - string file actual content
$anchor - string the target anchor (e.g., 'article:123')

submit_image() - Create a referenced image

function submit_image($message_headers, $entity_headers, $content, $anchor)

$message_headers - array of message attributes
$entity_headers - array of entity attributes (e.g., 'Content-Disposition')
$content - string image actual content
$anchor - string the target anchor (e.g., 'article:123')

submit_page() - Create a page out of a textual entity

function submit_page($message_headers, $entity_headers, $text, $anchor=NULL)

$message_headers - array of message attributes
$entity_headers - array of entity attributes
$text - string the textual entity to process
$anchor=NULL - string an optional anchor (e.g., 'article:123')
returns the anchor of created page, if any

If no anchor is provided, this function will create an article. Else it will create a comment attached to the provided anchor.

tick_hook() - Process new messages, if any

function tick_hook()

returns a string to be displayed in resulting page, if any

This function checks inbound mailboxes, and process new messages on their arrival.

This function is aiming to run silently, therefore errors are logged in a file.