NetAlertRaise 関数 (lmalert.h)

[アーティクル]
08/24/2023

[この関数は、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

発生させるアラートクラス (アラートの種類) を指定する定数文字列へのポインター。このパラメーターには、次の定義済みの値のいずれか、またはネットワークアプリケーションのユーザー定義アラートクラスを指定できます。アラートのイベント名には、任意のテキスト文字列を指定できます。

名前	意味
ALERT_ADMIN_EVENT	管理者の介入が必要です。
ALERT_ERRORLOG_EVENT	エラーログにエントリが追加されました。
ALERT_MESSAGE_EVENT	ユーザーまたはアプリケーションがブロードキャストメッセージを受信しました。
ALERT_PRINT_EVENT	印刷ジョブが完了したか、印刷エラーが発生しました。
ALERT_USER_EVENT	アプリケーションまたはリソースが使用されました。

[in] Buffer

中断メッセージをリッスンしているクライアントに送信するデータへのポインター。データは、固定長のSTD_ALERT構造で始まり、その後に 1 つのADMIN_OTHER_INFO、ERRLOG_OTHER_INFO、PRINT_OTHER_INFO、または USER_OTHER_INFO 構造体内の追加のメッセージデータが続く必要があります。最後に、バッファーには必要な可変長情報が含まれている必要があります。詳細については、次の「解説」セクションのコードサンプルを参照してください。

呼び出し元のアプリケーションは、すべての構造体と変数データのメモリを割り当てて解放する必要があります。詳細については、「ネットワーク管理機能バッファー」を参照してください。

[in] BufferSize

メッセージバッファーのサイズ (バイト単位)。

戻り値

関数が成功した場合、戻り値はNERR_Success。

関数が失敗した場合、戻り値はシステムエラーコードであり、は次のいずれかのエラーコードになります。考えられるすべてのエラーコードの一覧については、「システムエラーコード」を参照してください。

リターンコード	説明
ERROR_INVALID_PARAMETER	パラメーターが正しくありません。 AlertEventName パラメーターが NULL または空の文字列である場合、Buffer パラメーターが NULL であるか、BufferSize パラメーターがSTD_ALERT構造体のサイズと追加のメッセージデータ構造の固定サイズより小さい場合、このエラーが返されます。
ERROR_NOT_SUPPORTED	要求はサポートされていません。このエラーは、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