NetAlertRaiseEx 関数 (lmalert.h)

  • [アーティクル]

[この関数は Windows Vista ではサポートされていません。これは、アラート サービスがサポートされていないためです。

NetAlertRaiseEx 関数は、特定のイベントが発生したときに、登録されているすべてのクライアントに通知します。 NetAlertRaiseEx ではSTD_ALERT構造体を指定する必要がないため、この拡張関数を呼び出してアラート メッセージの送信を簡略化できます。

構文

NET_API_STATUS NET_API_FUNCTION NetAlertRaiseEx(
  [in] LPCWSTR AlertType,
  [in] LPVOID  VariableInfo,
  [in] DWORD   VariableInfoSize,
  [in] LPCWSTR ServiceName
);

パラメーター

[in] AlertType

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

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

[in] VariableInfo

割り込みメッセージをリッスンしているクライアントに送信するデータへのポインター。 データは、1 つのADMIN_OTHER_INFO、ERRLOG_OTHER_INFO、PRINT_OTHER_INFO、またはUSER_OTHER_INFO構造体の後に必要な可変長情報が続く必要があります。 詳細については、次の「解説」セクションのコード サンプルを参照してください。

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

[in] VariableInfoSize

VariableInfo パラメーターが指すバッファー内の変数情報のバイト数。

[in] ServiceName

中断メッセージを発生させるサービスの名前を指定する定数文字列へのポインター。

戻り値

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

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

リターン コード 説明
ERROR_INVALID_PARAMETER
 パラメーターが正しくありません。 このエラーは、AlertEventName パラメーターが NULL または空の文字列、ServiceName パラメーターが NULL または空の文字列、VariableInfo パラメーターが NULL、または VariableInfoSize パラメーターが 512 からSTD_ALERT構造体のサイズを引いた値を超える場合に返されます。
ERROR_NOT_SUPPORTED
 要求はサポートされていません。 このエラーは、Alerter サービスがサポートされていないため、Windows Vista 以降で返されます。

解説

NetAlertRaiseEx 関数を正常に実行するために特別なグループ メンバーシップは必要ありません。

NetAlertRaiseEx 関数を呼び出すとき、または関数が ERROR_FILE_NOT_FOUND で失敗した場合は、クライアント コンピューターで alerter サービスが実行されている必要があります。

例

次のコード サンプルは、 NetAlertRaiseEx 関数を呼び出して、次の種類の中断メッセージ (アラート) を発生させる方法を示しています。

各インスタンスで、コードは関連するアラート情報構造のメンバーに値を割り当てます。 この後、このサンプルでは、 ALERT_VAR_DATA マクロを呼び出して、構造体の後に続くメッセージ バッファーの部分へのポインターを取得します。 コードは、バッファーのこの部分の可変長文字列も入力します。 最後に、サンプルは NetAlertRaiseEx を呼び出してアラートを送信します。

呼び出し元のアプリケーションは、アラート メッセージ バッファー内のすべての構造体と可変長データのメモリを割り当てて解放する必要があることに注意してください。

ユーザー定義構造体と有効な文字列をユーザー アラートに渡すには、イベント メッセージ ファイルを作成し、アプリケーションにリンクする必要があります。 また、レジストリの EventLog セクションの EventMessageFile サブキーにアプリケーションを登録する必要もあります。 アプリケーションを登録しない場合、ユーザー アラートには、 USER_OTHER_INFO 構造に従う可変長文字列に渡す情報が含まれます。 EventMessageFile の詳細については、「イベント ログ」を参照してください。

#ifndef UNICODE
#define UNICODE
#endif

#pragma comment(lib, "netapi32.lib")

#include <windows.h>
#include <lm.h>
#include <stdio.h>
#include <time.h>
//
// Define default strings.
//
#define PROGRAM_NAME    TEXT("NETALRT")
#define szComputerName  TEXT("\\\\TESTCOMPUTER")
#define szUserName      TEXT("TEST")
#define szQueueName     TEXT("PQUEUE")
#define szDestName      TEXT("MYPRINTER")
#define szStatus        TEXT("OK")
//
// Define structure sizes.
//
#define VAREDSIZE 312  // maximum size of the variable length message
char buff[VAREDSIZE];
//
int main()
{
   time_t             now;
   PADMIN_OTHER_INFO  pAdminInfo; // ADMIN_OTHER_INFO structure
   PPRINT_OTHER_INFO  pPrintInfo; // PRINT_OTHER_INFO structure
   PUSER_OTHER_INFO   pUserInfo;  // USER_OTHER_INFO structure
   TCHAR              *p;
   DWORD dwResult; 

   time( &now );  // Retrieve the current time to print it later.

   //
   // Sending an administrative alert 
   //
   // Assign values to the members of the ADMIN_OTHER_INFO structure.
   //
   pAdminInfo = (PADMIN_OTHER_INFO) buff; 
   ZeroMemory(pAdminInfo, VAREDSIZE);
   //
   // Error 2377, NERR_LogOverflow, indicates
   //  a log file is full.
   //
   pAdminInfo->alrtad_errcode = 2377;
   pAdminInfo->alrtad_numstrings = 1;
   //
   // Retrieve a pointer to the variable data portion at the 
   //  end of the buffer by calling the ALERT_VAR_DATA macro.
   //
   p = (LPTSTR) ALERT_VAR_DATA(pAdminInfo); 
   //
   // Fill in the variable-length, concatenated strings 
   //  that follow the ADMIN_OTHER_INFO structure. These strings
   //  will be written to the message log.
   //
   wcscpy_s(p,VAREDSIZE/2, TEXT("'C:\\MYLOG.TXT'")); 
   //
   // Call the NetAlertRaiseEx function to raise the
   //  administrative alert.
   //
   dwResult = NetAlertRaiseEx(ALERT_ADMIN_EVENT, pAdminInfo, 255 , TEXT("MYSERVICE"));
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
   {
      wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
      return -1;
   }
   else
      wprintf(L"Administrative alert raised successfully.\n");


   //
   // Sending a print alert
   //
   // Assign values to the members of the PRINT_OTHER_INFO structure.
   //
   pPrintInfo = (PPRINT_OTHER_INFO) buff; 
   ZeroMemory(pPrintInfo, VAREDSIZE);        
   pPrintInfo->alrtpr_jobid = 5457;
   pPrintInfo->alrtpr_status = 0;
   pPrintInfo->alrtpr_submitted = (DWORD) now;
   pPrintInfo->alrtpr_size = 1000;
   //
   // Retrieve a pointer to the variable data portion at the 
   //  end of the buffer by calling the ALERT_VAR_DATA macro. 
   //
   p = (LPTSTR) ALERT_VAR_DATA(pPrintInfo);  
   //
   // Fill in the variable-length, concatenated strings 
   //  that follow the PRINT_OTHER_INFO structure. 
   //
   wcscpy_s(p, VAREDSIZE/2, szComputerName); // computername 
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-1, szUserName);     // user name
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-wcslen(szUserName)-2, 
       szQueueName);    // printer queuename
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-wcslen(szUserName)-wcslen(szQueueName)-3,
       szDestName);     // destination or printer name (optional)
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-wcslen(szUserName)-wcslen(szQueueName) 
       - wcslen(szDestName)-4, szStatus);       // status of the print job (optional)
   //
   // Call the NetAlertRaiseEx function to raise the
   //  print alert.
   //
   dwResult = NetAlertRaiseEx(ALERT_PRINT_EVENT, pPrintInfo, VAREDSIZE, TEXT("MYSERVICE"));
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
   {
      wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
      return -1;
   }
   else
      wprintf(L"Print alert raised successfully.\n");


   //
   // Sending a user alert
   //
   // Assign values to the members of the USER_OTHER_INFO structure.
   //
   pUserInfo  = (PUSER_OTHER_INFO)  buff; 
   ZeroMemory(pUserInfo, VAREDSIZE);
   pUserInfo->alrtus_errcode = 0xffff;
   pUserInfo->alrtus_numstrings = 1;
   //
   // Retrieve a pointer to the variable data portion at the 
   //  end of the buffer by calling the ALERT_VAR_DATA macro.
   //
   p = (LPTSTR) ALERT_VAR_DATA(pUserInfo); 
   //
   // Fill in the variable-length, concatenated strings 
   //  that follow the USER_OTHER_INFO structure.
   //
   wcscpy_s(p,(VAREDSIZE/2), TEXT("C:\\USERLOG.TXT"));
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2) - wcslen(TEXT("C:\\USERLOG.TXT"))-1, szUserName);
   //
   // Call the NetAlertRaiseEx function to raise the
   //  user alert.
   //
   dwResult = NetAlertRaiseEx(ALERT_USER_EVENT, pUserInfo, VAREDSIZE, TEXT("MYSERVICE"));
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
   {
      wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
      return -1;
   }
   else
      wprintf(L"User alert raised successfully.\n");

   return(dwResult);   
}

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー lmalert.h (include Lm.h)
Library Netapi32.lib
[DLL] Netapi32.dll

関連項目

ADMIN_OTHER_INFO

ALERT_VAR_DATA

アラート関数

ERRLOG_OTHER_INFO

NetAlertRaise

ネットワーク管理機能

ネットワーク管理の概要

PRINT_OTHER_INFO

USER_OTHER_INFO