NetWkstaSetInfo 函式 (lmwksta.h)

  • 發行項

NetWkstaSetInfo 函式會設定工作站，其中包含在系統重新初始化之後仍有效的資訊。

語法

NET_API_STATUS NET_API_FUNCTION NetWkstaSetInfo(
  [in]  LMSTR   servername,
  [in]  DWORD   level,
  [in]  LPBYTE  buffer,
  [out] LPDWORD parm_err
);

參數

[in] servername

字串的指標，指定要在其中執行函式之遠端伺服器的 DNS 或 NetBIOS 名稱。 如果此參數為 NULL，則會使用本機電腦。

[in] level

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

值 意義
100
 Windows NT：指定工作站環境的相關信息，包括平臺特定資訊、網域名稱和本機計算機，以及操作系統的相關信息。 緩衝區參數會指向WKSTA_INFO_100結構。 無法藉由呼叫此函式來設定此結構的 wk100_computername 和 wk100_langroup 字段。 若要設定這些值，請分別呼叫 SetComputerName/SetComputerNameEx 或 NetJoinDomain。
101
 Windows NT：除了層級 100 資訊之外，還會指定 LANMAN 目錄的路徑。 緩衝區參數會指向WKSTA_INFO_101結構。 無法藉由呼叫這個函式來設定此結構的 wk101_computername 和 wk101_langroup 字段。 若要設定這些值，請分別呼叫 SetComputerName/SetComputerNameEx 或 NetJoinDomain。
102
 Windows NT：除了層級 101 資訊之外，還會指定登入本機計算機的用戶數目。 緩衝區參數會指向WKSTA_INFO_102結構。 無法藉由呼叫此函式來設定此結構的 wk102_computername 和 wk102_langroup 欄位。 若要設定這些值，請分別呼叫 SetComputerName/SetComputerNameEx 或 NetJoinDomain。
502
 Windows NT：緩衝區參數會指向包含工作站環境相關信息的WKSTA_INFO_502結構。
 

請勿設定層級 1010-1013、1018、1023、1027、1028、1032、1033、1035 或 1041-1062。

[in] buffer

指定數據的緩衝區指標。 此數據的格式取決於 level 參數的值。 如需詳細資訊，請參閱 網路管理功能緩衝區。

[out] parm_err

值的指標，接收導致ERROR_INVALID_PARAMETER錯誤之工作站信息結構之第一個成員的索引。 如果此參數為 NULL，則不會在錯誤時傳回索引。 如需詳細資訊，請參閱＜備註＞一節。

傳回值

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

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

傳回碼 Description
ERROR_ACCESS_DENIED
 用戶無法存取要求的資訊。
ERROR_INVALID_PARAMETER
 其中一個函式參數無效。 如需詳細資訊，請參閱接下來的＜備註＞一節。

備註

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

NetWkstaSetInfo 函式會呼叫本機系統或遠端系統上的工作站服務。 使用 NetWkstaSetInfo 函式，實際上只能變更WKSTA_INFO_502結構的成員數目有限。 如果已設定工作站服務忽略的成員，則不會傳回任何錯誤。 工作站服務主要是使用登錄中的設定來設定。

您可以使用 NetWkstaUserSetInfo 函式來取代 NetWkstaSetInfo 函式，以在本機系統上設定組態資訊。 NetWkstaUserSetInfo 函式會呼叫 Local Security Authority (LSA) 。

如果 NetWkstaSetInfo 函式傳回ERROR_INVALID_PARAMETER，您可以使用 parm_err 參數來指出工作站信息結構的第一個成員無效。 (工作站資訊結構開頭為 WKSTA_INFO_，且其格式是由 level 參數所指定。) 下表列出可在 parm_err 參數中傳回的值，以及發生錯誤的對應結構成員。 (前置詞 wki*_ 表示成員可以以多個前置詞開頭，例如，wki100_或 wki402_.)

