NetAlertRaise 함수(lmalert.h)

아티클
03/02/2024

[경고자 서비스가 지원되지 않으므로 Windows Vista에서는 이 함수가 지원되지 않습니다.]

NetAlertRaise 함수는 특정 이벤트가 발생할 때 등록된 모든 클라이언트에 알깁니다.

경고 메시지 전송을 간소화하기 위해 확장 함수 NetAlertRaiseEx 를 대신 호출할 수 있습니다. NetAlertRaiseEx 는 STD_ALERT 구조를 지정할 필요가 없습니다.

구문

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

매개 변수

[in] AlertType

발생시키는 경고 클래스(경고 유형)를 지정하는 상수 문자열에 대한 포인터입니다. 이 매개 변수는 다음과 같은 미리 정의된 값 또는 네트워크 애플리케이션에 대한 사용자 정의 경고 클래스 중 하나일 수 있습니다. 경고의 이벤트 이름은 텍스트 문자열일 수 있습니다.

Name	의미
ALERT_ADMIN_EVENT	관리자의 개입이 필요합니다.
ALERT_ERRORLOG_EVENT	항목이 오류 로그에 추가되었습니다.
ALERT_MESSAGE_EVENT	사용자 또는 애플리케이션이 브로드캐스트 메시지를 받았습니다.
ALERT_PRINT_EVENT	인쇄 작업이 완료되었거나 인쇄 오류가 발생했습니다.
ALERT_USER_EVENT	애플리케이션 또는 리소스가 사용되었습니다.

[in] Buffer

인터럽트 메시지를 수신 대기하는 클라이언트에 보낼 데이터에 대한 포인터입니다. 데이터는 고정 길이 STD_ALERT 구조와 하나의 ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO 또는 USER_OTHER_INFO 구조의 추가 메시지 데이터로 시작해야 합니다. 마지막으로 버퍼에는 필요한 가변 길이 정보가 포함되어야 합니다. 자세한 내용은 다음 주의 섹션의 코드 샘플을 참조하세요.

호출 애플리케이션은 모든 구조체 및 변수 데이터에 대한 메모리를 할당하고 해제해야 합니다. 자세한 내용은 네트워크 관리 함수 버퍼를 참조하세요.

[in] BufferSize

메시지 버퍼의 크기(바이트)입니다.

반환 값

함수가 성공하면 반환 값이 NERR_Success.

함수가 실패하면 반환 값은 시스템 오류 코드이며 은 다음 오류 코드 중 하나일 수 있습니다. 가능한 모든 오류 코드 목록은 시스템 오류 코드를 참조하세요.

반환 코드	설명
ERROR_INVALID_PARAMETER	매개 변수가 잘못되었습니다. AlertEventName 매개 변수가 NULL이거나 빈 문자열이거나, Buffer 매개 변수가 NULL이거나, BufferSize 매개 변수가 STD_ALERT 구조체의 크기와 추가 메시지 데이터 구조의 고정 크기보다 작은 경우 이 오류가 반환됩니다.
ERROR_NOT_SUPPORTED	요청이 지원되지 않습니다. 이 오류는 경고 서비스가 지원되지 않으므로 Windows Vista 이상에서 반환됩니다.

설명

NetAlertRaise 함수를 성공적으로 실행하려면 특별한 그룹 멤버 자격이 필요하지 않습니다.

NetAlertRaise 함수를 호출할 때 클라이언트 컴퓨터에서 경고자 서비스를 실행해야 합니다. 그렇지 않으면 ERROR_FILE_NOT_FOUND 함수가 실패합니다.

예제

다음 코드 샘플에서는 NetAlertRaise 함수를 호출하고 STD_ALERT 및 ADMIN_OTHER_INFO 구조를 지정하여 관리 경고를 발생시키는 방법을 보여 줍니다. 먼저 샘플은 메시지 버퍼의 크기를 계산합니다. 그런 다음 GlobalAlloc 함수를 호출하여 버퍼를 할당합니다. 코드는 STD_ALERT 멤버와 버퍼의 ADMIN_OTHER_INFO 부분에 값을 할당합니다. 샘플은 ALERT_OTHER_INFO 매크로를 호출하여 ADMIN_OTHER_INFO 구조체에 대한 포인터를 검색합니다. 또한 ALERT_VAR_DATA 매크로를 호출하여 버퍼의 변수 데이터 부분에 대한 포인터를 검색합니다. 마지막으로 코드 샘플은 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);
}

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	lmalert.h(Lm.h 포함)
라이브러리	Netapi32.lib
DLL	Netapi32.dll