extract-msg 0.48.2__py3-none-any.whl

extract_msg/structures/misc_id.py

@@ -0,0 +1,222 @@
+"""
+Miscellaneous ID structures used in MSG files that don't fit into any of the
+other ID structure classifications.
+"""
+
+
+__all__ = [
+    'FolderID',
+    'GlobalObjectID',
+    'MessageID',
+    'ServerID',
+]
+
+
+import datetime
+
+from .. import constants
+from ._helpers import BytesReader
+from ..utils import filetimeToDatetime
+
+
+class FolderID:
+    """
+    A Folder ID structure specified in [MS-OXCDATA].
+    """
+
+    __SIZE__: int = 16
+
+    def __init__(self, data: bytes):
+        self.__rawData = data
+        self.__replicaID = constants.st.ST_LE_UI16.unpack(data[:2])[0]
+        # This entry is 6 bytes, so we pull some shenanigans to unpack it.
+        self.__globalCounter = constants.st.ST_LE_UI64.unpack(data[2:8] + b'\x00\x00')[0]
+
+    def __bytes__(self) -> bytes:
+        return self.toBytes()
+
+    def toBytes(self) -> bytes:
+        return self.__rawData
+
+    @property
+    def globalCounter(self) -> int:
+        """
+        An unsigned integer identifying the folder within its Store object.
+        """
+        return self.__globalCounter
+
+    @property
+    def replicaID(self) -> int:
+        """
+        An unsigned integer identifying a Store object.
+        """
+        return self.__replicaID
+
+
+
+class GlobalObjectID:
+    """
+    A GlobalObjectID structure, as specified in [MS-OXOCAL].
+    """
+
+    def __init__(self, data: bytes):
+        self.__rawData = data
+        reader = BytesReader(data)
+        expectedBytes = b'\x04\x00\x00\x00\x82\x00\xE0\x00\x74\xC5\xB7\x10\x1A\x82\xE0\x08'
+        errorMsg = 'Byte Array ID did not match for GlobalObjectID (got {actual}).'
+        self.__byteArrayID = reader.assertRead(expectedBytes, errorMsg)
+        self.__yh = reader.read(1)
+        self.__yl = reader.read(1)
+        self.__year = constants.st.ST_BE_UI16.unpack(self.__yh + self.__yl)[0]
+        self.__month = reader.readUnsignedByte()
+        self.__day = reader.readUnsignedByte()
+        self.__creationTime = filetimeToDatetime(reader.readUnsignedLong())
+        reader.assertNull(8, 'Reserved was not set to null.')
+        size = reader.readUnsignedInt()
+        self.__data = reader.read(size)
+
+    def __bytes__(self) -> bytes:
+        return self.toBytes()
+
+    def toBytes(self) -> bytes:
+        return self.__rawData
+
+    @property
+    def byteArrayID(self) -> bytes:
+        """
+        An array of 16 bytes identifying the bytes this BLOB as a Global Object
+        ID.
+        """
+        return self.__byteArrayID
+
+    @property
+    def creationTime(self) -> datetime.datetime:
+        """
+        The date and time when this Global Object ID was generated.
+        """
+        return self.__creationTime
+
+    @property
+    def data(self) -> bytes:
+        """
+        An array of bytes that ensures the uniqueness of the Global Object ID
+        amoung all Calendar objects in all mailboxes.
+        """
+        return self.__data
+
+    @property
+    def day(self) -> int:
+        """
+        The day from the PidLidExceptionReplaceTime property if the object
+        represents an exception. Otherwise, this is 0.
+        """
+        return self.__day
+
+    @property
+    def month(self) -> int:
+        """
+        The month from the PidLidExceptionReplaceTime property if the object
+        represents an exception. Otherwise, this is 0.
+        """
+        return self.__month
+
+    @property
+    def year(self) -> int:
+        """
+        The year from the PidLidExceptionReplaceTime property if the object
+        represents an exception. Otherwise, this is 0.
+        """
+        return self.__year
+
+
+
+class MessageID:
+    """
+    A Message ID structure, as defined in [MS-OXCDATA].
+    """
+
+    __SIZE__: int = 8
+
+    def __init__(self, data: bytes):
+        self.__rawData = data
+        self.__replicaID = constants.st.ST_LE_UI16.unpack(data[:2])[0]
+        # This entry is 6 bytes, so we pull some shenanigans to unpack it.
+        self.__globalCounter = constants.st.ST_LE_UI64.unpack(data[2:8] + b'\x00\x00')[0]
+
+    def __bytes__(self) -> bytes:
+        return self.toBytes()
+
+    def toBytes(self) -> bytes:
+        return self.__rawData
+
+    @property
+    def globalCounter(self) -> int:
+        """
+        An unsigned integer identifying the folder within its Store object.
+        """
+        return self.__globalCounter
+
+    @property
+    def isFolder(self) -> bool:
+        """
+        Tells if the object pointed to is actually a folder.
+        """
+        return self.__globalCounter == 0 and self.__replicaID == 0
+
+    @property
+    def replicaID(self) -> int:
+        """
+        An unsigned integer identifying a Store object.
+        """
+        return self.__replicaID
+
+
+
+class ServerID:
+    """
+    Class representing a PtypServerId.
+    """
+    def __init__(self, data: bytes):
+        """
+        :param data: The data to use to create the ServerID.
+
+        :raises TypeError: The data is not a ServerID.
+        """
+        # According to the docs, the first byte being a 1 means it follows this
+        # structure. A value of 0 means it does not.
+        if data[0] != 1:
+            raise TypeError('Not a standard ServerID.')
+        self.__rawData = data
+        self.__folderID = FolderID(data[1:9])
+        self.__messageID = MessageID(data[9:17])
+        self.__instance = constants.st.ST_LE_UI32.unpack(data[17:21])[0]
+
+    def __bytes__(self) -> bytes:
+        return self.toBytes()
+
+    def toBytes(self) -> bytes:
+        return self.__rawData
+
+    @property
+    def folderID(self) -> FolderID:
+        """
+        The folder the message will be in.
+        """
+        return self.__folderID
+
+    @property
+    def instance(self) -> int:
+        """
+        Instance number that is only used in multivalue properties for searching
+        for a specific ServerID. Will otherwise be 0.
+        """
+        return self.__instance
+
+    @property
+    def messageID(self) -> MessageID:
+        """
+        A MessageID identifying a message in a folder identified by the folderID
+        instance of this object. If the object pointed to is a folder, both
+        properties will be 0.
+        """
+        return self.__messageID

