レガシー Windows API(概要)について

ここで紹介しているAPIは、Windows95、Windows NT3.5時代のAPI群であり、最新のAPIは含まれていないことに注しして欲しい。なお、当時の解説書は現在よりもより詳細に解説しているため、参考になるはずである。

  • レイアウトを変換する際、崩れているページがあります。
  • 概要およびSampleコードはありますが、APIの解説はありません。

ご要望があれば旧版のWin32 API(HELP形式)をお譲りします。問い合わせフォームより申し込みください。

Windows API システム情報の概要

Microsoft(R) Win32(R) アプリケーション プログラミング インターフェイス (API) には、 現在のシステム構成を取得する関数があります。これらの関数は、 コンピュータ名やユーザー名、 環境変数の設定、 プロセッサの種類、 システム カラーなど、 さまざまなデータを取得します。また、 Win32 APIには、 システム設定の変更、 システムのシャットダウン、 Microsoft(R) Windows(TM) ヘルプ アプリケーションの起動などを行う関数もあります。

次に示すトピックでは、 Win32のシステム情報関数について説明しています。

システム構成

システムのシャットダウン

Windowsヘルプ

システム構成情報の取得

ハードウェア情報の取得

ウィンドウ要素の色の変更

システムのシャットダウンの例

Windowsヘルプの起動

システム情報関数

システム構成

GetUserName関数は、 現在システムにログオンしているユーザーの名前を取得します。ユーザー名は、 完全な名前がレジストリにあるときは完全な名前になり、 そうでないときはログオン名になります。

GetSystemInfo関数は、 ページ サイズや相手先ブランド供給 (OEM) 識別子、 プロセッサの個数と種類、 アプリケーションのアドレス範囲など、 プロセッサやメモリに関する情報を取得します。GetVersion関数は、 インストールされているMicrosoft Windowsのメジャー リビジョン番号とマイナ リビジョン番号を取得します。GetKeyboardType関数は、 キーボードの種類や現在のキーボードのファンクション キーの個数などの情報を取得します。

SystemParametersInfo関数は、 ダブルクリック時間、 スクリーン セーバーのタイム アウト、 ウィンドウの境界線の幅、 デスクトップ パターンなどの、 さまざまなシステム属性を取得、 設定します。アプリケーションがSystemParametersInfoを使ってパラメータを設定すると、 変更は即座に有効になります。また、 アプリケーションは、 この関数を使ってユーザーのプロファイルを更新し、 システムが再起動したときに変更を有効にすることもできます。

GetThreadDesktop関数は、 特定のスレッドのデスクトップのハンドルを取得します。このハンドルは、 セキュリティ属性を取得、 設定する関数を呼び出すときに使います。

Windowsディレクトリ」とは、 Windows用アプリケーションや初期化ファイル、 ヘルプ ファイルがあるディレクトリです。GetWindowsDirectory関数は、 このディレクトリのパスを取得します。アプリケーションは、 ファイルを作成するとき、 Windowsディレクトリにファイルを置いてください。共有されているWindowsを実行している各ユーザーに固有であることが保証されているのは、 このディレクトリだけです。

「システム ディレクトリ」とは、 Windowsのライブラリ、 ドライバ、 フォント ファイルがあるディレクトリです。GetSystemDirectory関数は、 このディレクトリのパスを取得します。

「環境変数」とは、 パスやファイル名などのシステムの要素を表すシンボル変数です。たとえば、 環境変数のPATHは、 実行可能ファイルを検索するディレクトリを表します。ユーザーがログオンすると、 システムは、 レジストリの環境セクションに基づいて環境変数を初期化します。ExpandEnvironmentStrings関数は、 指定された環境変数の値を取得します。

「システム メトリックス」とは、 Windowsのさまざまな表示要素の寸法です (「表示要素」とは、 システムのディスプレイ画面に表示されるウィンドウの各部分やWindowsによる表示です)。通常、 システム メトリックスには、 ウィンドウの境界線の幅、 アイコンの高さなどがあります。また、 システム メトリックスは、 マウスがインストールされているか、 2バイト文字がサポートされているか、 デバッグ バージョンのWindowsがインストールされているかなどの、 システムのそのほかの部分も記述します。GetSystemMetrics関数は、 指定されたシステム メトリックを取得します。

