OpenMcdf
OpenMCDF base exception.
Raised when a data setter/getter method is invoked
on a stream or storage object after the disposal of the owner
compound file object.
Raised when opening a file with invalid header
or not supported COM/OLE Structured storage version.
Raised when a named stream or a storage object
are not found in a parent storage.
Raised when a method call is invalid for the current object state
Raised when trying to add a duplicated CFItem
Items are compared by name as indicated by specs.
Two items with the same name CANNOT be added within
the same storage or sub-storage.
Raised when trying to load a Compound File with invalid, corrupted or mismatched fields (4.1 - specifications)
This exception is NOT raised when Compound file has been opened with NO_VALIDATION_EXCEPTION option.
Abstract base class for Structured Storage entities.
const String STORAGE_NAME = "report.xls";
CompoundFile cf = new CompoundFile(STORAGE_NAME);
FileStream output = new FileStream("LogEntries.txt", FileMode.Create);
TextWriter tw = new StreamWriter(output);
// CFItem represents both storage and stream items
VisitedEntryAction va = delegate(CFItem item)
{
tw.WriteLine(item.Name);
};
cf.RootStorage.VisitEntries(va, true);
tw.Close();
Get entity name
Size in bytes of the item. It has a valid value
only if entity is a stream, otherwise it is setted to zero.
Return true if item is Storage
This check doesn't use reflection or runtime type information
and doesn't suffer related performance penalties.
Return true if item is a Stream
This check doesn't use reflection or runtime type information
and doesn't suffer related performance penalties.
Return true if item is the Root Storage
This check doesn't use reflection or runtime type information
and doesn't suffer related performance penalties.
Get/Set the Creation Date of the current item
Get/Set the Modify Date of the current item
Get/Set Object class Guid for Root and Storage entries.
Action to apply to visited items in the OLE structured storage
Currently visited item
//We assume that xls file should be a valid OLE compound file
const String STORAGE_NAME = "report.xls";
CompoundFile cf = new CompoundFile(STORAGE_NAME);
FileStream output = new FileStream("LogEntries.txt", FileMode.Create);
TextWriter tw = new StreamWriter(output);
VisitedEntryAction va = delegate(CFItem item)
{
tw.WriteLine(item.Name);
};
cf.RootStorage.VisitEntries(va, true);
tw.Close();
Storage entity that acts like a logic container for streams
or substorages in a compound file.
Create a CFStorage using an existing directory (previously loaded).
The Storage Owner - CompoundFile
An existing Directory Entry
Create a new child stream inside the current storage
The new stream name
The new stream reference
Raised when adding an item with the same name of an existing one
Raised when adding a stream to a closed compound file
Raised when adding a stream with null or empty name
String filename = "A_NEW_COMPOUND_FILE_YOU_CAN_WRITE_TO.cfs";
CompoundFile cf = new CompoundFile();
CFStorage st = cf.RootStorage.AddStorage("MyStorage");
CFStream sm = st.AddStream("MyStream");
byte[] b = Helpers.GetBuffer(220, 0x0A);
sm.SetData(b);
cf.Save(filename);
Get a named stream contained in the current storage if existing.
Name of the stream to look for
A stream reference if existing
Raised if trying to delete item from a closed compound file
Raised if item to delete is not found
String filename = "report.xls";
CompoundFile cf = new CompoundFile(filename);
CFStream foundStream = cf.RootStorage.GetStream("Workbook");
byte[] temp = foundStream.GetData();
Assert.IsNotNull(temp);
cf.Close();
Get a named stream contained in the current storage if existing.
Name of the stream to look for
A stream reference if found, else null
Raised if trying to delete item from a closed compound file
String filename = "report.xls";
CompoundFile cf = new CompoundFile(filename);
CFStream foundStream = cf.RootStorage.TryGetStream("Workbook");
byte[] temp = foundStream.GetData();
Assert.IsNotNull(temp);
cf.Close();
Get a named storage contained in the current one if existing.
Name of the storage to look for
A storage reference if existing.
Raised if trying to delete item from a closed compound file
Raised if item to delete is not found
String FILENAME = "MultipleStorage2.cfs";
CompoundFile cf = new CompoundFile(FILENAME, UpdateMode.ReadOnly, false, false);
CFStorage st = cf.RootStorage.GetStorage("MyStorage");
Assert.IsNotNull(st);
cf.Close();
Get a named storage contained in the current one if existing.
Name of the storage to look for
A storage reference if found else null
Raised if trying to delete item from a closed compound file
String FILENAME = "MultipleStorage2.cfs";
CompoundFile cf = new CompoundFile(FILENAME, UpdateMode.ReadOnly, false, false);
CFStorage st = cf.RootStorage.TryGetStorage("MyStorage");
Assert.IsNotNull(st);
cf.Close();
Create new child storage directory inside the current storage.
The new storage name
Reference to the new storage
Raised when adding an item with the same name of an existing one
Raised when adding a storage to a closed compound file
Raised when adding a storage with null or empty name
String filename = "A_NEW_COMPOUND_FILE_YOU_CAN_WRITE_TO.cfs";
CompoundFile cf = new CompoundFile();
CFStorage st = cf.RootStorage.AddStorage("MyStorage");
CFStream sm = st.AddStream("MyStream");
byte[] b = Helpers.GetBuffer(220, 0x0A);
sm.SetData(b);
cf.Save(filename);
Visit all entities contained in the storage applying a user provided action
Raised when visiting items of a closed compound file
User action to apply to visited entities
Visiting recursion level. True means substorages are visited recursively, false indicates that only the direct children of this storage are visited
const String STORAGE_NAME = "report.xls";
CompoundFile cf = new CompoundFile(STORAGE_NAME);
FileStream output = new FileStream("LogEntries.txt", FileMode.Create);
TextWriter tw = new StreamWriter(output);
VisitedEntryAction va = delegate(CFItem item)
{
tw.WriteLine(item.Name);
};
cf.RootStorage.VisitEntries(va, true);
tw.Close();
Remove an entry from the current storage and compound file.
The name of the entry in the current storage to delete
cf = new CompoundFile("A_FILE_YOU_CAN_CHANGE.cfs", UpdateMode.Update, true, false);
cf.RootStorage.Delete("AStream"); // AStream item is assumed to exist.
cf.Commit(true);
cf.Close();
Raised if trying to delete item from a closed compound file
Raised if item to delete is not found
Raised if trying to delete root storage
FNV hash, short for Fowler/Noll/Vo
(not warranted) unique hash for byte array
This integer field contains the starting sector number for the mini FAT
Structured Storage signature
OLE structured storage stream Object
It is contained inside a Storage object in a file-directory
relationship and indexed by its name.
Set the data associated with the stream object.
byte[] b = new byte[]{0x0,0x1,0x2,0x3};
CompoundFile cf = new CompoundFile();
CFStream myStream = cf.RootStorage.AddStream("MyStream");
myStream.SetData(b);
Data bytes to write to this stream
Existing associated data will be lost after method invocation
Write a data buffer to a specific position into current CFStream object
Data buffer to Write
Position into the stream object to start writing from
Current stream will be extended to receive data buffer over
its current size
Write count bytes of a data buffer to a specific position into
the current CFStream object starting from the specified position.
Data buffer to copy bytes from
Position into the stream object to start writing from
The zero-based byte offset in buffer at which to
begin copying bytes to the current CFStream.
The number of bytes to be written to the current CFStream
Current stream will be extended to receive data buffer over
its current size.
Append the provided data to stream data.
byte[] b = new byte[]{0x0,0x1,0x2,0x3};
byte[] b2 = new byte[]{0x4,0x5,0x6,0x7};
CompoundFile cf = new CompoundFile();
CFStream myStream = cf.RootStorage.AddStream("MyStream");
myStream.SetData(b); // here we could also have invoked .AppendData
myStream.AppendData(b2);
cf.Save("MyLargeStreamsFile.cfs);
cf.Close();
Data bytes to append to this stream
This method allows user to create stream with more than 2GB of data,
appending data to the end of existing ones.
Large streams (>2GB) are only supported by CFS version 4.
Append data can also be invoked on streams with no data in order
to simplify its use inside loops.
Get all the data associated with the stream object.
CompoundFile cf2 = new CompoundFile("AFileName.cfs");
CFStream st = cf2.RootStorage.GetStream("MyStream");
byte[] buffer = st.ReadAll();
Array of byte containing stream data
Raised when the owner compound file has been closed.
Copy data from an existing stream.
A stream to read from
Input stream will NOT be closed after method invocation.
Existing associated data will be deleted.
Resize stream padding with zero if enlarging, trimming data if reducing size.
New length to assign to this stream
Action to implement when transaction support - sector
has to be written to the underlying stream (see specs).
Ad-hoc Heap Friendly sector collection to avoid using
large array that may create some problem to GC collection
(see http://www.simple-talk.com/dotnet/.net-framework/the-dangers-of-the-large-object-heap/ )
Configuration parameters for the compund files.
They can be OR-combined to configure
Compound file behaviour.
All flags are NOT set by Default.
Sector Recycling turn off,
free sectors erasing off,
format validation exception raised
Sector recycling reduces data writing performances
but avoids space wasting in scenarios with frequently
data manipulation of the same streams.
Free sectors are erased to avoid information leakage
No exception is raised when a validation error occurs.
This can possibly lead to a security issue but gives
a chance to corrupted files to load.
If this flag is set true,
backing stream is kept open after CompoundFile disposal
Binary File Format Version. Sector size is 512 byte for version 3,
4096 for version 4
Compound file version 3 - The default and most common version available. Sector size 512 bytes, 2GB max file size.
Compound file version 4 - Sector size is 4096 bytes. Using this version could bring some compatibility problem with existing applications.
Update mode of the compound file.
Default is ReadOnly.
ReadOnly update mode prevents overwriting
of the opened file.
Data changes are allowed but they have to be
persisted on a different file when required
using method
Update mode allows subsequent data changing operations
to be persisted directly on the opened file or stream
using the Commit
method when required. Warning: this option may cause existing data loss if misused.
Standard Microsoft© Compound File implementation.
It is also known as OLE/COM structured storage
and contains a hierarchy of storage and stream objects providing
efficent storage of multiple kinds of documents in a single file.
Version 3 and 4 of specifications are supported.
Get the configuration parameters of the CompoundFile object.
Returns the size of standard sectors switching on CFS version (3 or 4)
Standard sector size
Number of DIFAT entries in the header
Number of FAT entries in a DIFAT Sector
Sectors ID entries in a FAT Sector
Sector ID Size (int)
Flag for sector recycling.
Flag for unallocated sector zeroing out.
Initial capacity of the flushing queue used
to optimize commit writing operations
Maximum size of the flushing buffer used
to optimize commit writing operations
CompoundFile header
Compound underlying stream. Null when new CF has been created.
Create a blank, version 3 compound file.
Sector recycle is turned off to achieve the best reading/writing
performance in most common scenarios.
byte[] b = new byte[10000];
for (int i = 0; i < 10000; i++)
{
b[i % 120] = (byte)i;
}
CompoundFile cf = new CompoundFile();
CFStream myStream = cf.RootStorage.AddStream("MyStream");
Assert.IsNotNull(myStream);
myStream.SetData(b);
cf.Save("MyCompoundFile.cfs");
cf.Close();
Create a new, blank, compound file.
Use a specific Compound File Version to set 512 or 4096 bytes sectors
Set configuration parameters for the new compound file
byte[] b = new byte[10000];
for (int i = 0; i < 10000; i++)
{
b[i % 120] = (byte)i;
}
CompoundFile cf = new CompoundFile(CFSVersion.Ver_4, CFSConfiguration.Default);
CFStream myStream = cf.RootStorage.AddStream("MyStream");
Assert.IsNotNull(myStream);
myStream.SetData(b);
cf.Save("MyCompoundFile.cfs");
cf.Close();
Load an existing compound file.
Compound file to read from
//A xls file should have a Workbook stream
String filename = "report.xls";
CompoundFile cf = new CompoundFile(filename);
CFStream foundStream = cf.RootStorage.GetStream("Workbook");
byte[] temp = foundStream.GetData();
Assert.IsNotNull(temp);
cf.Close();
File will be open in read-only mode: it has to be saved
with a different filename. A wrapping implementation has to be provided
in order to remove/substitute an existing file. Version will be
automatically recognized from the file. Sector recycle is turned off
to achieve the best reading/writing performance in most common scenarios.
Load an existing compound file.
Compound file to read from
If true, recycle unused sectors
Select the update mode of the underlying data file
If true, overwrite with zeros unallocated sectors
String srcFilename = "data_YOU_CAN_CHANGE.xls";
CompoundFile cf = new CompoundFile(srcFilename, UpdateMode.Update, true, true);
Random r = new Random();
byte[] buffer = GetBuffer(r.Next(3, 4095), 0x0A);
cf.RootStorage.AddStream("MyStream").SetData(buffer);
//This will persist data to the underlying media.
cf.Commit();
cf.Close();
Load an existing compound file.
A stream containing a compound file to read
If true, recycle unused sectors
Select the update mode of the underlying data file
If true, overwrite with zeros unallocated sectors
String filename = "reportREAD.xls";
FileStream fs = new FileStream(filename, FileMode.Open);
CompoundFile cf = new CompoundFile(fs, UpdateMode.ReadOnly, false, false);
CFStream foundStream = cf.RootStorage.GetStream("Workbook");
byte[] temp = foundStream.GetData();
Assert.IsNotNull(temp);
cf.Close();
Raised when trying to open a non-seekable stream
Raised stream is null
Load an existing compound file from a stream.
Streamed compound file
String filename = "reportREAD.xls";
FileStream fs = new FileStream(filename, FileMode.Open);
CompoundFile cf = new CompoundFile(fs);
CFStream foundStream = cf.RootStorage.GetStream("Workbook");
byte[] temp = foundStream.GetData();
Assert.IsNotNull(temp);
cf.Close();
Raised when trying to open a non-seekable stream
Raised stream is null
Commit data changes since the previously commit operation
to the underlying supporting stream or file on the disk.
This method can be used
only if the supporting stream has been opened in
Update mode.
Commit data changes since the previously commit operation
to the underlying supporting stream or file on the disk.
If true, release loaded sectors to limit memory usage but reduces following read operations performance
This method can be used only if
the supporting stream has been opened in
Update mode.
Load compound file from an existing stream.
Stream to load compound file from
Return true if this compound file has been
loaded from an existing file or stream
Allocate space, setup sectors id and refresh header
for the new or updated mini sector chain.
The new MINI sector chain
Allocate space, setup sectors id in the FAT and refresh header
for the new or updated sector chain (Normal or Mini sectors)
The new or updated normal or mini sector chain
Allocate space, setup sectors id and refresh header
for the new or updated sector chain.
The new or updated generic sector chain
Check for transaction lock sector addition and mark it in the FAT.
Allocate space, setup sectors id and refresh header
for the new or updated FAT sector chain.
The new or updated generic sector chain
Setup the DIFAT sector chain
A FAT sector chain
Get the DIFAT Sector chain
A list of DIFAT sectors
Get the FAT sector chain
List of FAT sectors
Get a standard sector chain
First SecID of the required chain
A list of sectors
Get a mini sector chain
First SecID of the required chain
A list of mini sectors (64 bytes)
Get a sector chain from a compound file given the first sector ID
and the required sector type.
First chain sector's id
Type of Sectors in the required chain (mini sectors, normal sectors or FAT)
A list of Sectors as the result of their concatenation
The entry point object that represents the
root of the structures tree to get or set storage or
stream data.
//Create a compound file
string FILENAME = "MyFileName.cfs";
CompoundFile ncf = new CompoundFile();
CFStorage l1 = ncf.RootStorage.AddStorage("Storage Level 1");
l1.AddStream("l1ns1");
l1.AddStream("l1ns2");
l1.AddStream("l1ns3");
CFStorage l2 = l1.AddStorage("Storage Level 2");
l2.AddStream("l2ns1");
l2.AddStream("l2ns2");
ncf.Save(FILENAME);
ncf.Close();
Reset a directory entry setting it to StgInvalid in the Directory.
Sid of the directory to invalidate
Load directory entries from compound file. Header and FAT MUST be already loaded.
Commit directory entries change on the Current Source stream
Saves the in-memory image of Compound File to a file.
File name to write the compound file to
Raised if destination file is not seekable
Saves the in-memory image of Compound File to a stream.
Destination Stream must be seekable. Uncommitted data will be persisted to the destination stream.
The stream to save compound File to
Raised if destination stream is not seekable
Raised if Compound File Storage has been already disposed
MemoryStream ms = new MemoryStream(size);
CompoundFile cf = new CompoundFile();
CFStorage st = cf.RootStorage.AddStorage("MyStorage");
CFStream sm = st.AddStream("MyStream");
byte[] b = new byte[]{0x00,0x01,0x02,0x03};
sm.SetData(b);
cf.Save(ms);
cf.Close();
Scan FAT o miniFAT for free sectors to reuse.
Type of sector to look for
A Queue of available sectors or minisectors already allocated
Resize stream length
Check file size limit ( 2GB for version 3 )
Close the Compound File object CompoundFile and
free all associated resources (e.g. open file handle and allocated memory).
When the Close method is called,
all the associated stream and storage objects are invalidated:
any operation invoked on them will produce a CFDisposedException.
const String FILENAME = "CompoundFile.cfs";
CompoundFile cf = new CompoundFile(FILENAME);
CFStorage st = cf.RootStorage.GetStorage("MyStorage");
cf.Close();
try
{
byte[] temp = st.GetStream("MyStream").GetData();
// The following line will fail because back-end object has been closed
Assert.Fail("Stream without media");
}
catch (Exception ex)
{
Assert.IsTrue(ex is CFDisposedException);
}
When called from user code, release all resources, otherwise, in the case runtime called it,
only unmanagd resources are released.
If true, method has been called from User code, if false it's been called from .net runtime
Get a list of all entries with a given name contained in the document.
Name of entries to retrive
A list of name-matching entries
This function is aimed to speed up entity lookup in
flat-structure files (only one or little more known entries)
without the performance penalty related to entities hierarchy constraints.
There is no implied hierarchy in the returned list.
Compress free space by removing unallocated sectors from compound file
effectively reducing stream or file size.
Current implementation supports compression only for ver. 3 compound files.
//This code has been extracted from unit test
String FILENAME = "MultipleStorage3.cfs";
FileInfo srcFile = new FileInfo(FILENAME);
File.Copy(FILENAME, "MultipleStorage_Deleted_Compress.cfs", true);
CompoundFile cf = new CompoundFile("MultipleStorage_Deleted_Compress.cfs", UpdateMode.Update, true, true);
CFStorage st = cf.RootStorage.GetStorage("MyStorage");
st = st.GetStorage("AnotherStorage");
Assert.IsNotNull(st);
st.Delete("Another2Stream"); //17Kb
cf.Commit();
cf.Close();
CompoundFile.ShrinkCompoundFile("MultipleStorage_Deleted_Compress.cfs");
FileInfo dstFile = new FileInfo("MultipleStorage_Deleted_Compress.cfs");
Assert.IsTrue(srcFile.Length > dstFile.Length);
Remove unallocated sectors from compound file in order to reduce its size.
Current implementation supports compression only for ver. 3 compound files.
//This code has been extracted from unit test
String FILENAME = "MultipleStorage3.cfs";
FileInfo srcFile = new FileInfo(FILENAME);
File.Copy(FILENAME, "MultipleStorage_Deleted_Compress.cfs", true);
CompoundFile cf = new CompoundFile("MultipleStorage_Deleted_Compress.cfs", UpdateMode.Update, true, true);
CFStorage st = cf.RootStorage.GetStorage("MyStorage");
st = st.GetStorage("AnotherStorage");
Assert.IsNotNull(st);
st.Delete("Another2Stream"); //17Kb
cf.Commit();
cf.Close();
CompoundFile.ShrinkCompoundFile("MultipleStorage_Deleted_Compress.cfs");
FileInfo dstFile = new FileInfo("MultipleStorage_Deleted_Compress.cfs");
Assert.IsTrue(srcFile.Length > dstFile.Length);
Recursively clones valid structures, avoiding to copy free sectors.
Current source storage to clone
Current cloned destination storage
When called from user code, release all resources, otherwise, in the case runtime called it,
only unmanagd resources are released.
If true, method has been called from User code, if false it's been called from .net runtime
Stream decorator for a Sector or miniSector chain
Red Black Node interface