From 3f583916719eeef598d10a5d4e14ef14f008243b Mon Sep 17 00:00:00 2001
From: Rob Mensching <rob@firegiant.com>
Date: Tue, 11 May 2021 07:36:37 -0700
Subject: Merge Dtf

---
 .../IPackStreamContext.cs                          | 117 +++++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 src/dtf/WixToolset.Dtf.Compression/IPackStreamContext.cs

(limited to 'src/dtf/WixToolset.Dtf.Compression/IPackStreamContext.cs')

diff --git a/src/dtf/WixToolset.Dtf.Compression/IPackStreamContext.cs b/src/dtf/WixToolset.Dtf.Compression/IPackStreamContext.cs
new file mode 100644
index 00000000..19d77be5
--- /dev/null
+++ b/src/dtf/WixToolset.Dtf.Compression/IPackStreamContext.cs
@@ -0,0 +1,117 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
+
+namespace WixToolset.Dtf.Compression
+{
+    using System;
+    using System.IO;
+    using System.Diagnostics.CodeAnalysis;
+
+    /// <summary>
+    /// This interface provides the methods necessary for the
+    /// <see cref="CompressionEngine"/> to open and close streams for archives
+    /// and files. The implementor of this interface can use any kind of logic
+    /// to determine what kind of streams to open and where.
+    /// </summary>
+    public interface IPackStreamContext
+    {
+        /// <summary>
+        /// Gets the name of the archive with a specified number.
+        /// </summary>
+        /// <param name="archiveNumber">The 0-based index of the archive
+        /// within the chain.</param>
+        /// <returns>The name of the requested archive. May be an empty string
+        /// for non-chained archives, but may never be null.</returns>
+        /// <remarks>The archive name is the name stored within the archive, used for
+        /// identification of the archive especially among archive chains. That
+        /// name is often, but not necessarily the same as the filename of the
+        /// archive package.</remarks>
+        string GetArchiveName(int archiveNumber);
+
+        /// <summary>
+        /// Opens a stream for writing an archive package.
+        /// </summary>
+        /// <param name="archiveNumber">The 0-based index of the archive within
+        /// the chain.</param>
+        /// <param name="archiveName">The name of the archive that was returned
+        /// by <see cref="GetArchiveName"/>.</param>
+        /// <param name="truncate">True if the stream should be truncated when
+        /// opened (if it already exists); false if an existing stream is being
+        /// re-opened for writing additional data.</param>
+        /// <param name="compressionEngine">Instance of the compression engine
+        /// doing the operations.</param>
+        /// <returns>A writable Stream where the compressed archive bytes will be
+        /// written, or null to cancel the archive creation.</returns>
+        /// <remarks>
+        /// If this method returns null, the archive engine will throw a
+        /// FileNotFoundException.
+        /// </remarks>
+        Stream OpenArchiveWriteStream(
+            int archiveNumber,
+            string archiveName,
+            bool truncate,
+            CompressionEngine compressionEngine);
+
+        /// <summary>
+        /// Closes a stream where an archive package was written.
+        /// </summary>
+        /// <param name="archiveNumber">The 0-based index of the archive within
+        /// the chain.</param>
+        /// <param name="archiveName">The name of the archive that was previously
+        /// returned by
+        /// <see cref="GetArchiveName"/>.</param>
+        /// <param name="stream">A stream that was previously returned by
+        /// <see cref="OpenArchiveWriteStream"/> and is now ready to be closed.</param>
+        /// <remarks>
+        /// If there is another archive package in the chain, then after this stream
+        /// is closed a new stream will be opened.
+        /// </remarks>
+        void CloseArchiveWriteStream(int archiveNumber, string archiveName, Stream stream);
+
+        /// <summary>
+        /// Opens a stream to read a file that is to be included in an archive.
+        /// </summary>
+        /// <param name="path">The path of the file within the archive. This is often,
+        /// but not necessarily, the same as the relative path of the file outside
+        /// the archive.</param>
+        /// <param name="attributes">Returned attributes of the opened file, to be
+        /// stored in the archive.</param>
+        /// <param name="lastWriteTime">Returned last-modified time of the opened file,
+        /// to be stored in the archive.</param>
+        /// <returns>A readable Stream where the file bytes will be read from before
+        /// they are compressed, or null to skip inclusion of the file and continue to
+        /// the next file.</returns>
+        [SuppressMessage("Microsoft.Design", "CA1021:AvoidOutParameters")]
+        Stream OpenFileReadStream(
+            string path,
+            out FileAttributes attributes,
+            out DateTime lastWriteTime);
+
+        /// <summary>
+        /// Closes a stream that has been used to read a file.
+        /// </summary>
+        /// <param name="path">The path of the file within the archive; the same as
+        /// the path provided
+        /// when the stream was opened.</param>
+        /// <param name="stream">A stream that was previously returned by
+        /// <see cref="OpenFileReadStream"/> and is now ready to be closed.</param>
+        void CloseFileReadStream(string path, Stream stream);
+
+        /// <summary>
+        /// Gets extended parameter information specific to the compression
+        /// format being used.
+        /// </summary>
+        /// <param name="optionName">Name of the option being requested.</param>
+        /// <param name="parameters">Parameters for the option; for per-file options,
+        /// the first parameter is typically the internal file path.</param>
+        /// <returns>Option value, or null to use the default behavior.</returns>
+        /// <remarks>
+        /// This method provides a way to set uncommon options during packaging, or a
+        /// way to handle aspects of compression formats not supported by the base library.
+        /// <para>For example, this may be used by the zip compression library to
+        /// specify different compression methods/levels on a per-file basis.</para>
+        /// <para>The available option names, parameters, and expected return values
+        /// should be documented by each compression library.</para>
+        /// </remarks>
+        object GetOption(string optionName, object[] parameters);
+    }
+}
-- 
cgit v1.2.3-55-g6feb