extract_msg/structures/mon_stream.py

@@ -0,0 +1,55 @@
+__all__ = [
+    'MonikerStream',
+]
+
+
+from typing import final, Optional
+
+
+@final
+class MonikerStream:
+    def __init__(self, data: Optional[bytes] = None):
+        if data:
+            self.__clsid = data[:16]
+            self.__streamData = data[16:]
+        else:
+            self.__clsid = b'\x00' * 16
+            self.__streamData = b''
+
+    def __bytes__(self) -> bytes:
+        return self.toBytes()
+
+    def toBytes(self) -> bytes:
+        return self.__clsid + self.__streamData
+
+    @property
+    def clsid(self) -> bytes:
+        """
+        The CLSID, as a stream of 16 bytes, of an implementation specific object
+        capable of processing the stream data.
+        """
+        return self.__clsid
+
+    @clsid.setter
+    def clsid(self, data: bytes) -> None:
+        if not isinstance(data, bytes):
+            raise TypeError('CLSID MUST be bytes.')
+        if len(data) != 16:
+            raise ValueError('CLSID MUST be 16 bytes.')
+
+        self.__clsid = data
+
+    @property
+    def streamData(self) -> bytes:
+        """
+        An array of bytes that specifies the reference to the linked object.
+        """
+        return self.__streamData
+
+    @streamData.setter
+    def streamData(self, data: bytes) -> None:
+        if not isinstance(data, bytes):
+            raise TypeError('Stream data MUST be bytes.')
+
+        self.__streamData = data
+

extract_msg/structures/odt.py

