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

.. py:module:: dissect.ntfs.index


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

Classes
~~~~~~~

.. autoapisummary::

   dissect.ntfs.index.Match
   dissect.ntfs.index.Index
   dissect.ntfs.index.IndexRoot
   dissect.ntfs.index.IndexBuffer
   dissect.ntfs.index.IndexEntry




.. py:class:: Match


   Bases: :py:obj:`enum.Enum`

   Generic enumeration.

   Derive from this class to define new enumerations.

   .. py:attribute:: Less

      

   .. py:attribute:: Equal

      

   .. py:attribute:: Greater

      


.. py:class:: Index(record: dissect.ntfs.mft.MftRecord, name: str)


   Open an index with he given name on the given MFT record.

   :param name: The index to open.

   :raises FileNotFoundError: If no index with that name can be found.

   .. py:method:: __iter__() -> Iterator[IndexEntry]


   .. py:method:: index_buffer(vcn: int) -> IndexBuffer

      Return the :class:`IndexBuffer` at the specified cluster number.

      :param vcn: The virtual cluster number within the index allocation to read.

      :raises FileNotFoundError: If this index has no index allocation.


   .. py:method:: search(value: Any, exact: bool = True, cmp: Optional[Callable[[IndexEntry, Any], Match]] = None) -> IndexEntry

      Perform a binary search on this index.

      Returns the matching node if performing an exact search. Otherwise return the first match that is greater
      than the search value.

      :param value: The key to search.
      :param exact: Result must be an exact match.
      :param cmp: Optional custom comparator function.

      :raises NotImplementedError: If there is no collation (comparator) function for the collation rule of this index.
      :raises KeyError: If an exact match was requested but not found.


   .. py:method:: entries() -> Iterator[IndexEntry]

      Yield all :class:`IndexEntry`'s in this :class:`Index`.



.. py:class:: IndexRoot(index: Index, fh: BinaryIO)


   Represents the ``$INDEX_ROOT``.

   :param index: The :class:`Index`` class instance this :class:`IndexRoot` belongs to.
   :param fh: The file-like object to parse an index root on.

   .. py:property:: attribute_type
      :type: dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE

      Return the indexed attribute type.

   .. py:property:: collation_rule
      :type: dissect.ntfs.c_ntfs.COLLATION

      Return the collation rule.

   .. py:property:: bytes_per_index_buffer
      :type: int

      Return the size of an index buffer in the index allocation in bytes.

   .. py:property:: clusters_per_index_buffer
      :type: int

      Return the size of an index buffer in the index allocation in clusters.

   .. py:method:: entries() -> Iterator[IndexEntry]

      Yield all :class:`IndexEntry`'s in this :class:`IndexRoot`.



.. py:class:: IndexBuffer(index: Index, fh: BinaryIO, offset: int, size: int)


   Represent an index buffer in ``$INDEX_ALLOCATION``.

   :param index: The :class:`Index` class instance this :class:`IndexRoot` belongs to.
   :param fh: The file-like object of ``$INDEX_ALLOCATION``.
   :param offset: The offset in bytes to the index buffer on the file-like object we want to read.
   :param size: The size of the index buffer in bytes.

   :raises EOFError: If there's not enough data available to read an index buffer.
   :raises BrokenIndexError: If the index buffer doesn't start with the expected magic value.

   .. py:method:: entries() -> Iterator[IndexEntry]

      Yield all :class:`IndexEntry`'s in this :class:`IndexBuffer`.



.. py:class:: IndexEntry(index: Index, fh: BinaryIO, offset: int)


   Parse and interact with index entries.

   :param index: The :class:`Index` class instance this :class:`IndexEntry` belongs to.
   :param fh: The file-like object to parse an index entry on.
   :param offset: The offset in the file-like object to parse an index entry at.

   .. py:property:: is_end
      :type: bool

      Return whether this entry marks the end.

   .. py:property:: is_node
      :type: bool

      Return whether this entry is a node.

   .. py:property:: node_vcn
      :type: int

      Return the node VCN if this entry is a node.

   .. py:property:: length
      :type: int

      Return the length of this index entry.

   .. py:property:: key_length
      :type: int

      Return the length of this index entry.

   .. py:method:: dereference() -> dissect.ntfs.mft.MftRecord

      Dereference this :class:`IndexEntry` to the MFT record it points to.

      Note that the file reference is a union with the data part so only access this if you know the entry has
      a file reference and not a data part.

      :raises MftNotAvailableError: If no MFT is available.


   .. py:method:: key() -> bytes

      Return the index key of this entry.


   .. py:method:: data() -> bytes

      Return the data part of this entry.

      Note that the data part is a union with the file reference, so only access this if you know the entry has
      data and not a file reference.


   .. py:method:: attribute() -> Optional[dissect.ntfs.attr.AttributeRecord]

      Return the :class:`dissect.ntfs.attr.AttributeRecord` of the attribute contained in this entry.