Función NetAlertRaiseEx (lmalert.h)

  • Artículo

[Esta función no se admite a partir de Windows Vista porque no se admite el servicio alerter.]

La función NetAlertRaiseEx notifica a todos los clientes registrados cuando se produce un evento determinado. Puede llamar a esta función extendida para simplificar el envío de un mensaje de alerta porque NetAlertRaiseEx no requiere que especifique una estructura de STD_ALERT .

Sintaxis

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

Parámetros

[in] AlertType

Puntero a una cadena constante que especifica la clase de alerta (tipo de alerta) que se va a generar. Este parámetro puede ser uno de los siguientes valores predefinidos o una clase de alerta definida por el usuario para las aplicaciones de red. (El nombre del evento de una alerta puede ser cualquier cadena de texto).

Nombre Significado
ALERT_ADMIN_EVENT
 Se requiere la intervención de un administrador.
ALERT_ERRORLOG_EVENT
 Se agregó una entrada al registro de errores.
ALERT_MESSAGE_EVENT
 Un usuario o aplicación recibió un mensaje de difusión.
ALERT_PRINT_EVENT
 Se ha completado un trabajo de impresión o se ha producido un error de impresión.
ALERT_USER_EVENT
 Se usó una aplicación o un recurso.

[in] VariableInfo

Puntero a los datos que se van a enviar a los clientes que escuchan el mensaje de interrupción. Los datos deben constar de una estructura de ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO o USER_OTHER_INFO seguida de cualquier información necesaria de longitud variable. Para obtener más información, vea el ejemplo de código en la sección Comentarios siguiente.

La aplicación que llama debe asignar y liberar la memoria de todas las estructuras y datos variables. Para obtener más información, consulte Búferes de funciones de administración de red.

[in] VariableInfoSize

Número de bytes de información de variables en el búfer al que apunta el parámetro VariableInfo .

[in] ServiceName

Puntero a una cadena constante que especifica el nombre del servicio que genera el mensaje de interrupción.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es NERR_Success.

Si se produce un error en la función, el valor devuelto es un código de error del sistema y puede ser uno de los siguientes códigos de error. Para obtener una lista de todos los códigos de error posibles, consulte Códigos de error del sistema.

Código devuelto Descripción
ERROR_INVALID_PARAMETER
 Un parámetro es incorrecto. Este error se devuelve si el parámetro AlertEventName es NULL o una cadena vacía, el parámetro ServiceName es NULL o una cadena vacía, el parámetro VariableInfo es NULL o el parámetro VariableInfoSize es mayor que 512 menos el tamaño de la estructura STD_ALERT .
ERROR_NOT_SUPPORTED
 No se admite la solicitud. Este error se devuelve en Windows Vista y versiones posteriores, ya que no se admite el servicio Alerter.

Comentarios

No se requiere ninguna pertenencia especial a grupos para ejecutar correctamente la función NetAlertRaiseEx .

El servicio de alertas debe ejecutarse en el equipo cliente cuando se llama a la función NetAlertRaiseEx o se produce un error en la función con ERROR_FILE_NOT_FOUND.

Ejemplos

En el ejemplo de código siguiente se muestra cómo generar los siguientes tipos de mensajes de interrupción (alertas) mediante una llamada a la función NetAlertRaiseEx :

En cada instancia, el código asigna valores a los miembros de la estructura de información de alerta pertinente. A continuación, el ejemplo recupera un puntero a la parte del búfer de mensajes que sigue a la estructura llamando a la macro ALERT_VAR_DATA . El código también rellena las cadenas de longitud variable en esta parte del búfer. Por último, el ejemplo llama a NetAlertRaiseEx para enviar la alerta.

Tenga en cuenta que la aplicación que llama debe asignar y liberar la memoria para todas las estructuras y los datos de longitud variable en un búfer de mensajes de alerta.

Para pasar una estructura definida por el usuario y cadenas válidas en una alerta de usuario, debe crear un archivo de mensaje de evento y vincularlo con la aplicación. También debe registrar la aplicación en la subclave EventMessageFile de la sección EventLog del Registro. Si no registra la aplicación, la alerta de usuario contendrá la información que pasa en las cadenas de longitud variable que siguen a la estructura USER_OTHER_INFO . Para obtener más información sobre EventMessageFile, vea Registro de eventos.

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

Requisitos

   
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado lmalert.h (include Lm.h)
Library Netapi32.lib
Archivo DLL Netapi32.dll

Consulte también

ADMIN_OTHER_INFO

ALERT_VAR_DATA

Funciones de alerta

ERRLOG_OTHER_INFO

NetAlertRaise

Funciones de administración de redes

Introducción a la administración de redes

PRINT_OTHER_INFO

USER_OTHER_INFO