Join the discord

Unpakke Software Development Kit, API Reference and user manual

Introduction


After version 0.4b things have changed!


Unpakke v1.0 is a official release, written from scratch. Therefore, the old, pre v0.4b modules are no longer supported.
Sorry.

However, you can still download and use the older version of the app and its modules.

Although this manual is not absolutely complete, and probably will never be, it should give answers to most of your "why" and "how" questions.

If you are interested to learn how to use Unpakke, to unpack your favourite game, you might find that information at user manual section.

Or maybe you would like to create your own module for Unpakke? Then grab a fresh copy of the Module SDK, and take a look at the API Reference.


This help page is still a baby, so I encourage everyone to send me suggestions on how to improve it... or improve my English, maybe?

User manual


Welcome to the Unpakke's User manual!


The most obvious thing is the GUI that now Unpakke have.

Depending on the way you execute the program, you can use it as either GUI or CLI with the same result.

Packing (command line interface)


Chose the game format you would like to use, by checking Unpakke's homepage and download the appropriate module.

For packing you need the following parameters (in order of usage):

MODULE The module file name, handling the current game packing algorithm.
This parameter could be both relative or absolute file path.
In case the file path contains a space, you should always surround the whole parameter in double quotes (")
METHOD Unpakke method. For packing, this parameter should always be set to pack
INPUT
(directory)
The source folder, containing the files you like to pack.
This parameter could be both relative or absolute file path.
In case the file path contains a space, you should always surround the whole parameter in double quotes (")
OUTPUT
(file)
The destination file, where the data will be packed into.
This parameter could be both relative or absolute file path.
In case the file path contains a space, you should always surround the whole parameter in double quotes (")

The command line should look like this:

Exampleunpakke.exe <MODULE> pack <INPUT> <OUTPUT>

The result should be a newly created <OUTPUT> file containing the data from the <INPUT> folder.



Packing (graphical user interface)


Unpacking (command line interface)


Chose the game format you would like to use, by checking Unpakke's homepage and download the appropriate module.

For unpacking you need the following parameters (in order of usage):

MODULE The module file name, handling the current game unpacking algorithm.
This parameter could be both relative or absolute file path.
In case the file path contains a space, you should always surround the whole parameter in double quotes (")
METHOD Unpakke method. For unpacking, this parameter should always be set to unpack
INPUT
(file)
The source file, that holds the data you like to unpack.
This parameter could be both relative or absolute file path.
In case the file path contains a space, you should always surround the whole parameter in double quotes (")
OUTPUT
(directory)
The destination folder, where the data will be unpacked into.
This parameter could be both relative or absolute file path.
In case the file path contains a space, you should always surround the whole parameter in double quotes (")

The command line should look like this:

Exampleunpakke.exe <MODULE> unpack <INPUT> <OUTPUT>

The result should be a newly created <OUTPUT> folder containing the data from the <INPUT> file.



Unpacking (graphical user interface)


Repacking


As-is, repacking an existing archive is not supported.
However, there is a way to repack an existing archive in one-shot by combining the unpack and pack routines from the CLI.

Basically, what you need to do is:
1. Unpack the existing archive to a temporary place;
2. Replace the resources you like;
3. Pack back the archive;

In this case, using BATCH commands in a simple CMD/BAT file you can perform repacking.

API reference


Unpakke modules and the program itself are (badly) written in MinGW, under Code::Blocks IDE.

Although, you might use a compiler of your choice, keep in mind that the examples provided in the SDK are using MinGW's syntax.

The bare minimum to start developing modules for Unpakke is Code::Blocks with the MinGW provided here : http://www.codeblocks.org/downloads/26 (codeblocks-XX.XXmingw-setup.exe)

As we get that little detail cleared, let's see what you will have to deal with, if you bother developing your own modules.

There are three types of functions you might use from the module:

1. Shared - Helper functions used by the overall module functionality, both packing and unpacking;

2. Unpacking specific - Functions used by the unpacking process;

3. Packing specific - Functions used by the packing process.

All these functions are stored into Unpakke.exe core executable, and are ready to use wherever you need them in your module's code.

Shared functions


Shared functions are mostly helper functions like the built in compression/decompression and encryption/decryption one.

They are free to use is both packing or unpacking.

Unpacking specific


Unpacking functions are functions that, are obviously part of the unpacking process.
They should be fine to be used in the packing process too, but I don't think you will ever need to do such thing.

Packing specific


Packing functions are functions that, are obviously part of the packing process.
They should be fine to be used in the unpacking process too, but I don't think you will ever need to do such thing.

log function


Displays data in Unpakke's command line or log window. This function should be usually used for debugging purposes only.

Syntax void log(
   _In_ const char *fmt,
   _In_ ...
);

Parameters


fmt [in]

String formatting, as used in wsprintf


... [in]

One or more optional arguments.


Return value

Function does not return a value.


Example unsigned int a = 10;
unsigned int b = 20;
unsigned int c = 30;

log("value A: %d; value B: %d; value C: %d", a, b, c);
// result is "value A: 10; value B: 20; value C: 30"

upkkAdler32 function


Calculates the Adler32 checksum of a given data.

Syntax unsigned int upkkAdler32(
   _In_ unsigned char *dataBuffer,
   _In_ unsigned int bufferSize
);

Parameters


dataBuffer [in]

Input buffer


bufferSize [in]

Input buffer size in bytes


Return value

Function returns the Adler32 checksum of the given data.


Example unsigned char dataBuffer[] = "1234567890";
unsigned int bufferSize = 10;
unsigned int Adler32checksum;

// calculated checksum should be 0x0B2C020E
Adler32checksum = upkkAdler32(dataBuffer, bufferSize);

upkkAllocBuffer function


Allocates a memory buffer using VirtualAlloc with flAllocationType = MEM_COMMIT | MEM_RESERVE, and flProtect = PAGE_READWRITE

Syntax byte* upkkAllocBuffer(
   _In_ unsigned long bufferSize
);

Parameters


bufferSize [in]

Size of the requested buffer


Return value

On success, function returns the pointer to the allocated buffer.
If the function fails, the returned value is NULL.


Example byte data[] = "\x01\x02\x03\x04\x05";
byte *buffer;
unsigned long bufferSize = 5;

// First we allocate the buffer
buffer = upkkAllocBuffer(bufferSize);

// Next, we copy our data to the newly allocated buffer:
memcpy(buffer, data, bufferSize);

// Finally, if we don't need this buffer any more, we have to free it:
upkkReleaseBuffer(buffer);

upkkCompressBuffer function


Compresses a data with given compression algorithm.

Syntax byte* upkkCompressBuffer(
   _In_ int compAlgo,
   _In_ int compLevel,
   _In_ byte *inputBuffer,
   _In_ unsigned long inputBufferSize,
   _Inout_ unsigned long *outputBufferSize
);

Parameters


compAlgo [in]

Defines which compression algorithm should be used. This value can be one of the following:

COMPRESS_ZLIB
(0x10001000)
Deflate compression RFC 1951. It requires zlib1.dll to be located into /libs directory
COMPRESS_DEFLATE
(0x10001000)
Same as COMPRESS_ZLIB
COMPRESS_LZF
(0x10002000)
LZF (Lempel-Ziv Fast) compression LibLZF.
THIS COMPRESSION IS AVAILABLE AT VERSION 1.2 (build 1007) AND ABOVE

In near future, more compression algorithms should be added.


compLevel [in]

Compression level of the given algorithm. This value should be set to 0, if the specified compression algorithm doesn't support compression level.
- For COMPRESS_ZLIB this value can be a integer from 0x00 (worst compression) to 0x09 (best compression);
- For COMPRESS_LZF this value can be a integer from 0x00 (worst compression) to 0x16 (best compression);


inputBuffer [in]

Input data that is going to be compressed.


inputBufferSize [in]

Length of the input data in bytes.


outputBufferSize [in,out]

Length of the data, after compression


Return value

If the function success, the return value is a pointer to a buffer holding the compressed data. The length of the data is contained in the outputBufferSize parameter.
When it's no longer needed, the returned buffer should always be released using upkkReleaseBuffer.
If the function fail, the return value is NULL.


Example byte uncompressed_buffer[0x100];
byte *compressed_buffer;
DWORD compressed_buffer_size;

// outputBufferSize must hold a value big enough to fit the compressed data
// keep in mind, that sometimes the compressed data might be bigger than the decompressed one
compressed_buffer_size = 0x100 * 2;

// Assuming the uncompressed_buffer is filled with 0x100 bytes of data
// thus the inputBufferSize is 0x100
compressed_buffer = upkkCompressBuffer(COMPRESS_ZLIB, 0x09, uncompressed_buffer, 0x100, &compressed_buffer_size);

// At this point, compressed_buffer is holding the compressed data
// and compressed_buffer_size is holding the size of that buffer

// When we no longer need the compressed data, we can free its buffer
upkkReleaseBuffer(compressed_buffer);

upkkCountFiles function


Counts the number of files in a given directory. Based on its second argument, the upkkCountFiles function may act recursively (also count the files in the children directories).

Syntax DWORD upkkCountFiles(
   _In_ LPCTSTR baseDir,
   _In_ BOOL recursive
);

Parameters


baseDir [in]

Parent folder, which content needs to be counted.


recursive [in]

Count the files recursively (TRUE) or count the files in the parent folder only (FALSE)


Return value

Function returns the number of files contained in the given baseDir directory.


Example LPCTSTR baseDir = "C:\\unpakke_test";
DWORD numberOfFiles;

// numberOfFiles should contain the number of files in C:\\unpakke_test, and all of its sub folders
numberOfFiles = upkkCountFiles(baseDir, TRUE);

upkkCRC32 function


Calculates the CRC32 checksum of a given ASCII or binary data.

Syntax unsigned int upkkCRC32(
   _In_ unsigned char *dataBuffer,
   _In_ unsigned int bufferSize
);

Parameters


dataBuffer [in]

Input buffer


bufferSize [in]

Input buffer size in bytes


Return value

Function returns the CRC32 checksum of the given data.


Example unsigned char dataBuffer[] = "1234567890";
unsigned int bufferSize = 10;
unsigned int CRC32checksum;

// calculated checksum should be 0x261DAEE5
CRC32checksum = upkkCRC32(dataBuffer, bufferSize);

upkkCreateDirectory function


Creates a single directory or recursive one from provided full path.

Syntax BOOL upkkCreateDirectory(
   _In_ unsigned char *szDirName
);

Parameters


szDirName [in]

Directory name or full path


Return value

Function returns TRUE on success of FALSE on error.


Example // Create a directory in the current work directory:
upkkCreateDirectory("directory_name");

// or recursively, again in the current work directory:
upkkCreateDirectory("directory_name\\second_nested_directory\\third_nested_directory");

// or from absolute path:
upkkCreateDirectory("C:\\directory_name\\second_nested_directory\\third_nested_directory");

upkkDecompressBuffer function


Decompresses a data with given decompression algorithm.

Syntax byte* upkkDecompressBuffer(
   _In_ int compAlgo,
   _In_ byte *inputBuffer,
   _In_ unsigned long inputBufferSize,
   _Inout_ unsigned long* outputBufferSize
);

Parameters


compAlgo [in]

Defines which compression algorithm should be used. This value can be one of the following:

COMPRESS_ZLIB
(0x10001000)
Deflate compression RFC 1951. It requires zlib1.dll to be located into /libs directory
COMPRESS_DEFLATE
(0x10001000)
Same as COMPRESS_ZLIB
COMPRESS_LZF
(0x10002000)
LZF (Lempel-Ziv Fast) compression LibLZF.
AS OF VERSION 1.0 (build 1002) THIS COMPRESSION IS NOT YET IMPLEMENTED

In near future, more compression algorithms should be added.


inputBuffer [in]

Input data that is going to be decompressed.


inputBufferSize [in]

Length of the input data in bytes.


outputBufferSize [in,out]

Length of the data, after decompression


Return value

If the function success, the return value is a pointer to a buffer holding the decompressed data. The length of the data is contained in the outputBufferSize parameter.
When it's no longer needed, the returned buffer should always be released using upkkReleaseBuffer.
If the function fail, the return value is NULL.


Example byte compressed_buffer[0x100];
byte *uncompressed_buffer;
DWORD uncompressed_buffer_size;

// outputBufferSize must hold a value big enough to fit the uncompressed data
uncompressed_buffer_size = 0x100 * 2;

// Assuming the compressed_buffer is filled with 0x100 bytes of compressed data
// thus the inputBufferSize is 0x100
uncompressed_buffer = upkkDecompressBuffer(COMPRESS_ZLIB, compressed_buffer, 0x100, &uncompressed_buffer_size);

// At this point, uncompressed_buffer is holding the uncompressed data
// and uncompressed_buffer_size is holding the size of that buffer

// When we no longer need the uncompressed data, we can free its buffer
upkkReleaseBuffer(uncompressed_buffer);

upkkINIGetInt function


Obtain an numerical (integer) value from the unpakke.ini file. This file should contain user defined configurable values for the different modules.
Refer to the SDK to learn more about the unpakke.ini file format.

Syntax unsigned int upkkINIGetInt(
   _In_ LPCTSTR lpKeyName,
   _In_ int nDefault
);

Parameters


lpKeyName [in]

Requested key


nDefault [in]

Default value that is used in case the function fails to obtain lpKeyName value.


Return value

If the function success, the return value is the integer value pointed by lpKeyName key.
If the function fails, the return value is the value specified by nDefault.


Example DWORD ini_value;

// Take the variable_name value from the unpakke.ini file (current module section)
// In case the value cannot be obtained (for example if it does not exist)
// it will be replaced by the specified default value of 0x100

ini_value = upkkINIGetInt("variable_name", 0x100);

// At this point ini_value should hold the variable_name value

upkkINIGetString function


Obtain an ASCII (string) value from the unpakke.ini file. This file should contain configurable values for the different modules.
Refer to the SDK to learn more about the unpakke.ini file format.

Syntax unsigned int upkkINIGetString(
   _In_ LPCTSTR lpKeyName,
   _In_ LPCTSTR lpDefault,
   _Inout_ char *lpReturnedString,
   _In_ int nSize
);

Parameters


lpKeyName [in]

Requested key


lpDefault [in]

Default value that is used in case there's no key as the specified by lpKeyName.


lpReturnedString [in,out]

Stores the value of the requested key.


nSize [in]

Length of lpReturnedString.


Return value

On success, the return value is the length of the value specified by lpKeyName.

If the value is bigger than the provided by lpReturnedString buffer, the string is truncated to the length specified by lpReturnedString.

Overall, the function is using GetPrivateProfileString, so further information about the returned value should be found here.


Example char ini_value[0x101];
DWORD ini_value_len;

// Take the variable_name value from the unpakke.ini file (current module section)
// In case the value cannot be obtained (for example if it does not exist or exceeds the buffer length nSize)
// it will be replaced by the specified default value - "default value"

ini_value_len = upkkINIGetString("variable_name", "default value", ini_value, 0x100);

// At this point ini_value should hold the variable_name value
// and ini_value_len will hold its length

upkkReleaseBuffer function


Releases a buffer previously allocated by upkkAllocBuffer or VirtualAlloc.

Syntax BOOL upkkReleaseBuffer(
   _In_ byte *dataBuffer
);

Parameters


dataBuffer [in]

Input buffer that needs to be released


Return value

Function always return TRUE, but that should change in further releases.


Example byte *dataBuffer;

// First we allocate the buffer
dataBuffer = upkkAllocBuffer(5);

/* Your code goes here...
 * 
 */


// Finally, if we don't need this buffer any more, we have to free it:
upkkReleaseBuffer(dataBuffer);

upkkXORBuffer function


Performs the one of most simple and widespread encryption - XOR. The data is XORed against the provided key.

Syntax void upkkXORBuffer(
   _Inout_ byte *dataBuffer,
   _In_ int dataLength,
   _In_ byte *keyBuffer,
   _In_ int keyLength
);

Parameters


dataBuffer [in, out]

Data that needs to be encrypted/decrypted.


dataLength [in]

Length of the data


keyBuffer [in]

Encryption key


keyLength [in]

Length of the encryption key


Return value

Function doesn't return value. Instead, the result is replacing the content of dataBuffer.


Example byte dataBuffer[] = "Super secret data";
int dataLength = 17;
byte keyBuffer[]= "pass";
int keyLength = 4;

// At this point, dataBuffer is not yet encrypted and it looks like:
// 53 75 70 65 72 20 73 65 63 72 65 74 20 64 61 74 61


upkkXORBuffer(dataBuffer, dataLength, keyBuffer, keyLength);
// Now dataBuffer is encrypted and it looks like:
// 23 14 03 16 02 41 00 16 13 13 16 07 50 05 12 07 11


upkkXORBuffer(dataBuffer, dataLength, keyBuffer, keyLength);
// Finally, dataBuffer is again decrypted to its original state:
// 53 75 70 65 72 20 73 65 63 72 65 74 20 64 61 74 61

upkkRawCloseFile function


Closes a raw file handle. This function is a wrapper of CloseHandle.

Syntax void upkkRawCloseFile(
   _In_ HANDLE hFile
);

Parameters


hFile [in]

A file handle.


Return value

Function doesn't return value.


Example HANDLE hFile;
char szFileName[] = "file.bin";

// Open a file
hFile = upkkRawCreateFile(szFileName, OPEN_EXISTING);

// Manipulate the file

// Finally close it
upkkRawCloseFile(hFile);

upkkRawCreateFile function


Creates or opens a existing file. This function is a wrapper of CreateFile.

Syntax HANDLE upkkRawCreateFile(
   _In_ char *filePath,
   _In_ DWORD dwCreationDisposition
);

Parameters


filePath [in]

Filename with or without a file path.


dwCreationDisposition [in]

An action to take on a file or device that exists or does not exist.

CREATE_NEW
(0x00000001)
Creates a new file, only if it does not already exist.
CREATE_ALWAYS
(0x00000002)
Creates a new file.
OPEN_EXISTING
(0x00000003)
Opens a file only if it exists.
OPEN_ALWAYS
(0x00000004)
Opens a file.
TRUNCATE_EXISTING
(0x00000005)
Opens a file and truncates it so that its size is zero bytes, only if it exists.

Return value

Function returns file HANDLE on success or NULL on fail. The returned file HANDLE must be closed by upkkRawCloseFile


Example HANDLE hFile;
char szFileName[] = "file.bin";

// Open a file
hFile = upkkRawCreateFile(szFileName, OPEN_EXISTING);

// Manipulate the file

// Finally close it
upkkRawCloseFile(hFile);

upkkRawReadFile function


Reads from a raw file. This function is a wrapper of ReadFile.

Syntax DWORD upkkRawReadFile(
   _In_ HANDLE hFile,
   _In_ byte *data,
   _In_ DWORD dataSize
);

Parameters


hFile [in]

A handle of a file that is going to be read from.


data [in]

Data buffer that is about to be read to.


dataSize [in]

Size of the data buffer.


Return value

Function returns the number of bytes that were read from the file


Example HANDLE hFile;
char szFileName[] = "file.bin";
byte data_buffer[0x100];

// Open a file
hFile = upkkRawCreateFile(szFileName, OPEN_EXISTING);

// Read 0x100 bytes from the opened file
upkkRawReadFile(hFile, data_buffer, 0x100);

// Finally close it
upkkRawCloseFile(hFile);

upkkRawWriteFile function


Writes to a raw file. This function is a wrapper of WriteFile.

Syntax DWORD upkkRawWriteFile(
   _In_ HANDLE hFile,
   _In_ byte *data,
   _In_ DWORD dataSize
);

Parameters


hFile [in]

A handle of a file that is going to be write to.


data [in]

Data buffer that is about to be written to the file.


dataSize [in]

Size of the data buffer.


Return value

Function returns the number of bytes that were written to the file


Example HANDLE hFile;
char szFileName[] = "file.bin";
byte data_buffer[0x100];

// Open a file
hFile = upkkRawCreateFile(szFileName, OPEN_EXISTING);

// Assuming the data_buffer is holding our data
// Read 0x100 bytes from the opened file
upkkRawWriteFile(hFile, data_buffer, 0x100);

// Finally close it
upkkRawCloseFile(hFile);

upkkCloseStorage function


Closes file handle returned by upkkOpenStorage().

Syntax BOOL upkkCloseStorage(
   _In_ HANDLE storageHandle
);

Parameters


storageHandle [in]

File handle of the storage that needs to be closed.


Return value

This function returns the result of CloseHandle()


Example // Open the storage file
HANDLE hFile = upkkOpenStorage("archive_storage.bin", OPEN_EXISTING);

// At this point the storage file can be manipulated

// when we no longer need the storage file, we must close it
upkkCloseStorage(hFile);

upkkGetData function


Obtains a part of the archive file, based on size and offset.

Syntax byte* upkkGetData(
   _In_ unsigned int dataSize,
   _In_ unsigned int archiveOffset,
   _In_ DWORD dwMoveMethod,
   _In_ HANDLE containerHandle
);

Parameters


dataSize [in]

Length of the requested data


archiveOffset [in]

Offset of the requested data


dwMoveMethod [in]

Offset move method, used the same way as in SetFilePointer function.


This parameter can be be one of these standard predefined values:

FILE_BEGIN
(0x00000000)
Seeks the requested data as relative of the beginning of the file.
FILE_CURRENT
(0x00000001)
Seeks the requested data as relative of the current file pointer.
FILE_END
(0x00000002)
Seeks the requested data as relative of the end of the file.
FILE_IGNORE
(0x00000100)
Entirely ignores the dwMoveMethod parameter.

Additionally, you can specify these predefined values as additions to the standard ones:

FILE_RESTORE
(0x00001000)
Restores the file pointer to its original position before the ReadFile execution.

containerHandle [in]

If the requested data is stored in another file (eg. like in multi-file archives), this value should be set to the handle returned by upkkOpenStorage().
In every other case, this value should be set to NULL.


Return value

No matter of the execution result, the return value is a pointer to a buffer that SHOULD hold the requested data.
This buffer must be released by upkkReleaseBuffer when it's no longer needed.


Example byte* data_buffer;

// Take 0x100 bytes from the base archive, starting at offset 0x10 as relative to FILE_BEGIN
data_buffer = upkkGetData(0x100, 0x10, FILE_BEGIN, NULL);

// At this point data_buffer is ready to be manipulated

// When we no longer need the data_buffer, we must free it:
upkkReleaseBuffer(data_buffer);

upkkExtractData function


Dumps a given data buffer to specified file path.

Syntax BOOL upkkExtractData(
   _In_ LPCTSTR filePath,
   _In_ byte *dataBuffer,
   _In_ int dataLength
);

Parameters


filePath [in]

File path of the extracted file. This can be filename or filepath + file name. If filepath is provided, the directory three before the filename will be recursive created.


dataBuffer [in]

Data buffer holding the file contents


dataLength [in]

Length of the data hold by dataBuffer.


Return value

On success, the return value is TRUE.
If the function fails, the return value is FALSE.


Example char szOutputFile[] = "some_file.bin";
byte data_buffer[0x100];

// Assuming that data_buffer holds the data we want to dump

// Dump the data to the provided file (with or without filepath)
upkkExtractData(szOutputFile, data_buffer, 0x100);

upkkExtractFile function


upkkExtractFile is combination of upkkGetData and upkkExtractData.
The specified length of data, based on the offset is extracted to the provided file path.

Syntax BOOL upkkExtractFile(
   _In_ LPCTSTR filePath,
   _In_ unsigned int dataSize,
   _In_ unsigned int archiveOffset,
   _In_ DWORD dwMoveMethod,
   _In_ HANDLE containerHandle
);

Parameters


filePath [in]

File path of the extracted file.


dataSize [in]

Length of the requested data


archiveOffset [in]

Offset of the requested data


dwMoveMethod [in]

Offset move method, used the same way as in SetFilePointer function.


This parameter can be be one of these standard predefined values:

FILE_BEGIN
(0x00000000)
Seeks the requested data as relative of the beginning of the file.
FILE_CURRENT
(0x00000001)
Seeks the requested data as relative of the current file pointer.
FILE_END
(0x00000002)
Seeks the requested data as relative of the end of the file.
FILE_IGNORE
(0x00000100)
Entirely ignores the dwMoveMethod parameter.

Additionally, you can specify these predefined values as additions to the standard ones:

FILE_RESTORE
(0x00001000)
Restores the file pointer to its original position before the ReadFile execution.

containerHandle [in]

If the requested data is stored in another file (eg. like in multi-file archives), this value should be set to the handle returned by upkkOpenStorage().
In every other case, this value should be set to NULL.


Return value

On success, the return value is TRUE.
If the function fails, the return value is FALSE.


Example char szOutputFile[] = "some_file.bin";

// Dump 0x100 bytes from the base archive, starting at offset 0x10 as relative to FILE_BEGIN
upkkExtractFile(szOutputFile, 0x100, 0x10, FILE_BEGIN, NULL);

upkkGetOffset function


Retrieves the current offset of the archive file.

Syntax DWORD upkkGetOffset(
   _In_ HANDLE storageHandle
);

Parameters


storageHandle [in]

If the requested data is stored in another file (eg. like in multi-file archives), this value should be set to the handle returned by upkkOpenStorage().
In every other case, this value should be set to NULL.


Return value

The return value is the current offset of the archive file.


Example TODO

upkkOpenStorage function


Retrieves a file handle of another file, specified by file path.

Syntax HANDLE upkkOpenStorage(
   _In_ LPCTSTR lpFileName,
   _In_ DWORD dwCreationDisposition
);

Parameters


lpFileName [in]

File path of the requested storage file.


dwCreationDisposition [in]

File action to be performed. This value is equal and directly treated as dwCreationDisposition of the CreateFile function.

CREATE_NEW
(0x00000001)
Creates new file if does not exist already. If the file exists, the function fails.
CREATE_ALWAYS
(0x00000002)
Always creates a new file. If the file already exists, it gets overwritten.
OPEN_EXISTING
(0x00000003)
Opens an existing file. If the file does no exist, the function fails.
OPEN_ALWAYS
(0x00000004)
Opens an existing file. If the file does no exist, it creates it.
TRUNCATE_EXISTING
(0x00000005)
Opens an existing file and deletes its content. If the file does no exist, the function fails.

Return value

On success, function returns the file handle of the storage file.
If the function fails, the return value is NULL.

When the requested storage file is no longer needed, the handle returned by this function should be always freed by upkkCloseStorage().


Example // Open the storage file
HANDLE hFile = upkkOpenStorage("archive_storage.bin", OPEN_EXISTING);

// At this point the storage file can be manipulated

// when we no longer need the storage file, we must close it
upkkCloseStorage(hFile);

upkkInsertData function


Inserts given data to the specified offset of the archive.

Syntax BOOL upkkInsertData(
   _In_ byte *data,
   _In_ int dataSize,
   _In_ unsigned int archiveOffset,
   _In_ DWORD dwMoveMethod,
   _In_ HANDLE containerHandle
);

Parameters


data [in]

Data buffer, that is going to be inserted into the archive.


dataSize [in]

Length of the data


archiveOffset [in]

Destination offset of the data


dwMoveMethod [in]

Offset move method, used the same way as in SetFilePointer function.


This parameter can be be one of these standard predefined values:

FILE_BEGIN
(0x00000000)
Seeks the requested data as relative of the beginning of the file.
FILE_CURRENT
(0x00000001)
Seeks the requested data as relative of the current file pointer.
FILE_END
(0x00000002)
Seeks the requested data as relative of the end of the file.
FILE_IGNORE
(0x00000100)
Entirely ignores the dwMoveMethod parameter.

containerHandle [in]

If the destination is another file (eg. like in multi-file archives), this value should be set to the handle returned by upkkOpenStorage().
In every other case, this value should be set to NULL.


Return value

This function always return TRUE. But that should be changed soon.


Example byte data_buffer[0x100];

// Assuming the data_buffer is filled with 0x100 bytes of data

// Insert 0x100 bytes of the data to the main archive, at offset 0x10 as relative to FILE_BEGIN:
upkkInsertData(data_buffer, 0x100, 0x10, FILE_BEGIN, NULL);

// Or, append the 0x100 bytes of the data to the main archive's end:
upkkInsertData(data_buffer, 0x100, 0, FILE_CURRENT, NULL);

upkkInsertFile function


Inserts the content of a given file, to the specified offset in the destination archive.

Syntax BOOL upkkInsertFile(
   _In_ LPCTSTR filePath,
   _In_ unsigned int archiveOffset,
   _In_ DWORD dwMoveMethod,
   _In_ HANDLE containerHandle
);

Parameters


filePath [in]

File path to the file which data needs to be copied to the archive.


archiveOffset [in]

Destination offset of the data


dwMoveMethod [in]

Offset move method, used the same way as in SetFilePointer function.


This parameter can be be one of these standard predefined values:

FILE_BEGIN
(0x00000000)
Seeks the requested data as relative of the beginning of the file.
FILE_CURRENT
(0x00000001)
Seeks the requested data as relative of the current file pointer.
FILE_END
(0x00000002)
Seeks the requested data as relative of the end of the file.
FILE_IGNORE
(0x00000100)
Entirely ignores the dwMoveMethod parameter.

containerHandle [in]

If the destination is another file (eg. like in multi-file archives), this value should be set to the handle returned by upkkOpenStorage().
In every other case, this value should be set to NULL.


Return value

On success, the return value is TRUE.
If the function fails, the return value is FALSE.


Example char szFileName[] = "file.bin";

// Insert the content of "file.bin" to the main archive, at offset 0x10 as relative to FILE_BEGIN:
upkkInsertFile(szFileName, 0x10, FILE_BEGIN, NULL);

// Or, append the content of "file.bin" to the main archive's end:
upkkInsertFile(szFileName, 0, FILE_CURRENT, NULL);

upkkReadFile function


Read an entire file and return its content as a buffer of bytes. The second argument provided is where the buffer size is returned Inserts the content of a given file, to the specified offset in the destination archive.

Syntax byte* upkkReadFile(
   _In_ LPCTSTR filePath,
   _Out_ DWORD *dataSize
);

Parameters


filePath [in]

File path to the file that it's going to be read.


dataSize [out]

Destination for the file size value


Return value

On success, the return value is pointer to a buffer of bytes.
If the function fails, the return value is NULL.

The second parameter is passed as pointer to a DWORD variable and it's the place where the buffer size is stored.

Always free the returned buffer using upkkReleaseBuffer().


Example byte *data_buffer;
char szFileName[] = "file.bin";
DWORD data_size;

// Read the entire file
data_buffer = upkkReadFile(szFileName, &data_size);

// At this point, data_buffer holds the content of "file.bin"
// and data_size holds the size of that data_buffer


// When we no longer need data_buffer. we must free it
upkkReleaseBuffer(data_buffer);
© nullsecurity.org 2011-2024 | legal | terms & rules | contacts