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

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

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

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

Windows API エラーの概要

よくできたアプリケーションは、 予期しないエラーからでも修復できます。エラーが発生したら、 アプリケーションは、 ユーザーの介入を要求するか、 単独でエラーを修復します。極端な場合は、 ユーザーをログオフさせたり、 システムをシャット ダウンします。

Microsoft(R) Windows(TM) には、 0による除算などの例外のための特別なエラー処理機構があります。例外処理について詳しくは、 構造化例外処理の概要を参照してください。

次に示すトピックでは、 エラーについて説明しています。

ユーザーへの通知

ログオフとシャット ダウン

最終エラー コード

エラー メッセージ ボックス

ユーザーへの通知

ログオフ

シャット ダウン

最終エラー コードの取得

エラー関数

ユーザーへの通知

何らかのエラーが発生したことをユーザーに通知するには、 Beep関数やMessageBeep関数を使って警告音を生成するか、 FlashWindow関数を使ってウィンドウを点滅させます。また、 これらの関数を使ってユーザーの注意をひいてから、 エラーの詳細を示すメッセージ ボックスやエラー メッセージを表示します。

ログオフとシャット ダウン

現在のユーザーをログオフさせるには、 ExitWindows関数を使います。また、 ExitWindowsEx関数は、 次に示す処理のいずれかを行います。

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

システムのシャット ダウンと再起動

ログオフと、 すべてのアプリケーションの終了

ログオフによって、 終了関数を呼び出したプロセスのセキュリティ コンテキストに関連付けられているプロセスはすべて停止して、 ユーザーはシステムからログオフし、 [Logon]ダイアログ ボックスが表示されます。

「シャット ダウン」によって、 システムは、 コンピュータの電源を切っても安全な状態に移行します。ファイル システムのバッファはすべてディスクにフラッシュ (書き込み) され、 コンピュータの電源を切ってもよいことを示すメッセージ ボックスが表示されます。再起動オプションが指定されているときは、 コンピュータは再起動します。

シャット ダウンまたはシャット ダウンして再起動する場合、 呼び出し側のプロセスは、 SE_SHUTDOWN_NAME特権を持っていなければなりません。この特権を使用可能にしてシステムをシャット ダウンする例については、 シャット ダウンを参照してください。

最終エラー コード

エラーが発生すると、 Microsoft(R) Win32(R) アプリケーション プログラミング インターフェイス (API) のほとんどの関数は、 FALSENULL 0xFFFFFFFF、 -1を返します。また、 「最終エラー コード」と呼ばれる内部エラー コードも設定します。関数が正常に終了したときは、 最終エラー コードはリセットされません。エラー コードは各スレッドに対して個別に管理されています。あるスレッドでエラーが発生しても、 ほかのスレッドの最終エラー コードは変更されません。最終エラー コードを取得するには、 GetLastError関数を使います。エラー コードによって、 関数が失敗した理由をより詳細に知ることができます。

SetLastError関数は、 現在のスレッドの最終エラー コードを設定します。また、 SetLastErrorEx関数は、 エラーの重大さを示すエラーの種類を設定します。これらの関数は主としてダイナミック リンク ライブラリ用であり、 DLLはこれらの関数を使ってWin32 APIの動作をエミュレートできます。

Win32 APIでは、 上記の関数が返すエラー コードのセットを定義しています。このエラー コードは、 最終エラー コードの設定にも使えます。

エラー コードは、 32ビット値です (ビット31が最上位ビットです)。ビット29は、 アプリケーション定義のエラー用に予約されています。Win32 APIのエラー コードではこのビットはセットされません。アプリケーション用のエラー コードを定義する場合は、 このビットをセットして、 そのエラー コードがアプリケーション定義のものであることを示し、 システム定義のエラー コードと重複しないようにしてください。

エラー メッセージ ボックス

ドライブの準備ができていないとき (フロッピー ディスク ドライブのドアが開いているとき) などのエラーでは、 Windowsは、 エラーが発生したことを示すダイアログ ボックスを表示します。このようなエラーをユーザーの介入なしに処理するアプリケーションは、 SetErrorMode関数を使って、 エラー メッセージ ボックスが表示されないようにすることができます。

