Information

Description

The function

_getch(),_getwch(),_getche(),_getwche().

The use

Get a character from the console without echo (_getch(),_getchw()) or with echo (_getche(),_getwche()).

The prototype

int _getch(void);

wint_t _getwch(void);

int _getche(void);

wint_t _getwche(void);

Example

-

The parameters

No parameter.

The return value

Returns the character read. There is no error return.

The header file

_getch() -<conio.h>

_getche() -<conio.h>

_getwch() -<conio.h> or <wchar.h>

_getwche() -<conio.h> or <wchar.h>

Remarks

-

Table 10

Information

Description

The function

Beep().

The use

Generates simple tones on the speaker. The function is synchronous; it does not return control to its caller until the sound finishes.

The prototype

BOOL Beep(DWORD dwFreq, DWORD dwDuration);

Example

-

The parameters

dwFreq - [in] Frequency of the sound, in hertz. This parameter must be in the range 37 through 32,767 (0x25 through 0x7FFF). For Windows Me/98/95:  The Beep function ignores this parameter.

dwDuration - [in] Duration of the sound, in milliseconds.

Windows Me/98/95:  The Beep function ignores this parameter.

The return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().

The header file

<windows.h>

Remarks

Terminal Services:  The beep is redirected to the client.

Windows Me/98/95:  On computers with a sound card, the function plays the default sound event. On computers without a sound card, the function plays the standard system beep.

Table 11

Information

Description

The function

GetConsoleScreenBufferInfo().

The use

Retrieves information about the specified console screen buffer.

The prototype

BOOL GetConsoleScreenBufferInfo(HANDLE hConsoleOutput, PCONSOLE_SCREEN_BUFFER_INFO lpConsoleScreenBufferInfo);

Example

-

The parameters

hConsoleOutput - [in] Handle to a console screen buffer. The handle must have the GENERIC_READ access right.

lpConsoleScreenBufferInfo - [out] Pointer to a CONSOLE_SCREEN_BUFFER_INFO structure that receives the console screen buffer information.

The return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().

The header file

<windows.h>

Remarks

The rectangle returned in thesrWindow member of the CONSOLE_SCREEN_BUFFER_INFO structure can be modified and then passed to the SetConsoleWindowInfo() function to scroll the console screen buffer in the window, to change the size of the window, or both. All coordinates returned in the CONSOLE_SCREEN_BUFFER_INFO structure are in character-cell coordinates, where the origin (0, 0) is at the upper-left corner of the console screen buffer.

Table 12

Information

Description

The function

GetStdHandle().

The use

Retrieves a handle for the standard input, standard output, or standard error device.

The prototype

HANDLE GetStdHandle(DWORD nStdHandle);

Example

-

The parameters

nStdHandle

[in] Standard device for which a handle is to be returned. This parameter can be one of the following values:

1. STD_INPUT_HANDLE - Handle to the standard input device. Initially, this is a handle to the console input buffer, CONIN$.

2. STD_OUTPUT_HANDLE - Handle to the standard output device. Initially, this is a handle to the active console screen buffer, CONOUT$.

3. STD_ERROR_HANDLE - Handle to the standard error device. Initially, this is a handle to the active console screen buffer, CONOUT$.

The return value

If the function succeeds, the return value is a handle to the specified device, or a redirected handle set by a previous call to SetStdHandle(). The handle has GENERIC_READ and GENERIC_WRITE access rights, unless the application has usedSetStdHandle() to set a standard handle with lesser access.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError(). If an application does not have associated standard handles, such as a service running on an interactive desktop, and has not redirected them, the return value is NULL.

The header file

<windows.h>

Remarks

Handles returned by GetStdHandle() can be used by applications that need to read from or write to the console. When a console is created, the standard input handle is a handle to the console's input buffer, and the standard output and standard error handles are handles of the console's active screen buffer. These handles can be used by theReadFile() and WriteFile() functions, or by any of the console functions that access the console input buffer or a screen buffer (for example, theReadConsoleInput(),WriteConsole(), or GetConsoleScreenBufferInfo() functions).

