extract_msg.ole_writer Module
Module contents
- class extract_msg.ole_writer.DirectoryEntry[source]
Bases:
objectAn internal representation of a stream or storage in the OleWriter.
Originals should be inaccessible outside of the class.
- name: str = ''
- rightChild: DirectoryEntry | None = None
- leftChild: DirectoryEntry | None = None
- childTreeRoot: DirectoryEntry | None = None
- stateBits: int = 0
- creationTime: int = 0
- modifiedTime: int = 0
- type: DirectoryEntryType = 0
- id: int = -1
- leftSiblingID: int = 4294967295
- rightSiblingID: int = 4294967295
- childID: int = 4294967295
- startingSectorLocation: int = 0
- clsid: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
- data: bytes = b''
- class extract_msg.ole_writer.OleWriter(rootClsid: bytes = b'\x0b\r\x02\x00\x00\x00\x00\x00\xc0\x00\x00\x00\x00\x00\x00F')[source]
Bases:
objectTakes data to write to a compound binary format file, as specified in [MS-CFB].
- addEntry(path: str | List[str] | Tuple[str], data: bytes | SupportsBytes | None = None, storage: bool = False, **kwargs) None[source]
Adds an entry to the OleWriter instance at the path specified, adding storages with default settings where necessary. If the entry is not a storage, :param data: must be set.
- Parameters:
path – The path to add the entry at. Must not contain a path part that is an already added stream.
data – The bytes for a stream or an object with a
__bytes__method.storage – If
True, the entry to add is a storage. Otherwise, the entry is a stream.clsid – The CLSID for the stream/storage. Must a a bytes instance that is 16 bytes long.
creationTime – An 8 byte filetime int. Sets the creation time of the entry. Not applicable to streams.
modifiedTime – An 8 byte filetime int. Sets the modification time of the entry. Not applicable to streams.
stateBits – A 4 byte int. Sets the state bits, user-defined flags, of the entry. For a stream, this SHOULD be unset.
- Raises:
OSError – A stream was found on the path before the end or an entry with the same name already exists.
ValueError – Attempts to access an internal item.
ValueError – The data provided is too large.
- addOleEntry(path: str | List[str] | Tuple[str], entry: OleDirectoryEntry, data: bytes | SupportsBytes | None = None) None[source]
Uses the entry provided to add the data to the writer.
- Raises:
OSError – Tried to add an entry to a path that has not yet been added, tried to add as a child of a stream, or tried to add an entry where one already exists under the same name.
ValueError – The data provided is too large.
- deleteEntry(path) None[source]
Deletes the entry specified by :param path:, including all children.
- Raises:
OSError – If the entry does not exist or a part of the path that is not the last was a stream.
ValueError – Attempted to delete an internal data stream.
- editEntry(path: str | List[str] | Tuple[str], **kwargs) None[source]
Used to edit values of an entry by setting the specific kwargs. Set a value to something other than None to set it.
- Parameters:
data – The data of a stream. Will error if used for something other than a stream. Must be bytes or convertable to bytes.
clsid – The CLSID for the stream/storage. Must a a bytes instance that is 16 bytes long.
creationTime – An 8 byte filetime int. Sets the creation time of the entry. Not applicable to streams.
modifiedTime – An 8 byte filetime int. Sets the modification time of the entry. Not applicable to streams.
stateBits – A 4 byte int. Sets the state bits, user-defined flags, of the entry. For a stream, this SHOULD be unset.
To convert a 32 character hexadecial CLSID into the bytes for this function, the _unClsid function in the ole_writer submodule can be used.
- Raises:
OSError – The entry does not exist in the file.
TypeError – Attempted to modify the bytes of a storage.
ValueError – The type of a parameter was wrong, or the data of a parameter was invalid.
- fromMsg(msg: MSGFile) None[source]
Copies the streams and stream information necessary from the MSG file.
- fromOleFile(ole: OleFileIO, rootPath: str | List[str] | Tuple[str] = []) None[source]
Copies all the streams from the proided OLE file into this writer.
NOTE: This method does not handle any special rule that may be required by a format that uses the compound binary file format as a base when extracting an embedded directory. For example, MSG files require modification of an embedded properties stream when extracting an embedded MSG file.
- Parameters:
rootPath – A path (accepted by
olefile.OleFileIO) to the directory to use as the root of the file. If not provided, the file root will be used.- Raises:
OSError – If :param rootPath: does not exist in the file.
- getEntry(path: str | List[str] | Tuple[str]) DirectoryEntry[source]
Finds and returns a copy of an existing DirectoryEntry instance in the writer. Use this method to check the internal status of an entry.
- Raises:
OSError – If the entry does not exist.
ValueError – If access to an internal item is attempted.
- listItems(streams: bool = True, storages: bool = False) List[List[str]][source]
Returns a list of the specified items currently in the writter.
- Parameters:
streams – If
True, includes the path for each stream in the list.storages – If
True, includes the path for each storage in the list.
- renameEntry(path: str | List[str] | Tuple[str], newName: str) None[source]
Changes the name of an entry, leaving it in it’s current position.
- Raises:
OSError – If the entry does not exist or an entry with the new name already exists,
ValueError – If access to an internal item is attempted or the new name provided is invalid.
- walk() Iterator[Tuple[List[str], List[str], List[str]]][source]
Functional equivelent to
os.walk, but for going over the file structure of the OLE file to be written. Unlikeos.walk, it takes no arguments.- Returns:
A tuple of three lists. The first is the path, as a list of strings, for the directory (or an empty list for the root), the second is a list of the storages in the current directory, and the last is a list of the streams. Streams and storages are sorted caselessly.