NetAlertRaise 関数 (lmalert.h)
[この関数は、Alerter サービスがサポートされていないため、Windows Vista の時点ではサポートされていません。]
NetAlertRaise 関数は、特定のイベントが発生したときに、登録されているすべてのクライアントに通知します。
アラート メッセージの送信を簡略化するために、代わりに拡張関数 NetAlertRaiseEx を 呼び出すことができます。 NetAlertRaiseEx では、 STD_ALERT 構造体を指定する必要はありません。
構文
NET_API_STATUS NET_API_FUNCTION NetAlertRaise(
[in] LPCWSTR AlertType,
[in] LPVOID Buffer,
[in] DWORD BufferSize
);
パラメーター
[in] AlertType
発生させるアラート クラス (アラートの種類) を指定する定数文字列へのポインター。 このパラメーターには、次の定義済みの値のいずれか、またはネットワーク アプリケーションのユーザー定義アラート クラスを指定できます。 アラートのイベント名には、任意のテキスト文字列を指定できます。
[in] Buffer
中断メッセージをリッスンしているクライアントに送信するデータへのポインター。 データは、固定長のSTD_ALERT構造で始まり、その後に 1 つのADMIN_OTHER_INFO、ERRLOG_OTHER_INFO、PRINT_OTHER_INFO、または USER_OTHER_INFO 構造体内の追加のメッセージ データが続く必要があります。 最後に、バッファーには必要な可変長情報が含まれている必要があります。 詳細については、次の「解説」セクションのコード サンプルを参照してください。
呼び出し元のアプリケーションは、すべての構造体と変数データのメモリを割り当てて解放する必要があります。 詳細については、「 ネットワーク管理機能バッファー」を参照してください。
[in] BufferSize
メッセージ バッファーのサイズ (バイト単位)。
戻り値
関数が成功した場合、戻り値はNERR_Success。
関数が失敗した場合、戻り値はシステム エラー コードであり、 は次のいずれかのエラー コードになります。 考えられるすべてのエラー コードの一覧については、「 システム エラー コード」を参照してください。
リターン コード | 説明 |
---|---|
|
パラメーターが正しくありません。 AlertEventName パラメーターが NULL または空の文字列である場合、Buffer パラメーターが NULL であるか、BufferSize パラメーターがSTD_ALERT構造体のサイズと追加のメッセージ データ構造の固定サイズより小さい場合、このエラーが返されます。 |
|
要求はサポートされていません。 このエラーは、Alerter サービスがサポートされていないため、Windows Vista 以降で返されます。 |
注釈
NetAlertRaise 関数を正常に実行するために、特別なグループ メンバーシップは必要ありません。
NetAlertRaise 関数を呼び出すとき、または関数が ERROR_FILE_NOT_FOUND で失敗した場合は、クライアント コンピューターでアラーラー サービスが実行されている必要があります。
例
次のコード サンプルでは、 NetAlertRaise 関数を呼び出し、 STD_ALERT と ADMIN_OTHER_INFO 構造体を指定して、管理アラートを生成する方法を示します。 最初に、サンプルはメッセージ バッファーのサイズを計算します。 次に、 GlobalAlloc 関数の呼び出しでバッファーを割り当てます。 コードは、 STD_ALERT のメンバーとバッファーの ADMIN_OTHER_INFO 部分に値を割り当てます。 このサンプルでは、ALERT_OTHER_INFO マクロを呼び出して、ADMIN_OTHER_INFO構造体へのポインターを取得します。 また、 ALERT_VAR_DATA マクロを呼び出して、バッファーの変数データ部分へのポインターを取得します。 最後に、このコード サンプルでは、 GlobalFree 関数の呼び出しでバッファーに割り当てられたメモリを解放します。
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <windows.h>
#include <stdio.h>
#include <time.h>
#include <lm.h>
const int ALERT_VAR_DATA_SIZE = 216;
int wmain(int argc, wchar_t *argv[])
{
int nBufferSize;
LPVOID pAlertOtherInfo;
PSTD_ALERT pStdAlert; // STD_ALERT structure
PADMIN_OTHER_INFO pAdminOtherInfo; // ADMIN_OTHER_INFO structure
LPVOID pVarData;
time_t now;
DWORD dwResult;
//
// Check command line arguments.
//
if (argc != 2)
{
fwprintf(stderr, L"Usage: %s LogFileName\n", argv[0]);
exit(1);
}
// Calculate the buffer size;
// then allocate the memory for the buffer.
//
nBufferSize = sizeof(STD_ALERT) + ALERT_VAR_DATA_SIZE;
pAlertOtherInfo = (LPVOID) GlobalAlloc(GPTR, nBufferSize);
if (pAlertOtherInfo == NULL)
{
fwprintf(stderr, L"Unable to allocate memory\n");
exit(1);
}
//
// Assign values to the STD_ALERT portion of the buffer.
// (This is required when you call NetAlertRaise.)
//
pStdAlert = (PSTD_ALERT)pAlertOtherInfo;
time( &now );
pStdAlert->alrt_timestamp = (DWORD)now;
wcscpy_s(pStdAlert->alrt_eventname, EVLEN + 1, ALERT_ADMIN_EVENT);
wcscpy_s(pStdAlert->alrt_servicename, SNLEN + 1, argv[0]);
//
// Retrieve the pointer to the ADMIN_OTHER_INFO structure
// that follows the STD_ALERT portion of the buffer.
// Do this by calling the ALERT_OTHER_INFO macro.
//
pAdminOtherInfo = (PADMIN_OTHER_INFO)ALERT_OTHER_INFO(pAlertOtherInfo);
//
// Assign values to the ADMIN_OTHER_INFO structure.
//
pAdminOtherInfo->alrtad_numstrings = 1;
//
// Error 2377, NERR_LogOverflow, indicates
// a log file is full.
//
pAdminOtherInfo->alrtad_errcode = 2377;
//
// Retrieve the pointer to the variable data portion
// of the buffer by calling the ALERT_VAR_DATA macro.
//
pVarData = (LPTSTR)ALERT_VAR_DATA(pAdminOtherInfo);
//
// Supply the log file name for error 2377.
//
wcsncpy_s((wchar_t*) pVarData, ALERT_VAR_DATA_SIZE/2,
argv[1],
ALERT_VAR_DATA_SIZE/2 );
//
// Send an administrative alert by calling the
// NetAlertRaise function.
//
dwResult = NetAlertRaise(ALERT_ADMIN_EVENT,
pAlertOtherInfo,
nBufferSize);
//
// Display the results of the function call.
//
if (dwResult != NERR_Success)
wprintf(L"NetAlertRaise failed: %d\n", dwResult);
else
wprintf(L"Administrative alert raised successfully.\n");
//
// Free the allocated memory.
//
GlobalFree(pAlertOtherInfo);
return (dwResult);
}
要件
要件 | 値 |
---|---|
サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
対象プラットフォーム | Windows |
ヘッダー | lmalert.h (Lm.h を含む) |
Library | Netapi32.lib |
[DLL] | Netapi32.dll |