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.)
[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 |
|---|---|
|
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. |
|
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
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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für