/*
    Copyright (C) 2008 Andreas Baumann <abaumann@yahoo.com>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef WOLF_DAEMON_H
#define WOLF_DAEMON_H

/**
 * @addtogroup wolf_unix Unix-specific
 * @{
 */

/**
 * @addtogroup wolf_daemon Unix Daemons
 * @{
 */

/**
 * @file daemon.h
 * @brief helper to write a Unix daemon
 * @author Andreas Baumann <abaumann@yahoo.com>
 */

#include "errors.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief ADT representing the state of the daemon
 */
typedef struct wolf_daemon_t *wolf_daemon_p;

/**
 * @brief structure to fill out when creating a new daemon.
 */
typedef struct wolf_daemon_params_t {
	const char *daemon_name;		/**< name of the daemon (used for setproctitle,
						     default name of the  pidfile, logfile) */
	const char *pid_filename;		/**< name of the pid/lock file */
	const char *group_name;			/**< group of the effective user */
	const char *user_name;			/**< name of the effective user */
} wolf_daemon_params_t;

/**
 * Creates a new Unix daemon.
 *
 * @param params    steers how the daemon should be created.
 * @param error     indicates errors creating the daemon
 *
 * @return          the daemon object
 */
wolf_daemon_p wolf_daemon_new( wolf_daemon_params_t params,
                               wolf_error_t *error );

/**
 * Start the daemon
 *
 * @param demon     the daemon object to daemonize
 */
wolf_error_t wolf_daemon_start( wolf_daemon_p demon );

/**
 * Terminates the daemon. This must be the last function in
 * your main program as the call doesn't return!
 *
 * @param demon     the daemon object to daemonize
 */
void wolf_daemon_exit( wolf_daemon_p demon );

/**
 * Free up resources used by the daemon object (before daemonizing).
 * After a successful call to daemon_start daemon_exit will take
 * care of cleaning up. Use this if you have to bail out in main
 * just after daemon_new and before daemon_start.
 *
 * @param demon     the daemon object to free
 */
void wolf_daemon_free( wolf_daemon_p demon );

/**
 * Initialize signal handlers of the daemon.
 *
 * Must only be called if the daemon runs in foreground mode! Otherwise
 * signals are initiailized by wolf_daemon_start.
 *
 * Must be called before wolf_daemon_signals_install_handlers!
 */
wolf_error_t wolf_daemon_signals_initialize( void );

/**
 * Installs the default signal handlers of the daemon. After this fatal signals
 * lead to a graceful termination with logging, some signals are
 * ignored (as terminal signals) and some other signals can be
 * retrieved with wolf_daemon_signals_suspend in the main program.
 *
 * Must only be called if the daemon runs in foreground mode! Otherwise
 * signals are initiailized by wolf_daemon_start.
 *
 * wolf_daemon_signals_initialize must be called before.
 */
wolf_error_t wolf_daemon_signals_install_handlers( void );

/**
 * Suspend the current thread till a signal happens. Not all signals
 * are delivered this way, only those registered to have notifications
 * (see wolf_signal_install_notify). Per default the following signals
 * are delivered: SIGTERM, SIGINT, SIGHUP, SIGUSR1, SIGUSR2.
 *
 * @param timeout   wait at most timeout seconds, then return also
 *                  without signal
 * @param error     WOLF_OK if a signal occured, WOLF_ERR_TIMEOUT if
 *                  no signal happened after timeout seconds
 * @return          the signal number or undefined on timeout
 */
int wolf_daemon_signals_suspend( int timeout, wolf_error_t *error );

/**
 * Frees resources used for signal handling in the foreground mode
 * of the daemon.
 *
 * Must only be called if the daemon runs in foreground mode! Otherwise
 * signals are terminated by wolf_daemon_exit resp. wolf_daemon_free.
 */
void wolf_daemon_signals_terminate( void );

#ifdef __cplusplus
}
#endif

/** @} */ /* @addtogroup wolf_daemon */

/** @} */ /* @addtogroup wolf_unix */

#endif /* ifndef WOLF_DAEMON_H */