dropbox

libhul -- HoubySoft Update Library

a simple & light auto-update solution for Windows programs

This small (one .c file) library originally resulted from this StackOverflow question of mine. Since nobody came up with a library that did what I wanted, I decided to implement it myself; here's the result.

What is libhul?


A library that makes handling update checking in your C/C++ Windows application as simple as uploading a text file to your site containing information about the latest version, and calling a function in your C/C++ code.

Download

You can either browse the latest source on Github, or download a .zip with source code and binary directly here.

High-level overview

These are the steps that HUL is using to check and apply an update.

1. Download a status file from a predefined URL containing three elements separated by spaces in this order : the latest available version number, an URL to an exe update file (for example, a setup.exe), and an MD5 hash of the exe file specified to verify the integrity of the download.

2. HUL then checks the latest available version number from the status file against the current version of the program. If the latest available version number is higher than the current version number, HUL proceeds to step 3; otherwise, it stops here.

3. HUL checks whether the update was not already downloaded by checking the MD5 of its update file. If the MD5 doesn't match, or no file was found, it downloads the exe file specified in the status file. Then, it computes the MD5 hash for the newly-downloaded file. If the MD5 matches, HUL proceeds to step 4; otherwise, it stops here.

4. HUL creates a new process running the downloaded exe file. The program calling HUL can then quit (so that the exe file can overwrite it in case of an update, for example).


Detailed usage instructions

Installation

Build the library if you downloaded the source only. If you have the mingw suite installed, this is as simple as running mingw32-make. This will create a static library called libhul.a (this file should already be present in the archive if you downloaded the source & binary version). Then, copy hul.h to your compiler's include folder, and libhul.a to your compiler's library folder. When compiling your programs using libhul, #include and link against libhul.a and -lwininet.

Using libhul in your programs

First, you need to write a status file and upload it somewhere on the internet. The syntax for it is very simple; it must be one line, containing the latest version number, then a space, then an internet address to the update setup.exe, another space, and finally a MD5 of the update setup.exe. For example, this is a valid status file:
5.0.1 http://houbysoft.com/download/HCGsetup501.exe 1772edfda0eaf103abf78a5b21b1e9d2

It specifies that the latest version number is 5.0.1; if the client has an older version, the file http://houbysoft.com/download/HCGsetup501.exe will be downloaded and checked to make sure it has MD5 1772edfda0eaf103abf78a5b21b1e9d2.

To check for updates in your program, call the function hul_checkupdates() and save its return value (HUL *). The arguments for hul_checkupdates() are a char * with the current version of the program and a char * with the URL to the status file (i.e. the text file you upload to your server). The return value is a HUL *, which is a struct defined as follows:
typedef struct {
  char *version;
  char *url;
  char *md5;
} HUL;

So for example, if the program is currently version 4.2 and the status file can be found at http://example.com/statusfile, use:

HUL *update = hul_checkupdates("4.2","http://example.com/statusfile");
Then, you must check whether update is NULL or not. If it is NULL, it means an error occured. If it is not NULL, then you must check whether update->version is NULL. If it is NULL, it means the user has the latest version. If it is not, an update is available.

If that is the case, call:

hul_applyupdate(update,callback_function)
whenever you want to apply (i.e. download, MD5 check, and launch) the update. This will block until the update is launched; after it returns, you might want to quit so that the program can be overwritten during the update.
The first argument, update, is a HUL * that you got from hul_checkupdates(); the callback_function is a pointer (void (*statuscallback)(int)) to a function which should be called for status reporting purposes (if you do not want this, just use NULL).
The callback_function should have one int argument. This argument will either be in the range 0-100, in which case it represents the percentage of the download, or it will be one of these statuses (from hul.h):
    HUL_STATUS_DOWNLOAD_FINISHED : means the download finished
    HUL_STATUS_DOWNLOAD_IN_PROGRESS : this is used if it is impossible
        to determine the total size of the download and
        therefore percentages cannot be used.
    HUL_STATUS_CONNECTING : HUL is trying to connect to the update server.


If hul_applyupdate() returns FALSE, it means an error occured and the update could either not be downloaded or verified. If it returns TRUE, it means that the update file was successfully downloaded and was launched using CreateProcess().


Example

Please download the libhul archive, or browse the source at GitHub, and look in the folder "example" for a simple example program using libhul.

Feedback

Feedback, especially bug reports and feature requests, are very welcome. Please use the houbysoft bug tracker or just contact me directly.