Função SetTimeZoneInformation (timezoneapi.h)

Artigo
01/27/2024

Define as configurações de fuso horário atuais. Essas configurações controlam traduções do UTC (Tempo Universal Coordenado) para a hora local.

Para dar suporte a limites para o horário de verão que mudam de ano para ano, use a função SetDynamicTimeZoneInformation .

Sintaxe

BOOL SetTimeZoneInformation(
  [in] const TIME_ZONE_INFORMATION *lpTimeZoneInformation
);

Parâmetros

[in] lpTimeZoneInformation

Um ponteiro para uma estrutura TIME_ZONE_INFORMATION que contém as novas configurações.

Valor retornado

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

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Um aplicativo deve ter o privilégio SE_TIME_ZONE_NAME para que essa função tenha êxito. Esse privilégio é desabilitado por padrão. Use a função AdjustTokenPrivileges para habilitar o privilégio antes de chamar SetTimeZoneInformation e desabilitar o privilégio após a chamada SetTimeZoneInformation . Para obter mais informações, confira Executar com privilégios especiais.

Windows Server 2003 e Windows XP/2000: O aplicativo deve ter o privilégio SE_SYSTEMTIME_NAME.

Importante

Começando com o Windows Vista e o Windows Server 2008 por meio de todas as versões atuais do Windows, chame SetDynamicTimeZoneInformation em vez de SetTimeZoneInformation para definir informações de fuso horário do sistema. SetDynamicTimeZoneInformation dá suporte ao histórico completo de alterações no horário padrão e no horário de verão fornecidos pelos dados dinâmicos no Registro do Windows. Se um aplicativo usar SetTimeZoneInformation, o suporte ao horário de verão dinâmico será desabilitado para o sistema e a mensagem "Seu fuso horário atual não é reconhecido. Selecione um fuso horário válido." aparecerá para o usuário nas configurações de fuso horário do Windows.

Para informar Explorer que o fuso horário foi alterado, envie a mensagem WM_SETTINGCHANGE.

Todas as traduções entre UTC e hora local são baseadas na seguinte fórmula:

UTC = hora local + viés

O viés é a diferença, em minutos, entre UTC e hora local.

Exemplos

O exemplo a seguir exibe o fuso horário atual e ajusta o fuso horário um zona oeste. Os nomes de fuso horário antigos e novos são exibidos. Você também pode verificar as alterações usando Data e Hora no Painel de Controle. O novo nome é exibido na guia Data&Hora como o Fuso Horário Atual. O novo fuso horário é exibido na lista suspensa na guia Fuso Horário . Para desfazer essas alterações, basta escolher o fuso horário antigo na lista suspensa.

#define UNICODE 1
#define _UNICODE 1

#include <windows.h>
#include <stdio.h>
#include <string.h>
#include <strsafe.h>

int main()
{
   TIME_ZONE_INFORMATION tziOld, tziNew, tziTest;
   DWORD dwRet;

   // Enable the required privilege

   HANDLE hToken;
   TOKEN_PRIVILEGES tkp;

   OpenProcessToken(GetCurrentProcess(), TOKEN_ADJUST_PRIVILEGES|TOKEN_QUERY, &hToken);
   LookupPrivilegeValue(NULL, SE_TIME_ZONE_NAME, &tkp.Privileges[0].Luid);
   tkp.PrivilegeCount = 1;
   tkp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;
   AdjustTokenPrivileges(hToken, FALSE, &tkp, 0, (PTOKEN_PRIVILEGES)NULL, 0);

   // Retrieve the current time zone information

   dwRet = GetTimeZoneInformation(&tziOld);

   if(dwRet == TIME_ZONE_ID_STANDARD || dwRet == TIME_ZONE_ID_UNKNOWN)    
      wprintf(L"%s\n", tziOld.StandardName);
   else if( dwRet == TIME_ZONE_ID_DAYLIGHT )
      wprintf(L"%s\n", tziOld.DaylightName);
   else
   {
      printf("GTZI failed (%d)\n", GetLastError());
      return 0;
   }

   // Adjust the time zone information

   ZeroMemory(&tziNew, sizeof(tziNew));
   tziNew.Bias = tziOld.Bias + 60;
   StringCchCopy(tziNew.StandardName, 32, L"Test Standard Zone");
   tziNew.StandardDate.wMonth = 10;
   tziNew.StandardDate.wDayOfWeek = 0;
   tziNew.StandardDate.wDay = 5;
   tziNew.StandardDate.wHour = 2;

   StringCchCopy(tziNew.DaylightName, 32, L"Test Daylight Zone");
   tziNew.DaylightDate.wMonth = 4;
   tziNew.DaylightDate.wDayOfWeek = 0;
   tziNew.DaylightDate.wDay = 1;
   tziNew.DaylightDate.wHour = 2;
   tziNew.DaylightBias = -60;

   if( !SetTimeZoneInformation( &tziNew ) ) 
   {
      printf("STZI failed (%d)\n", GetLastError());
      return 0;
   }

   // Retrieve and display the newly set time zone information

   dwRet = GetTimeZoneInformation(&tziTest);

   if(dwRet == TIME_ZONE_ID_STANDARD || dwRet == TIME_ZONE_ID_UNKNOWN)    
      wprintf(L"%s\n", tziTest.StandardName);
   else if( dwRet == TIME_ZONE_ID_DAYLIGHT )
      wprintf(L"%s\n", tziTest.DaylightName);
   else printf("GTZI failed (%d)\n", GetLastError());

   // Disable the privilege

   tkp.Privileges[0].Attributes = 0; 
   AdjustTokenPrivileges(hToken, FALSE, &tkp, 0, (PTOKEN_PRIVILEGES) NULL, 0); 

   return 1;
}

Requisitos


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	timezoneapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll