How to Save a Package

  • Article

This topic shows how to use Packaging APIs to save a package.

This topic contains the following sections.

Introduction

The code example shows the details of the SavePackage function, which uses Packaging APIs to serialize a package that is represented by a package object.

SavePackage is declared in the opclib.h header file and defined in the opclib.cpp implementation file of the Set Author Sample. For the complete program, which can load, modify and save a package, see the Set Author Sample.

[!Important]
Using the same stream to both deserialize and serialize a package is not recommended and may result in undefined behavior.

 

Saving a Package

The SavePackage function shown in the following sections creates a write-only stream over a new package file and then serializes the package that is represented by a package object. If a stream was used to load package components, that stream may be accessed when package components are serialized.

The SavePackage function declaration from opclib.h:

HRESULT
    SavePackage(
    IOpcFactory *factory,
    IOpcPackage *package,
    LPCWSTR targetFileName
    );

Steps to Save a Package

  1. Define an IStream variable:

        IStream * targetFileStream = NULL;

  2. Create a write-only stream over the package to be saved:

        // Note: Do not use a writable stream to overwrite the data of a package
    // that is read.

    // Create a writable stream over the specified target file name.
    HRESULT hr = factory->CreateStreamOnFile(
                    targetFileName, 
                    OPC_STREAM_IO_WRITE, 
                    NULL, 
                    0, 
                    &targetFileStream
                    );

  3. Serialize the package data using the stream:

        if (SUCCEEDED(hr))
    {
        // After a stream over the specified file is created successfully,
        // write package data to the file.
        hr = factory->WritePackageToStream(
                package, 
                OPC_WRITE_DEFAULT, 
                targetFileStream
                );
    }

    // Release resources
    if (targetFileStream)
    {
        targetFileStream->Release();
        targetFileStream = NULL;
    }

Code Details

The following shows the SavePackage function definition in one convenient block found in opclib.cpp.

The SavePackage function definition:

HRESULT
SavePackage(
    IOpcFactory *factory,
    IOpcPackage *package,
    LPCWSTR targetFileName
    )
{
    IStream * targetFileStream = NULL;
    // Note: Do not use a writable stream to overwrite the data of a package
    // that is read.

    // Create a writable stream over the specified target file name.
    HRESULT hr = factory->CreateStreamOnFile(
                    targetFileName, 
                    OPC_STREAM_IO_WRITE, 
                    NULL, 
                    0, 
                    &targetFileStream
                    );

    if (SUCCEEDED(hr))
    {
        // After a stream over the specified file is created successfully,
        // write package data to the file.
        hr = factory->WritePackageToStream(
                package, 
                OPC_WRITE_DEFAULT, 
                targetFileStream
                );
    }

    // Release resources
    if (targetFileStream)
    {
        targetFileStream->Release();
        targetFileStream = NULL;
    }

    return hr;
}

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.

Packages How-To Topics

Overviews

Getting Started with the Packaging API

Packages Overview

Reference

IOpcFactory

IOpcFactory::CreateStreamOnFile

IOpcFactory::WritePackageToStream

IStream

Packaging API Reference

Packaging API Samples

Set Author Sample

Set Author opclib.h

Set Author opclib.cpp