NetServerTransportEnum 函式 (lmserver.h)
NetServerTransportEnum 函式會提供伺服器所管理之傳輸通訊協議的相關信息。
語法
NET_API_STATUS NET_API_FUNCTION NetServerTransportEnum(
[in] LMSTR 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
指定資料的資訊層級。 此參數可以是下列其中一個值。
| 值 | 意義 |
|---|---|
|
傳回傳輸通訊協議的相關信息，包括網路上的名稱、位址和位置。 bufptr 參數會指向SERVER_TRANSPORT_INFO_0 結構的數位。 |
|
傳回傳輸通訊協議的相關信息，包括名稱、位址、網路位置和網域。 bufptr 參數指向SERVER_TRANSPORT_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
值的指標，其中包含用來繼續現有伺服器傳輸搜尋的繼續句柄。 第一次呼叫時，句柄應該是零，後續呼叫則保持不變。 如果此參數為 NULL，則不會儲存任何繼續句柄。
傳回值
如果函式成功，傳回值會NERR_Success。
如果函式失敗，傳回值可以是下列其中一個錯誤碼。
| 傳回碼 | Description |
|---|---|
|
為 level 參數指定的值無效。 |
|
有更多專案可供使用。 指定夠大的緩衝區來接收所有專案。 |
|
記憶體不足。 |
|
提供的緩衝區太小。 |
備註
只有已驗證的使用者才能成功呼叫此函式。Windows XP/2000： 成功執行此函式不需要特殊群組成員資格。
範例
下列程式代碼範例示範如何使用 對 NetServerTransportEnum 函式的呼叫，擷取伺服器所管理之傳輸通訊協議的相關信息。 此範例會呼叫 NetServerTransportEnum，並指定資訊層級 0 ( SERVER_TRANSPORT_INFO_0) 。 此範例會列印每個傳輸通訊協定的名稱和列舉的總數。 最後，程式代碼範例會釋放配置給資訊緩衝區的記憶體。
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t *argv[])
{
LPSERVER_TRANSPORT_INFO_0 pBuf = NULL;
LPSERVER_TRANSPORT_INFO_0 pTmpBuf;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwResumeHandle = 0;
DWORD dwTotalCount = 0;
NET_API_STATUS nStatus;
LPTSTR pszServerName = NULL;
DWORD i;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
exit(1);
}
// The server is not the default local computer.
//
if (argc == 2)
pszServerName = (LPTSTR) argv[1];
//
// Call the NetServerTransportEnum function; specify level 0.
//
do // begin do
{
nStatus = NetServerTransportEnum(pszServerName,
dwLevel,
(LPBYTE *) &pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
{
if ((pTmpBuf = pBuf) != NULL)
{
//
// Loop through the entries;
// process access errors.
//
for (i = 0; i < dwEntriesRead; i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
//
// Print the transport protocol name.
//
wprintf(L"\tTransport: %s\n", pTmpBuf->svti0_transportname);
pTmpBuf++;
dwTotalCount++;
}
}
}
//
// Otherwise, indicate a system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
{
NetApiBufferFree(pBuf);
pBuf = NULL;
}
//
// Continue to call NetServerTransportEnum while
// there are more entries.
//
}
while (nStatus == ERROR_MORE_DATA); // end do
// Check again for an allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
//
// Print the final count of transports enumerated.
//
fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);
return 0;
}
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | lmserver.h (包含 Lm.h) |
| 程式庫 | Netapi32.lib |
| Dll | Netapi32.dll |