Next: Index Up: Sympa Mailing Lists Management Software version Previous: 27. Using Sympa commands Contents Index
Subsections

- 28.1 mail.pm
  - 28.1.1 public functions
  - 28.1.2 private functions
- 28.2 List.pm
  - 28.2.1 Functions for message distribution
  - 28.2.2 Functions for template sending
  - 28.2.3 Functions for service messages
  - 28.2.4 Functions for message notification
  - 28.2.5 Functions for topic messages
  - 28.2.6 Scenario evaluation
  - 28.2.7 Structure and access to list configuration parameters
- 28.3 sympa.pl
- 28.4 Commands.pm
  - 28.4.1 Commands processing
  - 28.4.2 tools for command processing
- 28.5 wwsympa.fcgi
- 28.6 report.pm
  - 28.6.1 Message diffusion
  - 28.6.2 Mail commands
  - 28.6.3 Web commands
- 28.7 tools.pl
- 28.8 Message.pm

#
28. Internals

This chapter describes these modules (or a part of) :

- `src/mail.pm` : low level of mail sending
- `src/List.pm` : list processing and informations about structure and access to list configuration parameters
- `src/sympa.pm` : the main script, for messages and mail commands processing.
- `src/Commands.pm` : mail commands processing
- `src/wwsympa.pm` : web interface
- `src/report.pm` : notification and error reports about requested services (mail and web)
- `src/tools.pm` : various tools
- `src/Message.pm` : Message object used to encapsule a received message.

#
28.1 mail.pm

This module deals with mail sending and does the SMTP job. It provides a function for message distribution to a list, the message can be encrypted. There is also a function to send service messages by parsing tt2 files, These messages can be signed. For sending, a call to sendmail is done or the message is pushed in a spool according to calling context.

## 28.1.1 public functions

mail_file(), mail_message(), mail_forward(), set_send_spool(), reaper().

###
28.1.1.1 mail_file()

Message is written by parsing a tt2 file (or with a string ). It writes mail headers if they are missing and they are encoded. Then the message is sent by calling mail::sending() function (see 28.1.2, page ).

IN :

1. `filename` : string - tt2 filename '' - no tt2 filename sent
2. `rcpt` (+) : SCALAR ref(ARRAY) - SMTP "RCPT To:" field
3. `data` (+) : ref(HASH) - used to parse tt2 file, contains header values, keys are :
   - `return_path` (+) : SMTP "MAIL From:" field if send by SMTP, q "X-Sympa-From:" field if send by spool
   - `to` : "To:" header field else it is $rcpt
   - `from` : "From:" field if $filename is not a full msg
   - `subject` : "Subject:" field if $filename is not a full msg
   - `replyto` : "Reply-to:" field if $filename is not a full msg
   - `headers` : ref(HASH), keys are other mail headers
   - `body` : body message if not $filename
   - `lang` : tt2 language if $filename
   - `list` : ref(HASH) if sign_mode='smime' - keys are :
     - `name` : list name
     - `dir` : list directory
4. `robot` (+) : robot
5. `sign_mode` : 'smime'- the mail is signed with smime undef - no signature

OUT : 1

###
28.1.1.2 mail_message()

Distributes a message to a list. The message is encrypted if needed, in this case, only one SMTP session is used for each recepient otherwise, recepient are grouped by domain for sending (it controls the number recepient arguments to call sendmail). Message is sent by calling mail::sendto() function (see 28.1.2, page ).

IN :

1. `message` (+) : ref(Message) - message to distribute
2. `from` (+) : message from
3. `robot` (+) : robot
4. `rcpt` (+) : ARRAY - recepients

OUT : `$numsmtp` = number of sendmail process undef

###
28.1.1.3 mail_forward()

Forward a message by calling mail::sending() function (see 28.1.2, page ).

IN :

1. `msg` (+) : ref(Message) ref(MIME::Entity) string - message to forward
2. `from` (+) : message from
3. `rcpt` (+) : ref(SCALAR) ref(ARRAY) - recepients
4. `robot` (+) : robot

OUT : 1 undef

###
28.1.1.4 set_send_spool()

Used by other processes than sympa.pl to indicate to send message by writting message in spool instead of calling mail::smtpto() function (see 28.1.2, page ). The concerned spool is set in `$send_spool` global variable, used by mail::sending() function (see 28.1.2, page ).

IN :

1. `spool` (+) : the concerned spool for sending.

OUT : -

###
28.1.1.5 reaper()

Non blocking function used to clean the defuncts child processes by waiting for them and then decreasing the counter. For exemple, this function is called by mail::smtpto() (see 28.1.2, page ), main loop of sympa.pl, task_manager.pl, bounced.pl.

IN :

1. `block`

OUT : the pid of the defunct process -1 if there is no such child process.

## 28.1.2 private functions

sendto(), sending(), smtpto().

###
28.1.2.1 sendto()

Encodes subject header. Encrypts the message if needed. In this case, it checks if there is only one recepient. Then the message is sent by calling mail::sending() function (see 28.1.2, page ).

IN :

1. `msg_header` (+) : ref(MIME::Head) - message header
2. `msg_body` (+) : message body
3. `from` (+) : message from
4. `rcpt` (+) : ref(SCALAR) ref(ARRAY) - message recepients (ref(SCALAR) for encryption)
5. `robot` (+) : robot
6. `encrypt` : 'smime_crypted' the mail is encrypted with smime undef - no encryption

OUT : 1 - sending by calling smtpto (sendmail) 0 - sending by push in spool undef

###
28.1.2.2 sending()

Signs the message according to `$sign_mode`. Chooses sending mode according to context. If `$send_spool` global variable is empty, the message is sent by calling mail::smtpto() function (see 28.1.2, page ) else the message is written in spool `$send_spool` in order to be handled by sympa.pl process (because only this is allowed to make a fork). When the message is pushed in spool, these mail headers are added :

- ``X-Sympa-To:'' : recepients
- ``X-Sympa-From:'' : from
- ``X-Sympa-Checksum:'' : to check allowed program to push in spool

A message pushed in spool like this will be handled later by sympa::DoSendMessage() function (see 28.3, page )

IN :

1. `msg` (+) : ref(MIME::Entity) string - message to send
2. `rcpt` (+) : ref(SCALAR) ref(ARRAY) - recepients (for SMTP : "RCPT To:" field)
3. `from` (+) : for SMTP : "MAIL From:" field for spool sending : "X-Sympa-From" field
4. `robot` (+) : robot
5. `listname` : listname ''
6. `sign_mode` (+) : 'smime' 'none'for signing
7. `sympa_email` : for the file name for spool sending

OUT : 1 - sending by calling smtpto() (sendmail) 0 - sending by pushing in spool undef

###
28.1.2.3 smtpto()

Calls to sendmail for the recipients given as argument by making a fork and an exec. Before, waits for number of children process number allowed by sympa.conf by calling mail::reaper() function (see 28.1.1, page ).

IN :

1. `from` (+) : SMTP "MAIL From:" field
2. `rcpt` (+) : ref(SCALAR)) ref(ARRAY) - SMTP "RCPT To:" field
3. `robot` (+) : robot

OUT : `mail::$fh` - file handle on opened file for ouput, for SMTP "DATA" field undef

#
28.2 List.pm

This module includes list processing functions.

Here are described functions about :

- Message distribution in a list
- Sending using templates
- Service messages
- Notification message
- Topic messages
- Scenario evaluation

Follows a description of structure and access on list parameters.

## 28.2.1 Functions for message distribution

distribute_message(), send_msg(), send_msg_digest().

These functions are used to message distribution in a list.

###
28.2.1.1 distribute_msg()

Prepares and distributes a message to a list :

- updates the list stats
- Loads information from message topic file if exists and adds X-Sympa-Topic header
- hides the sender if the list is anonymoused (list config : anonymous_sender) and changes name of msg topic file if exists.
- adds custom subject if necessary (list config : custom_subject)
- archives the message
- changes the reply-to header if necessary (list config : reply_to_header)
- removes unwanted headers if present (config : remove_headers))
- adds useful headers (X-Loop,X-Sequence,Errors-to,Precedence,X-no-archive - list config : custom_header)
- adds RFC 2919 header field (List-Id) and RFC 2369 header fields (list config : rfc2369_header_fields)
- stores message in digest if the list accepts digest mode (encrypted message can't be included in digest)
- sends the message by calling List::send_msg() (see 28.2.1, page ).

IN :

1. `self` (+) : ref(List) - the list concerned by distribution
2. `message` (+): ref(Message) - the message to distribute

OUT : result of List::send_msg() function (number of sendmail process)

###
28.2.1.2 send_msg()

This function is called by List::distribute_msg() (see 28.2.1, page ) to select subscribers according to their reception mode and to the ``Content-Type'' header field of the message. Sending are grouped according to their reception mode :

- normal : add a footer if the message is not protected (then the message is ``altered'') In a message topic context, selects only one who are subscribed to the topic of the message to distribute (calls to select_subcribers_for_topic(), see , page ).
- notice
- txt : add a footer
- html : add a footer
- urlize : add a footer and create an urlize directory for Web access

The message is sent by calling List::mail_message() (see 28.1.1, page ). If the message is ``smime_crypted'' and the user has not got any certificate, a message service is sent to him.

IN :

1. `self` (+) : ref(List) - the list concerned by distribution
2. `message` (+): ref(Message) - the message to distribute

OUT : `$numsmtp` : addition of mail::mail_message() function results ( = number of sendmail process ) undef

###
28.2.1.3 send_msg_digest()

Sends a digest message to the list subscribers with reception digest, digestplain or summary : it creates the list of subscribers in various digest modes and then creates the list of messages. Finally sending to subscribers is done by calling List::send_file() function (see 28.2.2, page ) with mail template ``digest'', ``digestplain'' or ``summary''.

IN :

1. `self` (+): ref(List) - the concerned list

OUT :

- 1 if sending
- 0 if no subscriber for sending digest, digestplain or summary
- undef

## 28.2.2 Functions for template sending

send_file(), send_global_file().

These functions are used by others to send files. These files are made from template given in parameters.

###
28.2.2.1 send_file()

Sends a message to a user, relative to a list. It finds the $tpl.tt2 file to make the message. If the list has a key and a certificat and if openssl is in the configuration, the message is signed. The parsing is done with variable $data set up first with parameter $context and then with configuration, here are set keys :

- if $who=SCALAR then
  - `user.password`
  - if $user key is not defined in $context then `user.email`(:= $who), `user.lang` (:= list lang) and if the user is in DB then `user.attributes` (:= attributes in DB user_table) are defined
  - if $who is subscriber of $self then `subscriber.date subscriber.update_date` and if exists then `subscriber.bounce subscriber.first_bounce` are defined
- `return_path` : used for SMTP ``MAIL From'' field or "X-Sympa-From:" field
- `lang` : the user lang or list lang or robot lang
- `fromlist` : "From:" field, pointed on list
- `from` : "From:" field, pointed on list if no defined in $context
- `replyto` : if openssl is is sympa.conf and the list has a key ('private_key') and a certificat ('cert.pem') in its directory
- `boundary` : boundary for multipart message if no contained in $context
- `conf.email conf.host conf.sympa conf.request conf.listmaster conf.wwsympa_url conf.title` : updated with robot config
- `list.lang list.name list.domain list.host list.subject list.dir list.owner`(ref(ARRAY)) : updated with list config

The message is sent by calling mail::mail_file() function (see 28.1.1, page ).

IN :

1. `self` (+) : ref(List)
2. `tpl` (+) : template file name without .tt2 extension ($tpl.tt2)
3. `who` (+) : SCALAR ref(ARRAY) - recepient(s)
4. `robot` (+) : robot
5. `context` : ref(HASH) - for the $data set up

OUT : 1 undef

###
28.2.2.2 send_global_file()

Sends a message to a user not relative to a list. It finds the $tpl.tt2 file to make the message. The parsing is done with variable $data set up first with parameter $context and then with configuration, here are set keys :

- `user.password user.lang`
- if $user key is not defined in $context then `user.email` (:= $who)
- `return_path` : used for SMTP ``MAIL From'' field or "X-Sympa-From:" field
- `lang` : the user lang or robot lang
- `from` : "From:" field, pointed on SYMPA if no defined in $context
- `boundary` : boundary for multipart message if no defined in $context
- `conf.email conf.host conf.sympa conf.request conf.listmaster conf.wwsympa_url conf.title` : updated with robot config
- `conf.version` : Sympa version
- `robot_domain` : the robot

The message is sent by calling mail::mail_file() function (see 28.1.1, page ).

IN :

1. `tpl` (+) : template file name (filename.tt2), without .tt2 extension
2. `who` (+) : SCALAR ref(ARRAY) - recepient(s)
3. `robot` (+) : robot
4. `context` : ref(HASH) - for the $data set up

OUT : 1 undef

## 28.2.3 Functions for service messages

archive_send(), send_to_editor(), request_auth(), send_auth().

These functions are used to send services messgase, correponding to a result of a command.

###
28.2.3.1 archive_send()

Sends an archive file ($file) to $who. The archive is a text file, independant from web archives. It checks if the list is archived. Sending is done by callingList::send_file() (see 28.2.2, page ) with mail template ``archive''.

IN :

1. `self` (+): ref(List) - the concerned list
2. `who` (+): recepient
3. `file` (+): name of the archive file to send

OUT : - undef

###
28.2.3.2 send_to_editor()

Sends a message to the list editor for a request concerning a message to distribute. The message awaiting for moderation is named with a key and is set in the spool queuemod. The key is a reference on the message for editor. The message for the editor is sent by calling List::send_file() (see 28.2.2, page ) with mail template ``moderate''. In msg_topic context, the editor is asked to tag the message.

IN :

1. `self` (+): ref(List) - the concerned list
2. `method` : 'md5' - for "editorkey" 'smtp' - for "editor"
3. `message` (+): ref(Message) - the message to moderate

OUT : $modkey - the moderation key for naming message waiting for moderation in spool queuemod. undef

###
28.2.3.3 request_auth()

Sends an authentification request for a requested command. The authentification request contains the command to be send next and it is authentified by a key. The message is sent to user by calling List::send_file() (see 28.2.2, page ) with mail template ``request_auth''.

IN :

1. `self` : ref(List) not required if $cmd = ``remind''.
2. `email`(+): recepient, the requesting command user
3. `cmd` :
   - if $self then 'signoff' 'subscribe' 'add' 'del' 'remind'
   - else 'remind'
4. `robot` (+): robot
5. `param` : ARRAY
   - 0 : used if $cmd ='subscribe' 'add' 'del' 'invite'
   - 1 : used if $cmd ='add'

OUT : 1 undef

###
28.2.3.4 send_auth()

Sends an authentifiaction request for a message sent for distribution. The message for distribution is copied in the authqueue spool to wait for confirmation by its sender . This message is named with a key. The request is sent to user by calling List::send_file() (see 28.2.2, page ) with mail template ``send_auth''. In msg_topic context, the sender is asked to tag his message.

IN :

1. `self`(+): ref(List) - the concerned list
2. `message`(+): ref(Message) - the message to confirm

OUT : $modkey, the key for naming message waiting for confirmation in spool queuemod. undef

## 28.2.4 Functions for message notification

send_notify_to_listmaster(), send_notify_to_owner(), send_notify_to_editor(), send_notify_to_user().

These functions are used to notify listmaster, list owner, list editor or user about events.

###
28.2.4.1 send_notify_to_listmaster()

Sends a notice to listmaster by parsing ``listmaster_notification'' template. The template makes a specified or a generic treatement according to variable $param.type (:= $operation parameter). The message is sent by calling List::send_file() (see 28.2.2, page ) or List::send_global_file() (see 28.2.2, page ) according to the context : global or list context. Available variables for the template are set up by this function, by $param parameter and by List::send_global_file() or List::send_file().

IN :

1. `operation` (+) : notification type, corresponds to $type in the template
2. `robot` (+): robot
3. `param` (+): ref(HASH) ref (ARRAY) - values for variable used in the template :
   - if ref(HASH) then variables used in the template are keys of this HASH. These following keys are required in the function, according to $operation value :
     - 'listname'(+) if $operation=('request_list_creation' 'automatic_bounce_management')
   - if ref(ARRAY) then variables used in template are named as : $param0, $param1, $param2, ...

OUT : 1 undef

###
28.2.4.2 send_notify_to_owner()

Sends a notice to list owner(s) by parsing ``listowner_notification'' template. The template makes a specified or a generic treatement according to variable $param.type ( := $operation parameter). The message is sent by calling List::send_file() (see 28.2.2, page ). Available variables for the template are set up by this function, by $param parameter and by List::send_file().

IN :

1. `self` (+): ref(List) - the list for owner notification
2. `operation` (+) : notification type, corresponds to $type in the template
3. `param` (+): ref(HASH) ref (ARRAY) - values for variable used in the template :
   - if ref(HASH) then variables used in the template are keys of this HASH.
   - if ref(ARRAY) then variables used in template are named as : $param0, $param1, $param2, ...

OUT : 1 undef

###
28.2.4.3 send_notify_to_editor()

Sends a notice to list editor(s) by parsing ``listeditor_notification'' template. The template makes a specified or a generic treatement according to variable $param.type ( := $operation parameter). The message is sent by calling List::send_file() (see 28.2.2, page ). Available variables for the template are set up by this function, by $param parameter and by List::send_file().

IN :

1. `self` (+): ref(List) - the list for editor notification
2. `operation` (+) : notification type, corresponds to $type in the template
3. `param` (+): ref(HASH) ref (ARRAY) - values for variable used in the template :
   - if ref(HASH) then variables used in the template are keys of this HASH.
   - if ref(ARRAY) then variables used in template are named as : $param0, $param1, $param2, ...

OUT : 1 undef

###
28.2.4.4 send_notify_to_user()

Sends a notice to a user by parsing ``user_notification'' template. The template makes a specified or a generic treatement according to variable $param.type ( := with $operation parameter). The message is sent by calling List::send_file() (see 28.2.2, page ). Available variables for the template are set up by this function, by $param parameter and by List::send_file().

IN :

1. `self` (+): ref(List) - the list for owner notification
2. `operation` (+) : notification type, corresponds to $type in the template
3. `user` (+) : user email to notify
4. `param` (+): ref(HASH) ref (ARRAY) - values for variable used in the template :
   - if ref(HASH) then variables used in the template are keys of this HASH.
   - if ref(ARRAY) then variables used in template are named as : $param0, $param1, $param2, ...

OUT : 1 undef

## 28.2.5 Functions for topic messages

is_there_msg_topic(), is_available_msg_topic(), get_available_msg_topic(), is_msg_topic_tagging_required, automatic_tag(), compute_topic(), tag_topic(), load_msg_topic_file(), modifying_msg_topic_for_subscribers(), select_subscribers_for_topic().

These functions are used to manages message topics.

N.B.: There is some exception to use some parameters : msg_topic.keywords for list parameters and topics_subscriber for subscribers options in the DB table. These parameters are used as string splitted by ',' but to access to each one, use the function tools::get_array_from_splitted_string() (see 28.7, page ) allows to access the enumeration.

###
28.2.5.1 is_there_msg_topic()

Tests if some message topic are defined (`msg_topic` list parameter, see , page ).

IN : `self` (+): ref(List)

OUT : 1 - some msg_topic are defined 0 - no msg_topic

###
28.2.5.2 is_available_msg_topic()

Checks for a topic if it is available in the list : look foreach `msg_topic.name` list parameter (see , page ).

IN :

1. `self` (+): ref(List)
2. `topic` (+) : the name of the requested topic

OUT : `topic` if it is available undef

###
28.2.5.3 get_available_msg_topic()

Returns an array of available message topics (`msg_topic.name` list parameter, see , page ).

IN : `self` (+): ref(List)

OUT : ref(ARRAY)

###
28.2.5.4 is_msg_topic_tagging_required()

Returns if the message must be tagged or not (`msg_topic_tagging` list parameter set to 'required', see , page ).

IN : `self` (+): ref(List)

OUT : 1 - the message must be tagged 0 - the msg can be no tagged

###
28.2.5.5 automatic_tag()

Computes topic(s) (with compute_topic() function) and tags the message (with tag_topic() function) if there are some topics defined.

IN :

1. `self` (+): ref(List)
2. `msg` (+): ref(MIME::Entity)- the message to tag
3. `robot` (+): robot

OUT : list of tagged topic : strings separated by ','. It can be empty. undef

###
28.2.5.6 compute_topic()

Computes topic(s) of the message. If the message is in a thread, topic is got from the previous message else topic is got from applying a regexp on the subject and/or the body of the message (`msg_topic_keywords_apply_on` list parameter, see, page ). Regexp is based on `msg_topic.keywords` list parameters (See , page ).

IN :

1. `self` (+): ref(List)
2. `msg` (+): ref(MIME::Entity)- the message to tag

OUT : list of computed topic : strings separated by ','. It can be empty.

###
28.2.5.7 tag_topic()

Tags the message by creating its topic information file in the `/usr/local/sympa-stable/spool/topic/` spool. The file contains the topic list and the method used to tag the message. Here is the format :

    TOPIC topicname,...
    METHOD editor|sender|auto

IN :

1. `self` (+): ref(List)
2. `msg_id` (+): string - the message ID of the message to tag
3. `topic_list` (+): the list of topics (strings splitted by ',')
4. `method` (+): 'auto' 'editor''sender' - the method used for tagging

OUT : name of the created topic information file (`directory/listname.msg_id`) undef

###
28.2.5.8 load_msg_topic_file()

Search and load msg topic file corresponding to the message ID (`directory/listname.msg_id`). It returns information contained inside.

IN :

1. `self` (+): ref(List)
2. `msg_id` (+): the message ID
3. `robot` (+): the robot

OUT : undef ref(HASH), keys are :

- `topic` : list of topics (strings separated by ',')
- `method` : 'auto' 'editor''sender' - the method used for tagging
- `msg_id` : message ID of the tagged message
- `filename` : name of the file

###
28.2.5.9 modifying_msg_topic_for_subscribers()

Deletes topics of subscriber that does not exist anymore and send a notify to concerned subscribers. (Makes a diff on msg_topic parameter between the list configuration before modification and a new state by calling tools::diff_on_arrays() function, see 28.7, page ). This function is used by wwsympa::do_edit_list().

IN :

1. `self` (+): ref(List) - the concerned list before modification
2. `new_msg_topic` (+) : ref(ARRAY) - new state of msg_topic parameters

OUT :

1. 1 if some subscriber topics have been deleted
2. 0 else

###
28.2.5.10 select_subscribers_for_topic()

Selects subscribers that are subscribed to one or more topic appearing in the topic list incoming when their reception mode is 'mail', and selects the other subscribers (reception mode different from 'mail'). This function is used by List::send_msg() function during message diffusion (see 28.2.1, page ).

IN :

1. `self` (+): ref(List)
2. `string_topic` (+): string splitted by ',' - the topic list
3. `subscribers` (+): ref(ARRAY) - list of subscriber emails

OUT : ARRAY - list of selected subscribers

##
28.2.6 Scenario evaluation

The following function is used to evaluate scenario file ```<`action`>`.`<`parameter_value`>`'', where `<`action`>`action corresponds to a configuration parameter for an action and `<`parameter_value`>` corresponds to its value.

### 28.2.6.1 request_action()

Return the action to perform for one sender using one authentication method to perform an operation

IN :

1. `operation` (+): SCALAR - the requested action corresponding to config parameter
2. `auth_method` (+): 'smtp''md5''pgp''smime'
3. `robot` (+): robot
4. `context` (): ref(HASH) - contains value to instantiate scenario variables (hash keys)
5. `debug` (): boolean - if true adds keys 'condition' and 'auth_method' to the returned hash.

OUT : undef ref(HASH) with keys :

- action : 'do_it''reject''request_auth''owner''editor''editorkey''listmaster'
- reason : 'value' if action == 'reject' in scenario and if there is reject(reason='value') to match a key in mail_tt2/authorization_reject.tt2. This is used in errors reports (see , page )
- tt2 : template name if action == 'reject' in scenario and there is reject(tt2='template_name').
- condition : the checked condition.
- auth_method : the checked auth_method.

## 28.2.7 Structure and access to list configuration parameters

List parameters are representated in the list configuration file, in the list object (`list->{'admin'}`) and on the Web interface. Here are translation and access functions :

|  | other (3) |  |
| (1) |  | (5) |
CONFIG FILE |  | LIST OBJECT |  | WEB INTERFACE
| (2) | (4) | (6) |

1. Loading file in memory :

        List::_load_admin_file(),_load_include_admin_user_file(),_load_list_param()

2. Saving list configuration in file :

        List::_save_admin_file(),_save_list_param()

3. Tools to get parameter values :

        List::get_param_value(),_get_param_value_anywhere(),_get_single_param_value()

4. Tools to initialize list parameter with defaults :

        List::_apply_default()

5. To present list parameters on the web interface :

        wwsympa::do_edit_list_request(),_prepare_edit_form(),_prepare_data()

6. To get updates on list parameters from the web interface :

        wwsympa::do_edit_list(),_check_new_value

List parameters can be simple or composed in paragraph, they can be unique or multiple and they can singlevalued or multivalued. Here are the different kinds of parameters and an exemple :

parameters | SIMPLE | COMPOSED
SINGLE | singlevalued | (a) | (b)
|  | lang | archiv.period
| multivalued | (c) | (d)
|  | topics | available_user_option.reception
MULTIPLE | singlevalued | (e) | (f)
|  | include_list | owner.email
| multi values | not defined | not defined

Here are these list parameters format in list configuration file in front of perl representation in memory :

| List Configuration FILE | `$list->{'admin'}`
(a) | param value | 'scalar'
(b) | param |
| p1 val1 | 'HASHscalar'
| p2 val2 |
(c) | param val1,val2,val3 | 'ARRAY(scalar & split_char)'
(d) | param |
| p1 val11, val12, val13 | 'HASHARRAY(scalar & split_char)'
| p2 val21, val22, val23 |
(e) | param val1 | 'ARRAY(scalar)'
| param val2 |
(d) | param |
| p1 val11 | 'ARRAY(HASHscalar)'
| p2 val12 |
| param |
| p1 val21 |
| p2 val22 |

#
28.3 sympa.pl

This is the main script ; it runs as a daemon and does the messages/commands processing. It uses these funstions : DoFile(), DoMessage(), DoCommand(), DoSendMessage(), DoForward(), SendDigest(), CleanSpool(), sigterm(), sighup().

Concerning reports about message distribution, function List::send_file() (see 28.2.2, page ) or List::send_global_file() (see 28.2.2, page ) is called with mail template ``message_report''. Concernong reports about commands, it is the mail template ``command_report''.

###
28.3.0.1 DoFile()

Handles a received file : function called by the sympa.pl main loop in order to process files contained in the queue spool. The file is encapsulated in a Message object not to alter it. Then the file is read, the header and the body of the message are separeted. Then the adequate function is called whether a command has been received or a message has to be redistributed to a list.

So this function can call various functions :

- sympa::DoMessage() for message distribution (see 28.3, page )
- sympa::DoCommand() for command processing (see 28.3, page )
- sympa::DoForward() for message forwarding to administrators (see 28.3, page )
- sympa::DoSendMessage() for wwsympa message sending (see 28.3, page ).

About command process a report can be sent by calling List::send_global_file() (see 28.2.2, page ) with template ``command_report''. For message report it is the template ``message_report''.

IN : `file`(+): the file to handle

OUT : $status - result of the called function undef

###
28.3.0.2 DoMessage()

Handles a message sent to a list (Those that can make loop and those containing a command are rejected). This function can call various functions :

- List::distribute_msg() for distribution (see 28.2.1, page )
- List::send_auth() for authentification or topic tagging by message sender(see 28.2.3, page )
- List::send_to_editor() for moderation or topic tagging by list moderator(see 28.2.3, page ).
- List::automatic_tag() for automatic topic tagging (see 28.2.5, page ).

IN :

1. `which`(+): 'list_name@domain_name - the concerned list
2. `message`(+): ref(Message) - sent message
3. `robot`(+): robot

OUT : 1 if everything went fine in order to remove the file from the queue undef

###
28.3.0.3 DoCommand()

Handles a command sent to sympa. The command is parse by calling Commands::parse() (see 28.4.1, page ).

IN :

1. `rcpt` : recepient `<`listname`>`-`<`subscribeunsubscribe`>`
2. `robot`(+): robot
3. `msg`(+): ref(MIME::Entity) - message containing the command
4. `file`(+): file containing the message

OUT : $success - result of Command::parse() function undef.

###
28.3.0.4 DoSendMessage()

Sends a message pushed in spool by another process (ex : wwsympa.fcgi) by calling function mail::mail_forward() (see 28.1.1, page ).

IN :

1. `msg`(+): ref(MIME::Entity)
2. `robot`(+): robot

OUT : 1 undef

###
28.3.0.5 DoForward()

Handles a message sent to `<`listname`>`-editor : the list editor, `<`list`>`-request : the list owner or the listmaster. The message is forwarded according to $function by calling function mail::mail_forward() (see 28.1.1, page ).

IN :

1. `name`(+): list name if ($function != 'listmaster')
2. `function`(+): 'listmaster' 'request' 'editor'
3. `robot`(+): robot
4. `msg`(+): ref(MIME::Entity)

OUT : 1 undef

###
28.3.0.6 SendDigest()

Reads the queuedigest spool and send old digests to the subscribers with the digest option by calling List::send_msg_digest() function mail::mail_forward() (see 28.2.1, page ).

IN : - OUT : - undef

###
28.3.0.7 CleanSpool()

Cleans old files from spool $spool_dir older than $clean_delay.

IN :

1. `spool_dir`(+) : the spool directory
2. `clean_delay`(+) : the delay in days

OUT : 1

###
28.3.0.8 sigterm()

This function is called when a signal -TERM is received by sympa.pl. It just changes the value of $signal loop variable in order to stop sympa.pl after endding its message distribution if in progress. (see 4.3, page )

IN : - OUT : -

###
28.3.0.9 sighup()

This function is called when a signal -HUP is received by sympa.pl. It changes the value of $signal loop variable and switchs of the "-mail" (see 4.3, page ) logging option and continues current task.

IN : - OUT : -

#
28.4 Commands.pm

This module does the mail commands processing.

## 28.4.1 Commands processing

parse(), add(), del(), subscribe(), signoff(), invite(), last(), index(), getfile(), confirm(), set(), distribute(), reject(), modindex(), review(), verify(), remind(), info(), stats(), help(), lists(), which(), finished().

###
28.4.1.1 parse()

Parses the command line and calls the adequate subroutine (following functions) with the arguments of the command. This function is called by sympa::DoCommand() (see 28.3, page ).

IN :

1. `sender`(+): the command sender
2. `robot`(+): robot
3. `i`(+): command line
4. `sign_mod` : 'smime' undef

OUT : 'unknown_cmd' $status - command process result

###
28.4.1.2 add()

Adds a user to a list (requested by another user), and can send acknowledgements. New subscriber can be notified by sending template 'welcome'.

IN :

1. `what`(+): command parameters : listname, email and comments eventually
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef

###
28.4.1.3 del()

Removes a user to a list (requested by another user), and can send acknowledgements. Unsubscriber can be notified by sending template 'removed'.

IN :

1. `what`(+): command parameters : listname and email
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1

###
28.4.1.4 subscribe()

Subscribes a user to a list. New subscriber can be notified by sending him template 'welcome'.

IN :

1. `what`(+): command parameters : listname and comments eventually
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef

###
28.4.1.5 signoff()

Unsubscribes a user from a list. He can be notified by sending him template 'bye'.

IN :

1. `which`(+): command parameters : listname and email
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 'syntax_error' 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef

###
28.4.1.6 invite()

Invites someone to subscribe to a list by sending him the template 'invite'.

IN :

1. `what`(+): command parameters : listname, email and comments
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef

###
28.4.1.7 last()

Sends back the last archive file by calling List::archive_send() function (see 28.2.3, page ).

IN :

1. `which`(+): listname
2. `robot`(+): robot

OUT : 'unknown_list' 'no_archive' 'not_allowed' 1

###
28.4.1.8 index()

Sends the list of archived files of a list.

IN :

1. `which`(+): listname
2. `robot`(+): robot

OUT : 'unknown_list' 'no_archive' 'not_allowed' 1

###
28.4.1.9 getfile()

Sends back the requested archive file by calling List::archive_send() function (see 28.2.3, page ).

IN :

1. `which`(+): commands parameters : listname and filename(archive file)
2. `robot`(+): robot

OUT : 'unknown_list' 'no_archive' 'not_allowed' 1

###
28.4.1.10 confirm()

Confirms the authentification of a message for its distribution on a list by calling function List::distribute_msg() for distribution (see 28.2.1, page ) or by calling List::send_to_editor() for moderation (see , page ).

IN :

1. `what`(+): authentification key (command parameter)
2. `robot`(+): robot

OUT : 'wrong_auth' 'msg_not_found' 1 undef

###
28.4.1.11 set()

Changes subscription options (reception or visibility)

IN :

1. `what`(+): command parameters : listname and reception mode (digestdigestplainnomailnormal...) or visibility mode(concealnoconceal).
2. `robot`(+): robot

OUT : 'syntax_error' 'unknown_list' 'not_allowed' 'failed' 1

###
28.4.1.12 distribute()

Distributes the broadcast of a validated moderated message.

IN :

1. `what`(+): command parameters : listname and authentification key
2. `robot`(+): robot

OUT : 'unknown_list' 'msg_not_found' 1 undef

###
28.4.1.13 reject()

Refuses and deletes a moderated message. Rejected message sender can be notified by sending him template 'reject'.

IN :

1. `what`(+): command parameters : listname and authentification key
2. `robot`(+): robot

OUT : 'unknown_list' 'wrong_auth' 1 undef

###
28.4.1.14 modindex()

Sends a list of current messages to moderate of a list (look into spool queuemod) by using template 'modindex'.

IN :

1. `name`(+): listname
2. `robot`(+): robot

OUT : 'unknown_list' 'not_allowed' 'no_file' 1

###
28.4.1.15 review()

Sends the list of subscribers of a list to the requester by using template 'review'.

IN :

1. `listname`(+): list name
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 'unknown_list' wrong_auth no_subscribers 'not_allowed' 1 undef

###
28.4.1.16 verify()

Verifies an S/MIME signature.

IN :

1. `listname`(+): list name
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 1

###
28.4.1.17 remind()

Sends a personal reminder to each subscriber of a list or of every list (if $which = *) using template 'remind' or 'global_remind'.

IN :

1. `which`(+): * listname
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 'syntax_error' 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef

###
28.4.1.18 info()

Sends the list information file to the requester by using template 'info_report'.

IN :

1. `listname`(+): name of concerned list
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef

###
28.4.1.19 stats()

Sends the statistics about a list using template 'stats_report'.

IN :

1. `listname`(+): list name
2. `robot`(+): robot
3. `sign_mod` : 'smime' undef - authentification

OUT : 'unknown_list' 'not_allowed' 1 undef

###
28.4.1.20 help()

Sends the help file for the software by using template 'helpfile'.

IN :

1. : ?
2. `robot`(+): robot

OUT : 1 undef

###
28.4.1.21 lists()

Sends back the list of public lists on this node by using template 'lists'.

IN :

1. : ?
2. `robot`(+): robot

OUT : 1 undef

###
28.4.1.22 which()

Sends back the list of lists that sender is subscribed to. If he is owner or editor, managed lists are noticed. Message is sent by using template 'which'.

IN :

1. : ?
2. `robot`(+): robot

OUT : 1

###
28.4.1.23 finished()

Called when 'quit' command is found. It sends a notification to sender : no process will be done after this line.

IN : -

OUT : 1

## 28.4.2 tools for command processing

get_auth_method()

###
28.4.2.1 get_auth_method()

Called by processing command functions to return the authentification method and to check the key if it is 'md5' method.

IN :

1. `cmd`(+): requesting command
2. `email`(+): used to compute auth if needed in command
3. `error`(+): ref(HASH) - keys are :
   - `type` : $type for ``message_report'' template parsing
   - `data` : ref(HASH) for ``message_report'' template parsing
   - `msg` : for do_log()
4. `sign_mod`(+): 'smime' - smime authentification undef - smtp or md5 authentification
5. `list`: ref(List) undef - in a list context or not

OUT : 'smime' 'md5' 'smtp' - authentification method if checking not failed undef

#
28.5 wwsympa.fcgi

This script provides the web interface to Sympa.

do_subscribe(), do_signoff(), do_add(), do_del(), do_change_email(), do_reject(), do_send_mail(), do_sendpasswd(), do_remind(), do_set(), do_send_me(), do_request_topic(), do_tag_topic_by_sender().

###
28.5.0.1 do_subscribe()

Subscribes a user to a list. New subscriber can be notified by sending him template 'welcome'.

- IN : -
- OUT : 'subrequest' 'login' 'info' $in.previous_action undef

###
28.5.0.2 do_signoff()

Unsubscribes a user from a list. The unsubscriber can be notified by sending him template 'bye'.

- IN : -
- OUT : 'sigrequest' 'login' 'info' undef

###
28.5.0.3 do_add()

Adds a user to a list (requested by another user) and can send acknowledgements. New subscriber can be notified by sending him template 'welcome'.

- IN : -
- OUT : 'loginrequest' ($in.previous_action 'review') undef

###
28.5.0.4 do_del()

Removes a user from a list (requested by another user) and can send acknowledgements. Unsubscriber can be notified by sending template 'removed'.

- IN : -
- OUT : 'loginrequest' ($in.previous_action 'review') undef

###
28.5.0.5 do_change_email()

Changes a user's email address in Sympa environment. Password can be send to user by sending template 'sendpasswd'.

- IN : -
- OUT : '1' 'pref' undef

###
28.5.0.6 do_reject()

Refuses and deletes moderated messages. Rejected message senders are notified by sending them template 'reject'.

- IN : -
- OUT : 'loginrequest' 'modindex' undef

###
28.5.0.7 do_distribute()

Distributes moderated messages by sending a command DISTRIBUTE to sympa.pl. For it, it calls mail::mail_file() (see 28.1.1, page ). As it is in a Web context, the message will be set in spool. In a context of message topic, tags the message by calling to function List::tag_topic() (see 28.2.5, page ).

- IN : -
- OUT : 'loginrequest' 'modindex' undef

###
28.5.0.8 do_modindex()

Allows a moderator to moderate a list of messages and documents and/or tag message in message topic context.

- IN : -
- OUT : 'loginrequest' 'admin' 1 undef

###
28.5.0.9 do_viewmod()

Allows a moderator to moderate a message and/or tag message in message topic context.

- IN : -
- OUT : 'loginrequest' 1 undef

###
28.5.0.10 do_send_mail()

Sends a message to a list by the Web interface. It uses mail::mail_file() (see 28.1.1, page ) to do it. As it is in a Web context, the message will be set in spool.

- IN : -
- OUT : 'loginrequest' 'info' undef

###
28.5.0.11 do_sendpasswd()

Sends a message to a user, containing his password, by sending him template 'sendpasswd' list by the Web interface.

- IN : -
- OUT : 'loginrequest' 'info' undef

###
28.5.0.12 do_request_topic()

Allows a sender to tag his mail in message topic context.

- IN : -
- OUT : 'loginrequest' 1 undef

###
28.5.0.13 do_tag_topic_by_sender()

Tags a message by its sender by calling List::tag_topic() and allows its diffusion by sending a command CONFIRM to sympa.pl.

- IN : -
- OUT : 'loginrequest' 'info' undef

###
28.5.0.14 do_remind()

Sends a command remind to sympa.pl by calling mail::mail_file() (see 28.1.1, page ). As it is in a Web context, the message will be set in spool.

- IN : -
- OUT : 'loginrequest' 'admin' undef

###
28.5.0.15 do_set()

Changes subscription options (reception or visibility)

- IN : -
- OUT : 'loginrequest' 'info' undef

###
28.5.0.16 do_send_me()

Sends a web archive message to a requesting user It calls mail::mail_forward() to do it (see 28.1.1, page ). As it is in a Web context, the message will be set in spool.

- IN : -
- OUT : 'arc' 1 undef

#
28.6 report.pm

This module provides various tools for notification and error reports in every Sympa interface (mail diffusion, mail command and web command).

For a requested service, there are four kinds of reports to users:

- success notification
  when the action does not involve any specific mail report or else, the user is notified of the well done of the processus.
- non authorization`(auth)`
  a user is not allowed to perform an action, Sympa provides reason of rejecting. The template used to provides this information is `mail_tt2/authorization_reject.tt2`. It contains a list of reasons, indexed by keywords that are mentioned in reject action scenario (see 13.1, page )
- user error`(user)`
  a error caused by the user, the user is informed about the error reason
- internal server error`(intern)`
  an error independent from the user, the user is succintly informed about the error reason but a mail with more information is sent to listmaster using template `mail_tt2/listmaster_notification.tt2`(If it is not necessary, keyword used is `'intern_quiet'`.

For other reports than non authorizations templates used depends on the interface :

- message diffusion : `mail_tt2/message_report.tt2`
- mail commands : `mail_tt2/command_report.tt2`
- web commands : `web_tt2/notice.tt2` for positive notifications and `web_tt2/error.tt2` for rejects.

##
28.6.1 Message diffusion

These reports use template `mail_tt2/message_report.tt2` and there are two functions : `reject_report_msg()` and `notice_report_msg()`.

###
28.6.1.1 reject_report_msg()

Sends a notification to the user about an error rejecting his requested message diffusion.

IN :

1. `type`(+): 'intern''intern_quiet''user''auth' - the error type
2. `error`: SCALAR - depends on $type :
   - 'intern' : string error sent to listmaster
   - 'user' : $entry in `message_report.tt2`
   - 'auth' : $reason in `authorization_reject.tt2`
3. `user`(+): SCALAR - the user to notify
4. `param`: ref(HASH) - for variable instantiation `message_report.tt2` (key `msgid`(+) is required if type == 'intern')
5. `robot`: SCALAR - robot
6. `msg_string`: SCALAR - rejected message
7. `list`: ref(List) - in a list context

OUT : 1 undef

###
28.6.1.2 notice_report_msg()

Sends a notification to the user about a success about his requested message diffusion.

IN :

1. `entry`(+): $entry in `message_report.tt2`
2. `user`(+): SCALAR - the user to notify
3. `param`: ref(HASH) - for variable instantiation `message_report.tt2`
4. `robot`(+): SCALAR - robot
5. `list`: ref(List) - in a list context

OUT : 1 undef

##
28.6.2 Mail commands

A mail can contains many commands. Errors and notices are stored in module global arrays before sending (intern_error_cmd, user_error_cmd, global_error_cmd, auth_reject_cmd, notice_cmd). Moreover used errors here we can have global errors on mail containing commands, so there is a function for that. These reports use template `mail_tt2/command_report.tt2` and there are many functions :

###
28.6.2.1 init_report_cmd()

Inits global arrays for mail command reports.

IN : -

OUT : -

###
28.6.2.2 is_there_any_report_cmd()

Looks for some mail command reports in one of global arrays.

IN : -

OUT : 1 if there are some reports to send

###
28.6.2.3 global_report_cmd()

Concerns global reports of mail commands. There are many uses cases :

1. internal server error for a differed sending at the end of the mail processing :
   - `global_report_cmd('intern',$error,$data,$sender,$robot)`
   - `global_report_cmd('intern_quiet',$error,$data)` : the listmaster won't be noticied
2. internal server error for sending every reports directly (by calling `send_report_cmd()`) :
   - `global_report_cmd('intern',$error,$data,$sender,$robot,1)`
   - `global_report_cmd('intern_quiet',$error,$data,$sender,$robot,1)` : the listmaster won't be noticied
3. user error for a differed sending at the end of the mail processing :
   `global_report_cmd('user',$error,$data`
4. user error for sending every reports directly (by calling `send_report_cmd()`) :
   `global_report_cmd('user',$error,$data,$sender,$robot,1)`

IN :

1. `type`(+): 'intern''intern_quiet''user'
2. `error`: SCALAR - depends on $type :
   - 'intern' : string error sent to listmaster
   - 'user' : $glob.entry in `command_report.tt2`
3. `data`: ref(HASH) - for variable instantiation in `command_report.tt2`
4. `sender`: SCALAR - the user to notify
5. `robot`: SCALAR - robot
6. `now`: BOOLEAN - send reports now if true

OUT : 1 undef

###
28.6.2.4 reject_report_cmd()

Concerns reject reports of mail commands. These informations are sent at the end of the mail processing. There are many uses cases :

1. internal server error :
   - `reject_report_cmd('intern',$error,$data,$cmd,$sender,$robot)`
   - `reject_report_cmd('intern_quiet',$error,$data,$cmd)` : the listmaster won't be noticied
2. user error :
   `reject_report_cmd('user',$error,$data,$cmd)`
3. non authorization :
   `reject_report_cmd('auth',$error,$data,$cmd)`

IN :

1. `type`(+): 'intern''intern_quiet''user''auth'
2. `error`: SCALAR - depends on $type :
   - 'intern' : string error sent to listmaster
   - 'user' : $u_err.entry in `command_report.tt2`
   - 'auth' : $reason in `authorization_reject.tt2`
3. `data`: ref(HASH) - for variable instantiation in `command_report.tt2`
4. `cmd`: SCALAR - the rejected command, $xx.cmd in `command_report.tt2`
5. `sender`: SCALAR - the user to notify
6. `robot`: SCALAR - robot

OUT : 1 undef

###
28.6.2.5 notice_report_cmd()

Concerns positive notices of mail commands. These informations are sent at the end of the mail processing.

IN :

1. `entry`: $notice.entry in `command_report.tt2`
2. `data`: ref(HASH) - for variable instantiation in `command_report.tt2`
3. `cmd`: SCALAR - the rejected command, $xx.cmd in `command_report.tt2`

OUT : 1 undef

###
28.6.2.6 send_report_cmd()

Sends the template `command_report.tt2` to $sender with global arrays and then calls to `init_report_command.tt2` function. (It is used by sympa.pl at the end of mail process if there are some reports in gloal arrays)

IN :

1. `sender`(+): SCALAR - the user to notify
2. `robot`(+): SCALAR - robot

OUT : 1

##
28.6.3 Web commands

It can have many errors and notices so they are stored in module global arrays before html sending. (intern_error_web, user_error_web, auth_reject_web, notice_web). These reports use `web_tt2/notice.tt2` template for notices and `web_tt2/error.tt2` template for rejects.

###
28.6.3.1 init_report_web()

Inits global arrays for web command reports.

IN : -

OUT : -

###
28.6.3.2 is_there_any_reject_report_web()

Looks for some rejected web command reports in one of global arrays for reject.

IN : -

OUT : 1 if there are some reject reports to send (not notice)

###
28.6.3.3 get_intern_error_web()

Return array of web intern error

IN : -

OUT : ref(ARRAY) - clone of intern_error_web

###
28.6.3.4 get_user_error_web()

Return array of web user error

IN : -

OUT : ref(ARRAY) - clone of user_error_web

###
28.6.3.5 get_auth_reject_web()

Return array of web authorisation reject

IN : -

OUT : ref(ARRAY) - clone of auth_reject_web

###
28.6.3.6 get_notice_web()

Return array of web notice

IN : -

OUT : ref(ARRAY) - clone of notice_web

###
28.6.3.7 reject_report_web()

Concerning reject reports of web commands, there are many uses cases :

1. internal server error :
   - `reject_report_web('intern',$error,$data,$action,$list,$user,$robot)`
   - `reject_report_web('intern_quiet',$error,$data,$action,$list)` : the listmaster won't be noticied
2. user error :
   `reject_report_web('user',$error,$data,$action, $list)`
3. non authorization :
   `reject_report_web('auth',$error,$data,$action, $list)`

IN :

1. `type`(+): 'intern''intern_quiet''user''auth'
2. `error`(+): SCALAR - depends on $type :
   - 'intern' : $error in `listmaster_notification.tt2` and possibly $i_err.msg in `error.tt2`
   - 'intern_quiet' : possibly $i_err.msg in `error.tt2`
   - 'user' : $u_err.msg in `error.tt2`
   - 'auth' : $reason in `authorization_reject.tt2`
3. `data`: ref(HASH) - for variable instantiation in `notice.tt2`
4. `action`(+): SCALAR - the rejected actin, $xx.action in `error.tt2`, $action in `listmaster_notification.tt2`
5. `list`: '' ref(List)
6. `user`: SCALAR - the user for listmaster notification
7. `robot`: SCALAR - robot for listmaster notification

OUT : 1 undef

###
28.6.3.8 notice_report_web()

Concerns positive notices of web commands.

IN :

1. `msg`: $notice.msg in `notice.tt2`
2. `data`: ref(HASH) - for variable instantiation in `notice.tt2`
3. `action`: SCALAR - the noticed command, $notice.cmd in `notice.tt2`

OUT : 1 undef

#
28.7 tools.pl

This module provides various tools for Sympa.

###
28.7.0.1 checkcommand()

Checks for no command in the body of the message. If there are some command in it, it returns true and sends a message to $sender by calling List::send_global_file() (see 28.2.2, page ) with mail template ``message_report''.

IN :

1. `msg`(+): ref(MIME::Entity) - the message to check
2. `sender`(+): the message sender
3. `robot`(+): robot

OUT :

- 1 if there are some command in the message
- 0 else

###
28.7.0.2 get_array_from_splitted_string()

Return an array made from a string splitted by ','. It removes spaces.

IN : `string`(+): string to split

OUT : ref(ARRAY) -

###
28.7.0.3 diff_on_arrays()

Makes set operation on arrays seen as set (with no double) :

IN :

1. `A`(+): ref(ARRAY) - set
2. `B`(+): ref(ARRAY) - set

OUT : ref(HASH) with keys :

- deleted : A B
- added : B A
- intersection : A B
- union : A B

###
28.7.0.4 clean_msg_id()

Cleans a msg_id to use it without '
n', '
s', < and >.

IN : `msg_id`(+): the message id

OUT : the clean msg_id

###
28.7.0.5 clean_email()

Lower-case it and remove leading and trailing spaces.

IN : `msg_id`(+): the email

OUT : the clean email

###
28.7.0.6 make_tt2_include_path()

Make an array of include path for tt2 parsing

IN :

1. `robot`(+): SCALAR - the robotset
2. `dir`: SCALAR - directory ending each path
3. `lang`: SCALAR - for lang directories
4. `list`: ref(List) - for list directory

OUT : ref(ARRAY) - include tt2 path, respecting path priorities.

#
28.8 Message.pm

This module provides objects to encapsulate file message in order to prevent it from its alteration for using signatures.

###
28.8.0.1 new()

Creates an object Message and initialize it :

- `msg` : ref(MIME::Entity)
- `altered` if the message is altered
- `filename` : the file containing the message
- `size` : the message size
- `sender` : the first email address, in the 'From' field
- `decoded_subject` : the 'Subject' field decoded by MIME::Words::decode_mimewords
- `subject_charset` : the charset used to encode the 'Subject' field
- `rcpt` : the 'X-Sympa-To' field
- `list` : ref(List) if it is a message no addressed to Sympa or a listmaster
- `topic` : the 'X-Sympa-Topic' field.
- in a 'openssl' context - decrypt message :
  - `smime_crypted` : 'smime_crypted' if it is in a 'openssl' context
  - `orig_msg` : ref(MIME::Entity) - crypted message
  - `msg` : ref(MIME::Entity) - decrypted message (see tools::smime_decrypt())
  - `msg_as_string` : string - decrypted message (see tools::smime_decrypt())
- in a 'openssl' context - check signature :
  - `protected` : 1 if the message should not be altered
  - `smime_signed` : 1 if the message is signed
  - `smime_subject` : ref(HASH)if the message is signed - information on the signer see tools::smime_parse_cert().

IN :

1. `pkg`(+): Message
2. `file`(+): the message file

OUT : ref(Message) undef

###
28.8.0.2 dump()

Dump the message object in the file descriptor $output

IN :

1. `self`(+): ref(Message)
2. `output`(+): file descriptor

OUT : '1'

###
28.8.0.3 add_topic()

Adds the message topic in the Message object (`topic'` and adds the 'X-Sympa-Topic' field in the ref(MIME::Entity) `msg'`.

IN :

1. `self`(+): ref(Message)
2. `topic`(+): string splitted by ',' - list of topic

OUT : '1'

###
28.8.0.4 get_topic()

Returns the topic(s) of the message

IN : `self`(+): ref(Message)

OUT : '' if no message topic | string splitted by ',' if message topic

N.B.:

- (+) : required parameter, value must not be empty
- : ``or'' for parameters value
- $ : reference to code parameters or variables
- condition for parameter

Next: Index Up: Sympa Mailing Lists Management Software version Previous: 27. Using Sympa commands Contents Index