Getting Started with the Packaging API
The Windows 7 Packaging feature is a set of COM-based APIs that provides support for accessing, modifying, and saving packages using C and C++. This topic includes the prerequisites and programming information needed to begin using the APIs.
This topic contains the following sections.
- Prerequisites
- Header and IDL Files
- Accessing the Packaging APIs: Creating a Factory
- Packaging API Support for Previous Versions of Windows
- Packaging API Programming Notes
- Additional Resources
- Disclaimer
- Related topics
Prerequisites
For a table of prerequisites, see Packaging.
Header and IDL Files
The Packaging APIs are defined in the following header and IDL files:
| File | Description |
|---|---|
| msopc.h | Header that defines C and C++ versions of the primary Packaging interfaces and errors. |
| msopc.idl | IDL that defines the primary Packaging interfaces. |
Accessing the Packaging APIs: Creating a Factory
Windows 7 provides a factory implementation of the IOpcFactory interface, which you instantiate by calling the CoCreateInstance function. Through this factory, the IOpcFactory interface provides a portal to other Packaging interfaces and objects.
To get started with the Packaging APIs, create a Packaging factory instance, as shown in the following code.
IOpcFactory * factory = NULL;
// Create a new factory.
HRESULT hr = CoCreateInstance(
__uuidof(OpcFactory),
NULL,
CLSCTX_INPROC_SERVER,
__uuidof(IOpcFactory),
(LPVOID*)&factory
);
| C++ |
|---|
|
CoCreateInstance, which is used to create a Packaging factory, must be called on a thread that is bound to a COM apartment. If the factory is created in a multithreaded apartment, you must synchronize access to Packaging objects.
Once created, the factory is not tied to any particular package and can be used as long as an application is running; however, you must release the factory by calling the interface's Release method before calling the CoUninitialize function and exiting the application.
Packaging API Support for Previous Versions of Windows
The Platform Update for Windows Vista is a set of run-time libraries that enables developers to target applications to both Windows 7 and previous versions of Windows. The Platform Update for Windows Vista will be available to all Windows Vista customers through Windows Update. Third-party applications that require Platform Update for Windows Vista can have Windows Update detect whether it is installed; if it is not, Windows Update will download and install it in the background.
The Platform Update for Windows Vista provides the following support for the Packaging API.
- IOpcUri
- IOpcPartUri
- IOpcFactory (only the following methods are supported)
Supported Packaging APIs can be used to create streams over files as well as to create and interact with package-based URI.
The behavior and performance of supported Packaging interfaces and methods are the same on all supported versions of Windows.
If an application attempts to instantiate or call an unsupported Packaging interface or method, the attempt will fail. If the call is to an unsupported IOpcFactory method, the E_NOTIMPL error code will be returned. For more information, see Platform Update for Windows Vista.
Packaging API Programming Notes
COM Programming Notes
When programming with Packaging APIs, remember the following:
The ThreadingModel used by the Packaging APIs is "Both", also known as the mixed-model.
[!Caution]
Packaging objects are not thread-safe; the caller must synchronize access to Packaging objects.The Packaging APIs do not support any form of marshaling across apartments; if the caller attempts to implement marshaling for Packaging interfaces the attempt will fail or cause undefined behavior.
Passing raw pointers to Packaging objects across apartments may lead to undefined behavior.
Multithreading Notes
When programming with Packaging APIs in a multithreaded environment, adhere to the following guidelines:
If a thread and a Packaging object exist in the same apartment, the thread can call the object.
The CoInitializeEx function must be called before a Packaging object is called by a thread.
[!Caution]
The caller must synchronize access to Packaging objects.
If the OPC_CACHE_ON_ACCESS value of the OPC_READ_FLAGS enumeration is used to load a package, the part content of different parts may be read concurrently by using distinct streams from distinct threads. This applies to the content accessed by calling either the IOpcPart::GetContentStream or IOpcRelationshipSet::GetRelationshipsContentStream method. Potential performance improvements that are made possible by concurrent read operations are contingent on the implementation of the data source.
Different packages may be serialized concurrently, by calling IOpcFactory::WritePackageToStream and using distinct package objects and distinct streams.
Packaging objects that represent package components in different packages may be accessed concurrently by distinct threads.
The following operations will result in undefined behavior; errors that occur as a result of these operations may not be recoverable.
- Concurrent attempts to modify the same package.
- Concurrent attempts to read the same Packaging object.
- Any attempt to access a Packaging object while the parent package is being serialized. The serialization operation will not be affected.
- Any attempt to serialize a package while another serialization or deserialization operation on the package is already in progress.
Error Handling Notes
When programming with the Packaging Digital Signature APIs, remember the following:
- Some package signature related errors may not be exposed until the IOpcDigitalSignatureManager::Validate method is called.
- Errors that are introduced into a package signature when the caller is using the IOpcSigningOptions interface to set signature information may not be exposed until IOpcDigitalSignatureManager::Sign is called.
The following Packaging APIs and Packaging objects can still execute or be accessed successfully after an error is encountered.
- Part content streams that have been cached will be accessible.
- If the relationships contained in a Relationships part have been parsed successfully and cached, the IOpcRelationshipSet::GetRelationshipsContentStream method can be called from the IOpcRelationshipSet interface pointer that represents that part. Relationships are cached when they are modified.
Additional Resources
While not required to use the Packaging API, knowledge of the following technologies will advance your understanding of the Packaging API.
| Technology | Description |
|---|---|
| Markup Compatibility requirements in the ECMA-376 OpenXML standard | If your application interacts with packages that comply with different editions of the ECMA-376 OpenXML, 1st Edition, Part 2: Open Packaging Conventions (OPC), familiarity with markup compatibility requirements will be helpful in developing your application. For more information, see 1st edition, Part 5: Markup Compatibility in the ECMA-376 OpenXML (https://go.microsoft.com/fwlink/p/?linkid=123375). |
Disclaimer
Code examples are not intended to be complete and working programs. The code examples that are referenced on this page, for example, do not perform parameter checking, error checking, or error handling. Use these examples as a starting point, then add the code necessary to create a robust application. For more information about error handling in COM, see the Error Handling (COM) topic.