The standard handles of a process may be redirected by a call to SetStdHandle(), in which caseGetStdHandle() returns the redirected handle. If the standard handles have been redirected, you can specify the CONIN$ value in a call to the CreateFile() function to get a handle to a console's input buffer. Similarly, you can specify theCONOUT$ value to get a handle to a console's active screen buffer.

Table 13

Information

Description

The function

srand().

The use

Sets a random starting point.

The prototype

void srand(unsigned int seed);

Example

-

The parameters

seed - Seed for random-number generation.

The return value

none

The header file

<stdio.h>

Remarks

The srand function sets the starting point for generating a series of pseudorandom integers. To reinitialize the generator, use 1 as the seed argument. Any other value for seed sets the generator to a random starting point. rand() retrieves the pseudorandom numbers that are generated. Calling rand before any call to srand generates the same sequence as calling srand with seed passed as 1.

Table 14

Information

Description

The function

rand().

The use

Generates a pseudorandom number.

The prototype

int rand(void);

Example

-

The parameters

No parameter.

The return value

rand() returns a pseudorandom number, as described above. There is no error return.

The header file

<stdlib.h>

Remarks

The rand function returns a pseudorandom integer in the range 0 to RAND_MAX. Use thesrand() function to seed the pseudorandom-number generator before callingrand().

Table 15

Item

Description

Structure

COORD.

Info

Defines the coordinates of a character cell in a console screen buffer. The origin of the coordinate system (0, 0) is at the top, left cell of the buffer.

Definition

typedef struct _COORD {

  SHORT X;

  SHORT Y;

} COORD, *PCOORD;

Members

X - Horizontal coordinate or column value.

Y - Vertical coordinate or row value.

Header file

<windows.h>

Remark

-

Table 16.

Item

Description

Structure

CONSOLE_SCREEN_BUFFER_INFO.

Info

Contains information about a console screen buffer.

Definition

typedef struct _CONSOLE_SCREEN_BUFFER_INFO {

  COORD dwSize;

  COORD dwCursorPosition;

  WORD wAttributes;

  SMALL_RECT srWindow;

  COORD dwMaximumWindowSize;

} CONSOLE_SCREEN_BUFFER_INFO;

Members

dwSize - ACOORD structure that contains the size of the console screen buffer, in character columns and rows.

dwCursorPosition - A COORD structure that contains the column and row coordinates of the cursor in the console screen buffer.

wAttributes - Attributes of the characters written to a screen buffer by the WriteFile() andWriteConsole() functions, or echoed to a screen buffer by theReadFile() and ReadConsole() functions.

srWindow - A SMALL_RECT structure that contains the console screen buffer coordinates of the upper-left and lower-right corners of the display window.

dwMaximumWindowSize - A COORD structure that contains the maximum size of the console window, given the current screen buffer size and font and the screen size.

Header file

<windows.h>

Remark

-

Table 17.

Item

Description

Structure

SMALL_RECT.

Info

Defines the coordinates of the upper left and lower right corners of a rectangle.

Definition

typedef struct _SMALL_RECT {

  SHORT Left;

  SHORT Top;

  SHORT Right;

  SHORT Bottom;

} SMALL_RECT;

Members

Left - X-coordinate of the upper left corner of the rectangle.

Top - Y-coordinate of the upper left corner of the rectangle.

Right - X-coordinate of the lower right corner of the rectangle.

Bottom - Y-coordinate of the lower right corner of the rectangle.

Header file

<windows.h>

Remark

This structure is used by console functions to specify rectangular areas of console screen buffers, where the coordinates specify the rows and columns of screen-buffer character cells.

Table 18.

Item

Description

Structure

RECT.

Info

Defines the coordinates of the upper-left and lower-right corners of a rectangle.

Definition

typedef struct _RECT {

  LONG left;

  LONG top;

  LONG right;

  LONG bottom;

} RECT, *PRECT;

Members

left - Specifies the x-coordinate of the upper-left corner of the rectangle.

top - Specifies the y-coordinate of the upper-left corner of the rectangle.

right - Specifies the x-coordinate of the lower-right corner of the rectangle.

bottom - Specifies the y-coordinate of the lower-right corner of the rectangle.

Header file

<windows.h>

Remark

When RECT is passed to the FillRect() function, the rectangle is filled up to, but not including, the right column and bottom row of pixels. This structure is identical to the RECTL structure.

Table 19.