Swift support for Microsoft OLE2 format, also known as Structured Storage, Compound File Binary Format or Compound Document File Format.
Some of the file formats that utilize it:
- Encrypted Office Open XML documents (Microsoft Office 2003+, Word
.docx
, Excel.xlsx
, PowerPoint.pptx
) - Microsoft Office 97-2003 documents (BIFF5 and later in Word
.doc
, Excel.xls
, PowerPoint.ppt
, Visio.vsd
, Project.mpp
) vbaProject.bin
in MS Office 2007+ files- Image Composer and FlashPix files
- Outlook messages
- StickyNotes
- Zeiss AxioVision ZVI files
- Olympus FluoView OIB files
- McAfee antivirus quarantine files
- Hancom Word's
.hwp
file format
...and more. If you know of a file format that is based on CFBF, please submit a pull request so that it's added to the list.
Automatically generated documentation is available on our GitHub Pages.
Join our Discord for any questions and friendly banter.
An OLE2 file has a minuature filesystem embedded in
it that is
represented as a tree of
DirectoryEntry
values in OLEKit.
To read a file and an entry within the file:
- Add
import OLEKit
at the top of a relevant source file. - Use
OLEFile(_ path: String)
to create a new instance with a path to your OLE2 file. - Use the
root
property of typeDirectoryEntry
onOLEFile
to read the root directory entry, and thechildren
property onDirectoryEntry
to traverse the tree of entries. - Call
stream(_ entry:)
on yourOLEFile
instance to get access to the entry. This returns an instance ofDataReader
that provides helperread()
functions for reading raw data.
import OLEKit
let filepath = "./categories.xlsx"
let entryName = "EncryptionInfo"
let ole = try OLEFile(filepath)
guard
let infoEntry = oleFile.root.children.first(where: { $0.name == entryName })
else { fatalError("entry \(entryName) not found in file \(filepath)") }
let stream = try oleFile.stream(infoEntry)
// Read version bytes from the encryption stream in little-endian order
let major: UInt16 = stream.read()
let minor: UInt16 = stream.read()
guard major == 4 && minor == 4
else { fatalError("unknown version: major \(major), minor \(minor)") }
// change position in the `stream`
reader.seek(toOffset: 8)
// get the rest of the data
let rawStreamData = reader.readDataToEnd()
You can refer to source code of the CryptoOffice library for a more detailed example.
Apple Platforms
- Xcode 11.2 or later
- Swift 5.1 or later
Linux
- Swift 5.1 or later
Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies on all platforms.
Once you have your Swift package set up, adding OLEKit
as a dependency is as
easy as adding it to the dependencies
value of your Package.swift
.
dependencies: [
.package(
url: "https://github.com/CoreOffice/OLEKit.git",
.upToNextMinor(from: "0.2.0")
)
]
If you're using OLEKit in an app built with Xcode, you can also add it as a direct dependency using Xcode's GUI.
This project uses SwiftFormat and SwiftLint to enforce formatting and coding style. We encourage you to run SwiftFormat within a local clone of the repository in whatever way works best for you either manually or automatically via an Xcode extension, build phase or git pre-commit hook etc.
To guarantee that these tools run before you commit your changes on macOS, you're encouraged to run this once to set up the pre-commit hook:
brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit
Refer to the pre-commit documentation page for more details and installation instructions for other platforms.
SwiftFormat and SwiftLint also run on CI for every PR and thus a CI build can fail with incosistent formatting or style. We require CI builds to pass for all PRs before merging.
This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to coreoffice@desiatov.com.
OLEKit is licensed under the Apache License, Version 2.0 (the "License"); you may not use this library except in compliance with the License. See the LICENSE file for more info.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
OLEKit is based on the code from the olefile library, which uses FreeBSD-style license, check out LICENSE-olefile for details.