:py:mod:`dissect.ntfs.util`
===========================

.. py:module:: dissect.ntfs.util


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

Classes
~~~~~~~

.. autoapisummary::

   dissect.ntfs.util.AttributeMap
   dissect.ntfs.util.AttributeCollection



Functions
~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   dissect.ntfs.util.apply_fixup
   dissect.ntfs.util.ensure_volume
   dissect.ntfs.util.get_full_path
   dissect.ntfs.util.ts_to_ns



.. py:class:: AttributeMap(dict=None, /, **kwargs)


   Bases: :py:obj:`collections.UserDict`

   Utility dictionary-like object for interacting with a collection of attributes.

   Allows convenient accessing of attributes added to this collection. For example:
   - Get attributes by name, e.g. ``attributes.DATA`` to get all ``$DATA`` attributes.
   - Get attributes by type code enum or integer, e.g. ``attributes[0x80]`` or ``attributes[ATTRIBUTE_TYPE_CODE.DATA]``.
   - Check attribute membership by enum or integer, e.g. ``0x80 in attributes`` or ``ATTRIBUTE_TYPE_CODE.DATA in attributes``.
   - Find all attributes with a given name and type, e.g. ``attributes.find("$I30", ATTRIBUTE_TYPE_CODE.INDEX_ROOT)``.

   Note that any data retrieval from an ``AttributeMap`` will always succeed and return an
   :class:`~dissect.ntfs.util.AttributeCollection`, either empty or containing one or more attributes.

   .. py:method:: __getattr__(attr: str) -> AttributeCollection


   .. py:method:: __getitem__(item: Union[dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE, int]) -> AttributeCollection


   .. py:method:: __contains__(key: Union[dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE, int]) -> bool


   .. py:method:: add(attr: dissect.ntfs.attr.Attribute) -> None

      Add an attribute to the collection.

      Note that this is the only intended way to modify the :class:`AttributeMap`!

      :param attr: The attribute to add.


   .. py:method:: find(name: str, attr_type: dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE) -> AttributeCollection

      Find attributes by name and attribute type.

      :param name: The name of the attribute to find, usually ``""``.
      :param attr_type: The attribute type to find.



.. py:class:: AttributeCollection


   Bases: :py:obj:`list`

   Utility list-like object for interacting with a list of attributes.

   Allows convenient access to attribute properties for a list of one or more attributes.

   For example, if we have only one attribute we want to access the ``size``, we want to be able
   to do ``attribute_list.size`` instead of ``attribute_list[0].size``.

   Additionally, we can also provide functionality here that we want to perform on a group of
   attributes, like ``open()`` and ``size()``.

   .. py:method:: __getattr__(attr: str) -> Any


   .. py:method:: open(allocated: bool = False) -> BinaryIO

      Open the data streams on a list of attributes, resident or non-resident.

      :param allocated: Use the actual stream size or the allocated stream size (i.e. include slack space or not).

      :returns: A file-like object for the data of this list of attributes.


   .. py:method:: size(allocated: bool = False) -> int

      Retrieve the data stream size for this list of attributes.

      :param allocated: Return the actual stream size or the allocated stream size (i.e. include slack space or not).

      :returns: The requested stream size.


   .. py:method:: dataruns() -> list[tuple[int, int]]

      Get the dataruns for this list of attributes.

      :raises TypeError: If attribute is resident.



.. py:function:: apply_fixup(data: bytes) -> bytes

   Parse and apply fixup data from ``MULTI_SECTOR_HEADER`` to the given bytes.

   :param data: The bytes to fixup

   :returns: The fixed up bytes.


.. py:function:: ensure_volume(ntfs: dissect.ntfs.ntfs.NTFS) -> None

   Check if a volume is available for reading.

   A volume in this context refers to a disk or other file that contains the raw NTFS data, not contained
   in system files like the ``$MFT``.

   :raises VolumeNotAvailableError: If a volume is not available.


.. py:function:: get_full_path(mft: dissect.ntfs.mft.Mft, name: str, parent: dissect.cstruct.Instance, seen: set[str] = None) -> str

   Walk up parent file references to construct a full path.

   :param mft: The MFT object to use for looking up file references.
   :param name: The file name to use.
   :param parent: The parent reference to start backtracking from.

   :raises FilenameNotAvailableError: If an MFT record has no filename.


.. py:function:: ts_to_ns(ts: int) -> int

   Convert Windows timestamps to nanosecond timestamps.