Função GetCalendarInfoW (winnls.h)

Artigo
11/20/2024

Recupera informações sobre um calendário para uma localidade especificada pelo identificador.

Observação Por motivos de interoperabilidade, o aplicativo deve preferir a função GetCalendarInfoExGetCalendarInfo porque a Microsoft está migrando para o uso de nomes de localidade em vez de identificadores de localidade para novas localidades. Qualquer aplicativo executado somente no Windows Vista e posterior deve usar GetCalendarInfoEx.

Sintaxe

int GetCalendarInfoW(
  [in]            LCID    Locale,
  [in]            CALID   Calendar,
  [in]            CALTYPE CalType,
  [out, optional] LPWSTR  lpCalData,
  [in]            int     cchData,
  [out, optional] LPDWORD lpValue
);

Parâmetros

[in] Locale

identificador de localidade que especifica a localidade para a qual recuperar informações de calendário. Você pode usar a macro MAKELCID para criar um identificador de localidade ou usar um dos seguintes valores predefinidos.

[in] Calendar

do identificador de calendário.

[in] CalType

Tipo de informação a ser recuperada. Para obter mais informações, consulte informações de tipo de calendário.

ObservaçãoGetCalendarInfo retornará apenas uma cadeia de caracteres se esse parâmetro especificar CAL_IYEAROFFSETRANGE ou CAL_SERASTRING. Em ambos os casos, a era atual é retornada.

CAL_USE_CP_ACP é relevante apenas para a versão ANSI dessa função.

Para CAL_NOUSEROVERRIDE, a função ignora qualquer valor definido por SetCalendarInfo e usa as configurações de banco de dados para a localidade padrão do sistema atual. Esse tipo é relevante apenas na combinação CAL_NOUSEROVERRIDE | CAL_ITWODIGITYEARMAX. CAL_ITWODIGITYEARMAX é o único valor que pode ser definido por SetCalendarInfo.

[out, optional] lpCalData

Ponteiro para um buffer no qual essa função recupera os dados solicitados como uma cadeia de caracteres. Se CAL_RETURN_NUMBER for especificado em CalType, esse parâmetro deverá recuperar NULL.

[in] cchData

Tamanho, em caracteres, do buffer lpCalData . O aplicativo pode definir esse parâmetro como 0 para retornar o tamanho necessário para o buffer de dados do calendário. Nesse caso, o parâmetro lpCalData não é usado. Se CAL_RETURN_NUMBER for especificado para CalType, o valor de cchData deverá ser 0.

[out, optional] lpValue

Ponteiro para uma variável que recebe os dados solicitados como um número. Se CAL_RETURN_NUMBER for especificado em CalType, lpValue não deverá ser NULL. Se CAL_RETURN_NUMBER não for especificado em CalType, lpValue deverá ser NULL.

Valor de retorno

Retorna o número de caracteres recuperados no buffer lpCalData, com cchData definido como um valor diferente de zero, se bem-sucedido. Se a função for bem-sucedida, cchData será definido como 0 e CAL_RETURN_NUMBER não for especificado, o valor retornado será o tamanho do buffer necessário para armazenar as informações do calendário. Se a função for bem-sucedida, cchData for definido 0 e CAL_RETURN_NUMBER for especificado, o valor retornado será o tamanho do valor recuperado em lpValue, ou seja, 2 para a versão Unicode da função ou 4 para a versão ANSI.

Essa função retornará 0 se não for bem-sucedida. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar um dos seguintes códigos de erro:

ERROR_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou foi definido incorretamente como NULL.
ERROR_INVALID_FLAGS. Os valores fornecidos para sinalizadores não eram válidos.
ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.

Observações

Observação esta API está sendo atualizada para dar suporte à alteração da era japonesa de maio de 2019. Se o aplicativo der suporte ao calendário japonês, você deverá validar que ele lida corretamente com a nova era. Consulte Preparar seu aplicativo para a de alteração da era japonesa para obter mais informações.

Quando a versão ANSI dessa função é usada com um identificador de localidade somente Unicode, a função pode ser bem-sucedida porque o sistema operacional usa a página de código do sistema. No entanto, caracteres que são indefinidos na página de código do sistema aparecem na cadeia de caracteres como um ponto de interrogação (?).

Nota

O cabeçalho winnls.h define GetCalendarInfo como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winnls.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

de informações de tipo de calendário

GetCalendarInfoEx

de Suporte à Linguagem Nacional

funções de suporte à linguagem nacional

SetCalendarInfo

Compartilhar via