NetMessageNameEnum 函式 (lmmsg.h)

發行項
08/24/2023

[Windows Vista 不支援此函式，因為不支援 Messenger 服務。]

NetMessageNameEnum函式會列出接收指定電腦上的訊息別名。函式需要啟動 Messenger 服務。

語法

NET_API_STATUS NET_API_FUNCTION NetMessageNameEnum(
  [in]      LPCWSTR servername,
  [in]      DWORD   level,
  [out]     LPBYTE  *bufptr,
  [in]      DWORD   prefmaxlen,
  [out]     LPDWORD entriesread,
  [out]     LPDWORD totalentries,
  [in, out] LPDWORD resume_handle
);

參數

[in] servername

常數位符串的指標，指定函式執行所在遠端伺服器的 DNS 或 NetBIOS 名稱。如果此參數為 Null，則會使用本機電腦。

[in] level

指定資料的資訊層級。此參數可以是下列其中一個值。

值	意義
0	傳回訊息別名。 bufptr參數指向MSG_INFO_0結構的陣列。
1	傳回訊息別名。 bufptr參數指向MSG_INFO_1結構的陣列。此層級僅適用于相容性。不支援訊息轉送。

[out] bufptr

接收資料的緩衝區指標。此資料的格式取決於 level 參數的值。此緩衝區是由系統所配置，而且必須使用 NetApiBufferFree 函式釋放。請注意，即使函式因ERROR_MORE_DATA而失敗，您也必須釋放緩衝區。

[in] prefmaxlen

指定所傳回資料的慣用最大長度，以位元組為單位。如果您指定MAX_PREFERRED_LENGTH，函式會配置資料所需的記憶體數量。如果您在此參數中指定另一個值，它可以限制函式傳回的位元組數目。如果緩衝區大小不足以保存所有專案，函式會傳回ERROR_MORE_DATA。如需詳細資訊，請參閱網路管理功能緩衝區和網路管理功能緩衝區長度。

[out] entriesread

值指標，這個值會接收實際列舉的專案計數。

[out] totalentries

值的指標，這個值會接收可能已從目前繼續位置列舉的專案總數。請注意，應用程式應該只將此值視為提示。

[in, out] resume_handle

值的指標，其中包含用來繼續現有訊息別名搜尋的繼續控制碼。第一次呼叫時，控制碼應該是零，後續呼叫則保持不變。如果 resume_handle 為 Null，則不會儲存任何繼續控制碼。

傳回值

如果函式成功，傳回值會NERR_Success。

如果函式失敗，傳回值可以是下列其中一個錯誤碼。

傳回碼	描述
ERROR_ACCESS_DENIED	呼叫端沒有適當的存取權來完成作業。
ERROR_INVALID_LEVEL	為 level 參數指定的值無效。
ERROR_INVALID_PARAMETER	參數不正確。
ERROR_MORE_DATA	有更多專案可供使用。指定足夠的緩衝區來接收所有專案。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足。
ERROR_NOT_SUPPORTED	不支援此要求。此錯誤會在 Windows Vista 和更新版本上傳回。
NERR_BufTooSmall	提供的緩衝區太小。

備註

只有 Administrators 本機群組的成員可以在遠端伺服器上成功執行 NetMessageNameEnum 函式。

若要擷取訊息名稱資料表中特定訊息別名的相關資訊，您可以呼叫 NetMessageNameGetInfo 函式。

需求


最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	lmmsg.h (包括 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll