NetAlertRaiseEx-Funktion (lmalert.h)

[Diese Funktion wird ab Windows Vista nicht unterstützt, da der Warnungsdienst nicht unterstützt wird.]

Die NetAlertRaiseEx-Funktion benachrichtigt alle registrierten Clients, wenn ein bestimmtes Ereignis auftritt. Sie können diese erweiterte Funktion aufrufen, um das Senden einer Warnmeldung zu vereinfachen, da NetAlertRaiseEx keine STD_ALERT-Struktur angeben muss.

Syntax

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

Parameter

[in] AlertType

Ein Zeiger auf eine konstante Zeichenfolge, die die warnungsklasse (Warnungstyp) angibt, die ausgelöst werden soll. Dieser Parameter kann einer der folgenden vordefinierten Werte oder eine benutzerdefinierte Warnungsklasse für Netzwerkanwendungen sein. (Der Ereignisname für eine Warnung kann eine beliebige Textzeichenfolge sein.)

Name	Bedeutung
ALERT_ADMIN_EVENT	Ein Administratoreingriff ist erforderlich.
ALERT_ERRORLOG_EVENT	Dem Fehlerprotokoll wurde ein Eintrag hinzugefügt.
ALERT_MESSAGE_EVENT	Ein Benutzer oder eine Anwendung hat eine Broadcastnachricht empfangen.
ALERT_PRINT_EVENT	Ein Druckauftrag wurde abgeschlossen, oder es ist ein Druckfehler aufgetreten.
ALERT_USER_EVENT	Eine Anwendung oder Ressource wurde verwendet.

[in] VariableInfo

Ein Zeiger auf die Daten, die an die Clients gesendet werden sollen, die auf die unterbrechende Nachricht lauschen. Die Daten sollten aus einer ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO oder USER_OTHER_INFO-Struktur bestehen, gefolgt von erforderlichen Informationen mit variabler Länge. Weitere Informationen finden Sie im Codebeispiel im folgenden Abschnitt "Hinweise".

Die aufrufende Anwendung muss den Arbeitsspeicher für alle Strukturen und Variablendaten zuordnen und freigeben. Weitere Informationen finden Sie unter Netzwerkverwaltungsfunktionspuffer.

[in] VariableInfoSize

Die Anzahl der Byte von Variableninformationen im Puffer, auf den der VariableInfo-Parameter verweist.

[in] ServiceName

Ein Zeiger auf eine konstante Zeichenfolge, die den Namen des Diensts angibt, der die unterbrechende Nachricht auslöst.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode, und ein kann einer der folgenden Fehlercodes sein. Eine Liste aller möglichen Fehlercodes finden Sie unter Systemfehlercodes.

Rückgabecode	Beschreibung
ERROR_INVALID_PARAMETER	Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn der AlertEventName-ParameterNULL oder eine leere Zeichenfolge, der ServiceName-ParameterNULL oder eine leere Zeichenfolge, der VariableInfo-ParameterNULL oder der VariableInfoSize-Parameter größer als 512 abzüglich der Größe der STD_ALERT-Struktur ist.
ERROR_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt. Dieser Fehler wird unter Windows Vista und höher zurückgegeben, da der Warnungsdienst nicht unterstützt wird.

Hinweise

Für die erfolgreiche Ausführung der NetAlertRaiseEx-Funktion ist keine spezielle Gruppenmitgliedschaft erforderlich.

Der Warnungsdienst muss auf dem Clientcomputer ausgeführt werden, wenn Sie die NetAlertRaiseEx-Funktion aufrufen, oder die Funktion schlägt mit ERROR_FILE_NOT_FOUND fehl.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie die folgenden Typen von Unterbrechungsmeldungen (Warnungen) ausgelöst werden, indem Sie die NetAlertRaiseEx-Funktion aufrufen:

• Eine administratorische Warnung durch Angeben einer ADMIN_OTHER_INFO-Struktur
• Eine Druckwarnung durch Angabe einer PRINT_OTHER_INFO-Struktur
• Eine Benutzerwarnung durch Angeben einer USER_OTHER_INFO-Struktur

In jedem instance der Code den Membern der relevanten Warnungsinformationsstruktur Werte zu. Anschließend ruft das Beispiel einen Zeiger auf den Teil des Nachrichtenpuffers ab, der der Struktur folgt, indem das makro ALERT_VAR_DATA aufgerufen wird. Der Code füllt auch die Zeichenfolgen mit variabler Länge in diesem Teil des Puffers aus. Schließlich ruft das Beispiel NetAlertRaiseEx auf, um die Warnung zu senden.

Beachten Sie, dass die aufrufende Anwendung den Arbeitsspeicher für alle Strukturen und Daten mit variabler Länge in einem Warnungsmeldungspuffer zuordnen und freigeben muss.

Um eine benutzerdefinierte Struktur und gültige Zeichenfolgen in einer Benutzerwarnung zu übergeben, müssen Sie eine Ereignismeldungsdatei erstellen und mit Ihrer Anwendung verknüpfen. Sie müssen die Anwendung auch im Unterschlüssel EventMessageFile im Abschnitt EventLog der Registrierung registrieren. Wenn Sie die Anwendung nicht registrieren, enthält die Benutzerwarnung die Informationen, die Sie in den Zeichenfolgen variabler Länge übergeben, die der USER_OTHER_INFO-Struktur folgen. Weitere Informationen zu EventMessageFile finden Sie unter Ereignisprotokollierung.

#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);   
}

Anforderungen

Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	lmalert.h (lm.h einschließen)
Bibliothek	Netapi32.lib
DLL	Netapi32.dll

Weitere Informationen

ADMIN_OTHER_INFO

ALERT_VAR_DATA

Warnungsfunktionen

ERRLOG_OTHER_INFO

NetAlertRaise

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung

PRINT_OTHER_INFO

USER_OTHER_INFO