Sympa(3Sympa)

NAME
Sympa - Future base class of Sympa functional objects

DESCRIPTION
This module aims to be the base class for functional objects of Sympa: Site, Robot, Family and List.

  Functions
Handling the Authentication Token

compute_auth
        # To compute site-wide token
        Sympa::compute_auth(('*', 'user@dom.ain', 'remind');
        # To cpmpute a token specific to a list
        Sympa::compute_auth($list, 'user@dom.ain', 'subscribe');

    Genererate a MD5 checksum using private cookie and parameters.

    Parameters:

    $that
        Sympa::List, Robot or Site.

    $email
        Recipient (the person who asked for the command).

    $cmd
        XXX

    Returns:

    Authenticaton key.

request_auth
        # To send robot or site auth request
        Sympa::request_auth('*', 'user@dom.ain', 'remind');
        # To send auth request specific to a list
        Sympa::request_auth($list, 'user@dom.ain', 'subscribe'):

    Sends an authentication request for a requested command.

    Parameters:

    $that
        Sympa::List, Robot or Site.

    $email
        Recipient (the person who asked for the command)

    $cmd
        'signoff', 'subscribe', 'add', 'del' or 'remind' if $that is List. 'remind' else.

    @param
        [0] is used if $cmd is subscribe|add|del|invite. [1] is used if $cmd is 'add'.

    Returns:

    1 or "undef".

Finding config files and templates

search_fullpath ( $that, $name, [ opt => val, ...] )
        # To get file name for global site
        $file = Sympa::search_fullpath('*', $name);
        # To get file name for a robot
        $file = Sympa::search_fullpath($robot_id, $name);
        # To get file name for a family
        $file = Sympa::search_fullpath($family, $name);
        # To get file name for a list
        $file = Sympa::search_fullpath($list, $name);

    Look for a file in the list > robot > site > default locations.

    Possible values for options:
        order => 'all'
        subdir => directory ending each path
        lang => language
        lang_only => if paths without lang subdirectory would be omitted

    Returns full path of target file "root/subdir/lang/name" or "root/subdir/name". root is the location determined by target object $that. subdir and lang are optional. If "lang_only" option is set, paths without lang subdirectory is omitted.

get_search_path ( $that, [ opt => val, ... ] )
        # To make include path for global site
        @path = @{Sympa::get_search_path('*')};
        # To make include path for a robot
        @path = @{Sympa::get_search_path($robot_id)};
        # To make include path for a family
        @path = @{Sympa::get_search_path($family)};
        # To make include path for a list
        @path = @{Sympa::get_search_path($list)};

    make an array of include path for tt2 parsing

    IN :
          -$that(+) : ref(Sympa::List) | ref(Sympa::Family) | Robot | "*"
          -%options : options

    Possible values for options:
        subdir => directory ending each path
        lang => language
        lang_only => if paths without lang subdirectory would be omitted

    OUT : ref(ARRAY) of tt2 include path

Sending Notifications

send_dsn ( $that, $message, [ { key => val, ... }, [ $status, [ $diag ] ] ] )
        # To send site-wide DSN
        Sympa::send_dsn('*', $message, {'recipient' => $rcpt},
            '5.1.2', 'Unknown robot');
        # To send DSN related to a robot
        Sympa::send_dsn($robot, $message, {'listname' => $name},
            '5.1.1', 'Unknown list');
        # To send DSN specific to a list
        Sympa::send_dsn($list, $message, {}, '2.1.5', 'Success');

    Sends a delivery status notification (DSN) to SENDER by parsing dsn.tt2 template.

send_file ( $that, $tpl, $who, [ $context, [ options... ] ] )
        # To send site-global (not relative to a list or a robot)
        # message
        Sympa::send_file('*', $template, $who, ...);
        # To send global (not relative to a list, but relative to a
        # robot) message
        Sympa::send_file($robot, $template, $who, ...);
        # To send message relative to a list
        Sympa::send_file($list, $template, $who, ...);

    Send a message to user(s). Find the tt2 file according to $tpl, set up $data for the next parsing (with $context and configuration) Message is signed if the list has a key and a certificate

    Note: List::send_global_file() was deprecated.

send_notify_to_listmaster ( $that, $operation, $data )
        # To send notify to super listmaster(s)
        Sympa::send_notify_to_listmaster('*', 'css_updated', ...);
        # To send notify to normal (per-robot) listmaster(s)
        Sympa::send_notify_to_listmaster($robot, 'web_tt2_error', ...);
        # To send notify to normal listmaster(s) of robot the list belongs to.
        Sympa::send_notify_to_listmaster($list, 'request_list_creation', ...);

    Sends a notice to (super or normal) listmaster by parsing listmaster_notification.tt2 template.

    Parameters:

    $self
        Sympa::List, Robot or Site.

    $operation
        Notification type.

    $param
        Hashref or arrayref. Values for template parsing.

    Returns:

    1 or "undef".

Internationalization

best_language ( LANG, ... )
        # To get site-wide best language.
        $lang = Sympa::best_language('*', 'de', 'en-US;q=0.9');
        # To get robot-wide best language.
        $lang = Sympa::best_language($robot, 'de', 'en-US;q=0.9');
        # To get list-specific best language.
        $lang = Sympa::best_language($list, 'de', 'en-US;q=0.9');

    Chooses best language under the context of List, Robot or Site. Arguments are language codes (see Language) or ones with quality value. If no arguments are given, the value of "HTTP_ACCEPT_LANGUAGE" environment variable will be used.

    Returns language tag or, if negotiation failed, lang of object.

get_supported_languages ( $that )
    Function. Gets supported languages, canonicalized. In array context, returns array of supported languages. In scalar context, returns arrayref to them.

Users

These are accessors derived from configuration parameters.

get_listmasters_email ( $that )
        # To get addresses of super-listmasters.
        @addrs = Sympa::get_listmasters_email('*');
        # To get addresses of normal listmasters of a robot.
        @addrs = Sympa::get_listmasters_email($robot);
        # To get addresses of normal listmasters of the robot of a family.
        @addrs = Sympa::get_listmasters_email($family);
        # To get addresses of normal listmasters of the robot of a list.
        @addrs = Sympa::get_listmasters_email($list);

    Gets valid email addresses of listmasters. In array context, returns array of addresses. In scalar context, returns arrayref to them.

is_listmaster ( $that, $who )
    Is the user listmaster?

SEE ALSO
Sympa::Site (not yet available), Sympa::Robot (not yet available), Sympa::Family, Sympa::List.