ReadHeader function

This method is deprecated.

Retrieves the header of an FESF encrypted file.

Syntax

HRESULT

ReadHeader(

    [in]  REFGUID Volume,

    [in]  BSTR    Path,

    [out] ULONG *MaxHeaderLength,

    [out, retval] VARIANT *Header

   )

Parameters

Volume [in]

A reference to a GUID that identifies the volume on which the file resides.  See Remarks for further information.

Path [in]

A string containing the path of a file whose header is to be read.  This may be a fully qualified path or a path relative to the Volume argument.  Refer to the Remarks section.

MaxHeaderLength [out]

The maximum total length, in bytes, of the Header Data that can be written without having to extend the file.  See Remarks for more information.

Header [out]

A pointer to a VARIANT into which to return, on success, the Client Solution's Policy Header Data.  See the Remarks for more information.

Return value

S_OK on success

Other standard HRESULT values may be returned indicating the failure of the operation.

Remarks

Important: This method is deprecated and is pending removal from FESF. Do not use it. Convert existing code that uses it as soon as possible. Use the equivalent function provided by the FesfUtil2 Library.

A Client Solution component calls ReadHeader to retrieve its Policy Header Data from an FESF encrypted file.  In case the Solution component wants to subsequently update the Policy Header Data, this method also returns the maximum size of a new Header Data area that may be written without having to extend the file.

If Volume is equal to FE_SHADOW_VOLUME_GUID (indicating that Path refers to a file on a network volume), then Path is interpreted as either as a fully qualified path, suitable for direct evaluation or as the concatenation of the shadow device name and path.

If Volume is equal to GUID_NULL (indicating that no GUID is provided) then Path is inspected and treated as though either FE_SHADOW_VOLUME_GUID or FE_NETWORK_GUID was provided.

Otherwise, Volume represents a local volume and Path is interpreted as relative to that volume.

The Policy DLL’s Header Data is returned to the caller in a CComSafeArray of bytes, described by a COM (automation) VARIANT structure.  The header data in the returned CComSafeArray can be used directly or copied to a buffer, as shown in the example below.

The calling COM client must have SE_RESTORE_NAME privilege available to call this function.

Examples

BYTE *existingHeader{ nullptr };

BYTE *newHeader{ nullptr };

auto headerLength = (ULONG)0;

ULONG newLength;

ULONG maxHeaderLength{ 0 };

VARIANT variantHeader;

CString errorString(L"");

//

// Read the existing Header

//

hr = spDS->ReadHeader(const_cast<GUID *>(&GUID_NULL),

                      GetUniversalFilePath(file),

                      &maxHeaderLength,

                      &variantHeader);

if (!SUCCEEDED(hr))

{

    wprintf(L"%-30ws <E> ReadHeader failed 0x%x\n", findData.cFileName, hr);

    break;

}

//

// We need to convert the variant version of the header into a

// byte array version of the header, which we do via a

// safearray of bytes.

//

CComSafeArray<BYTE> headerAsSafeArray;

if (nullptr == variantHeader.parray)

{

    wprintf(L"%-30ws <E> ReadHeader returned null header (hr=0x%x)\n",

            findData.cFileName, hr);

    break;

}

headerAsSafeArray.Attach(variantHeader.parray);

headerLength = headerAsSafeArray.GetCount();

existingHeader = new BYTE[headerLength];

//

// Move the data from the safe array back into the header buffer

//

for (ULONG index = 0; index < headerLength; index++)

{

    existingHeader[index] = headerAsSafeArray.GetAt(index);

}

The above snippet comes from the SampUpdateHeader example that’s provided as part of the UM_SAMPLE Solution.  Refer to that example for more details.

See Also

Requirements