1// Copyright 2008 Google Inc.
2// Author: Lincoln Smith
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8//      http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15//
16// Types and value definitions to support the implementation of RFC 3284 -
17// The VCDIFF Generic Differencing and Compression Data Format.
18// The RFC text can be found at http://www.faqs.org/rfcs/rfc3284.html
19// Many of the definitions below reference sections in that text.
20
21#ifndef OPEN_VCDIFF_VCDIFF_DEFS_H_
22#define OPEN_VCDIFF_VCDIFF_DEFS_H_
23
24#include <config.h>
25#include <limits.h>             // UCHAR_MAX
26#include <stdint.h>             // int32_t
27
28namespace open_vcdiff {
29
30enum VCDiffResult {
31  RESULT_SUCCESS = 0,
32  // Many functions within open-vcdiff return signed integer types,
33  // and can also return either of these special negative values:
34  //
35  // An error occurred while performing the requested operation.
36  RESULT_ERROR = -1,
37  // The end of available data was reached
38  // before the requested operation could be completed.
39  RESULT_END_OF_DATA = -2
40};
41
42// The delta file header section as described in section 4.1 of the RFC:
43//
44//    "Each delta file starts with a header section organized as below.
45//     Note the convention that square-brackets enclose optional items.
46//
47//           Header1                                  - byte = 0xD6
48//           Header2                                  - byte = 0xC3
49//           Header3                                  - byte = 0xC4
50//           Header4                                  - byte
51//           Hdr_Indicator                            - byte
52//           [Secondary compressor ID]                - byte
53//           [Length of code table data]              - integer
54//           [Code table data]
55//
56//     The first three Header bytes are the ASCII characters 'V', 'C' and
57//     'D' with their most significant bits turned on (in hexadecimal, the
58//     values are 0xD6, 0xC3, and 0xC4).  The fourth Header byte is
59//     currently set to zero.  In the future, it might be used to indicate
60//     the version of Vcdiff."
61//
62typedef struct DeltaFileHeader {
63  unsigned char header1;  // Always 0xD6 ('V' | 0x80)
64  unsigned char header2;  // Always 0xC3 ('C' | 0x80)
65  unsigned char header3;  // Always 0xC4 ('D' | 0x80)
66  unsigned char header4;  // 0x00 for standard format, 'S' if extensions used
67  unsigned char hdr_indicator;
68} DeltaFileHeader;
69
70// The possible values for the Hdr_Indicator field, as described
71// in section 4.1 of the RFC:
72//
73//    "The Hdr_Indicator byte shows if there is any initialization data
74//     required to aid in the reconstruction of data in the Window sections.
75//     This byte MAY have non-zero values for either, both, or neither of
76//     the two bits VCD_DECOMPRESS and VCD_CODETABLE below:
77//
78//         7 6 5 4 3 2 1 0
79//        +-+-+-+-+-+-+-+-+
80//        | | | | | | | | |
81//        +-+-+-+-+-+-+-+-+
82//                     ^ ^
83//                     | |
84//                     | +-- VCD_DECOMPRESS
85//                     +---- VCD_CODETABLE
86//
87//     If bit 0 (VCD_DECOMPRESS) is non-zero, this indicates that a
88//     secondary compressor may have been used to further compress certain
89//     parts of the delta encoding data [...]"
90// [Secondary compressors are not supported by open-vcdiff.]
91//
92//    "If bit 1 (VCD_CODETABLE) is non-zero, this indicates that an
93//     application-defined code table is to be used for decoding the delta
94//     instructions. [...]"
95//
96const unsigned char VCD_DECOMPRESS = 0x01;
97const unsigned char VCD_CODETABLE = 0x02;
98
99// The possible values for the Win_Indicator field, as described
100// in section 4.2 of the RFC:
101//
102//    "Win_Indicator:
103//
104//     This byte is a set of bits, as shown:
105//
106//      7 6 5 4 3 2 1 0
107//     +-+-+-+-+-+-+-+-+
108//     | | | | | | | | |
109//     +-+-+-+-+-+-+-+-+
110//                  ^ ^
111//                  | |
112//                  | +-- VCD_SOURCE
113//                  +---- VCD_TARGET
114//
115//     If bit 0 (VCD_SOURCE) is non-zero, this indicates that a
116//     segment of data from the "source" file was used as the
117//     corresponding source window of data to encode the target
118//     window.  The decoder will use this same source data segment to
119//     decode the target window.
120//
121//     If bit 1 (VCD_TARGET) is non-zero, this indicates that a
122//     segment of data from the "target" file was used as the
123//     corresponding source window of data to encode the target
124//     window.  As above, this same source data segment is used to
125//     decode the target window.
126//
127//     The Win_Indicator byte MUST NOT have more than one of the bits
128//     set (non-zero).  It MAY have none of these bits set."
129//
130const unsigned char VCD_SOURCE = 0x01;
131const unsigned char VCD_TARGET = 0x02;
132// If this flag is set, the delta window includes an Adler32 checksum
133// of the target window data.  Not part of the RFC draft standard.
134const unsigned char VCD_CHECKSUM = 0x04;
135
136// The possible values for the Delta_Indicator field, as described
137// in section 4.3 of the RFC:
138//
139//    "Delta_Indicator:
140//     This byte is a set of bits, as shown:
141//
142//      7 6 5 4 3 2 1 0
143//     +-+-+-+-+-+-+-+-+
144//     | | | | | | | | |
145//     +-+-+-+-+-+-+-+-+
146//                ^ ^ ^
147//                | | |
148//                | | +-- VCD_DATACOMP
149//                | +---- VCD_INSTCOMP
150//                +------ VCD_ADDRCOMP
151//
152//          VCD_DATACOMP:   bit value 1.
153//          VCD_INSTCOMP:   bit value 2.
154//          VCD_ADDRCOMP:   bit value 4.
155//
156//     [...] If the bit VCD_DECOMPRESS (Section 4.1) was on, each of these
157//     sections may have been compressed using the specified secondary
158//     compressor.  The bit positions 0 (VCD_DATACOMP), 1
159//     (VCD_INSTCOMP), and 2 (VCD_ADDRCOMP) respectively indicate, if
160//     non-zero, that the corresponding parts are compressed."
161// [Secondary compressors are not supported, so open-vcdiff decoding will fail
162//  if these bits are not all zero.]
163//
164const unsigned char VCD_DATACOMP = 0x01;
165const unsigned char VCD_INSTCOMP = 0x02;
166const unsigned char VCD_ADDRCOMP = 0x04;
167
168// A COPY address has 32 bits, which places a limit
169// of 2GB on the maximum combined size of the dictionary plus
170// the target window (= the chunk of data to be encoded.)
171typedef int32_t VCDAddress;
172
173// The address modes used for COPY instructions, as defined in
174// section 5.3 of the RFC.
175//
176// The first two modes (0 and 1) are defined as SELF (addressing forward
177// from the beginning of the source window) and HERE (addressing backward
178// from the current position in the source window + previously decoded
179// target data.)
180//
181// After those first two modes, there are a variable number of NEAR modes
182// (which take a recently-used address and add a positive offset to it)
183// and SAME modes (which match a previously-used address using a "hash" of
184// the lowest bits of the address.)  The number of NEAR and SAME modes
185// depends on the defined size of the address cache; since this number is
186// variable, these modes cannot be specified as enum values.
187enum VCDiffModes {
188  VCD_SELF_MODE = 0,
189  VCD_HERE_MODE = 1,
190  VCD_FIRST_NEAR_MODE = 2,
191  VCD_MAX_MODES = UCHAR_MAX + 1  // 256
192};
193
194}  // namespace open_vcdiff
195
196#endif  // OPEN_VCDIFF_VCDIFF_DEFS_H_
197