Función NetAlertRaise (lmalert.h)

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

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

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

Consulte también

ADMIN_OTHER_INFO

ALERT_OTHER_INFO

ALERT_VAR_DATA

Funciones de alerta

ERRLOG_OTHER_INFO

NetAlertRaiseEx

Funciones de administración de red

Introducción a la administración de redes

PRINT_OTHER_INFO

STD_ALERT

USER_OTHER_INFO