/// <summary>
        /// Will create an DocumentStream backed by a tempoary file.
        /// </summary>
        /// <remarks>
        /// We prefer to create the temporary file in the same location as the
        /// source to inherit the folders attributes and security.
        ///
        /// If we can not we will use a system generated file.
        /// </remarks>
        /// <param name="copyoriginal">When true we will copy the source file if
        /// possible.  You must check for a non-zero result on the returning stream
        /// to determin success.</param>
        /// <returns>An DocumentStream.</returns>
        internal DocumentStream CreateTemporary(bool copyOriginal)
        {
            CriticalFileToken tempToken = null;
            DocumentStream    result    = null;

            FileStream temporary    = null;
            bool       isFileSource = (_xpsFileToken != null);

            //----------------------------------------------------------------------
            // Open File in Same Location (if possible)
            if (isFileSource)
            {
                MakeTempFile(true, out temporary, out tempToken);
            }

            //----------------------------------------------------------------------
            // Open File in System Generated Location
            if (tempToken == null)
            {
                // TODO: Should we prompt user asking if it is okay in the case
                // where the source is a local file, as it may mean degraded
                // security?  We could check if this would be the case by
                // comparing ACLs & attributes before prompting

                MakeTempFile(false, out temporary, out tempToken);
            }

            //----------------------------------------------------------------------
            // File Was Opened
            if ((temporary != null) && (tempToken != null))
            {
                //------------------------------------------------------------------
                // Copy Data
                if (copyOriginal)
                {
                    // We use a native File.Copy if possible because this is
                    // most performant.  This is only possible if the source is file
                    // based.
                    if (isFileSource)
                    {
                        string sourcePath = _xpsFileToken.Location.LocalPath;
                        string tempPath   = tempToken.Location.LocalPath;

                        temporary.Close();

                        File.Copy(sourcePath, tempPath, true);

                        temporary = new FileStream(
                            tempPath,
                            FileMode.Open,
                            FileAccess.ReadWrite,
                            FileShare.None);

                        // we did the copy
                        copyOriginal = false;

                        Trace.SafeWrite(Trace.File, "Performed a file copy from source.");
                    }
                    else
                    {
                        StreamHelper.CopyStream(
                            this, temporary);
                        Trace.SafeWrite(Trace.File, "Performed a stream copy from source.");
                    }
                }

                //------------------------------------------------------------------
                // Create the DocumentStream
                result = new DocumentStream(
                    tempToken, temporary, this);

                result.DeleteOnClose = true;

                Trace.SafeWrite(Trace.File, "Created temporary file {0}.", tempToken.Location);
            }
            else
            {
                // rescind consent if any was given
                tempToken = null;
                Trace.SafeWrite(Trace.File, "Unable to create a temporary file.  Caller is expected to disable edits.");
            }
            return(result);
        }
        //--------------------------------------------------------------------------
        // Internal Methods
        //--------------------------------------------------------------------------

        /// <summary>
        /// Will create an XpsDocument by copying this one to a target file and
        /// returning a stream corresponding to the new file.
        /// </summary>
        /// <exception cref="System.ArgumentNullException"/>
        /// <exception cref="System.IO.InvalidDataException"/>
        /// <param name="copiesToken">The token for the target file.</param>
        /// <returns>An DocumentStream.</returns>
        internal DocumentStream Copy(CriticalFileToken copiesToken)
        {
            DocumentStream result;
            FileStream     target = null;

            bool isFileSource = (_xpsFileToken != null);

            Invariant.Assert(copiesToken != null, "No target file to which to copy.");

            ThrowIfInvalidXpsFileForSave(copiesToken.Location);

            string sourcePath = string.Empty;
            string copiesPath = copiesToken.Location.LocalPath;

            // if the source is a file, we need to release our lock on the source
            // file and also assert for permissions to read the file
            if (isFileSource)
            {
                Target.Close();
                sourcePath = _xpsFileToken.Location.LocalPath;
            }

            try
            {
                // if the source is a file, file copy is the fastest
                if (isFileSource)
                {
                    File.Copy(sourcePath, copiesPath, true);

                    // If the original file was marked read-only, the copy will be read-only as
                    // well.  However, the copy is done for the purpose of creating a new file,
                    // so it should not be marked read-only.
                    FileAttributes attrib = File.GetAttributes(copiesPath);
                    if ((attrib & FileAttributes.ReadOnly) == FileAttributes.ReadOnly)
                    {
                        File.SetAttributes(copiesPath, attrib ^ FileAttributes.ReadOnly);
                    }

                    // open the destination file that was just created by File.Copy
                    target = new FileStream(
                        copiesPath,
                        FileMode.Open,
                        FileAccess.ReadWrite,
                        FileShare.None);
                }
                else
                {
                    // open the destination file for create; we will copy the
                    // source stream's data to the new stream outside the assert
                    target = new FileStream(
                        copiesPath,
                        FileMode.Create,
                        FileAccess.ReadWrite,
                        FileShare.None);
                }
            }
            // Since we have already closed the original file, we need to reopen it if we
            // fail to copy the file or open the new file.  After doing so, we rethrow the
            // original exception so it can be handled at a higher level.
#pragma warning suppress 56500 // suppress PreSharp Warning 56500: Avoid `swallowing errors by catching non-specific exceptions..
            catch
            {
                if (isFileSource)
                {
                    Trace.SafeWrite(
                        Trace.File,
                        "File copy failed -- reopening original file.");
                    try
                    {
                        Target = new FileStream(
                            sourcePath,
                            FileMode.Open,
                            FileAccess.Read,
                            FileShare.Read);
                    }
                    // If we fail to reopen the original file, rethrow an exception to
                    // indicate this specific error.
#pragma warning suppress 56500 // suppress PreSharp Warning 56500: Avoid `swallowing errors by catching non-specific exceptions..
                    catch (Exception e)
                    {
                        Trace.SafeWrite(
                            Trace.File,
                            "Unable to reopen original file.");

                        throw new UnauthorizedAccessException(
                                  SR.Get(SRID.DocumentStreamCanNoLongerOpen), e);
                    }
                }
                throw;
            }

            if (isFileSource)
            {
                Trace.SafeWrite(Trace.File, "Performed a file copy from source.");

                // reacquire our stream
                ReOpenWriteable();
            }
            else
            {
                // if the source wasn't a file, we want to copy the stream now
                StreamHelper.CopyStream(this, target);
                Trace.SafeWrite(Trace.File, "Performed a stream copy from source.");
            }

            //----------------------------------------------------------------------
            // Create the DocumentStream
            result = new DocumentStream(copiesToken, target, this);

            result.DeleteOnClose = false;

            Trace.SafeWrite(Trace.File, "Created copy to file {0}.", copiesToken.Location);

            return(result);
        }