NetAlertRaise 函式 (lmalert.h)

發行項
02/28/2024

[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 結構開始，後面接著一個 ADMIN_OTHER_INFO、 ERRLOG_OTHER_INFO、 PRINT_OTHER_INFO或 USER_OTHER_INFO 結構中的其他訊息數據。最後，緩衝區應該包含任何必要的可變長度資訊。如需詳細資訊，請參閱下列一節中的程式代碼範例。

呼叫的應用程式必須配置並釋放所有結構和變數數據的記憶體。如需詳細資訊，請參閱網路管理功能緩衝區。

[in] BufferSize

訊息緩衝區的大小，以位元組為單位。

傳回值

如果函式成功，傳回值會NERR_Success。

如果函式失敗，傳回值為系統錯誤碼，而且可以是下列其中一個錯誤碼。如需所有可能錯誤碼的清單，請參閱系統錯誤碼。

傳回碼	Description
ERROR_INVALID_PARAMETER	參數不正確。如果 AlertEventName 參數為 NULL 或空字串、Buffer 參數為 NULL，或 BufferSize 參數小於STD_ALERT結構的大小加上其他訊息數據結構的固定大小，則會傳回此錯誤。
ERROR_NOT_SUPPORTED	不支援此要求。 Windows Vista 和更新版本會傳回此錯誤，因為不支援 Alerter 服務。

備註

成功執行 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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	lmalert.h (包括 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll