NetWkstaSetInfo 函数 (lmwksta.h)

项目
03/13/2024

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

指向指定数据的缓冲区的指针。此数据的格式取决于级别参数的值。有关详细信息，请参阅网络管理功能缓冲区。

[out] parm_err

指向一个值的指针，该值接收导致ERROR_INVALID_PARAMETER错误的工作站信息结构第一个成员的索引。如果此参数为 NULL，则错误时不会返回索引。有关详细信息，请参见“备注”部分。

返回值

如果函数成功，则返回值NERR_Success。

如果函数失败，则返回值可能是以下错误代码之一。

返回代码	说明
ERROR_ACCESS_DENIED	用户无权访问请求的信息。
ERROR_INVALID_PARAMETER	其中一个函数参数无效。有关更多信息，请参见下面的“备注”部分。

注解

只有管理员组的成员才能在远程服务器上成功执行 NetWkstaSetInfo 函数。

NetWkstaSetInfo 函数调用本地系统或远程系统上的工作站服务。实际上，只能使用 NetWkstaSetInfo 函数更改有限数量的 WKSTA_INFO_502 结构的成员。如果设置了工作站服务忽略的成员，则不会返回错误。工作站服务主要使用注册表中的设置进行配置。

可以使用 NetWkstaUserSetInfo 函数代替 NetWkstaSetInfo 函数来设置本地系统上的配置信息。 NetWkstaUserSetInfo 函数调用本地安全机构 (LSA) 。

如果 NetWkstaSetInfo 函数返回ERROR_INVALID_PARAMETER，则可以使用 parm_err 参数来指示工作站信息结构的第一个成员无效。 (工作站信息结构以WKSTA_INFO_开头，其格式由级别参数指定。) 下表列出了可在 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

工作站服务参数设置存储在注册表中，而不是存储在 LAN 管理器以前使用的 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 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	lmwksta.h (包括 Lm.h)
Library	Netapi32.lib
DLL	Netapi32.dll