|
Aspose::Words::FileFormatUtil Class Reference
Provides utility methods for working with file formats, such as detecting file format or converting file extensions to/from file format enums.
- Examples
Shows how to detect encoding in an html file.
SharedPtr<FileFormatInfo> info = FileFormatUtil::DetectFileFormat(MyDir + u"Document.html");
ASSERT_EQ(LoadFormat::Html, info->get_LoadFormat());
// The Encoding property is used only when we create a FileFormatInfo object for an html document.
ASSERT_EQ(u"Windows-1252", info->get_Encoding()->get_WebName());
ASSERT_EQ(1252, info->get_Encoding()->get_CodePage());
#include <Aspose.Words.Cpp/FileFormatUtil.h>
Public Member Functions | |
| FileFormatUtil () | |
Static Public Member Functions | |
| static LoadFormat | ContentTypeToLoadFormat (String contentType) |
| Converts IANA content type into a load format enumerated value. More... | |
| static SaveFormat | ContentTypeToSaveFormat (String contentType) |
| Converts IANA content type into a save format enumerated value. More... | |
| static SharedPtr< FileFormatInfo > | DetectFileFormat (SharedPtr< Stream > stream) |
| Detects and returns the information about a format of a document stored in a stream. More... | |
| static SharedPtr< FileFormatInfo > | DetectFileFormat (String fileName) |
| Detects and returns the information about a format of a document stored in a disk file. More... | |
| static SaveFormat | ExtensionToSaveFormat (String extension) |
| Converts a file name extension into a SaveFormat value. More... | |
| static String | ImageTypeToExtension (ImageType imageType) |
| Converts an Aspose.Words image type enumerated value into a file extension. The returned extension is a lower-case string with a leading dot. More... | |
| static String | LoadFormatToExtension (LoadFormat loadFormat) |
| Converts a load format enumerated value into a file extension. The returned extension is a lower-case string with a leading dot. More... | |
| static SaveFormat | LoadFormatToSaveFormat (LoadFormat loadFormat) |
| Converts a LoadFormat value to a SaveFormat value if possible. More... | |
| static String | SaveFormatToExtension (SaveFormat saveFormat) |
| Converts a save format enumerated value into a file extension. The returned extension is a lower-case string with a leading dot. More... | |
| static LoadFormat | SaveFormatToLoadFormat (SaveFormat saveFormat) |
| Converts a SaveFormat value to a LoadFormat value if possible. More... | |
Constructor & Destructor Documentation
◆ FileFormatUtil()
| Aspose::Words::FileFormatUtil::FileFormatUtil | ( | ) |
Member Function Documentation
◆ ContentTypeToLoadFormat()
|
static |
Converts IANA content type into a load format enumerated value.
- Exceptions
-
System::ArgumentException Throws when cannot convert.
- Examples
Shows how to find the corresponding Aspose load/save format from each media type string.
// The ContentTypeToSaveFormat/ContentTypeToLoadFormat methods only accept official IANA media type names, also known as MIME types.
// All valid media types are listed here: https://www.iana.org/assignments/media-types/media-types.xhtml.
// Trying to associate a SaveFormat with a partial media type string will not work.
// If Aspose.Words does not have a corresponding save/load format for a content type, an exception will also be thrown.
ASSERT_THROW(FileFormatUtil::ContentTypeToSaveFormat(u"application/zip"), System::ArgumentException);
// Files of the types listed below can be saved, but not loaded using Aspose.Words.
ASSERT_EQ(SaveFormat::Xps, FileFormatUtil::ContentTypeToSaveFormat(u"application/vnd.ms-xpsdocument"));
// For file types that can be saved and loaded, we can match a media type to both a load format and a save format.
ASSERT_EQ(LoadFormat::Docx, FileFormatUtil::ContentTypeToLoadFormat(u"application/vnd.openxmlformats-officedocument.wordprocessingml.document"));
ASSERT_EQ(SaveFormat::Docx, FileFormatUtil::ContentTypeToSaveFormat(u"application/vnd.openxmlformats-officedocument.wordprocessingml.document"));
◆ ContentTypeToSaveFormat()
|
static |
Converts IANA content type into a save format enumerated value.
- Exceptions
-
System::ArgumentException Throws when cannot convert.
- Examples
Shows how to find the corresponding Aspose load/save format from each media type string.
// The ContentTypeToSaveFormat/ContentTypeToLoadFormat methods only accept official IANA media type names, also known as MIME types.
// All valid media types are listed here: https://www.iana.org/assignments/media-types/media-types.xhtml.
// Trying to associate a SaveFormat with a partial media type string will not work.
// If Aspose.Words does not have a corresponding save/load format for a content type, an exception will also be thrown.
ASSERT_THROW(FileFormatUtil::ContentTypeToSaveFormat(u"application/zip"), System::ArgumentException);
// Files of the types listed below can be saved, but not loaded using Aspose.Words.
ASSERT_EQ(SaveFormat::Xps, FileFormatUtil::ContentTypeToSaveFormat(u"application/vnd.ms-xpsdocument"));
// For file types that can be saved and loaded, we can match a media type to both a load format and a save format.
ASSERT_EQ(LoadFormat::Docx, FileFormatUtil::ContentTypeToLoadFormat(u"application/vnd.openxmlformats-officedocument.wordprocessingml.document"));
ASSERT_EQ(SaveFormat::Docx, FileFormatUtil::ContentTypeToSaveFormat(u"application/vnd.openxmlformats-officedocument.wordprocessingml.document"));
◆ DetectFileFormat() [1/2]
|
static |
Detects and returns the information about a format of a document stored in a stream.
The stream must be positioned at the beginning of the document.
When this method returns, the position in the stream is restored to the original position.
Even if this method detects the document format, it does not guarantee that the specified document is valid. This method only detects the document format by reading data that is sufficient for detection. To fully verify that a document is valid you need to load the document into a Document object.
This method throws FileCorruptedException when the format is recognized, but the detection cannot complete because of corruption.
- Parameters
-
stream The stream.
- Returns
- A FileFormatInfo object that contains the detected information.
- Examples
Shows how to use the FileFormatUtil methods to detect the format of a document.
// Load a document from a file that is missing a file extension, and then detect its file format.
{
SharedPtr<System::IO::FileStream> docStream = System::IO::File::OpenRead(MyDir + u"Word document with missing file extension");
SharedPtr<FileFormatInfo> info = FileFormatUtil::DetectFileFormat(docStream);
LoadFormat loadFormat = info->get_LoadFormat();
ASSERT_EQ(LoadFormat::Doc, loadFormat);
// Below are two methods of converting a LoadFormat to its corresponding SaveFormat.
// 1 - Get the file extension string for the LoadFormat, then get the corresponding SaveFormat from that string:
String fileExtension = FileFormatUtil::LoadFormatToExtension(loadFormat);
SaveFormat saveFormat = FileFormatUtil::ExtensionToSaveFormat(fileExtension);
// 2 - Convert the LoadFormat directly to its SaveFormat:
saveFormat = FileFormatUtil::LoadFormatToSaveFormat(loadFormat);
// Load a document from the stream, and then save it to the automatically detected file extension.
auto doc = MakeObject<Document>(docStream);
ASSERT_EQ(u".doc", FileFormatUtil::SaveFormatToExtension(saveFormat));
doc->Save(ArtifactsDir + u"File.SaveToDetectedFileFormat" + FileFormatUtil::SaveFormatToExtension(saveFormat));
}
◆ DetectFileFormat() [2/2]
|
static |
Detects and returns the information about a format of a document stored in a disk file.
Even if this method detects the document format, it does not guarantee that the specified document is valid. This method only detects the document format by reading data that is sufficient for detection. To fully verify that a document is valid you need to load the document into a Document object.
This method throws FileCorruptedException when the format is recognized, but the detection cannot complete because of corruption.
- Parameters
-
fileName The file name.
- Returns
- A FileFormatInfo object that contains the detected information.
- Examples
Shows how to use the FileFormatUtil class to detect the document format and encryption.
auto doc = MakeObject<Document>();
// Configure a SaveOptions object to encrypt the document
// with a password when we save it, and then save the document.
auto saveOptions = MakeObject<OdtSaveOptions>(SaveFormat::Odt);
saveOptions->set_Password(u"MyPassword");
doc->Save(ArtifactsDir + u"File.DetectDocumentEncryption.odt", saveOptions);
// Verify the file type of our document, and its encryption status.
SharedPtr<FileFormatInfo> info = FileFormatUtil::DetectFileFormat(ArtifactsDir + u"File.DetectDocumentEncryption.odt");
ASSERT_EQ(u".odt", FileFormatUtil::LoadFormatToExtension(info->get_LoadFormat()));
ASSERT_TRUE(info->get_IsEncrypted());
Shows how to use the FileFormatUtil class to detect the document format and presence of digital signatures.
// Use a FileFormatInfo instance to verify that a document is not digitally signed.
SharedPtr<FileFormatInfo> info = FileFormatUtil::DetectFileFormat(MyDir + u"Document.docx");
ASSERT_EQ(u".docx", FileFormatUtil::LoadFormatToExtension(info->get_LoadFormat()));
ASSERT_FALSE(info->get_HasDigitalSignature());
SharedPtr<CertificateHolder> certificateHolder = CertificateHolder::Create(MyDir + u"morzal.pfx", u"aw", nullptr);
auto signOptions = MakeObject<SignOptions>();
signOptions->set_SignTime(System::DateTime::get_Now());
DigitalSignatureUtil::Sign(MyDir + u"Document.docx", ArtifactsDir + u"File.DetectDigitalSignatures.docx", certificateHolder, signOptions);
// Use a new FileFormatInstance to confirm that it is signed.
info = FileFormatUtil::DetectFileFormat(ArtifactsDir + u"File.DetectDigitalSignatures.docx");
ASSERT_TRUE(info->get_HasDigitalSignature());
// We can load and access the signatures of a signed document in a collection like this.
ASSERT_EQ(1, DigitalSignatureUtil::LoadSignatures(ArtifactsDir + u"File.DetectDigitalSignatures.docx")->get_Count());
◆ ExtensionToSaveFormat()
|
static |
Converts a file name extension into a SaveFormat value.
If the extension cannot be recognized, returns Unknown.
- Parameters
-
extension The file extension. Can be with or without a leading dot. Case-insensitive.
- Exceptions
-
System::ArgumentNullException Throws if the parameter is null.
- Examples
Shows how to use the FileFormatUtil methods to detect the format of a document.
// Load a document from a file that is missing a file extension, and then detect its file format.
{
SharedPtr<System::IO::FileStream> docStream = System::IO::File::OpenRead(MyDir + u"Word document with missing file extension");
SharedPtr<FileFormatInfo> info = FileFormatUtil::DetectFileFormat(docStream);
LoadFormat loadFormat = info->get_LoadFormat();
ASSERT_EQ(LoadFormat::Doc, loadFormat);
// Below are two methods of converting a LoadFormat to its corresponding SaveFormat.
// 1 - Get the file extension string for the LoadFormat, then get the corresponding SaveFormat from that string:
String fileExtension = FileFormatUtil::LoadFormatToExtension(loadFormat);
SaveFormat saveFormat = FileFormatUtil::ExtensionToSaveFormat(fileExtension);
// 2 - Convert the LoadFormat directly to its SaveFormat:
saveFormat = FileFormatUtil::LoadFormatToSaveFormat(loadFormat);
// Load a document from the stream, and then save it to the automatically detected file extension.
auto doc = MakeObject<Document>(docStream);
ASSERT_EQ(u".doc", FileFormatUtil::SaveFormatToExtension(saveFormat));
doc->Save(ArtifactsDir + u"File.SaveToDetectedFileFormat" + FileFormatUtil::SaveFormatToExtension(saveFormat));
}
◆ ImageTypeToExtension()
|
static |
Converts an Aspose.Words image type enumerated value into a file extension. The returned extension is a lower-case string with a leading dot.
- Exceptions
-
System::ArgumentException Throws when cannot convert.
- Examples
Shows how to extract images from a document, and save them to the local file system as individual files.
auto doc = MakeObject<Document>(MyDir + u"Images.docx");
// Get the collection of shapes from the document,
// and save the image data of every shape with an image as a file to the local file system.
SharedPtr<NodeCollection> shapes = doc->GetChildNodes(NodeType::Shape, true);
ASSERT_EQ(9, shapes->LINQ_Count([](SharedPtr<Node> s) { return (System::DynamicCast<Shape>(s))->get_HasImage(); }));
int imageIndex = 0;
for (const auto& shape : System::IterateOver(shapes->LINQ_OfType<SharedPtr<Shape>>()))
{
if (shape->get_HasImage())
{
// The image data of shapes may contain images of many possible image formats.
// We can determine a file extension for each image automatically, based on its format.
String imageFileName =
String::Format(u"File.ExtractImages.{0}{1}", imageIndex, FileFormatUtil::ImageTypeToExtension(shape->get_ImageData()->get_ImageType()));
shape->get_ImageData()->Save(ArtifactsDir + imageFileName);
imageIndex++;
}
}
◆ LoadFormatToExtension()
|
static |
Converts a load format enumerated value into a file extension. The returned extension is a lower-case string with a leading dot.
The WordML value is converted to ".wml".
- Exceptions
-
System::ArgumentException Throws when cannot convert.
- Examples
Shows how to use the FileFormatUtil methods to detect the format of a document.
// Load a document from a file that is missing a file extension, and then detect its file format.
{
SharedPtr<System::IO::FileStream> docStream = System::IO::File::OpenRead(MyDir + u"Word document with missing file extension");
SharedPtr<FileFormatInfo> info = FileFormatUtil::DetectFileFormat(docStream);
LoadFormat loadFormat = info->get_LoadFormat();
ASSERT_EQ(LoadFormat::Doc, loadFormat);
// Below are two methods of converting a LoadFormat to its corresponding SaveFormat.
// 1 - Get the file extension string for the LoadFormat, then get the corresponding SaveFormat from that string:
String fileExtension = FileFormatUtil::LoadFormatToExtension(loadFormat);
SaveFormat saveFormat = FileFormatUtil::ExtensionToSaveFormat(fileExtension);
// 2 - Convert the LoadFormat directly to its SaveFormat:
saveFormat = FileFormatUtil::LoadFormatToSaveFormat(loadFormat);
// Load a document from the stream, and then save it to the automatically detected file extension.
auto doc = MakeObject<Document>(docStream);
ASSERT_EQ(u".doc", FileFormatUtil::SaveFormatToExtension(saveFormat));
doc->Save(ArtifactsDir + u"File.SaveToDetectedFileFormat" + FileFormatUtil::SaveFormatToExtension(saveFormat));
}
◆ LoadFormatToSaveFormat()
|
static |
Converts a LoadFormat value to a SaveFormat value if possible.
- Exceptions
-
System::ArgumentException Throws when cannot convert.
- Examples
Shows how to use the FileFormatUtil methods to detect the format of a document.
// Load a document from a file that is missing a file extension, and then detect its file format.
{
SharedPtr<System::IO::FileStream> docStream = System::IO::File::OpenRead(MyDir + u"Word document with missing file extension");
SharedPtr<FileFormatInfo> info = FileFormatUtil::DetectFileFormat(docStream);
LoadFormat loadFormat = info->get_LoadFormat();
ASSERT_EQ(LoadFormat::Doc, loadFormat);
// Below are two methods of converting a LoadFormat to its corresponding SaveFormat.
// 1 - Get the file extension string for the LoadFormat, then get the corresponding SaveFormat from that string:
String fileExtension = FileFormatUtil::LoadFormatToExtension(loadFormat);
SaveFormat saveFormat = FileFormatUtil::ExtensionToSaveFormat(fileExtension);
// 2 - Convert the LoadFormat directly to its SaveFormat:
saveFormat = FileFormatUtil::LoadFormatToSaveFormat(loadFormat);
// Load a document from the stream, and then save it to the automatically detected file extension.
auto doc = MakeObject<Document>(docStream);
ASSERT_EQ(u".doc", FileFormatUtil::SaveFormatToExtension(saveFormat));
doc->Save(ArtifactsDir + u"File.SaveToDetectedFileFormat" + FileFormatUtil::SaveFormatToExtension(saveFormat));
}
◆ SaveFormatToExtension()
|
static |
Converts a save format enumerated value into a file extension. The returned extension is a lower-case string with a leading dot.
The WordML value is converted to ".wml".
The FlatOpc value is converted to ".fopc".
- Exceptions
-
System::ArgumentException Throws when cannot convert.
- Examples
Shows how to use the FileFormatUtil methods to detect the format of a document.
// Load a document from a file that is missing a file extension, and then detect its file format.
{
SharedPtr<System::IO::FileStream> docStream = System::IO::File::OpenRead(MyDir + u"Word document with missing file extension");
SharedPtr<FileFormatInfo> info = FileFormatUtil::DetectFileFormat(docStream);
LoadFormat loadFormat = info->get_LoadFormat();
ASSERT_EQ(LoadFormat::Doc, loadFormat);
// Below are two methods of converting a LoadFormat to its corresponding SaveFormat.
// 1 - Get the file extension string for the LoadFormat, then get the corresponding SaveFormat from that string:
String fileExtension = FileFormatUtil::LoadFormatToExtension(loadFormat);
SaveFormat saveFormat = FileFormatUtil::ExtensionToSaveFormat(fileExtension);
// 2 - Convert the LoadFormat directly to its SaveFormat:
saveFormat = FileFormatUtil::LoadFormatToSaveFormat(loadFormat);
// Load a document from the stream, and then save it to the automatically detected file extension.
auto doc = MakeObject<Document>(docStream);
ASSERT_EQ(u".doc", FileFormatUtil::SaveFormatToExtension(saveFormat));
doc->Save(ArtifactsDir + u"File.SaveToDetectedFileFormat" + FileFormatUtil::SaveFormatToExtension(saveFormat));
}
◆ SaveFormatToLoadFormat()
|
static |
Converts a SaveFormat value to a LoadFormat value if possible.
- Exceptions
-
System::ArgumentException Throws when cannot convert.
- Examples
Shows how to convert a save format to its corresponding load format.
// Some file types can have documents saved to, but not loaded from using Aspose.Words.
// If we attempt to convert a save format of such a type to a load format, an exception will be thrown.