@@ -0,0 +1,74 @@
+__all__ = [
+    'ODTStruct',
+]
+
+import struct
+from typing import final, Optional
+
+from ..enums import ODTCf, ODTPersist1, ODTPersist2
+
+
+@final
+class ODTStruct:
+    def __init__(self, data: Optional[bytes] = None):
+        if data:
+            values = struct.unpack('<HH', data[:8])
+            self.__cf = ODTCf(values[0])
+            self.__persist1 = ODTPersist1(values[1])
+            if len(data) >= 6:
+                self.__persist2 = ODTPersist2(struct.unpack('<H', data[4:6])[0])
+            else:
+                self.__persist2 = ODTPersist2.NONE
+        else:
+            self.__cf = ODTCf.UNSPECIFIED
+            self.__persist1 = ODTPersist1.NONE
+            self.__persist2 = ODTPersist2.NONE
+
+    def __bytes__(self) -> bytes:
+        return self.toBytes()
+
+    def toBytes(self) -> bytes:
+        return struct.pack('<HHH', self.__cf, self.__persist1, self.__persist2)
+
+    @property
+    def cf(self) -> ODTCf:
+        """
+        An enum value that specifies the format this OLE object uses to
+        transmit data to the host application.
+        """
+        return self.__cf
+
+    @cf.setter
+    def cf(self, value: ODTCf) -> None:
+        if not isinstance(value, ODTCf):
+            raise TypeError(':property cf: MUST be of type ODTCf.')
+
+        self.__cf = value
+
+    @property
+    def odtPersist1(self) -> ODTPersist1:
+        """
+        Flags that specify information about the OLE object.
+        """
+        return self.__persist1
+
+    @odtPersist1.setter
+    def odtPersist1(self, value: ODTPersist1) -> None:
+        if not isinstance(value, ODTPersist1):
+            raise TypeError(':property odtPersist1: MUST be of type ODTPersist1.')
+
+        self.__persist1 = value
+
+    @property
+    def odtPersist2(self) -> ODTPersist2:
+        """
+        Flags that specify additional information about the OLE object.
+        """
+        return self.__persist2
+
+    @odtPersist2.setter
+    def odtPersist2(self, value: ODTPersist2) -> None:
+        if not isinstance(value, ODTPersist2):
+            raise TypeError(':property odtPersist2: MUST be of type ODTPersist2.')
+
+        self.__persist2 = value

