:py:mod:`dissect.target.plugins.os.windows.datetime`
====================================================

.. py:module:: dissect.target.plugins.os.windows.datetime




Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   dissect.target.plugins.os.windows.datetime.TimezoneInformation
   dissect.target.plugins.os.windows.datetime.WindowsTimezone
   dissect.target.plugins.os.windows.datetime.WindowsDateTimePlugin



Functions
~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   dissect.target.plugins.os.windows.datetime.parse_systemtime_transition
   dissect.target.plugins.os.windows.datetime.parse_dynamic_dst
   dissect.target.plugins.os.windows.datetime.parse_tzi
   dissect.target.plugins.os.windows.datetime.get_dst_range
   dissect.target.plugins.os.windows.datetime.translate_tz



Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.target.plugins.os.windows.datetime.tz_def
   dissect.target.plugins.os.windows.datetime.c_tz
   dissect.target.plugins.os.windows.datetime.SUNDAY
   dissect.target.plugins.os.windows.datetime.SundayFirstCalendar
   dissect.target.plugins.os.windows.datetime.ZERO
   dissect.target.plugins.os.windows.datetime.HOUR


.. py:data:: tz_def
   :value: Multiline-String

   .. raw:: html

      <details><summary>Show Value</summary>

   .. code-block:: python

      """
      typedef struct _SYSTEMTIME {
          WORD wYear;
          WORD wMonth;
          WORD wDayOfWeek;
          WORD wDay;
          WORD wHour;
          WORD wMinute;
          WORD wSecond;
          WORD wMilliseconds;
      } SYSTEMTIME;
      
      typedef struct _REG_TZI_FORMAT {
          LONG Bias;
          LONG StandardBias;
          LONG DaylightBias;
          SYSTEMTIME StandardDate;
          SYSTEMTIME DaylightDate;
      } REG_TZI_FORMAT;
      """

   .. raw:: html

      </details>



.. py:data:: c_tz

.. py:data:: SUNDAY

.. py:data:: SundayFirstCalendar

.. py:class:: TimezoneInformation

   Bases: :py:obj:`NamedTuple`


   .. py:attribute:: bias
      :type:  datetime.timedelta


   .. py:attribute:: standard_bias
      :type:  datetime.timedelta


   .. py:attribute:: daylight_bias
      :type:  datetime.timedelta


   .. py:attribute:: standard_date
      :type:  c_tz


   .. py:attribute:: daylight_date
      :type:  c_tz


.. py:data:: ZERO

.. py:data:: HOUR

.. py:function:: parse_systemtime_transition(systemtime: c_tz, year: int) -> datetime.datetime

   Return the transition datetime for a given year using the SYSTEMTIME of a STD or DST transition date.

   The SYSTEMTIME date of a TZI structure needs to be used to calculate the actual date for a given year.
   The wMonth member indicates the month, the wDayOfWeek member indicates the weekday and the wDay indicates the
   occurance of the day of the week within the month (1 to 5, where 5 indicates the final occurrence during the
   month if that day of the week does not occur 5 times).

   Reference:
       - https://docs.microsoft.com/en-us/windows/win32/api/timezoneapi/ns-timezoneapi-time_zone_information


.. py:function:: parse_dynamic_dst(key: dissect.target.helpers.regutil.RegistryKey) -> dict[int, TimezoneInformation]

   Parse dynamic DST information from a given TimeZoneInformation registry key.

   If a timezone has dynamic DST information, there's a "Dynamic DST" subkey with values for each year.
   The FirstEntry and LastEntry contain the first and last year respectively. The TZI structure is the same as the
   main TimeZoneInformation TZI.


.. py:function:: parse_tzi(tzi: bytes) -> TimezoneInformation

   Parse binary TZI into a ``TimezoneInformation`` namedtuple.


.. py:function:: get_dst_range(tzi: TimezoneInformation, year: int) -> tuple[datetime.datetime, datetime.datetime]

   Get the start and end date of DST for the given year.


.. py:class:: WindowsTimezone(name: str, key: dissect.target.helpers.regutil.RegistryKey)

   Bases: :py:obj:`datetime.tzinfo`


   A ``datetime.tzinfo`` class representing a timezone from parsed Windows TZI data.

   Mostly inspired by the examples in the Python documentation.


   .. py:attribute:: name


   .. py:attribute:: display


   .. py:attribute:: dlt_name


   .. py:attribute:: std_name


   .. py:attribute:: tzi


   .. py:attribute:: dynamic_dst


   .. py:attribute:: bias


   .. py:method:: __repr__() -> str


   .. py:method:: is_dst(dt: datetime.datetime) -> bool


   .. py:method:: utcoffset(dt: datetime.datetime) -> int

      datetime -> timedelta, positive for east of UTC, negative for west of UTC



   .. py:method:: dst(dt: datetime.datetime) -> datetime.timedelta

      datetime -> DST offset as timedelta, positive for east of UTC.

      Return 0 if DST not in effect.  utcoffset() must include the DST
      offset.



   .. py:method:: tzname(dt: datetime.datetime) -> str

      datetime -> string name of time zone.



.. py:class:: WindowsDateTimePlugin(target: dissect.target.target.Target)

   Bases: :py:obj:`dissect.target.plugins.os.default.datetime.DateTimePlugin`


   Generic implementation for datetime plugin.


   .. py:attribute:: __namespace__
      :value: 'datetime'


      Defines the plugin namespace.


   .. py:method:: check_compatible() -> None

      Perform a compatibility check with the target.

      This function should return ``None`` if the plugin is compatible with the current target (``self.target``).
      For example, check if a certain file exists. Otherwise it should raise an
      :class:`UnsupportedPluginError`.

      :raises UnsupportedPluginError: If the plugin could not be loaded.



   .. py:method:: tz(name: str) -> datetime.tzinfo

      Return a ``datetime.tzinfo`` of the given timezone name.



   .. py:method:: tzinfo() -> datetime.tzinfo

      Return a ``datetime.tzinfo`` of the current system timezone.



.. py:function:: translate_tz(key: dissect.target.helpers.regutil.RegistryKey, name: str) -> str

   Translate a timezone resource string to English.

   Non-English distributions of Windows contain a local translation in the "Display", "Dlt" and "Std" keys.
   The ``MUI_*`` keys contain a reference to the English timezone name we want, e.g. "@tzres.dll,-1337".