common/dlog.h

/*
 * Copyright (c) 2000-2001 Silicon Graphics, Inc.
 * All Rights Reserved.
 *
 * 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.
 *
 * This program is distributed in the hope that it would 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, write the Free Software Foundation,
 * Inc.,  51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
#ifndef DLOG_H
#define DLOG_H

/* dlog.[hc] - operator dialog abstraction
 *
 * abstracts dialogs with the operator
 */

extern bool_t dlog_init( int argc, char *argv[ ] );


/* tells if dialogs are allowed;
 * will be false if invoked to right of unnamed pipe,
 * or if pipe to left breaks.
 */
extern bool_t dlog_allowed( void );


/* allows signal handler to notify dlog of broken write pipe
 */
extern void dlog_desist( void );

/* returns the dialog tty file descriptor. returns -1 if none
 */
extern int dlog_fd( void );

/* returns BOOL_TRUE if a dialog consumed the given signal
 */
extern bool_t dlog_sighandler( int signo );

/* bracket a dialog session
 */
extern void dlog_begin( char *preamblestr[ ], size_t preamblecnt );
extern void dlog_end( char *postamblestr[ ], size_t postamblecnt );


/* multiple choice question abstraction. if any exception event index
 * set to IXMAX, that event will be ignored. returns index of selected
 * choice, or exception index if exception occured.
 */
extern ix_t dlog_multi_query( char *querystr[ ],	/* pre-choices output */
			      size_t querycnt,		/* length of above */
			      char *choicestr[ ],	/* choices */
			      size_t choicecnt,		/* length of above */
			      char *hilitestr,		/* to distinguish */
			      ix_t hiliteix,		/* highlighted choice */
			      char *defaultstr,		/* to distinguish */
			      ix_t defaultix,		/* return if cr */
			      time32_t timeout,		/* secs b4 giving up */
			      ix_t timeoutix,		/* return if timeout */
			      ix_t sigintix,		/* return if SIGINT */
			      ix_t sighupix,		/* return if SIGHUP */
			      ix_t sigquitix );		/* return if SIGQUIT */
extern void dlog_multi_ack( char *ackstr[ ], size_t ackcnt );

/* call the caller's callback to display whatever, using provided print
 * function, then prompt for and return an arbitrary string. two types
 * defined: pointer to the caller's function to print, and pointer to
 * function used by that function to do output. returns okix if successful,
 * timeoutix if times out, sigintix if SIGINT recieved, sighupix if SIGHUP
 * received, sigquitix if SIGQUIT received. if any of the exception indices
 * are set to IXMAX by the caller, those events will be ignored.
 */
typedef void ( * dlog_pcbp_t )( void *pctxp, char *s, ... );
typedef void ( * dlog_ucbp_t )( void *uctxp, dlog_pcbp_t pcb, void *pctxp );
extern ix_t dlog_string_query( dlog_ucbp_t ucb, /* user's print func */
			       void *uctxp,	/* user's context for above */
			       char *bufp,	/* typed string returned in */
			       size_t bufsz,	/* buffer size */
			       time32_t timeout,  /* secs b4 giving up */
			       ix_t timeoutix,  /* return if timeout */
			       ix_t sigintix,	/* return if SIGINT */
			       ix_t sighupix,	/* return if SIGHUP */
			       ix_t sigquitix,  /* return if SIGQUIT */
			       ix_t okix );     /* return if successful */
extern void dlog_string_ack( char *ackstr[ ], size_t ackcnt );

#endif /* DLOG_H */