extract_msg/structures/ole_pres.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'OLEPresentationStream',
+]
+
+
+from typing import List, Optional, Union
+
+from ._helpers import BytesReader
+from .cfoas import ClipboardFormatOrAnsiString
+from ..constants import st
+from .dv_target_device import DVTargetDevice
+from ..enums import ADVF, ClipboardFormat, DVAspect
+from .toc_entry import TOCEntry
+
+
+class OLEPresentationStream:
+    """
+    [MS-OLEDS] OLEPresentationStream.
+    """
+
+    def __init__(self, data: bytes):
+        reader = BytesReader(data)
+        acf = self.__ansiClipboardFormat = ClipboardFormatOrAnsiString(reader)
+
+        # Validate the structure based on the documentation.
+        if acf.markerOrLength == 0:
+            raise ValueError('Invalid OLEPresentationStream (MarkerOrLength is 0).')
+        if acf.clipboardFormat is ClipboardFormat.CF_BITMAP:
+            raise ValueError('Invalid OLEPresentationStream (Format is CF_BITMAP).')
+        if 0x201 < acf.markerOrLength < 0xFFFFFFFE:
+            raise ValueError('Invalid OLEPresentationStream (ANSI length was more than 0x201).')
+
+        targetDeviceSize = reader.readUnsignedInt()
+        if targetDeviceSize < 0x4:
+            raise ValueError('Invalid OLEPresentationStream (TargetDeviceSize was less than 4).')
+        if targetDeviceSize > 0x4:
+            # Read the TargetDevice field.
+            self.__targetDevice = DVTargetDevice(reader.read(targetDeviceSize))
+        else:
+            self.__targetDevice = None
+
+        self.__aspect = reader.readUnsignedInt()
+        self.__lindex = reader.readUnsignedInt()
+        self.__advf = reader.readUnsignedInt()
+
+        # Reserved1.
+        self.__reserved1 = reader.read(4)
+
+        self.__width = reader.readUnsignedInt()
+        self.__height = reader.readUnsignedInt()
+        size = reader.readUnsignedInt()
+        self.__data = reader.read(size)
+
+        if acf.clipboardFormat is ClipboardFormat.CF_METAFILEPICT:
+            self.__reserved2 = reader.read(18)
+        else:
+            self.__reserved2 = b'\x00' * 18.
+
+        self.__tocSignature = reader.readUnsignedInt()
+        self.__tocEntries = []
+        if self.__tocSignature == 0x494E414E: # b'NANI' in little endian.
+            for _ in range(reader.readUnsignedInt()):
+                self.__tocEntries.append(TOCEntry(reader))
+
+    def __bytes__(self) -> bytes:
+        return self.toBytes()
+
+    def toBytes(self) -> bytes:
+        ret = bytes(self.__ansiClipboardFormat)
+
+        if self.__targetDevice is None:
+            ret += b'\x04\x00\x00\x00'
+        else:
+            dvData = bytes(self.__targetDevice)
+            ret += st.ST_LE_UI32.pack(len(dvData))
+            ret += dvData
+
+        ret += st.ST_LE_UI32.pack(self.__aspect)
+        ret += st.ST_LE_UI32.pack(self.__lindex)
+        ret += st.ST_LE_UI32.pack(self.__advf)
+        ret += self.__reserved1
+        ret += st.ST_LE_UI32.pack(self.__width)
+        ret += st.ST_LE_UI32.pack(self.__height)
+        ret += st.ST_LE_UI32.pack(len(self.__data)) + self.__data
+        if self.reserved2: # Shortcut since this property has protection.
+            ret += self.__reserved2
+
+        if self.__tocSignature == 0x494E414E:
+            ret += st.ST_LE_UI32.pack(len(self.__tocEntries))
+            for entry in self.__tocEntries:
+                ret += bytes(entry)
+        else:
+            ret += b'\x00\x00\x00\x00'
+
+        return ret
+
+    @property
+    def advf(self) -> Union[int, ADVF]:
+        """
+        An implementation specific hint on how to render the presentation data
+        on screen. May be ignored on processing.
+        """
+        return self.__advf
+
+    @advf.setter
+    def advf(self, val: Union[int, ADVF]) -> None:
+        if not isinstance(val, int):
+            raise TypeError(':property advf: must be an int.')
+        if val < 0:
+            raise ValueError(':property advf: must be positive.')
+        if val > 0xFFFFFFFF:
+            raise ValueError(':property advf: cannot be greater than 0xFFFFFFFF.')
+
+        self.__advf = val
+
+    @property
+    def ansiClipboardFormat(self) -> ClipboardFormatOrAnsiString:
+        return self.__ansiClipboardFormat
+
+    @property
+    def aspect(self) -> Union[int, DVAspect]:
+        """
+        An implementation specific hint on how to render the presentation data
+        on screen. May be ignored on processing.
+        """
+        return self.__aspect
+
+    @aspect.setter
+    def aspect(self, val: Union[int, DVAspect]) -> None:
+        if not isinstance(val, int):
+            raise TypeError(':property aspect: must be an int.')
+        if val < 0:
+            raise ValueError(':property aspect: must be positive.')
+        if val > 0xFFFFFFFF:
+            raise ValueError(':property aspect: cannot be greater than 0xFFFFFFFF.')
+
+        self.__aspect = val
+
+    @property
+    def data(self) -> bytes:
+        """
+        The presentation data. The form of this data depends on :property clipboardFormat: of :property ansiClipboardFormat:.
+        """
+        return self.__data
+
+    @data.setter
+    def data(self, val: bytes) -> None:
+        if not isinstance(val, bytes):
+            raise TypeError(':property data: must be bytes.')
+        self.__data = val
+
+    @property
+    def height(self) -> int:
+        """
+        The height, in pixels, of the presentation data.
+        """
+        return self.__height
+
+    @height.setter
+    def height(self, val: int) -> None:
+        if not isinstance(val, int):
+            raise TypeError(':property height: must be an int.')
+        if val < 0:
+            raise ValueError(':property height: must be positive.')
+        if val > 0xFFFFFFFF:
+            raise ValueError(':property height: cannot be greater than 0xFFFFFFFF.')
+
+        self.__height = val
+
+    @property
+    def lindex(self) -> int:
+        """
+        An implementation specific hint on how to render the presentation data on screen. May be ignored on processing.
+        """
+        return self.__lindex
+
+    @lindex.setter
+    def lindex(self, val: int) -> None:
+        if not isinstance(val, int):
+            raise TypeError(':property lindex: must be an int.')
+        if val < 0:
+            raise ValueError(':property lindex: must be positive.')
+        if val > 0xFFFFFFFF:
+            raise ValueError(':property lindex: cannot be greater than 0xFFFFFFFF.')
+
+        self.__lindex = val
+
+    @property
+    def reserved1(self) -> bytes:
+        """
+        4 bytes that can contain any arbitrary data. Must be *exactly* 4 bytes
+        when setting.
+        """
+        return self.__reserved1
+
+    @reserved1.setter
+    def reserved1(self, val: bytes) -> None:
+        if not isinstance(val, bytes):
+            raise TypeError(':property reserved1: must by bytes.')
+        if len(val) != 4:
+            raise ValueError(':property reserved1: must be exactly 4 bytes.')
+
+        self.__reserved1 = val
+
+    @property
+    def reserved2(self) -> Optional[bytes]:
+        """
+        Optional additional data that is only set if the clipboard format of
+        :property ansiClipboardFormat: is ``CF_METAFILEPICT``.
+
+        Getting this will automatically correct the value retrieved based on
+        the clipboard format, but will *not* modify the underlying data.
+
+        Must be *exactly* 18 bytes when setting.
+        """
+        if self.__ansiClipboardFormat.clipboardFormat is not ClipboardFormat.CF_METAFILEPICT:
+            return None
+        return self.__reserved2
+
+    @reserved2.setter
+    def reserved2(self, val: bytes) -> None:
+        if self.__ansiClipboardFormat.clipboardFormat is not ClipboardFormat.CF_METAFILEPICT:
+            raise ValueError(':property reserved2: cannot be set if the clipboard format (from :property ansiClipboardFormat:) is not CF_METAFILEPICT.')
+        if not isinstance(val, bytes):
+            raise TypeError(':property reserved2: must by bytes.')
+        if len(val) != 18:
+            raise ValueError(':property reserved2: must be exactly 18 bytes.')
+
+        self.__reserved2 = val
+
+    @property
+    def targetDevice(self) -> Optional[DVTargetDevice]:
+        return self.__targetDevice
+
+    @targetDevice.setter
+    def targetDevice(self, val: Optional[DVTargetDevice]) -> None:
+        if val is not None and not isinstance(val, DVTargetDevice):
+            raise TypeError(':property targetDevice: must be None or a DVTargetDevice.')
+
+        self.__targetDevice = val
+
+    @property
+    def tocEntries(self) -> List[TOCEntry]:
+        """
+        A list of TOCEntry structures. If :property tocSignature: is not set to
+        ``0x494E414E``, accessing this value will clear the list.
+
+        :returns: A direct reference to the list, allowing for modification.
+            This class WILL NOT change this reference over the lifetime of the
+            object.
+        """
+        if self.__tocSignature != 0x494E414E:
+            self.__tocEntries.clear()
+        return self.__tocEntries
+
+    @property
+    def tocSignature(self) -> int:
+        """
+        If this field does not contain ``0x494E414E``, then
+        :property tocEntries: MUST be empty. Modifications to the list will be lost when it is next retrieved, meaning changes while this property is not ``0x494E414E`` WILL be lost.
+
+        Setting this to a value other than ``0x494E414E`` will clear the list
+        immediately.
+        """
+        return self.__tocSignature
+
+    @tocSignature.setter
+    def tocSignature(self, val: int) -> None:
+        if not isinstance(val, int):
+            raise TypeError(':property tocSignature: must be an int.')
+        if val < 0:
+            raise ValueError(':property tocSignature: must be positive.')
+        if val > 0xFFFFFFFF:
+            raise ValueError(':property tocSignature: cannot be greater than 0xFFFFFFFF.')
+
+        if val != 0x494E414E:
+            self.__tocEntries.clear()
+
+        self.__tocSignature = val
+
+    @property
+    def width(self) -> int:
+        """
+        The width, in pixels, of the presentation data.
+        """
+        return self.__width
+
+    @width.setter
+    def width(self, val: int) -> None:
+        if not isinstance(val, int):
+            raise TypeError(':property width: must be an int.')
+        if val < 0:
+            raise ValueError(':property width: must be positive.')
+        if val > 0xFFFFFFFF:
+            raise ValueError(':property width: cannot be greater than 0xFFFFFFFF.')
+
+        self.__width = val
+
+