/*++
/* NAME
/*	qmgr_scan 3
/* SUMMARY
/*	queue scanning
/* SYNOPSIS
/*	#include "qmgr.h"
/*
/*	QMGR_SCAN *qmgr_scan_create(queue_name)
/*	const char *queue_name;
/*
/*	char	*qmgr_scan_next(scan_info)
/*	QMGR_SCAN *scan_info;
/*
/*	void	qmgr_scan_request(scan_info, flags)
/*	QMGR_SCAN *scan_info;
/*	int	flags;
/* DESCRIPTION
/*	This module implements queue scans. A queue scan always runs
/*	to completion, so that all files get a fair chance. The caller
/*	can request that a queue scan be restarted once it completes.
/*
/*	qmgr_scan_create() creates a context for scanning the named queue,
/*	but does not start a queue scan.
/*
/*	qmgr_scan_next() returns the base name of the next queue file.
/*	A null pointer means that no file was found. qmgr_scan_next()
/*	automagically restarts a queue scan when a scan request had
/*	arrived while the scan was in progress.
/*
/*	qmgr_scan_request() records a request for the next queue scan. The
/*	flags argument is the bit-wise OR of zero or more of the following,
/*	unrecognized flags being ignored:
/* .IP QMGR_FLUSH_ONCE
/*	Forget state information about dead hosts or transports.
/*	This request takes effect immediately.
/* .IP QMGR_FLUSH_DFXP
/*	Override the defer_transports setting. This takes effect
/*	immediately when a queue scan is in progress, and affects
/*	the next queue scan.
/* .IP QMGR_SCAN_ALL
/*	Ignore queue file time stamps. This takes effect immediately
/*	when a queue scan is in progress, and affects the next queue
/*	scan.
/* .IP QMGR_SCAN_START
/*	Start a queue scan when none is in progress, or restart the
/*	current scan upon completion.
/* DIAGNOSTICS
/*	Fatal: out of memory.
/*	Panic: interface violations, internal consistency errors.
/* LICENSE
/* .ad
/* .fi
/*	The Secure Mailer license must be distributed with this software.
/* AUTHOR(S)
/*	Wietse Venema
/*	IBM T.J. Watson Research
/*	P.O. Box 704
/*	Yorktown Heights, NY 10598, USA
/*--*/

/* System library. */

#include <sys_defs.h>

/* Utility library. */

#include <msg.h>
#include <mymalloc.h>
#include <scan_dir.h>

/* Global library. */

#include <mail_scan_dir.h>

/* Application-specific. */

#include "qmgr.h"

/* qmgr_scan_start - start queue scan */

static void qmgr_scan_start(QMGR_SCAN *scan_info)
{
    const char *myname = "qmgr_scan_start";

    /*
     * Sanity check.
     */
    if (scan_info->handle)
	msg_panic("%s: %s queue scan in progress",
		  myname, scan_info->queue);

    /*
     * Give the poor tester a clue.
     */
    if (msg_verbose)
	msg_info("%s: %sstart %s queue scan",
		 myname,
		 scan_info->nflags & QMGR_SCAN_START ? "re" : "",
		 scan_info->queue);

    /*
     * Start or restart the scan.
     */
    scan_info->flags = scan_info->nflags;
    scan_info->nflags = 0;
    scan_info->handle = scan_dir_open(scan_info->queue);
}

/* qmgr_scan_request - request for future scan */

void    qmgr_scan_request(QMGR_SCAN *scan_info, int flags)
{

    /*
     * Apply "forget all dead destinations" requests immediately. Throttle
     * dead transports and queues at the earliest opportunity: preferably
     * during an already ongoing queue scan, otherwise the throttling will
     * have to wait until a "start scan" trigger arrives.
     * 
     * The QMGR_FLUSH_ONCE request always comes with QMGR_FLUSH_DFXP, and
     * sometimes it also comes with QMGR_SCAN_ALL. It becomes a completely
     * different story when a flush request is encoded in file permissions.
     */
    if (flags & QMGR_FLUSH_ONCE)
	qmgr_enable_all();

    /*
     * Apply "ignore time stamp" requests also towards the scan that is
     * already in progress.
     */
    if (scan_info->handle != 0 && (flags & QMGR_SCAN_ALL))
	scan_info->flags |= QMGR_SCAN_ALL;

    /*
     * Apply "override defer_transports" requests also towards the scan that
     * is already in progress.
     */
    if (scan_info->handle != 0 && (flags & QMGR_FLUSH_DFXP))
	scan_info->flags |= QMGR_FLUSH_DFXP;

    /*
     * If a scan is in progress, just record the request.
     */
    scan_info->nflags |= flags;
    if (scan_info->handle == 0 && (flags & QMGR_SCAN_START) != 0) {
	scan_info->nflags &= ~QMGR_SCAN_START;
	qmgr_scan_start(scan_info);
    }
}

/* qmgr_scan_next - look for next queue file */

char   *qmgr_scan_next(QMGR_SCAN *scan_info)
{
    char   *path = 0;

    /*
     * Restart the scan if we reach the end and a queue scan request has
     * arrived in the mean time.
     */
    if (scan_info->handle && (path = mail_scan_dir_next(scan_info->handle)) == 0) {
	scan_info->handle = scan_dir_close(scan_info->handle);
	if (msg_verbose && (scan_info->nflags & QMGR_SCAN_START) == 0)
	    msg_info("done %s queue scan", scan_info->queue);
    }
    if (!scan_info->handle && (scan_info->nflags & QMGR_SCAN_START)) {
	qmgr_scan_start(scan_info);
	path = mail_scan_dir_next(scan_info->handle);
    }
    return (path);
}

/* qmgr_scan_create - create queue scan context */

QMGR_SCAN *qmgr_scan_create(const char *queue)
{
    QMGR_SCAN *scan_info;

    scan_info = (QMGR_SCAN *) mymalloc(sizeof(*scan_info));
    scan_info->queue = mystrdup(queue);
    scan_info->flags = scan_info->nflags = 0;
    scan_info->handle = 0;
    return (scan_info);
}