UpdateHeader function

This method is deprecated.

Updates the header of an FESF encrypted file.

Syntax

HRESULT

UpdateHeader(

    [in] REFGUID Volume,

    [in] BSTR    Path,

    [in] VARIANT *  NewHeader

   )

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 to update.  This may be a fully qualified path or a path relative to the Volume argument.  Refer to the Remarks section.

NewHeader [in]

A pointer to a VARIANT that describes a CComSafeArray of bytes holding the new header that is to be substituted for the existing header on the file.

Return value

S_OK on success

The error code E_INVALIDARG is returned if the function is called with a header that is larger than can be accommodated in the existing file without extension.

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.

This operation requires exclusive access to the file.  A Client Solution component calls UpdateHeader to replace the existing Policy Header Data in an FESF encrypted file with new Policy Header Data.  The old Policy Header Data is discarded.

If Volume is equal to FE_SHADOW_VOLUME_GUID (indicating that Path refers to a file on a shadow 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 new data must be less than or equal to the number of bytes returned in the MaxHeaderLength parameter of the FesfDS->ReadHeader method.  If the Client Solution component needs to write a header that’s larger than MaxHeaderLength bytes, it must use the FesfDS->UpdateHeaderWithExtension method.

UpdateHeader is optimized to allow a Client Solution to update an existing header within specific size constraints, and with as little overhead as possible. If the size of the Header Data to be written is less than the maximum Header Data length returned in the MaxHeaderLength parameter of the FesfDS->ReadHeader function, the Client Solution component can call FesfDS->UpdateHeader.  If the Header Data to be written is greater than MaxHeaderLength bytes, the FesfDS->UpdateHeaderWithExtension function must be used.

Solutions should note that, depending on the size of the new Header Data to be written, UpdateHeader may not inherently be transactionally safe. Thus, the file being updated could become corrupted if an unrecoverable error occurs during the header update process.  If absolute safety is required, the Client Solution component should make a backup copy of the file being updated, call UpdateHeader, and when the update succeeds delete the backup copy.

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

Examples

//

// Now write the header back to the safe array so that we can

// write it out to the file

//

for (auto index = (ULONG)0; index < newLength; index++)

{

    headerAsSafeArray.SetAt(index, newHeader[index]);

}

if (action == HeaderUpdateSeqNumber || action == HeaderUpdateSizeRandom ||

        action == HeaderUpdateSizeIncreasing)

{

    //

    // If the header is larger than the maximum allowed size,

    // we have to call a different function to do it

    //

    if (newLength <= maxHeaderLength)

    {

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

                                GetUniversalFilePath(file),

                                &variantHeader);

    }

    else

    {

        hr = spDS->UpdateHeaderWithExtension(

                    const_cast<GUID *>(&GUID_NULL),

                    GetUniversalFilePath(file),

                    &variantHeader);

    }

    if (!SUCCEEDED(hr))

    {

        wprintf(L"%-30ws <E> UpdateHeader failed (hr=0x%x)\n", 

                   findData.cFileName, hr);

        break;

    }

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

FesfDS->UpdateHeaderWithExtension.

Requirements