NetAlertRaiseEx 函式 (lmalert.h)

發行項
08/24/2023

[自 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

常數位符串的指標，指定要引發之警示類別 (類型的警示) 。此參數可以是下列其中一個預先定義的值，或網路應用程式的使用者定義警示類別。 (警示的事件名稱可以是任何文字 string.)

名稱	意義
ALERT_ADMIN_EVENT	需要系統管理員的介入。
ALERT_ERRORLOG_EVENT	已將專案新增至錯誤記錄檔。
ALERT_MESSAGE_EVENT	使用者或應用程式收到廣播訊息。
ALERT_PRINT_EVENT	列印工作已完成或發生列印錯誤。
ALERT_USER_EVENT	已使用應用程式或資源。

[in] VariableInfo

要傳送給接聽中斷訊息之用戶端之資料的指標。資料應該包含一個 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	不支援此要求。 Windows Vista 和更新版本會傳回此錯誤，因為不支援 Alerter 服務。

備註

成功執行 NetAlertRaiseEx 函 式不需要特殊群組成員資格。

當您呼叫 NetAlertRaiseEx 函式時，警示程式服務必須在用戶端電腦上執行，否則函式會因為ERROR_FILE_NOT_FOUND而失敗。

範例

下列程式碼範例示範如何藉由呼叫 NetAlertRaiseEx 函式，引發下列類型的中斷訊息 (警示) ：

藉由指定 ADMIN_OTHER_INFO 結構來管理警示
藉由指定 PRINT_OTHER_INFO 結構來列印警示
藉由指定 USER_OTHER_INFO 結構來警示使用者

在每個實例中，程式碼都會將值指派給相關警示資訊結構的成員。在此之後，此範例會藉由呼叫 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 (包含 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll