acs_mail_lite::inbound_queue_pull_one (private)

 acs_mail_lite::inbound_queue_pull_one -h_array_name h_array_name \
    -p_array_name p_array_name -aml_email_id aml_email_id \
    [ -mark_processed_p mark_processed_p ] \
    [ -legacy_array_name legacy_array_name ]

Defined in packages/acs-mail-lite/tcl/email-inbound-procs.tcl

Puts email referenced by aml_email_id from the inbound queue into array of h_array_name and p_array_name for use by registered callbacks. Arrays are repopulated with values in the same manner that acs_mail_lite::inbounde_queue_insert receives them. See below for details. When complete, marks the email in the queue as processed, if mark_processed_p is 1. Array content corresponds to these tables:

    h_arr($name) $value         acs_mail_lite_ie_headers

    Some indexes match fields of table acs_mail_lite_from_external:

    h_arr(aml_email_id)     assigned by acs_mail_lite::inbound_queue_insert
    h_arr(aml_to)           to email including any label
    h_arr(aml_to_addrs)     to_email_addrs
    h_arr(aml_from)         from email including any label
    h_arr(aml_from_addrs)   from_email_addrs
    h_arr(aml_priority)     priority
    h_arr(aml_subject)      email subject (normalized index reference).
    h_arr(aml_msg_id)       email message-id or msg-id's cross-reference
                            see acs_mail_lite_msg_id_map.msg_id
    h_arr(aml_size_chars)   size_chars

    Some headers are transferred from the email generation process.
    See acs_mail_lite::unique_id_create for details:

    h_arr(aml_package_id)
    h_arr(aml_party_id)
    h_arr(aml_object_id)
    h_arr(aml_other)


    Some headers are internally generated during input:

    h_arr(aml_type)         Type of email from acs_mail_lite::email_type
    h_arr(aml_received_cs)  Time received in seconds since Tcl epoch
    h_arr(aml_datetime_cs)  Time unique_id generated in seconds since Tcl epoch
    h_arr(aml_processed_p)  processed_p
    h_arr(aml_priority)     a priority number assigned to email.

    Email parts (of body) are kept in a separate array:

    p_arr($section_ref,<field>)  acs_mail_lite_ie_parts (content of a part)
    p_arr($section_ref,nv_list)  acs_mail_lite_part_nv_pairs
    p_arr(section_ref_list) list of section_refs


    where index is section_ref based on section_ref, and
    where top most section_ref is a natural number as
    there may be more than one tree.

    Specifically, for p_arr array:

    content        is  p_arr($section_ref,content)
    c_type         is  p_arr($section_ref,c_type)
    filename       is  p_arr($section_ref,filename)
    c_filepathname is  p_arr($section_ref,c_filepathname)

    where:
    c_type is content-type header
    filename is filename of an attachment in email
    c_filepathname is the filepathname within the system.

    Each section may have headers:

    To avoid any header-name collision with content, c_type etc,
    headers are supplied in a name_value_list only:

    list of headers by section is  p_arr($section_ref,name_value_list)
    list of section_refs       is  p_arr(section_ref_list)

    For direct compatibility with legacy email systems that used:
    

acs_mail_lite::email_parse, a compatible array is passed to legacy_array_name, if parameter is used.

Switches:

-h_array_name (required)

-p_array_name (required)

-aml_email_id (required)

-mark_processed_p (optional, defaults to "1")

-legacy_array_name (optional)

See Also:

• acs_mail_lite::email_parse

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Source code:

    upvar 1 $h_array_name h_arr
    upvar 1 $p_array_name p_arr
    if { $legacy_array_name ne "" } {
        upvar 1 $legacy_array_name l_arr
        set build_l_arr_p 1
        # Save data in l_arr according to acs_mail_lite::parse_email
        # in incoming-mail-procs.tcl
    } else {
        set build_l_arr_p 0
    }

    # This query may be redundant to some info in acs_mail_lite_ie_headers.
    # acs_mail_lite_from_external
    set x_list [db_list_of_lists acs_mail_lite_from_external_r1 {
        select priority, to_email_addrs, from_email_addrs,
        subject, msg_id,
        size_chars, received_cs, processed_p, release_p
        from acs_mail_lite_from_external
        where aml_email_id=:aml_email_id
    }]
    lassign $x_list h_arr(aml_priority)  h_arr(aml_to_email_addrs)  h_arr(aml_from_email_addrs)  h_arr(aml_subject)  h_arr(aml_msg_id)  h_arr(aml_size_chars)  h_arr(aml_received_cs)  h_arr(aml_processed_p)  h_arr(aml_release_p)

    # collect from acs_mail_lite_ie_headers
    set h_lists [db_list_of_lists acs_mail_lite_ie_headers_r1 {
        select h_name, h_value
        from acs_mail_lite_ie_headers
        where aml_email_id=:aml_email_id } ]
    set h_names_ul [list ]
    foreach {n v} $h_lists {
        set h_arr(${n}) "${v}"
        lappend h_names_ul $n
    }

    if { $build_l_arr_p } {
        set l_headers_ul [array get h_arr]
        lappend l_headers_ul message-id $h_arr(aml_msg_id)
        lappend l_headers_ul subject $h_arr(aml_subject)
        lappend l_headers_ul from $h_arr(aml_from_email_addrs)
        lappend l_headers_ul to $h_arr(aml_to_email_addrs)
        # provide lowercase of some headers if they exist
        set to_lc_list [list date references in-reply-to return-path]
        foreach tol $to_lc_list {
            set tol_idx [lsearch -exact -nocase $h_names_ul $tol ]
            if { $tol > -1 } {
                set tol_ref [lindex $h_names_ul $tol_idx]
                lappend l_headers_ul $tol $h_arr(${tol_ref})
            }
        }
        if { $h_arr(received_cs) ne "" } {
            lappend l_headers_ul received [clock format $h_arr(received_cs) ]
        }
        set l_arr(headers) $l_headers_ul
    }

    # collect from acs_mail_lite_ie_parts
    set p_lists [db_list_of_lists acs_mail_lite_ie_parts_r1 {
        select section_id,c_type,filename,content,c_filepathname
        from acs_mail_lite_ie_parts
        where aml_email_id=:aml_email_id } ]
    foreach row $p_lists {
        set section_ref [acs_mail_lite::section_ref_of [lindex $row 0]]
        set p_arr(${section_ref},c_type) [lindex $row 1]
        set p_arr(${section_ref},filename) [lindex $row 2]
        set p_arr(${section_ref},content) [lindex $row 3]
        set p_arr(${section_ref},c_filepathname) [lindex $row 4]
        if { $section_ref ni $p_arr(section_ref_list) } {
            lappend p_arr(section_ref_list) $section_ref
        }
    }
    # collect from acs_mail_lite_ie_part_nv_pairs
    set nvp_lists [db_list_of_lists acs_mail_lite_ie_part_nv_pairs_r1 {
        select section_id, p_name, p_value
        from acs_mail_lite_ie_part_nv_pairs
        where aml_email_id=:aml_email_id } ]
    set reserved_fields_ul [list content c_type filename c_filename]
    foreach row $nvp_lists {
        set section_ref [acs_mail_lite::section_ref_of [lindex $row 0]]
        set name [lindex $row 1]
        set value [lindex $row 2]
        if { $name ni $reserved_fields_ul } {
            lappend p_arr(${section_ref},name_value_list) $name $value
        }
        if { $section_ref ni $p_arr(section_ref_list) } {
            lappend p_arr(section_ref_list) $section_ref
        }
    }
    if { $build_l_arr_p } {
        # Legacy approach assumes "application/octet-stream"
        # for all attachments and
        # base64 for encoding of all files.
        #
        # Encoding has already been handled for files before queueing.

        # Legacy approach replaces nested parts with flat list
        # from parse_email:
        #   The bodies consists of a list with two elements:
        #     content-type and content.
        #   The files consists of a list with three elements:
        #     content-type, filename and content.

        set bodies_list [list]
        set files_list [list]
        set default_encoding [encoding system]
        foreach part $p_arr(section_ref_list) {

            lappend bodies_list [list  $p_arr(${section_ref},c_type)  $p_arr(${section_ref},content) ]
            # check for local filename
            if { $p_arr(${section_ref},c_filepathname) ne "" } {
                # Since this is saved as a file and already decoded,
                # guess content_type from file
                # instead of assuming content type is same
                # as type used in email transport.
                set content_type [ns_guesstype $p_arr(${section_ref},c_filepathname)]

                lappend files_list [list  $content_type  $default_encoding  $p_arr(${section_ref},filename)  $p_arr(${section_ref},c_filepathname) ]

            }
        }
        set l_arr(bodies) $bodies_list
        set l_arr(files) $files_list
    }

    return 1

XQL Not present:

PostgreSQL, Oracle

Generic XQL file:

packages/acs-mail-lite/tcl/email-inbound-procs.xql