NetAlertRaise-Funktion (lmalert.h)

Artikel
02/28/2024

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

Die NetAlertRaise-Funktion benachrichtigt alle registrierten Clients, wenn ein bestimmtes Ereignis auftritt.

Um das Senden einer Warnmeldung zu vereinfachen, können Sie stattdessen die erweiterte Funktion NetAlertRaiseEx aufrufen. NetAlertRaiseEx erfordert keine Angabe einer STD_ALERT-Struktur .

Syntax

NET_API_STATUS NET_API_FUNCTION NetAlertRaise(
  [in] LPCWSTR AlertType,
  [in] LPVOID  Buffer,
  [in] DWORD   BufferSize
);

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] Buffer

Ein Zeiger auf die Daten, die an die Clients gesendet werden sollen, die auf die unterbrechende Nachricht lauschen. Die Daten sollten mit einer STD_ALERT-Struktur fester Länge beginnen, gefolgt von zusätzlichen Nachrichtendaten in einer ADMIN_OTHER_INFO-, ERRLOG_OTHER_INFO-, PRINT_OTHER_INFO- oder USER_OTHER_INFO-Struktur . Schließlich sollte der Puffer alle erforderlichen Informationen mit variabler Länge enthalten. 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] BufferSize

Die Größe des Nachrichtenpuffers in Bytes.

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 ist, der Buffer-ParameterNULL ist oder der BufferSize-Parameter kleiner als die Größe der STD_ALERT-Struktur plus der festen Größe für die zusätzliche Nachrichtendatenstruktur 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

Es ist keine spezielle Gruppenmitgliedschaft erforderlich, um die NetAlertRaise-Funktion erfolgreich auszuführen.

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

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Sie eine Administratorwarnung auslösen, indem Sie die NetAlertRaise-Funktion aufrufen und STD_ALERT - und ADMIN_OTHER_INFO-Strukturen angeben. Zunächst berechnet das Beispiel die Größe des Nachrichtenpuffers. Anschließend wird der Puffer mit einem Aufruf der GlobalAlloc-Funktion zugeordnet. Der Code weist den Membern des STD_ALERT und den ADMIN_OTHER_INFO Teilen des Puffers Werte zu. Das Beispiel ruft einen Zeiger auf die ADMIN_OTHER_INFO-Struktur ab, indem das makro ALERT_OTHER_INFO aufgerufen wird. Außerdem wird ein Zeiger auf den Variablendatenteil des Puffers abgerufen, indem das Makro ALERT_VAR_DATA aufgerufen wird. Schließlich gibt das Codebeispiel den für den Puffer zugewiesenen Arbeitsspeicher mit einem Aufruf der GlobalFree-Funktion frei.

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

Anforderungen

Anforderung	Wert
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