Condividi tramite

Funzione NetAlertRaiseEx (lmalert.h)

  • Articolo

[Questa funzione non è supportata come in Windows Vista perché il servizio avvisi non è supportato.]

La funzione NetAlertRaiseEx notifica a tutti i client registrati quando si verifica un evento specifico. È possibile chiamare questa funzione estesa per semplificare l'invio di un messaggio di avviso perché NetAlertRaiseEx non richiede di specificare una struttura di STD_ALERT .

Sintassi

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

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.

Nome Significato
ALERT_ADMIN_EVENT
 È necessario un intervento dell'amministratore.
ALERT_ERRORLOG_EVENT
 È stata aggiunta una voce al log degli errori.
ALERT_MESSAGE_EVENT
 Un utente o un'applicazione ha ricevuto un messaggio di trasmissione.
ALERT_PRINT_EVENT
 Si è verificato un processo di stampa completato o si è verificato un errore di stampa.
ALERT_USER_EVENT
 È stata usata un'applicazione o una risorsa.

[in] VariableInfo

Puntatore ai dati da inviare ai client in ascolto del messaggio di interruzione. I dati devono essere costituiti da una strutturaADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO o USER_OTHER_INFO seguita da eventuali informazioni sulla lunghezza variabile necessarie. Per altre informazioni, vedere l'esempio di codice nella sezione Osservazioni seguenti.

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 della rete.

[in] VariableInfoSize

Numero di byte di informazioni sulle variabili nel buffer a cui punta il parametro VariableInfo .

[in] ServiceName

Puntatore a una stringa costante che specifica il nome del servizio che genera il messaggio di interruzione.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è 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
ERROR_INVALID_PARAMETER
 Un parametro non è corretto. Questo errore viene restituito se il parametro AlertEventName è NULL o una stringa vuota, il parametro ServiceName è NULL o una stringa vuota, il parametro VariableInfo è NULL o il parametro VariableInfoSize è maggiore di 512 meno le dimensioni della struttura STD_ALERT.
ERROR_NOT_SUPPORTED
 La richiesta non è supportata. Questo errore viene restituito in Windows Vista e versioni successive poiché il servizio Alerter non è supportato.

Commenti

Non è necessaria alcuna appartenenza a gruppi speciali per eseguire correttamente la funzione NetAlertRaiseEx .

Il servizio alerter deve essere in esecuzione nel computer client quando si chiama la funzione NetAlertRaiseEx oppure la funzione ha esito negativo con ERROR_FILE_NOT_FOUND.

Esempio

L'esempio di codice seguente illustra come generare i tipi seguenti di messaggi di interruzione (avvisi) chiamando la funzione NetAlertRaiseEx :

In ogni istanza il codice assegna valori ai membri della struttura di informazioni di avviso pertinenti. A questo scopo, l'esempio recupera un puntatore alla parte del buffer del messaggio che segue la struttura chiamando la macro ALERT_VAR_DATA . Il codice inserisce anche le stringhe a lunghezza variabile in questa parte del buffer. Infine, l'esempio chiama NetAlertRaiseEx per inviare l'avviso.

Si noti che l'applicazione chiamante deve allocare e liberare la memoria per tutte le strutture e i dati a lunghezza variabile in un buffer di messaggi di avviso.

Per passare una struttura definita dall'utente e stringhe valide in un avviso utente, è necessario creare un file di messaggio di evento e collegarlo all'applicazione. È anche necessario registrare l'applicazione nella sottochiave EventMessageFile nella sezione EventLog del Registro di sistema. Se non si registra l'applicazione, l'avviso utente conterrà le informazioni passate nelle stringhe a lunghezza variabile che seguono la struttura USER_OTHER_INFO . Per altre informazioni su EventMessageFile, vedere Registrazione eventi.

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

Requisiti

   
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

Vedi anche

ADMIN_OTHER_INFO

ALERT_VAR_DATA

Funzioni di avviso

ERRLOG_OTHER_INFO

NetAlertRaise

Funzioni di gestione della rete

Panoramica sulla gestione della rete

PRINT_OTHER_INFO

USER_OTHER_INFO