值 成員
WKSTA_PLATFORM_ID_PARMNUM wki*_platform_id
WKSTA_COMPUTERNAME_PARMNUM wki*_computername
WKSTA_LANGROUP_PARMNUM wki*_langroup
WKSTA_VER_MAJOR_PARMNUM wki*_ver_major
WKSTA_VER_MINOR_PARMNUM wki*_ver_minor
WKSTA_LOGGED_ON_USERS_PARMNUM wki*_logged_on_users
WKSTA_LANROOT_PARMNUM wki*_lanroot
WKSTA_LOGON_DOMAIN_PARMNUM wki*_logon_domain
WKSTA_LOGON_SERVER_PARMNUM wki*_logon_server
WKSTA_CHARWAIT_PARMNUM wki*_char_wait
WKSTA_CHARTIME_PARMNUM wki*_collection_time
WKSTA_CHARCOUNT_PARMNUM wki*_maximum_collection_count
WKSTA_KEEPCONN_PARMNUM wki*_keep_conn
WKSTA_KEEPSEARCH_PARMNUM wki*_keep_search
WKSTA_MAXCMDS_PARMNUM wki*_max_cmds
WKSTA_NUMWORKBUF_PARMNUM wki*_num_work_buf
WKSTA_MAXWRKCACHE_PARMNUM wki*_max_wrk_cache
WKSTA_SESSTIMEOUT_PARMNUM wki*_sess_timeout
WKSTA_SIZERROR_PARMNUM wki*_siz_error
WKSTA_NUMALERTS_PARMNUM wki*_num_alerts
WKSTA_NUMSERVICES_PARMNUM wki*_num_services
WKSTA_ERRLOGSZ_PARMNUM wki*_errlog_sz
WKSTA_PRINTBUFTIME_PARMNUM wki*_print_buf_time
WKSTA_NUMCHARBUF_PARMNU wki*_num_char_buf
WKSTA_SIZCHARBUF_PARMNUM wki*_siz_char_buf
WKSTA_WRKHEURISTICS_PARMNUM wki*_wrk_heuristics
WKSTA_MAILSLOTS_PARMNUM wki*_mailslots
WKSTA_MAXTHREADS_PARMNUM wki*_max_threads
WKSTA_SIZWORKBUF_PARMNUM wki*_siz_work_buf
WKSTA_NUMDGRAMBUF_PARMNUM wki*_num_dgram_buf
 

工作站服務參數設定會儲存在登錄中，而不是網路管理員先前使用的 LanMan.ini 檔案中。 NetWkstaSetInfo 函式不會變更 LanMan.ini 檔案中的值。 當工作站服務停止並重新啟動時，除非命令行參數) 覆寫工作站參數，否則工作站參數會重設為登錄 (中指定的預設值。 重設工作站參數時，可以覆寫先前呼叫 NetWkstaSetInfo 所設定的值。

範例

下列程式代碼範例示範如何使用 NetServerSetInfo 函式的呼叫，設定與工作站相關聯的會話逾時值。 (工作階段逾時是伺服器在中斷非使用中工作階段連線之前所等候的秒數。) 程式代碼會指定資訊層級 502 (WKSTA_INFO_502) 。

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#include <stdio.h>
#include <windows.h> 
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPWKSTA_INFO_502 pBuf = NULL;
   WKSTA_INFO_502 wi;
   DWORD dwLevel = 502;
   NET_API_STATUS nStatus;
   LPWSTR pszServerName = NULL;

   if ((argc < 2) || (argc > 3))
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName] SessionTimeOut\n", argv[0]);
      exit(1);
   }

   if (argc == 3)
      pszServerName = argv[1];
   //
   // Retrieve the current settings.
   //
   nStatus = NetWkstaGetInfo(pszServerName,
                             dwLevel,
                             (LPBYTE *)&pBuf);

   if (nStatus != NERR_Success)
   {
      fprintf(stderr, "A system error has occurred (NetWkstaGetInfo): %d\n", nStatus);
      return -1;
   }

   if (pBuf != NULL)
   {
      //
      // Copy the existing settings to the new structure,
      //   and free the buffer.
      //
      CopyMemory(&wi, pBuf, sizeof(wi));
      NetApiBufferFree(pBuf);
   }
   else
   {
      fprintf(stderr, "Memory invalid!\n");
      return -1;
   }
   //
   // Set a new session time-out value by
   //   calling the NetWkstaSetInfo function.
   //
   wi.wki502_sess_timeout = _wtoi(argv[argc-1]);
   nStatus = NetWkstaSetInfo(pszServerName,
                             dwLevel,
                             (LPBYTE)&wi,
                             NULL);
   //
   // Display the result of the call.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Workstation information reset: session time-out = %d\n", _wtoi(argv[argc-1]));
   else
      fprintf(stderr, "A system error has occurred (NetWkstaSetInfo): %d\n", nStatus);

   return 0;
}

規格需求

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

另請參閱

NetWkstaGetInfo

NetWkstaUserGetInfo

NetWkstaUserSetInfo

網路管理功能

網路管理概觀

工作站和工作站使用者函式