@joebigelow / wix
Code Commits Issues Pulls Sessions CI/CD
main
main
cs 117 lines 5.84 KB
Raw
1 // 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.
2
3 namespace WixToolset.Dtf.Compression
4 {
5 using System;
6 using System.IO;
7 using System.Diagnostics.CodeAnalysis;
8
9 /// <summary>
10 /// This interface provides the methods necessary for the
11 /// <see cref="CompressionEngine"/> to open and close streams for archives
12 /// and files. The implementor of this interface can use any kind of logic
13 /// to determine what kind of streams to open and where.
14 /// </summary>
15 public interface IPackStreamContext
16 {
17 /// <summary>
18 /// Gets the name of the archive with a specified number.
19 /// </summary>
20 /// <param name="archiveNumber">The 0-based index of the archive
21 /// within the chain.</param>
22 /// <returns>The name of the requested archive. May be an empty string
23 /// for non-chained archives, but may never be null.</returns>
24 /// <remarks>The archive name is the name stored within the archive, used for
25 /// identification of the archive especially among archive chains. That
26 /// name is often, but not necessarily the same as the filename of the
27 /// archive package.</remarks>
28 string GetArchiveName(int archiveNumber);
29
30 /// <summary>
31 /// Opens a stream for writing an archive package.
32 /// </summary>
33 /// <param name="archiveNumber">The 0-based index of the archive within
34 /// the chain.</param>
35 /// <param name="archiveName">The name of the archive that was returned
36 /// by <see cref="GetArchiveName"/>.</param>
37 /// <param name="truncate">True if the stream should be truncated when
38 /// opened (if it already exists); false if an existing stream is being
39 /// re-opened for writing additional data.</param>
40 /// <param name="compressionEngine">Instance of the compression engine
41 /// doing the operations.</param>
42 /// <returns>A writable Stream where the compressed archive bytes will be
43 /// written, or null to cancel the archive creation.</returns>
44 /// <remarks>
45 /// If this method returns null, the archive engine will throw a
46 /// FileNotFoundException.
47 /// </remarks>
48 Stream OpenArchiveWriteStream(
49 int archiveNumber,
50 string archiveName,
51 bool truncate,
52 CompressionEngine compressionEngine);
53
54 /// <summary>
55 /// Closes a stream where an archive package was written.
56 /// </summary>
57 /// <param name="archiveNumber">The 0-based index of the archive within
58 /// the chain.</param>
59 /// <param name="archiveName">The name of the archive that was previously
60 /// returned by
61 /// <see cref="GetArchiveName"/>.</param>
62 /// <param name="stream">A stream that was previously returned by
63 /// <see cref="OpenArchiveWriteStream"/> and is now ready to be closed.</param>
64 /// <remarks>
65 /// If there is another archive package in the chain, then after this stream
66 /// is closed a new stream will be opened.
67 /// </remarks>
68 void CloseArchiveWriteStream(int archiveNumber, string archiveName, Stream stream);
69
70 /// <summary>
71 /// Opens a stream to read a file that is to be included in an archive.
72 /// </summary>
73 /// <param name="path">The path of the file within the archive. This is often,
74 /// but not necessarily, the same as the relative path of the file outside
75 /// the archive.</param>
76 /// <param name="attributes">Returned attributes of the opened file, to be
77 /// stored in the archive.</param>
78 /// <param name="lastWriteTime">Returned last-modified time of the opened file,
79 /// to be stored in the archive.</param>
80 /// <returns>A readable Stream where the file bytes will be read from before
81 /// they are compressed, or null to skip inclusion of the file and continue to
82 /// the next file.</returns>
83 [SuppressMessage("Microsoft.Design", "CA1021:AvoidOutParameters")]
84 Stream OpenFileReadStream(
85 string path,
86 out FileAttributes attributes,
87 out DateTime lastWriteTime);
88
89 /// <summary>
90 /// Closes a stream that has been used to read a file.
91 /// </summary>
92 /// <param name="path">The path of the file within the archive; the same as
93 /// the path provided
94 /// when the stream was opened.</param>
95 /// <param name="stream">A stream that was previously returned by
96 /// <see cref="OpenFileReadStream"/> and is now ready to be closed.</param>
97 void CloseFileReadStream(string path, Stream stream);
98
99 /// <summary>
100 /// Gets extended parameter information specific to the compression
101 /// format being used.
102 /// </summary>
103 /// <param name="optionName">Name of the option being requested.</param>
104 /// <param name="parameters">Parameters for the option; for per-file options,
105 /// the first parameter is typically the internal file path.</param>
106 /// <returns>Option value, or null to use the default behavior.</returns>
107 /// <remarks>
108 /// This method provides a way to set uncommon options during packaging, or a
109 /// way to handle aspects of compression formats not supported by the base library.
110 /// <para>For example, this may be used by the zip compression library to
111 /// specify different compression methods/levels on a per-file basis.</para>
112 /// <para>The available option names, parameters, and expected return values
113 /// should be documented by each compression library.</para>
114 /// </remarks>
115 object GetOption(string optionName, object[] parameters);
116 }
117 }