NetAlertRaiseEx 함수(lmalert.h)

[이 함수는 Windows Vista에서 지원되지 않습니다. 경고자 서비스가 지원되지 않기 때문입니다.]

NetAlertRaiseEx 함수는 특정 이벤트가 발생할 때 등록된 모든 클라이언트에 알깁니다. NetAlertRaiseEx에서 STD_ALERT 구조를 지정할 필요가 없으므로 이 확장 함수를 호출하여 경고 메시지 전송을 간소화할 수 있습니다.

구문

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

매개 변수

[in] AlertType

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

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

[in] VariableInfo

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

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

[in] VariableInfoSize

VariableInfo 매개 변수가 가리키는 버퍼의 변수 정보 바이트 수입니다.

[in] ServiceName

인터럽트 메시지를 발생시키는 서비스의 이름을 지정하는 상수 문자열에 대한 포인터입니다.

반환 값

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

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

반환 코드	설명
ERROR_INVALID_PARAMETER	매개 변수가 잘못되었습니다. AlertEventName 매개 변수가 NULL이거나 빈 문자열이거나, ServiceName 매개 변수가 NULL이거나, 빈 문자열이거나, VariableInfo 매개 변수가 NULL이거나, VariableInfoSize 매개 변수가 512보다 크면 이 오류가 반환되어 STD_ALERT 구조체의 크기를 뺀 값입니다.
ERROR_NOT_SUPPORTED	요청이 지원되지 않습니다. 이 오류는 경고 서비스가 지원되지 않으므로 Windows Vista 이상에서 반환됩니다.

설명

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

NetAlertRaiseEx 함수를 호출할 때 경고자 서비스가 클라이언트 컴퓨터에서 실행 중이거나 ERROR_FILE_NOT_FOUND 함께 함수가 실패해야 합니다.

예제

다음 코드 샘플에서는 NetAlertRaiseEx 함수를 호출하여 다음과 같은 유형의 인터럽트 메시지(경고)를 발생시키는 방법을 보여 줍니다.

• ADMIN_OTHER_INFO 구조를 지정하여 관리 경고
• PRINT_OTHER_INFO 구조를 지정하여 인쇄 경고
• USER_OTHER_INFO 구조를 지정하여 사용자 경고

각 instance 코드는 관련 경고 정보 구조의 멤버에게 값을 할당합니다. 그런 다음 샘플은 ALERT_VAR_DATA 매크로를 호출하여 구조체를 따르는 메시지 버퍼 부분에 대한 포인터를 검색합니다. 또한 코드는 버퍼의 이 부분에 있는 가변 길이 문자열을 채웁니다. 마지막으로 샘플은 NetAlertRaiseEx 를 호출하여 경고를 보냅니다.

호출하는 애플리케이션은 경고 메시지 버퍼의 모든 구조 및 가변 길이 데이터에 대한 메모리를 할당하고 해제해야 합니다.

사용자 경고에 사용자 정의 구조 및 유효한 문자열을 전달하려면 이벤트 메시지 파일을 만들고 애플리케이션에 연결해야 합니다. 또한 레지스트리의 EventLog 섹션에 있는 EventMessageFile 하위 키에 애플리케이션을 등록해야 합니다. 애플리케이션을 등록하지 않으면 사용자 경고에는 USER_OTHER_INFO 구조 다음에 오는 가변 길이 문자열에 전달하는 정보가 포함됩니다. EventMessageFile에 대한 자세한 내용은 이벤트 로깅을 참조하세요.

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

요구 사항

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

참고 항목

ADMIN_OTHER_INFO

ALERT_VAR_DATA

경고 함수

ERRLOG_OTHER_INFO

NetAlertRaise

네트워크 관리 함수

네트워크 관리 개요

PRINT_OTHER_INFO

USER_OTHER_INFO