また、 メニューやスクロール バー、 ボタンなどのウィンドウ要素の色を取得、 設定するには、 GetSysColor関数やSetSysColors関数を使います。

システムのシャットダウン

Win32 APIは、 アプリケーションがローカル コンピュータやリモート コンピュータをシャットダウンする方法を用意しています。この機能は、 システム管理者がリモート コンピュータのシステム ソフトウェアを更新するときに特に役立ちます。InitiateSystemShutdown関数は、 タイマを起動し、 ログオフするようにユーザーに要求するダイアログ ボックスを表示します。ダイアログ ボックスが表示されている間、 AbortSystemShutdown関数は、 タイマを停止して、 コンピュータがシャットダウンしないようにします。しかし、 タイマの設定時間が経過すると、 コンピュータはシャットダウンします。また、 InitiateSystemShutdownは、 シャットダウン後にコンピュータを再起動できます。

Windowsヘルプ

アプリケーションは、 Windowsヘルプ アプリケーションを起動することによって、 ユーザーにヘルプを提供できます。WinHelp関数は、 指定されたヘルプ ファイルの指定されたコンテキストをオープンします。

システム情報の使用

ここでは、 次の処理の実行方法を説明します。

システム構成情報の取得

ハードウェア情報の取得

ウィンドウ要素の色の変更

システムのシャットダウン

Windowsヘルプの起動

システム構成情報の取得

次の例は、 GetComputerName関数、 GetUserName関数、 GetSystemDirectory関数、 GetWindowsDirectory関数、 ExpandEnvironmentStrings関数を使って、 システムの構成を示す情報を取得します。この例は、 ウィンドウのクライアント領域にこの情報を表示します。

LPTSTR lpszSystemInfo;/* ptr. to system info. string */
DWORD cchBuff = 256;/* size of comp. or user name*/
TCHAR tchBuffer2[BUFFER];/* buffer for concat'd. str. */

DWORD dwResult;/* function return value */

SYSTEM_INFO siSysInfo;/* struct. for hardware info. */
int aTabs[1] = {260};/* tab stop for TabbedTextOut */

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */
int nSize;/* size of string */

lpszSystemInfo = tchBuffer2;

/* Get and display the name of the computer. */

GetComputerName(lpszSystemInfo, &cchBuff);

nSize = sprintf(tchBuffer, "Computer name: %s",
lpszSystemInfo);
TextOut(hdc, 15, 20, tchBuffer, nSize);

/* Get and display the user name. */

GetUserName(lpszSystemInfo, &cchBuff);

nSize = sprintf(tchBuffer, "User name: %s",
lpszSystemInfo);
TextOut(hdc, 15, 40, tchBuffer, nSize);

/* Get and display the system directory. */

nSize = GetSystemDirectory(lpszSystemInfo, MAX_PATH);

nSize = sprintf(tchBuffer, "System directory: %s",
lpszSystemInfo);
TextOut(hdc, 15, 60, tchBuffer, nSize);

/* Get and display the Windows directory. */

nSize = GetWindowsDirectory(lpszSystemInfo, MAX_PATH);

nSize = sprintf(tchBuffer, "Windows directory: %s",
lpszSystemInfo);
TextOut(hdc, 15, 80, tchBuffer, nSize);

/* Display the "environment variables" header. */

nSize = sprintf(tchBuffer,
"Environment variables (partial list):");
TextOut(hdc, 15, 105, tchBuffer, nSize);

/* Expand the OS and NTVERSION environment variables. */

dwResult = ExpandEnvironmentStrings(
"OS=%OS%NTVERSION=%NTVERSION%",
lpszSystemInfo,
BUFFER);

TextOut(hdc, 25, 120, (LPCTSTR) lpszSystemInfo,
dwResult - 1);

/* Expand the PATH environment variable. */

dwResult = ExpandEnvironmentStrings(
"PATH=%PATH%",
lpszSystemInfo,
BUFFER);

TextOut(hdc, 25, 135, (LPCTSTR) lpszSystemInfo,
dwResult - 1);

/* Expand the LIBPATH environment variable. */

