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.

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

Vedi anche

ADMIN_OTHER_INFO

ALERT_OTHER_INFO

ALERT_VAR_DATA

Funzioni di avviso

ERRLOG_OTHER_INFO

NetAlertRaiseEx

Funzioni di gestione di rete

Panoramica della gestione della rete

PRINT_OTHER_INFO

STD_ALERT

USER_OTHER_INFO