Función NetAlertRaise (lmalert.h)

Artículo
03/05/2024

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

La función NetAlertRaise notifica a todos los clientes registrados cuando se produce un evento determinado.

Para simplificar el envío de un mensaje de alerta, puede llamar a la función extendida NetAlertRaiseEx en su lugar. NetAlertRaiseEx no requiere que especifique una estructura de STD_ALERT .

Sintaxis

NET_API_STATUS NET_API_FUNCTION NetAlertRaise(
  [in] LPCWSTR AlertType,
  [in] LPVOID  Buffer,
  [in] DWORD   BufferSize
);

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 recurso.

[in] Buffer

Puntero a los datos que se van a enviar a los clientes que escuchan el mensaje de interrupción. Los datos deben comenzar con una estructura de STD_ALERT de longitud fija seguida de datos de mensajes adicionales en una ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO o estructura de USER_OTHER_INFO . Por último, el búfer debe incluir cualquier información de longitud variable necesaria. 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 para todas las estructuras y datos de variables. Para obtener más información, consulte Búferes de funciones de administración de redes.

[in] BufferSize

Tamaño, en bytes, del búfer de mensajes.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto se 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 Buffer es NULL o el parámetro BufferSize es menor que el tamaño de la estructura de STD_ALERT más el tamaño fijo de la estructura de datos de mensaje adicional.
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 NetAlertRaise .

El servicio del alertador debe ejecutarse en el equipo cliente al llamar a la función NetAlertRaise 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 una alerta administrativa llamando a la función NetAlertRaise y especificando STD_ALERT y estructuras de ADMIN_OTHER_INFO . En primer lugar, el ejemplo calcula el tamaño del búfer de mensajes. A continuación, asigna el búfer con una llamada a la función GlobalAlloc . El código asigna valores a los miembros del STD_ALERT y a las partes ADMIN_OTHER_INFO del búfer. El ejemplo recupera un puntero a la estructura ADMIN_OTHER_INFO llamando a la macro ALERT_OTHER_INFO . También recupera un puntero a la parte de datos variables del búfer llamando a la macro ALERT_VAR_DATA . Por último, el ejemplo de código libera la memoria asignada para el búfer con una llamada a la función 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);
}

Requisitos

Requisito	Value
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