dwResult = ExpandEnvironmentStrings(
"LIBPATH=%LIBPATH%",
lpszSystemInfo,
BUFFER);

TextOut(hdc, 25, 150, (LPCTSTR) lpszSystemInfo,
dwResult - 1);

/* Expand the TMP environment variable. */

dwResult = ExpandEnvironmentStrings(
"TMP=%TMP%",
lpszSystemInfo,
BUFFER);

TextOut(hdc, 25, 165, (LPCTSTR) lpszSystemInfo,
dwResult - 1);

次の例は、 GetVersion関数を使ってWindowsの現在のバージョンを取得し、 メッセージ ボックスにバージョン番号を表示します。

DWORD dwResult;/* function return value */

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */
int nSize;/* size of string */

dwResult = GetVersion();

nSize = sprintf(tchBuffer, "Windows version %d.%d\n",
LOBYTE(LOWORD(dwResult)),
HIBYTE(LOWORD(dwResult)));

MessageBox(NULL, tchBuffer, "GetVersion", MB_ICONINFORMATION);

ハードウェア情報の取得

次の例は、 GetSystemInfo関数を使って、 OEM識別子やプロセッサの種類、 ページ サイズなどのハードウェア情報を取得します。この例は、 ウィンドウのクライアント領域に情報を表示します。

SYSTEM_INFO siSysInfo;/* struct. for hardware info. */

int aTabs[1] = {260};/* tab stop for TabbedTextOut */

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

int nSize; /* size of string */

/* Display the "hardware information" header. */

nSize = sprintf(tchBuffer,

"Hardware information:");

TextOut(hdc, 15, 20, tchBuffer, nSize);

/* Copy the hardware information to the SYSTEM_INFO structure. */

GetSystemInfo(&siSysInfo);

/* Display the contents of the SYSTEM_INFO structure. */

nSize = sprintf(tchBuffer,

"OEM ID: %u\tNumber of Processors: %u",

siSysInfo.dwOemId,

siSysInfo.dwNumberOfProcessors);

TabbedTextOut(hdc, 25, 40, tchBuffer,

nSize, 1, aTabs, 25);

nSize = sprintf(tchBuffer,

"Page size: %u\tProcessor Type: %u",

siSysInfo.dwPageSize,

siSysInfo.dwProcessorType);

TabbedTextOut(hdc, 25, 60, tchBuffer,

nSize, 1, aTabs, 25);

nSize = sprintf(tchBuffer,

"Minimum app address: %lx\tMaximum app address: %lx",

siSysInfo.lpMinimumApplicationAddress,

siSysInfo.lpMaximumApplicationAddress);

TabbedTextOut(hdc, 25, 80, tchBuffer,

nSize, 1, aTabs, 25);

nSize = sprintf(tchBuffer,

"Active processor mask: %u",

siSysInfo.dwActiveProcessorMask);

TextOut(hdc, 25, 100, tchBuffer, nSize);

次の例は、 GetSystemMetrics関数を使って、 マウスがインストールされているかどうかと、 マウス ボタンが交換されているかどうかを調べます。また、 SystemParametersInfo関数を使って、 マウスのしきい値と速度を取得します。情報はメッセージ ボックスに表示します。

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

int nSize;/* size of string */

BOOL fResult;/* system shutdown flag */

int aMouseInfo[3];/* array for mouse info. */

/* Is there a mouse? */

fResult = GetSystemMetrics(SM_MOUSEPRESENT);

if (fResult == 0) {

/* Indicate if there is no mouse. */

nSize = sprintf(tchBuffer, "No mouse installed.");

} else {

/*

* If there is a mouse, determine if

* its buttons are swapped.

*/

fResult = GetSystemMetrics(SM_SWAPBUTTON);

if (fResult == 0) {

nSize = sprintf(tchBuffer, "Buttons not swapped.\r");

} else {

nSize = sprintf(tchBuffer, "Buttons swapped.\r");

}

/* Get the mouse speed and the threshold values. */

SystemParametersInfo(SPI_GETMOUSE, /* get mouse info.*/

NULL,/* not used*/

&aMouseInfo,/* holds mouse info. */

NULL);/* not used*/

nSize += sprintf(tchBuffer + nSize,

"Speed: %d\r", aMouseInfo[2]);

sprintf(tchBuffer + nSize,

"Threshold (x,y): %d,%d",

aMouseInfo[0], aMouseInfo[1]);

}

