Função NetWkstaSetInfo (lmwksta.h)

Artigo
03/14/2023

A função NetWkstaSetInfo configura uma estação de trabalho com informações que permanecem em vigor depois que o sistema é reinicializado.

Sintaxe

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

Parâmetros

[in] servername

Um ponteiro para uma cadeia de caracteres que especifica o nome DNS ou NetBIOS do servidor remoto no qual a função deve ser executada. Se esse parâmetro for NULL, o computador local será usado.

[in] level

O nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
100	Windows NT: especifica informações sobre um ambiente de estação de trabalho, incluindo informações específicas da plataforma, os nomes do domínio e do computador local e informações sobre o sistema operacional. O parâmetro de buffer aponta para uma estrutura WKSTA_INFO_100 . Os campos wk100_computername e wk100_langroup dessa estrutura não podem ser definidos chamando essa função. Para definir esses valores, chame SetComputerName/SetComputerNameEx ou NetJoinDomain, respectivamente.
101	Windows NT: além das informações de nível 100, especifica o caminho para o diretório LANMAN. O parâmetro de buffer aponta para uma estrutura WKSTA_INFO_101 . Os campos wk101_computername e wk101_langroup dessa estrutura não podem ser definidos chamando essa função. Para definir esses valores, chame SetComputerName/SetComputerNameEx ou NetJoinDomain, respectivamente.
102	Windows NT: além das informações de nível 101, especifica o número de usuários que estão conectados ao computador local. O parâmetro buffer aponta para uma estrutura WKSTA_INFO_102 . Os campos wk102_computername e wk102_langroup dessa estrutura não podem ser definidos chamando essa função. Para definir esses valores, chame SetComputerName/SetComputerNameEx ou NetJoinDomain, respectivamente.
502	Windows NT: o parâmetro de buffer aponta para uma estrutura WKSTA_INFO_502 que contém informações sobre o ambiente da estação de trabalho.

Não defina os níveis 1010-1013, 1018, 1023, 1027, 1028, 1032, 1033, 1035 ou 1041-1062.

[in] buffer

Um ponteiro para o buffer que especifica os dados. O formato desses dados depende do valor do parâmetro level . Para obter mais informações, consulte Buffers de função de gerenciamento de rede.

[out] parm_err

Um ponteiro para um valor que recebe o índice do primeiro membro da estrutura de informações da estação de trabalho que causa o erro de ERROR_INVALID_PARAMETER. Se esse parâmetro for NULL, o índice não será retornado com erro. Para obter mais informações, consulte a seção Comentários.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NERR_Success.

Se a função falhar, o valor retornado poderá ser um dos códigos de erro a seguir.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O usuário não tem acesso às informações solicitadas.
ERROR_INVALID_PARAMETER	Um dos parâmetros de função é inválido. Para obter mais informações, consulte a seção Comentários a seguir.

Comentários

Somente os membros do grupo Administradores podem executar com êxito a função NetWkstaSetInfo em um servidor remoto.

A função NetWkstaSetInfo chama o serviço de estação de trabalho no sistema local ou em um sistema remoto. Apenas um número limitado de membros da estrutura WKSTA_INFO_502 pode realmente ser alterado usando a função NetWkstaSetInfo . Nenhum erro será retornado se um membro for definido e ignorado pelo serviço de estação de trabalho. O serviço de estação de trabalho é definido principalmente usando configurações no Registro.

A função NetWkstaUserSetInfo pode ser usada em vez da função NetWkstaSetInfo para definir informações de configuração no sistema local. A função NetWkstaUserSetInfo chama a LSA (Autoridade de Segurança Local).

Se a função NetWkstaSetInfo retornar ERROR_INVALID_PARAMETER, você poderá usar o parâmetro parm_err para indicar o primeiro membro da estrutura de informações da estação de trabalho inválido. (Uma estrutura de informações da estação de trabalho começa com WKSTA_INFO_ e seu formato é especificado pelo parâmetro level .) A tabela a seguir lista os valores que podem ser retornados no parâmetro parm_err e o membro da estrutura correspondente que está com erro. (O prefixo wki*_ indica que o membro pode começar com vários prefixos, por exemplo, wki100_ ou wki402_.)

Valor	Membro
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

As configurações de parâmetro de serviço de estação de trabalho são armazenadas no registro, não no arquivo LanMan.ini usado anteriormente pelo LAN Manager. A função NetWkstaSetInfo não altera os valores no arquivo LanMan.ini. Quando o serviço de estação de trabalho é interrompido e reiniciado, os parâmetros de estação de trabalho são redefinidos para os valores padrão especificados no Registro (a menos que sejam substituídos por parâmetros de linha de comando). Os valores definidos por chamadas anteriores para NetWkstaSetInfo podem ser substituídos quando os parâmetros de estação de trabalho são redefinidos.

Exemplos

O exemplo de código a seguir demonstra como definir o valor de tempo limite da sessão associado a uma estação de trabalho usando uma chamada para a função NetServerSetInfo . (O tempo limite da sessão é o número de segundos que o servidor espera antes de desconectar uma sessão inativa.) O código especifica o nível de informações 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;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	lmwksta.h (inclua Lm.h)
Biblioteca	Netapi32.lib
DLL	Netapi32.dll