Introduction

There may be times when you want to include a binary resource in your apps and extract them later to use on the fly.

How to use the BinRes class

Using the BinRes class is very straightforward. Follow the steps below to use it in an existing project.

After putting the source files (BinRes.cpp and BinRes.h) into the directory you wish to use them from, add the files to your Visual Studio project. Include binres.h in the file you want to use the class:

#include "binres.h"

There is no need to create an instance of BinRes, because all member functions are declared static. Optionally set up an output path where you want the binary file to be written to using setOutputPath.

BinRes::setOutputPath(strPath);

Finally, call ExtractBinResource passing through the resource name, the resource identifier and the output name you would like for the binary file. E.g.

CTestHarnessDlg::OnExtractResource()
{
    BinRes::ExtractBinResource("BIN", 132, "debugViewer.exe");
}

That's all you have to do to take advantage of the BinRes class.

Setting up your binary resource

The first thing we need to do to use the class BinRes in our application is to add a binary file. For my included binary file I decided to visit www.sysinternals.com and downloaded the most excellent DebugView application (which allows you to monitor OutputDebugString calls on your local system). This is the binary exe we will use and add to our resources.

Sample Image

Okay, select the ResourceView tab in Visual Studio, right mouse click the resources and select import to import a new resource.

Sample Image

At the Import Resource Dialog select "Custom" from the Open as combo box, and "All Files (*.*)" from the Files of type combo box and navigate to the binary file you are going to add to your resources. I have selected Dbgview.exe

Sample Image

At the Custom Resource Type dialog box enter a suitable name. I have chosen "BIN" which is short for, you guessed it, BINARIES

And that's it. We have successfully added a binary resource to our test app resources. Now lets move on to looking at how to use the code.

Examining the code

The main function that is used with the BinRes class is ExtractBinResource. Let's now dissect this class function to see exactly what is going on. Here is the function in its entirety.

void BinRes::ExtractBinResource(std::string strCustomResName, 
                int nResourceId, 
                std::string strOutputName)
{
    HGLOBAL hResourceLoaded;  // handle to loaded resource
    HRSRC   hRes              // handle/ptr to res. info.
    char    *lpResLock        // pointer to resource data
    DWORD   dwSizeRes;
    std::string strOutputLocation;
    std::string strAppLocation;

    // lets get the app location
    strAppLocation = getAppLocation();
    strOutputLocation = strAppLocation += "\\";
    strOutputLocation += strOutputName;

    hRes = FindResource(NULL, 
                        MAKEINTRESOURCE(nResourceId), 
                        strCustomResName.c_str()
                    );

    hResourceLoaded = LoadResource(NULL, hRes);
    lpResLock = (char *) LockResource(hResourceLoaded);
    dwSizeRes = SizeofResource(NULL, hRes);

    std::ofstream outputFile(strOutputLocation.c_str(), std::ios::binary);
    outputFile.write((const char *) lpResLock, dwSizeRes);
    outputFile.close();
}

After we have set up variables the first API that is called is FindResource. This finds the location of the resource identified by nResourceId and gets a handle to it. Obviously, we need this handle so we can load the resource.

hRes = FindResource(NULL, 
                    MAKEINTRESOURCE(nResourceId), 
                    strCustomResName.c_str()
                );

The next line loads our resource into memory so we can work with it.

hResLoad = LoadResource(NULL, hRes);

Once our resource is loaded we get a pointer to it so we can traverse and write the data to an output file. We get a pointer by calling LockResource.

lpResLock = (char *) LockResource(hResLoad);

Now we have a pointer to the resource in memory but how big is the resource? How do we know when to stop writing data to the output file? Ideally we need to get size of the resource, and we do this by calling the aptly named API, SizeofResource.

dwSizeRes = SizeofResource(NULL, hRes);

Now we have got everything we need to write out the data to the file. We have the output name (that's passed in to us by the caller, a pointer to our resource in memory and the size of the resource, so the next thing we do is open an output stream for our file.

std::ofstream outputFile(strTemp.c_str(), std::ios::binary);

With our output file open we then write the resource data in memory to the open file using ofstream's write.

outputFile.write((const char *) lpResLock, dwSizeRes);

And the final step is to close the file.

outputFile.close();

ExtractBinResource parameters explained

The first parameter is the name of the new Resource Type we created, when we added our binary resource to the project. In our case we named the new type "BIN", and this is what we pass through.
The second parameter is the resource id for our binary resource. In the ResourceView tab it is shown as IDR_BIN1 but if you open resource.h you will see that IDR_BIN1 is an alias for a number. This is the number we need to pass through as the second parameter.
The third parameter is the output name of the binary file that is preferred. Simple!

BinRes::ExtractBinResource("BIN", 132, "debugViewer.exe");

Conclusion

And that's it! Et Voila. My first CP article completed. Possible improvements to the class could include adding an output location. At the moment the file is outputted to the same directory the program is run in.

And of course all suggestions/feedback/bug reports are welcomed.

History

Version 1 - 21 May 2003 - First version

Adding and extracting binary resources