/* Display the mouse information. */

MessageBox(NULL, tchBuffer, "Mouse information",

MB_ICONINFORMATION);

次の例は、 SystemParametersInfoを使ってマウスの移動速度を2倍にし、 win.iniファイルとfilewin.iniファイルのMouseSpeed値を更新します。

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

int nSize;/* size of string */

int aMouseInfo[3];/* array for mouse info. */

/* Get the current mouse speed. */

SystemParametersInfo(SPI_GETMOUSE, /* get mouse info.*/

NULL,/* not used*/

&aMouseInfo,/* holds mouse info. */

NULL);/* not used*/

/* Double it. */

aMouseInfo[2] = 2 * aMouseInfo[2];

/* Change the mouse speed to the new value and update WIN.INI. */

SystemParametersInfo(SPI_SETMOUSE, /* set mouse info.*/

NULL,/* not used*/

aMouseInfo,/* mouse info. to set */

SPIF_UPDATEINIFILE);/* update win.ini*/

ウィンドウ要素の色の変更

次の例は、 SetSysColors関数を使って、 アクティブなウィンドウの境界線の色を暗い紫、 アクティブなタイトル バーの色を暗いシアン、 ウィンドウの背景色を明るい灰色にそれぞれ変更します。

/* window elements to change */
int aiElements[3] = {COLOR_ACTIVEBORDER,
COLOR_ACTIVECAPTION,
COLOR_WINDOW};
DWORD aColors[3];/* array of RGB values */

/* Define the new colors. */

aColors[0] = RGB(0x80, 0x00, 0x80);/* dark purple */
aColors[1] = RGB(0x00, 0x80, 0x80);/* dark cyan*/
aColors[2] = RGB(0xC0, 0xC0, 0xC0);/* light gray*/

/*
* Set the window elements in aiElements to the colors
* specified in aColors.
*/

SetSysColors(3, aiElements, aColors);

次の例は、 GetSysColors関数を使って、 ウィンドウの背景色を取得し、 赤、 緑、 青(RGB)の値を16進表記でメッセージ ボックスに表示します。

DWORD dwResult;/* function return value */

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */
int nSize;/* size of string */

/* Get the color of the window background. */

dwResult = GetSysColor(COLOR_WINDOW);

nSize = sprintf(tchBuffer,
"Window color: {%x, %x, %x}",
GetRValue(dwResult),
GetGValue(dwResult),
GetBValue(dwResult));

MessageBox(NULL, tchBuffer, "GetSysColor", MB_ICONINFORMATION);

システムのシャットダウンの例

次の例は、 InitiateSystemShutdown関数を使って、 ローカル コンピュータのシステム シャットダウン処理を開始します。ユーザーがログオンしているコンピュータをシャットダウンするには、 まず、 SE_SHUTDOWN_NAME特権を使用可能にしなければなりません。

HANDLE hToken;/* handle to process token */
TOKEN_PRIVILEGES tkp;/* ptr. to token structure */

BOOL fResult;/* system shutdown flag */

/*
* Get the current process token handle
* so we can get shutdown privilege.
*/

if (!OpenProcessToken(GetCurrentProcess(),
TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &hToken))
ErrorHandler("OpenProcessToken failed.");

/* Get the LUID for shutdown privilege. */

LookupPrivilegeValue(NULL, SE_SHUTDOWN_NAME,
&tkp.Privileges[0].Luid);

tkp.PrivilegeCount = 1;/* one privilege to set*/
tkp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;

/* Get shutdown privilege for this process. */

AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,
(PTOKEN_PRIVILEGES) NULL, 0);

/* Cannot test the return value of AdjustTokenPrivileges. */

if (GetLastError() != ERROR_SUCCESS)
ErrorHandler("AdjustTokenPrivileges enable failed.");

/* Display the shutdown dialog box and start the time-out countdown. */

