Windows 7 includes new native-code APIs that provide functionality to compose and parse Part URIs. These APIs are provided through the IOpcUri and IOpcPartUri interfaces. Managed-code provides similar functionality with the System.IO.Packaging PackUriHelper class.

A difference between the two API sets is that while the managed-code PackUriHelper APIs support both Pack URIs and Part URIs (also called "part names"), the native-code IOpcFactory::CreatePartUri and IOpcPartUri APIs only provide functionality to create and manage Part URIs. The native-code Packaging APIs do not provide any functionality to access packages or package content as external resources, and therefore only supports Part URIs to address part content within the immediate package.

The managed-code PackUriHelper and native-code CreatePartUri/IOpcPartUri APIs are both designed to be ECMA 376-2 (2006) compliant.

The table below shows a comparison between the managed-code and native-code APIs, and which APIs provide similar functionality:

Managed API

Equivalent Native API

Parity

PackUriHelper.CreatePartUri

IOpcFactory::CreatePartUri

See 1.1

No equivalent API

IOpcFactory::CreatePackageRootUri

 

PackUriHelper.GetRelationshipPartUri

IOpcUri::GetRelationshipsPartUri

Identical

PackUriHelper.GetRelativeUri

IOpcUri::GetRelativeUri

Identical

PackUriHelper.ResolvePartUri

IOpcUri::CombinePartUri

See 1.2

PackUriHelper.ComparePartUri

IOpcPartUri::ComparePartUri

Identical

PackUriHelper.GetSourcePartUriFromRelationshipPartUri

IOpcPartUri::GetSourceUri

Identical

PackUriHelper.IsRelationshipPartUri

IOpcPartUri::IsRelationshipsPartUri

Identical

PackUriHelper.Create

No equivalent API

 

PackUriHelper.ComparePackUri

No equivalent API

 

PackUriHelper.GetNormalizedPartUri

No equivalent API

 

PackUriHelper.GetPackageUri

No equivalent API

 

PackUriHelper.GetPartUri

No equivalent API

 

1. API differences

1.1 IOpcFactory::CreatePartUri differences from PackUriHelper.CreatePartUri

The functionality of the native-code IOpcFactory::CreatePartUri API, follows the rules provided in ECMA 376-2 OPC standard, Appendix A.3 for resolving a relative reference to a valid Part URI (part name). The IOpcFactory::CreatePartUri and IOpcUri::CombinePartUri native-code APIs both produce the same output ("Native-code Behavior" below).

Input

Native-code CreatePartUri Behavior

Managed-code CreatePartUri Behavior

Contains bad UTF-8 encoding e.g. '%FC':

Leaves %FC unchanged in output.

Changes to valid UTF-8 output %C3%BC. (See * below)

Contains empty segments i.e. multiple forward slashes

Collapses multiple forward slashes to a single forward slash.

Does not collapse. (This is OPC rule violation).

Begins with 2 or more forward slashes

Collapses multiple forward slashes to a single forward slash.

Fails, throws an "ArgumentException".

Contains a single trailing forward slash

Removes trailing slash.

Fails, throws an "ArgumentException".

Contains a percent-encoded NULL (%00)

Returns an "E_UNEXPECTED" HRESULT error.

Percent-encoded NULL is kept unchanged, and returns a valid part name.

* - Characters above 0x7F are required to be escaped using UTF-8. For example, if the input URI contains %FC, which is not a legal UTF-8 sequence, the rules provided in RFC 3987 section 3.1, require leaving the input unchanged. The PackUriHelper.CreatePartUri method however, decodes %FC as UTF-16 to its octet <FC> (character 'ü') and then re-encodes it to the valid UTF-8, '%C3%BC'. Unfortunately, this approach is incompliant with RFC rules. [Note: If the relative reference contains a %FC, both IOpcUri::CombinePartUri and PackUriHelper.ResolvePartUri leave it unchanged.]

1.2 IOpcUri::CombinePartUri differences from PackUriHelper.ResolvePartUri

The managed-code PackUriHelper.ResolvePartUri API differs from the native-code IOpcUri::CombinePartUri API in that it resolves the input relative reference against a base URI, but it does not ensure that the result is a valid part name. In contrast, the native-code IOpcUri::CombinePartUri API both resolves the input and ensures that the result is a valid part name.

Input

Native-code CombinePartUri Behavior

Managed-code ResolvePartUri Behavior

Contains percent-encoded unreserved characters

Un-encodes unreserved characters, resulting in a valid part name.

Leaves characters in encoded form resulting in an invalid part name.

Contains empty segments i.e. multiple forward slashes

Collapses multiple slashes to a single forward slash, resulting in a valid part name.

Does not collapse empty segments, resulting in an invalid part name.

Begins with 2 or more forward slashes

Collapses multiple slashes to a single forward slash, resulting in a valid part name

Fails, throws an "ArgumentException".

Contains a single trailing forward slash

Removes trailing slash.

Does not remove trailing slash resulting in an invalid part name.

Contains a percent-encoded NULL (%00)

Returns an " E_UNEXPECTED " HRESULT error.

Percent-encoded NULL is kept unchanged, and returns a valid part name.

- Ali Naqvi