NetWkstaSetInfo

The NetWkstaSetInfo function configures a workstation. The information remains in effect after the system has been reinitialized.

Security Requirements

Only members of the Administrators local group can successfully execute the NetWkstaSetInfo function on a remote server.

NET_API_STATUS NetWkstaSetInfo(
  LPWSTR servername, 
  DWORD level,       
  LPBYTE buffer,     
  LPDWORD parm_err   
);

Parameters

servername

[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.

level

[in] Specifies the information level of the data. This parameter can be one of the following values.

Value	Meaning
100	Specifies information about a workstation environment, including platform-specific information, the names of the domain and the local computer, and information concerning the operating system. The buffer parameter points to a WKSTA_INFO_100 structure.
101	In addition to level 100 information, specifies the path to the LANMAN directory. The buffer parameter points to a WKSTA_INFO_101 structure.
102	In addition to level 101 information, specifies the number of users who are logged on to the local computer. The buffer parameter points to a WKSTA_INFO_102 structure.

Do not set levels 1010-1013, 1018, 1023, 1027, 1028, 1032, 1033, 1035, or 1041-1062. Level 502 is obsolete.

buffer

[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.

parm_err

[out] Pointer to a DWORD value that receives the index of the first member of the workstation information structure that causes the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Remarks

See the end of this Remarks section for a code sample that demonstrates use of the NetWkstaSetInfo function.

You must be a member of the Administrators local group to successfully execute NetWkstaSetInfo on a remote server or on a computer that has local security enabled.

The NetWkstaSetInfo function does not change the values in the LANMAN.INI file. When the workstation service is stopped and restarted, workstation parameters are reset to the default values specified in the LANMAN.INI file (unless they are overwritten by command-line parameters). Values set by previous calls to NetWkstaSetInfo can be overwritten when workstation parameters are reset.

If the NetWkstaSetInfo function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the workstation information structure that is invalid. (A workstation information structure begins with WKSTA_INFO_ and its format is specified by the level parameter.) The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error. (The prefix wki*_ indicates that the member can begin with multiple prefixes, for example, wki100_ or wki402_.)

The following code sample demonstrates how to set the session time-out value associated with a workstation using a call to the NetServerSetInfo function. (The session time-out is the number of seconds the server waits before disconnecting an inactive session.) The code specifies information level 502 (WKSTA_INFO_502).

#ifndef UNICODE
#define UNICODE
#endif

#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;
   LPTSTR 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;
}

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Unsupported.
  Header: Declared in Lmwksta.h; include Lm.h.
  Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Workstation and Workstation User Functions, NetWkstaGetInfo, WKSTA_INFO_100, WKSTA_INFO_101, WKSTA_INFO_102