エラーの使用

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

ウィンドウの点滅、 警告音、 およびエラー メッセージ ボックスの表示

現在のユーザーのログオフ

システムのシャット ダウンと再起動

Win32関数失敗後の最終エラー コードの取得

ユーザーへの通知

次に示すコード例は、 ウィンドウを点滅させてシステム警告音を再生し、 メッセージ ボックスを表示します。

FlashWindow(hwnd, TRUE); /* invert the title bar*/
Sleep(500);/* wait a bit*/
FlashWindow(hwnd, TRUE); /* invert again*/

/* Play the system exclamation sound. */

MessageBeep(MB_ICONEXCLAMATION);

ログオフ

ExitWindows関数は、 現在のユーザーをログオフさせます。ユーザーがログオフするには、 すべてのアプリケーションが終了に同意しなければなりません。WM_QUERYENDSESSIONメッセージに対してFALSEを返すアプリケーションがあれば、 ユーザーはログオフしません。アプリケーションでWM_QUERYENDSESSIONメッセージを処理するときは、 そのメッセージがほかのアプリケーションやWindowsが生成したものであっても、 ユーザーがログオフ操作を取り消せるようにしてください。

次の例は、 WM_QUERYENDSESSIONメッセージを受け取ったときに表示したメッセージ ボックスの[No]ボタンをユーザーが選択しなければ、 ユーザーをログオフさせます。

ExitWindows(0, 0); /* log the current user off*/

case WM_QUERYENDSESSION: /* in application's MainWndProc */
{
int i= MessageBox(NULL, "Shutdown?",
"Received WM_QUERYENDSESSION", MB_YESNO);

/*
* Return TRUE to allow shutdown, FALSE to stop.
*/

return i == IDYES;
break;
}

シャット ダウン

システムをシャット ダウンするには、 ExitWindowsEx関数を使います。シャット ダウンによって、 ファイル バッファがディスクにフラッシュされ、 システムは、 安全にコンピュータの電源を切ることができる状態に移行します。システムをシャット ダウンするには、 呼び出し側のプロセスはSE_SHUTDOWN_NAME特権を持っていなければなりません。

次に示す例は、 SE_SHUTDOWN_NAME特権を使用可能にして、 システムをシャット ダウンします。

HANDLE hToken;
TOKEN_PRIVILEGES tkp;

/* Get a token for this process. */

if (!OpenProcessToken(GetCurrentProcess(),
TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &hToken))
error("OpenProcessToken");

/* Get the LUID for shutdown privilege. */

LookupPrivilegeValue(NULL, TEXT("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)
error("AdjustTokenPrivileges");

/* Shut down the system and force all applications to close. */

if (!ExitWindowsEx(EWX_SHUTDOWN | EWX_FORCE, 0))
error("ExitWindowsEx");

セキュリティ特権の設定について詳しくは、 セキュリティの概要を参照してください。

最終エラー コードの取得

Win32 APIの関数は、 失敗すると、 最終エラー コードを設定します。エラーの詳細が必要なときは、 最終エラー コードを取得してください。

次の例は、 このトピックのほかの例で使われるエラー処理関数を示しています。

void error(LPSTR lpszFunction)
{
CHAR szBuf[80];
DWORD dw = GetLastError();

sprintf(szBuf, "%s failed: GetLastError returned %u\n",
lpszFunction, dw);

MessageBox(NULL, szBuf, "ERROR", MB_OK);
ExitProcess(dw);
}

エラー関数

エラーに関する関数を次に示します。

Beep

ExitWindows

ExitWindowsEx

FlashWindow

GetLastError

MessageBeep

SetErrorMode

SetLastError

SetLastErrorEx

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

CloseSound

CountVoiceNotes

GetThresholdEvent

GetThresholdStatus

OpenSound

SetSoundNoise

SetVoiceAccent

SetVoiceEnvelope

SetVoiceNote

SetVoiceQueueSize

SetVoiceSound

SetVoiceThreshold

StartSound

StopSound

SyncAllVoices

WaitSoundState

▲ページトップに戻る

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