1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
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);
}
}
|
