GetCalendarInfoEx function (winnls.h)

  • Article

Retrieves information about a calendar for a locale specified by name.

Note  The application should call this function in preference to GetCalendarInfo if designed to run only on Windows Vista and later.

 
Note  This function can retrieve data that changes between releases, for example, due to a custom locale. If your application must persist or transmit data, see Using Persistent Locale Data.
 

Syntax

int GetCalendarInfoEx(
  [in, optional]  LPCWSTR lpLocaleName,
  [in]            CALID   Calendar,
  [in, optional]  LPCWSTR lpReserved,
  [in]            CALTYPE CalType,
  [out, optional] LPWSTR  lpCalData,
  [in]            int     cchData,
  [out, optional] LPDWORD lpValue
);

Parameters

[in, optional] lpLocaleName

Pointer to a locale name, or one of the following predefined values.

[in] Calendar

Calendar identifier.

[in, optional] lpReserved

Reserved; must be NULL.

[in] CalType

Type of information to retrieve. For more information, see Calendar Type Information.

Note  GetCalendarInfoEx returns only one string if this parameter specifies CAL_IYEAROFFSETRANGE or CAL_SERASTRING. In both cases the current era is returned.
 
For CAL_NOUSEROVERRIDE, the function ignores any value set by SetCalendarInfo and uses the database settings for the current system default locale. This type is relevant only in the combination CAL_NOUSEROVERRIDE | CAL_ITWODIGITYEARMAX. CAL_ITWODIGITYEARMAX is the only value that can be set by SetCalendarInfo.

[out, optional] lpCalData

Pointer to a buffer in which this function retrieves the requested data as a string. If CAL_RETURN_NUMBER is specified in CalType, this parameter must retrieve NULL.

[in] cchData

Size, in characters, of the lpCalData buffer. The application can set this parameter to 0 to return the required size for the calendar data buffer. In this case, the lpCalData parameter is not used. If CAL_RETURN_NUMBER is specified for CalType, the value of cchData must be 0.

[out, optional] lpValue

Pointer to a variable that receives the requested data as a number. If CAL_RETURN_NUMBER is specified in CalType, then lpValue must not be NULL. If CAL_RETURN_NUMBER is not specified in CalType, then lpValue must be NULL.

Return value

Returns the number of characters retrieved in the lpCalData buffer if successful. If the function succeeds, cchData is set to 0, and CAL_RETURN_NUMBER is not specified, the return value is the size of the buffer required to hold the locale information. If the function succeeds, cchData is set to 0, and CAL_RETURN_NUMBER is specified, the return value is the size of the value written to the lpValue parameter. This size is always 2.

The function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.
  • ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
  • ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.

Remarks

Note  This API is being updated to support the May 2019 Japanese era change. If your application supports the Japanese calendar, you should validate that it properly handles the new era. See Prepare your application for the Japanese era change for more information.
 
Beginning in Windows 8: If your app passes language tags to this function from the Windows.Globalization namespace, it must first convert the tags by calling ResolveLocaleName.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps | UWP apps]
Minimum supported server Windows 2000 Server [desktop apps | UWP apps]
Target Platform Windows
Header winnls.h (include Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

See also

Calendar Type Information

GetCalendarInfo

National Language Support

National Language Support Functions

SetCalendarInfo