fResult = InitiateSystemShutdown(
NULL, /* shut down local computer */
"Click on the main window and press \
the Escape key to cancel shutdown.",
/* msg. to user */
20,/* time-out period */
FALSE,/* prompt user to close apps. */
TRUE);/* reboot after shutdown*/

if (!fResult) {
ErrorHandler("InitiateSystemShutdown failed.");
}

/* Disable shutdown privilege. */

tkp.Privileges[0].Attributes = 0;
AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,
(PTOKEN_PRIVILEGES) NULL, 0);

if (GetLastError() != ERROR_SUCCESS)
ErrorHandler("AdjustTokenPrivileges disable failed.");

InitiateSystemShutdownで指定したタイム アウト時間内にAbortSystemShutdown関数が実行されたときは、 システムはシャットダウンしません。次の例は、 ユーザーがアプリケーションのメイン ウィンドウをクリックしてEscキーを押したとき、 システムがシャットダウンしないようにします。上記のように、 システムのシャットダウンを中止するには、 アプリケーションはSE_SHUTDOWN_NAME特権を使用可能にしなければなりません。

HANDLE hToken;/* handle to process token */
TOKEN_PRIVILEGES tkp;/* ptr. to token structure */

BOOL fResult;/* system shutdown flag */

case WM_KEYDOWN:

/* Process only the Escape key. */

if (wParam != VK_ESCAPE) {
break;
}

/*
* Get the current process token handle
* so we can get shutdown privilege.
*/

if (!OpenProcessToken(GetCurrentProcess(),
TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &hToken))
ErrorHandler("OpenProcessToken failed.");

/* Get the LUID for shutdown privilege. */

LookupPrivilegeValue(NULL, SE_SHUTDOWN_NAME,
&tkp.Privileges[0].Luid);

tkp.PrivilegeCount = 1; /* one privilege to set */
tkp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;

/* Get shutdown privilege for this process. */

AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,
(PTOKEN_PRIVILEGES)NULL, 0);

/* Cannot test the return value of AdjustTokenPrivileges. */

if (GetLastError() != ERROR_SUCCESS)
ErrorHandler("AdjustTokenPrivileges enable failed.");

/* Prevent the system from shutting down. */

fResult = AbortSystemShutdown(NULL);

if (!fResult) {
ErrorHandler("AbortSystemShutdown failed.");
}

/* Disable shutdown privilege. */

tkp.Privileges[0].Attributes = 0;
AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,
(PTOKEN_PRIVILEGES) NULL, 0);

if (GetLastError() != ERROR_SUCCESS)
ErrorHandler("AdjustTokenPrivileges disable failed.");

break;

Windowsヘルプの起動

次の例は、 WinHelp関数を使って、 Windowsヘルプ アプリケーションを起動してWindows NTヘルプ ファイルをオープンし、 ヘルプ ファイルの目次を表示します。

HWND hwnd;// main window handle

BOOL bResult// for checking boolean function result

bResult = WinHelp(hWnd, "WINNT.HLP", HELP_CONTENTS, 0L);

次の例は、 Windows NTユーザー ヘルプ ファイルをオープンし、 そのファイル内からキーワード文字列と関連付けられているトピックを検索してそのトピックを表示します。

HWND hwnd;// main window handle

BOOL bResult// for checking boolean function result

bResult = WinHelp(hWnd, "WINNT.HLP", HELP_KEY,

(DWORD) "finding topics");

システム情報関数

システム情報の取得と設定、 システムのシャットダウン、 Windowsヘルプの起動を行う関数を次に示します。

AbortSystemShutdown

ExpandEnvironmentStrings

GetComputerName

GetKeyboardType

GetSysColor

GetSystemDirectory

GetSystemInfo

GetSystemMetrics

GetThreadDesktop

GetUserName

GetVersion

GetVersionEx

GetWindowsDirectory

InitiateSystemShutdown

SetComputerName

SetSysColors

SystemParametersInfo

WinHelp

使われなくなったか、 または削除された関数

DOS3Call

GetCurrentPDB

GetCurrentTask

GetDOSEnvironment

GetWinFlags

IsTask

▲ページトップに戻る

【本を読んでもよくらからない】 … 個別指導でわかりやすくお教えします
inserted by FC2 system