Fungsi NetAlertRaise (lmalert.h)

Artikel
03/14/2023

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

Fungsi NetAlertRaise memberi tahu semua klien terdaftar ketika peristiwa tertentu terjadi.

Untuk menyederhanakan pengiriman pesan pemberitahuan, Anda dapat memanggil fungsi yang diperluas NetAlertRaiseEx sebagai gantinya. NetAlertRaiseEx tidak mengharuskan Anda menentukan struktur STD_ALERT .

Sintaks

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

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] Buffer

Penunjuk ke data untuk dikirim ke klien yang mendengarkan pesan yang mengganggu. Data harus dimulai dengan struktur STD_ALERT panjang tetap diikuti dengan data pesan tambahan dalam satu struktur ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, atau USER_OTHER_INFO . Terakhir, buffer harus menyertakan 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] BufferSize

Ukuran, dalam byte, dari buffer pesan.

Mengembalikan nilai

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 Buffer adalah NULL, atau parameter BufferSize kurang dari ukuran struktur STD_ALERT ditambah ukuran tetap untuk struktur data pesan tambahan.
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 NetAlertRaise .

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

Contoh

Sampel kode berikut menunjukkan cara menaikkan pemberitahuan administratif dengan memanggil fungsi NetAlertRaise dan menentukan struktur STD_ALERT dan ADMIN_OTHER_INFO . Pertama, sampel menghitung ukuran buffer pesan. Kemudian mengalokasikan buffer dengan panggilan ke fungsi GlobalAlloc . Kode menetapkan nilai kepada anggota STD_ALERT dan bagian ADMIN_OTHER_INFO buffer. Sampel mengambil penunjuk ke struktur ADMIN_OTHER_INFO dengan memanggil makro ALERT_OTHER_INFO . Ini juga mengambil penunjuk ke bagian data variabel buffer dengan memanggil makro ALERT_VAR_DATA . Terakhir, sampel kode membebaskan memori yang dialokasikan untuk buffer dengan panggilan ke fungsi 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);
}

Persyaratan

Persyaratan	Nilai
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