Funzione NetAlertRaise (lmalert.h)
[Questa funzione non è supportata a partire da Windows Vista perché il servizio alerter non è supportato.]
La funzione NetAlertRaise notifica a tutti i client registrati quando si verifica un determinato evento.
Per semplificare l'invio di un messaggio di avviso, è possibile chiamare invece la funzione estesa NetAlertRaiseEx . NetAlertRaiseEx non richiede di specificare una struttura STD_ALERT .
Sintassi
NET_API_STATUS NET_API_FUNCTION NetAlertRaise(
[in] LPCWSTR AlertType,
[in] LPVOID Buffer,
[in] DWORD BufferSize
);
Parametri
[in] AlertType
Puntatore a una stringa costante che specifica la classe di avviso (tipo di avviso) da generare. Questo parametro può essere uno dei valori predefiniti seguenti o una classe di avviso definita dall'utente per le applicazioni di rete. Il nome dell'evento per un avviso può essere qualsiasi stringa di testo.
[in] Buffer
Puntatore ai dati da inviare ai client in ascolto del messaggio di interruzione. I dati devono iniziare con una struttura a lunghezza fissa STD_ALERT seguita da dati di messaggio aggiuntivi in una struttura di ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO o USER_OTHER_INFO . Infine, il buffer deve includere tutte le informazioni di lunghezza variabile necessarie. Per altre informazioni, vedere l'esempio di codice nella sezione Osservazioni seguente.
L'applicazione chiamante deve allocare e liberare la memoria per tutte le strutture e i dati delle variabili. Per altre informazioni, vedere Buffer delle funzioni di gestione di rete.
[in] BufferSize
Dimensione, in byte, del buffer dei messaggi.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene NERR_Success.
Se la funzione ha esito negativo, il valore restituito è un codice di errore di sistema e può essere uno dei codici di errore seguenti. Per un elenco di tutti i codici di errore possibili, vedere Codici di errore di sistema.
| Codice restituito | Descrizione |
|---|---|
|
Un parametro non è corretto. Questo errore viene restituito se il parametro AlertEventName è NULL o una stringa vuota, il parametro Buffer è NULL o il parametro BufferSize è minore delle dimensioni della struttura STD_ALERT più le dimensioni fisse per la struttura di dati del messaggio aggiuntiva. |
|
La richiesta non è supportata. Questo errore viene restituito in Windows Vista e versioni successive perché il servizio Alerter non è supportato. |
Commenti
Per eseguire correttamente la funzione NetAlertRaise non è necessaria alcuna appartenenza a gruppi speciali.
Il servizio alerter deve essere in esecuzione nel computer client quando si chiama la funzione NetAlertRaise oppure la funzione ha esito negativo con ERROR_FILE_NOT_FOUND.
Esempio
Nell'esempio di codice seguente viene illustrato come generare un avviso amministrativo chiamando la funzione NetAlertRaise e specificando STD_ALERT e strutture ADMIN_OTHER_INFO . In primo luogo, il campione calcola le dimensioni del buffer dei messaggi. Alloca quindi il buffer con una chiamata alla funzione GlobalAlloc . Il codice assegna valori ai membri del STD_ALERT e alle parti ADMIN_OTHER_INFO del buffer. L'esempio recupera un puntatore alla struttura ADMIN_OTHER_INFO chiamando la macro ALERT_OTHER_INFO . Recupera anche un puntatore alla parte dati variabile del buffer chiamando la macro ALERT_VAR_DATA . Infine, l'esempio di codice libera la memoria allocata per il buffer con una chiamata alla funzione 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);
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | lmalert.h (include Lm.h) |
| Libreria | Netapi32.lib |
| DLL | Netapi32.dll |