1 /*---------------------------------------------------------------------------*
2 
3   Copyright (C) Nintendo.  All rights reserved.
4 
5   These coded instructions, statements, and computer programs contain
6   proprietary information of Nintendo of America Inc. and/or Nintendo
7   Company Ltd., and are protected by Federal copyright law.  They may
8   not be disclosed to third parties or copied or duplicated in any form,
9   in whole or in part, without the prior written consent of Nintendo.
10 
11  *---------------------------------------------------------------------------*/
12 
13 #ifndef __SZFILE_H
14 #define __SZFILE_H
15 
16 /* ---------------------------------------------------------------------------------
17 
18 This library is provided to assist in parsing and decoding data in .7z files.
19 
20 You can create a .7z file on Windows by installing the 7Zip toolkit from www.7zip.com,
21 and then using the tool directory or if you install the shell extension by right-clicking
22 on selection of files or a folder and selecting "7Zip -> Add To Archive..." or one of the
23 other options on the menu.
24 
25 The library works on both Windows and Cafe, and respects differences in CPU
26 endianness.  7z files are in little-endian byte order but the target system
27 may be big-endian (Cafe).
28 
29 The main library function is
30 
31 SZFILE_CreateArc
32 
33 It takes as input the address of a control structure to use, and a blob of memory that
34 is the original .7z compressed ZIP file, which has been placed into memory in its
35 entirety by some mechanism (built in, loaded, etc.).
36 This library does not do the loading.
37 
38 The function parses the file and creates a manifest that looks like a folder tree.
39 The manifest has pointers in it that refer to data in the original input blob.
40 A pointer to the root folder is returned by the function into the control structure.
41 
42 The library function uses allocate/free functions you provide to allocate and free
43 memory as needed during operations with the archive.  Different functions may be specified
44 for different archives.
45 
46 The manifest of directories in the archive contains the SZFILE_DIR and SZFILE_ENTRY
47 structures that refer to each other. The structures are in target system
48 byte order and can be used directly.
49 
50 When you are finished with the archive you should purge all memory used for it using
51 the SZFILE_PurgeArc function.  This function does not remove or free the original blob
52 of memory used to create the archive, which may not be freeable in some circumstances.
53 
54 --------------------------------------------------------------------------------- */
55 
56 #ifdef _MSC_VER
57 #include <windows.h>
58 #else
59 #ifdef EPPC
60 #include <cafe.h>
61 #else
62 #error !!! Unknown compilation target
63 #endif
64 #endif
65 
66 #ifdef __cplusplus
67 extern "C" {
68 #endif
69 
70 #ifdef EPPC
71 typedef u8 UINT8;
72 typedef u16 UINT16;
73 typedef u32 UINT32;
74 typedef u64 UINT64;
75 #endif
76 
77 /* --------------------------------------------------------------------------------- */
78 
79 /* these functions are used by SZFILE_ functions that work on an archive to allocate
80    and free memory.  You associate specific functions with an archive when it is created
81    using the SZFILE_CreateArc function. */
82 typedef void * (*SZFILE_pf_Alloc)(size_t aBytes);
83 typedef void   (*SZFILE_pf_Free)(void *addr);
84 
85 /* This manifest structure describes a single file in the .7z archive. */
86 struct _SZFILE_ENTRY
87 {
88     struct _SZFILE_DIR *    mpParentDir;
89     UINT32                  mArcIndex;
90     char const *            mpNameOnly;
91     UINT32                  mNameOnlyLen;
92     UINT32                  mStreamIx;
93     UINT32                  mStreamUnpackedOffset;
94     UINT32                  mUncompBytes;
95 };
96 typedef struct _SZFILE_ENTRY SZFILE_ENTRY;
97 
98 /* This manifest structure describes a single directory/subdirectory in the .7z archive. */
99 struct _SZFILE_DIR
100 {
101     struct _SZFILE_ARC *    mpArc;
102     struct _SZFILE_DIR *    mpParentDir;
103     char const *            mpNameOnly;
104     UINT32                  mNameOnlyLen;
105     UINT32                  mNumFiles;
106     SZFILE_ENTRY *          mpFilesArray;
107     struct _SZFILE_DIR *    mpSubDirList;
108     struct _SZFILE_DIR *    mpNextSib;
109 };
110 typedef struct _SZFILE_DIR SZFILE_DIR;
111 
112 /* this is the archive control structure.  it has an opaque pointer to implementation bits,
113    a reference to the original data used to build the manifest, and pointers to both the
114    uncompressed streams (if they have been uncompressed), and the root directory for the
115    directories and files in the archive */
116 struct _SZFILE_ARC
117 {
118     void *          mpImp;
119 
120     UINT8 const *   mpSrcFile;
121     UINT32          mSrcFileBytes;
122 
123     SZFILE_pf_Alloc mfAlloc;
124     SZFILE_pf_Free  mfFree;
125 
126     UINT32          mNumStreams;
127     UINT8 **        mppUnpackedStreams;
128 
129     SZFILE_DIR *    mpRootDir;
130 };
131 typedef struct _SZFILE_ARC SZFILE_ARC;
132 
133 /* this function is used to populate an SZFILE_ARC structure by parsing the .7z file
134    specified as an argument.  The afAlloc and afFree functions match the prototypes of
135    malloc and free (respectively), and are associated with the archive for its lifespan. */
136 int     SZFILE_CreateArc(SZFILE_ARC *apArc, UINT8 const *apFileData, UINT32 aFileBytes, SZFILE_pf_Alloc afAlloc, SZFILE_pf_Free afFree);
137 
138 /* this function extracts a specific stream in the archive (there may be more than one stream).
139    a stream is never extracted more than once */
140 int     SZFILE_UnpackStream(SZFILE_ARC *apArc, UINT32 aStreamIx);
141 
142 /* this function allows you to find a file by its full path in an archive.  it returns via
143    an output parameter a pointer to the entry for the file if it is found */
144 int     SZFILE_FindInArc(SZFILE_ARC *apArc, char const *apFileName, SZFILE_ENTRY **apRetEntryPtr);
145 
146 /* this function extracts any stream associated with a file entry and returns a pointer to its
147    data as well as the size of the extracted file.  a stream is never extracted more than once but
148    this function will extract a stream automatically (via SZFILE_UnpackStream) if it needs to */
149 int     SZFILE_GetUnpackedFile(SZFILE_ENTRY *apEntry, UINT8 **apRetDataPtr, UINT32 *apRetDataBytes);
150 
151 /* this is an easy-use helper function that you can use to get to the data of a file and have
152    any extracting that needs to be done execute automatically. It is implemented using the
153    SZFILE_FindInArc and SZFILE_GetUnpackedFile functions */
154 UINT8 * SZFILE_Get(SZFILE_ARC *apArc, char const *apFileName, UINT32 *apRetFileBytes);
155 
156 /* this function is used to free all memory used to create the manifest for an archive from the original
157    .7z file contents.  this function does not free the original file data buffer specified in the
158    SZFILE_CreateArc function call */
159 void    SZFILE_PurgeArc(SZFILE_ARC *apArc);
160 
161 /* these are errorcodes that can occur as results of use of the functions above.
162    a zero result from a function means "success" */
163 #define SZFILE_ERRCODE(x)                          ((int)(0xBADE0000 | (x)))
164 #define ERRCODE_SZFILE_OUTOFMEMORY                 SZFILE_ERRCODE(1)
165 #define ERRCODE_SZFILE_INTERNAL                    SZFILE_ERRCODE(2)
166 #define ERRCODE_SZFILE_BADARG                      SZFILE_ERRCODE(3)
167 #define ERRCODE_SZFILE_CORRUPT                     SZFILE_ERRCODE(4)
168 #define ERRCODE_SZFILE_EMPTY                       SZFILE_ERRCODE(5)
169 #define ERRCODE_SZFILE_FILENOTFOUND                SZFILE_ERRCODE(6)
170 #define ERRCODE_SZFILE_PATHNOTFOUND                SZFILE_ERRCODE(7)
171 
172 /* --------------------------------------------------------------------------------- */
173 
174 #ifdef __cplusplus
175 }
176 #endif
177 
178 /* --------------------------------------------------------------------------------- */
179 
180 #endif // __SZFILE_H
181 
182