ComposerDesktopProject/include/aaio.h

/**
 * @file aaio.h
 *
 * AAIO Advanced I/O
 *
 * Many people moving from Windows programming to UNIX program have problems 
 * with the missing non-blocking getch() and getche() functions provided by 
 * conio.h. This library provides the functionality of getch(), getche() and
 * kbhit(). It does not require an initialization (like curses) and does 
 * not abuse the terminal (i.e. whenever the mode of the terminal is 
 * changed its state is stored so it can be restored). For increased 
 * efficiency there exists funcionality to allow abuse of the terminal as well 
 * as functions to restore or reset the terminal when the application exits.
 *
 * @author Daniel Aarno
 * @version 0.3.0
 */

/*
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

 * Copyright (c) 2004-2005 by Daniel Aarno - <[email protected]>
 * M. Sc. Electrical Engineering * http://www.nada.kth.se/~bishop
 * 
 * All Rights Reserved
 * ATTRIBUTION ASSURANCE LICENSE (adapted from the original BSD license)
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the conditions below are met.
 * These conditions require a modest attribution to  (the
 * "Author"), who hopes that its promotional value may help justify the
 * thousands of dollars in otherwise billable time invested in writing
 * this and other freely available, open-source software.
 * 
 * 1. Redistributions of source code, in whole or part and with or without
 * modification (the "Code"), must prominently display this GPG-signed
 * text in verifiable form.
 * 2. Redistributions of the Code in binary form must be accompanied by
 * this GPG-signed text in any documentation and, each time the resulting
 * executable program or a program dependent thereon is launched, a
 * prominent display (e.g., splash screen or banner text) of the Author's
 * attribution information, which includes:
 * (a) Name ("Daniel Aarno"),
 * (b) Professional identification ("M. Sc. Electrical Engineering"), and
 * (c) URL ("http://www.nada.kth.se/~bishop").
 * 3. Neither the name nor any trademark of the Author may be used to
 * endorse or promote products derived from this software without specific
 * prior written permission.
 * 4. Users are entirely responsible, to the exclusion of the Author and
 * any other persons, for compliance with (1) regulations set by owners or
 * administrators of employed equipment, (2) licensing terms of any other
 * software, and (3) local regulations regarding use, including those
 * regarding import, export, and use of encryption software.
 * 
 * THIS FREE SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
 * EVENT SHALL THE AUTHOR OR ANY CONTRIBUTOR BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * EFFECTS OF UNAUTHORIZED OR MALICIOUS NETWORK ACCESS;
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (GNU/Linux)

iD8DBQFCHuXui6ECThHTSIkRAk9qAKCVs7kMSUtv5YhljeQsAA52EcjTFgCeNflz
w0lAUG3zeHQcJ+7t6tpce4s=
=qlVs
-----END PGP SIGNATURE-----
*/

#ifndef _L_AAIO_
#define _L_AAIO_

#define AAIO_VERSION 0.3.0

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Get a character from stdin. Block until a character is available 
 * but does not wait for a new line. Characters are not echoed on to 
 * screen.
 * 
 * @return The first character available cast to an int or -1 on error.
 * @see getche
 */
int getch(void);

/**
 * Get a character from stdin. Block until a character is available 
 * but does not wait for a new line. Characters are echoed on to 
 * screen.
 * 
 * @return The first character available cast to an int or -1 on error.
 * @see getch
 */
int getche(void);

/**
 * Get the number of characters available on stdin.
 *
 * @return The number of characters that can be read from stdin without 
 * blocking, -1 on error.
 * @see getch
 * @see getche
 */
int kbhit(void);

/**
 * Perform a hard reset of the terminal to cause it to go back to its 
 * original state.
 *
 * @return -1 on error, 0 on success.
 * @see reset(1)
 * @see aaio_reset
 */
int aaio_hard_reset(void);

/**
 * Reset the terminal to the state it was in when aaio_grant_tty_lock was
 * called.
 * 
 * @deprecated There is no need to use the aaio_grant_tty_lock and
 * aaio_reset functions as of version 0.2.0 an later. The speedup thay
 * can achieve is reduced to an insignificant level. The functionality
 * may be removed in later versions of the library.
 *
 * @return -1 on error, 0 on success.
 * @see aaio_hard_reset
 * @see aaio_grant_tty_lock
 */
int aaio_reset(void);

/**
 * Allow the aaio functions (getch, getche and kbhit) to "abuse" the terminal
 * (i.e. change the terminal settings without resetting them. This gives a
 * boost to performance that can be usefull in some cases. Most often,
 * however, it is not necessary or recomended to grant the tty lock to aaio.
 *
 * If the lock has been granted aaio_reset must be called before program 
 * exit to reset the terminal to its original state.
 *
 * @deprecated There is no need to use the aaio_grant_tty_lock and
 * aaio_reset functions as of version 0.2.0 an later. The speedup thay
 * can achieve is reduced to an insignificant level. The functionality
 * may be removed in later versions of the library.
 *
 * @return -1 on error, 0 on success.
 * @note The aaio library does not really get a lock on the tty, others may
 * change the tty settings, however this will corrupt the aaio library and
 * can cause undefined results.
 * @see aaio_reset
 */
int aaio_grant_tty_lock(void);
  
/**
 * Flush any remaining characters from the stdandard input.
 * 
 * @return The number of charactes removed.
 */
int aaio_flush(void);

#ifdef __cplusplus
}
#endif

#endif