Fungsi NetAlertRaiseEx (lmalert.h)

[Fungsi ini tidak didukung pada Windows Vista karena layanan peringatan tidak didukung.]

Fungsi NetAlertRaiseEx memberi tahu semua klien terdaftar ketika peristiwa tertentu terjadi. Anda dapat memanggil fungsi yang diperluas ini untuk menyederhanakan pengiriman pesan pemberitahuan karena NetAlertRaiseEx tidak mengharuskan Anda menentukan struktur STD_ALERT .

Sintaks

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

Parameter

[in] AlertType

Penunjuk ke string konstanta yang menentukan kelas pemberitahuan (jenis pemberitahuan) untuk dinaikkan. Parameter ini dapat menjadi salah satu nilai yang telah ditentukan sebelumnya berikut, atau kelas pemberitahuan yang ditentukan pengguna untuk aplikasi jaringan. (Nama peristiwa untuk pemberitahuan dapat berupa string teks apa pun.)

Nama	Makna
ALERT_ADMIN_EVENT	Diperlukan intervensi administrator.
ALERT_ERRORLOG_EVENT	Entri ditambahkan ke log kesalahan.
ALERT_MESSAGE_EVENT	Pengguna atau aplikasi menerima pesan siaran.
ALERT_PRINT_EVENT	Pekerjaan cetak selesai atau terjadi kesalahan cetak.
ALERT_USER_EVENT	Aplikasi atau sumber daya digunakan.

[in] VariableInfo

Penunjuk ke data untuk dikirim ke klien yang mendengarkan pesan yang mengganggu. Data harus terdiri dari satu struktur ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, atau USER_OTHER_INFO diikuti oleh informasi panjang variabel yang diperlukan. Untuk informasi selengkapnya, lihat sampel kode di bagian Keterangan berikut.

Aplikasi panggilan harus mengalokasikan dan membebaskan memori untuk semua struktur dan data variabel. Untuk informasi selengkapnya, lihat Buffer Fungsi Manajemen Jaringan.

[in] VariableInfoSize

Jumlah byte informasi variabel dalam buffer yang diacu oleh parameter VariableInfo .

[in] ServiceName

Penunjuk ke string konstanta yang menentukan nama layanan yang meningkatkan pesan yang mengganggu.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan NERR_Success.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan sistem dan dapat menjadi salah satu kode kesalahan berikut. Untuk daftar semua kemungkinan kode kesalahan, lihat Kode Kesalahan Sistem.

Menampilkan kode	Deskripsi
ERROR_INVALID_PARAMETER	Parameter salah. Kesalahan ini dikembalikan jika parameter AlertEventName adalah NULL atau string kosong, parameter ServiceName adalah NULL atau string kosong, parameter VariableInfo adalah NULL, atau parameter VariableInfoSize lebih besar dari 512 dikurangi ukuran struktur STD_ALERT .
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan pada Windows Vista dan kemudian karena layanan Pemberitahuan tidak didukung.

Keterangan

Tidak ada keanggotaan grup khusus yang diperlukan untuk berhasil menjalankan fungsi NetAlertRaiseEx .

Layanan pemberitahuan harus berjalan di komputer klien saat Anda memanggil fungsi NetAlertRaiseEx , atau fungsi gagal dengan ERROR_FILE_NOT_FOUND.

Contoh

Contoh kode berikut menunjukkan cara menaikkan jenis pesan yang mengganggu (pemberitahuan) berikut dengan memanggil fungsi NetAlertRaiseEx :

• Pemberitahuan administratif dengan menentukan struktur ADMIN_OTHER_INFO
• Pemberitahuan cetak dengan menentukan struktur PRINT_OTHER_INFO
• Pemberitahuan pengguna dengan menentukan struktur USER_OTHER_INFO

Dalam setiap instans kode menetapkan nilai kepada anggota struktur informasi pemberitahuan yang relevan. Setelah ini, sampel mengambil penunjuk ke bagian buffer pesan yang mengikuti struktur dengan memanggil makro ALERT_VAR_DATA . Kode ini juga mengisi string panjang variabel dalam bagian buffer ini. Terakhir, sampel memanggil NetAlertRaiseEx untuk mengirim pemberitahuan.

Perhatikan bahwa aplikasi panggilan harus mengalokasikan dan membebaskan memori untuk semua struktur dan data panjang variabel dalam buffer pesan pemberitahuan.

Untuk meneruskan struktur yang ditentukan pengguna dan string yang valid dalam pemberitahuan pengguna, Anda harus membuat file pesan peristiwa dan menautkannya dengan aplikasi Anda. Anda juga harus mendaftarkan aplikasi di subkuntang EventMessageFile di bagian EventLog dari registri. Jika Anda tidak mendaftarkan aplikasi, pemberitahuan pengguna akan berisi informasi yang Anda berikan dalam string panjang variabel yang mengikuti struktur USER_OTHER_INFO . Untuk informasi selengkapnya tentang EventMessageFile, lihat Pengelogan Peristiwa.

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

Persyaratan

Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	lmalert.h (termasuk Lm.h)
Pustaka	Netapi32.lib
DLL	Netapi32.dll

Lihat juga

ADMIN_OTHER_INFO

ALERT_VAR_DATA

Fungsi Pemberitahuan

ERRLOG_OTHER_INFO

NetAlertRaise

Fungsi Manajemen Jaringan

Gambaran Umum Manajemen Jaringan

PRINT_OTHER_INFO

USER_OTHER_INFO