If you want your software to work with Software Updata, you should check up the Creating SDF's page first.
Now, before you continue, you need to have full-time webspace on the Internet available to you at your disposal.
This page tells you how to set up an updates database server for your software by using a standard Software Updata protocal.
The list file structure
| Line | Data information |
|---|---|
| 1: | Update title |
| 2: | Author(s) |
| 3: | Release date |
| 4: | Update description |
| 5: | Update files list |
| 6: | Update database ID or download URL |
| 7: | Download file name |
| 8: | Download file MD5 value |
| 9: | Install method |
| 10: | [Blank line] |
| And the next update... | |
|
Please note that the order of data is very important and must be correct otherwise Software Updata will not function correctly. Software Updata has no error checking for errors in the server update list as this would take too long to do, thus no errors must be present otherwise your software users won't be happy! |
|
Example
Map Pack 1 Afrow UK 2004/08/07, 22:51 HI's first map pack containing: hi_sands_v2.bsp, hi_farmhouse.bsp maps\hi_farmhouse.bsp:|maps\hi_sands_v2.bsp:0b5add4a986c http://www.afrowuk.com/downloads/hi_mappack1.zip hi_mappack1.zip b1b731bf8cd7754de2fbd7f06a359320 1 Bob's hotel map Bob 2002/03/14, 6:20 Bob's first map; a hotel! maps\bob_hotel.bsp:00359c97aea9925a5826eba15e691538 http://www.geoshities.com/bob/bob_hotel.zip bob_hotel.zip e5a39797ea6317a6de17bccced660545 1 Bob's hotel map patch Bob 2002/03/14, 6:20 An update for Bob's first map. maps\bob_hotel.bsp:75fdfd6876fd6f7d6f7dffdfdflkuy87 http://www.geoshities.com/bob/bob_hotel-v2.zip bob_hotel-v2.zip 656nwnfgd8gjgrd653u4t59uyfdlut9g 1
Data in detail
| # | Data identity | Possible value |
|---|---|---|
| 1 | Update title | The title for this update. |
| 2 | Author(s) | The authors for this update. |
| 3 | Release date |
Date that this update was released or uploaded (to server). The date should be in the format yyyy/mm/dd (as recommended by W3C) |
| 4 | Update description | Description of what this update is, contains, fixes, or does. |
| 5 | Update files list |
A list of update files and their MD5 values, seperated by pipe-line characters ("|"). For more info, see the update file list section further down this page. |
| 6 | Update database ID or download URL |
The identity for this update, or just the download URL. For more information for using a database identity for a URL server (or not), see the section further down this page. |
| 7 | Download file name | The file name for this download. |
| 8 | Download file MD5 value | The MD5 value for this download file. The MD5 value does not have to be included (you can have it on the URL server instead), or the line can be left blank. |
| 9 | Install method |
Either 1 or 2. 1: The update download is decompressed if the file type is recognised. If it's an EXE or MSI (installers) then it is simply executed for the user. If it is of any other file type, then it is simply copied to the software install folder (like 2 below.) 2: The update download is copied to the software install folder no matter what file type it is. |
| 10 | [Blank line] | Seperates this update data segment and the next one. |
Update list methods
- The list could be generated as output from a web applicated written in e.g. PHP or Perl.
- Or you could create a web application to create a seperate text file list on the server.
- Or you could just hand-write a text file.
Whichever method you use is up to you, but for the Hostile Intent Map Database (my last update database site prior to writing these documents) I used a Perl script which read from the server update database and wrote output to swupdata.txt on the server.
Update list notes
- Each update list segment must be seperated by one blank line (or more). The blank line will tell Software Updata where the current segment ends and where the next segment begins.
- If your update is missing e.g. a title, don't just delete the whole line, but just leave the line blank which will keep the number of data lines intact.
Update files list (on line #5)
Each update file data segment is seperated by pipe-line characters ("|") and should be in the format of file_name.ext:file_md5.
Like so...
[update file 1 path]:[md5]|[update file 2 path]:[md5]|etc...
Notes
- Each update file should have its relative path specified too. E.g. for Quake maps, maps\mapfile.bsp
- An MD5 value is a group of characters that designates a file's identity. If the file is changed in any way, its MD5 value changes.
Software Updata uses this to check if a update file is different (corrupt or old). - MD5 values do not have to be included (you can leave them off completely).
So for example, mymap1.bsp:|mymap2.bsp:|etc...
However, if a update file is found to be corrupt or of an older version, Software Updata will not notice this (as no MD5 value is present). - You can have a very long list of updates (maximum of 8192 characters).
- The file name and MD5 value must be 100% correct. Else, Software Updata will keep reporting that this update still needs updating.
- To create MD5 values use the MakeMD5.exe program located in the 'Cache' folder. The program will make MD5 values for all files in its EXE folder (the folder that you put MakeMD5.exe in).
Using a URL server
A URL server can be used to make the overall updates list download size smaller (useful for large update databases) by passing the download URL to the client only when it is requested.
This is completely optional. You can place the download URL's in the updates list instead (as shown in the example on this page) or you must place the download's ID there instead. Don't use the URLServer attribute in your software's SDF if you do not want to use a URL server.
A URL server should be a web application (e.g. PHP, Perl or ASP) that feeds a download URL for the queried update to the Software Updata program.
To set up a URL server follow the following steps...
- Set the URL server's web address (URL) in your software's SDF...
For this example, we can use 'URLServer=http://www.afrowuk.com/urlserver.php?id='. - Set the update identity in the update list file...
For this example, we can use update ID '54'.
What happens next?
With the above settings set, when Software Updata wants the current update's download URL, it will send a query to 'http://www.afrowuk.com/urlserver.php?id=54' and get the download URL!
Below is how the URL server output should be...
| Line | Data information |
|---|---|
| 1: | Download URL's (multiple URL's seperated by pipe-line characters "|"). |
| 2: |
Download file MD5 value. If you do not wish to include an MD5 value, leave this line blank. |
| 3: | [Blank line] |
Tools
Software Updata comes with two tools as standard.
The first (MakeMD5.exe) generates an MD5 checksum for all files in the same folder that it sits in.
The second (listgen.exe) generates a update list from a config (cfg) file and a folder containing files for the update. Just run Tools\listgen.exe and see what happens! There's more info about this tool further down the page.
Packaging updates
Software Updata automatically decompresses the following archive formats:
- 7z (recommended)
- RAR (recommended)
- ZIP
- GZIP
- TAR
- BZIP2
- CAB
- ARJ
- Z
- CPIO
- RPM
- DEB
- SPLIT
If the file extension is of EXE or MSI, then they are simply executed for the user to install it manually (and will wait for them to finish). If the downloaded update has any other file extension, it is simply copied to the software installation directory. An example of having updates in non-archived files, could be Quake3 with pk3 files (pk3's are already compressed.)
If you want Software Updata to ignore one of the above file types including EXE or MSI (to simply copy them to the software's installation folder) then you should use the IgnoreFileTypes attribute in your SDF. There is more information on the Make SDF's page.
7z and RAR formats are recommended as they compress files better than the other formats, taking up less webspace. However, if you plan on allowing users to download the updates directly from your website, then RAR or ZIP is probably your best solution.
Archives must be compressed with full output folder information. E.g. for the Quake game, map files go into the 'maps' folder, textures into the 'textures' folder and so on.
Even if a archive file only contains e.g. a .exe file, the output folder information for it to be extracted to e.g. "bin" must still be present. Otherwise, files in archives will not be decompressed into the correct software directories.
Maintenance on your server
If you are maintaining your server, place the word "maintain" at the top of the update list, and Software Updata will prevent users from using your service.
Multiple download URL's
Multiple update download URL's can be supplied either via the URL server or in the update list for individual updates. Each URL should be seperated by a pipe-line character, e.g. url1|url2.
If Software Updata finds that the first URL is broken, the next URL is tried.
Download conflicts
In the event that two or more downloads contain one or more of the same files. Software Updata will check these updates and remove one download or the other(s) from the user's updates list screen.
Download statistics
If a URLForward SDF value is set to say for example, http://www.mywebsite.com/swupdata/stats.php?
then that URL will be executed with the update download URL on the end of it:
e.g.
http://www.mysite.com/stats.php?http://www.mysite.com/download/file.zip
stats.php will add to the download count for file.zip (say in a text file on the server) and then forward to the download URL directly with the "Location" header.
Note: Do not use the HTML Meta Refresh attribute to redirect. It will not work.
Here is stats.php as an example...
<?php
// Open stats.txt for reading
$fp = fopen("swupdata/stats.txt", "r");
$downloads = fgets($fp);
fclose($fp);
// Increment download count
$downloads++;
// Write new download count back
$fp = fopen("swupdata/stats.txt", "w");
fwrite($fp, $downloads);
fclose($fp);
// We're done now, lets let them download!
header("Location: " . $QUERY_STRING);
?>
If you have more than one download on your site, you could include a download ID (for example) beside the download URL in the updates list:
e.g. http://www.mysite.com/stats.php?file01;http://www.mysite.com/download/file.zip
Automatic broken link reporting
If a URLReport SDF value is used, then that URL will be executed with the broken URL on the end of it (as the query string) when a download URL is found to be broken.
e.g. http://www.mysite.com/broken.pl?http://www.mysite.com/download/file.zip
Here is brokenurls.pl as an example...
#!/usr/bin/perl -w
print "Content-type: text/html\n\n";
read(STDIN, my $querypost, $ENV{'CONTENT_LENGTH'});
if ($ENV{'QUERY_STRING'}) {
# Write broken download URL to file
open (FILE, ">>brokenurls.txt");
print FILE $ENV{'QUERY_STRING'} . "\n";
close (FILE);
# Output empty file
print " ";
} else {
if ($querypost) {
# Clear list
open (FILE, ">brokenurls.txt");
print FILE "";
close (FILE);
print 'List cleared!';
} else {
# With no query string, print list of broken URL's
my $urls = 0;
open (FILE, "<brokenurls.txt");
while (<FILE>) {
chomp ($_);
$urls++;
print $urls . ': <a href="' . $_ . '">' . $_ . '</a><br />';
}
close (FILE);
if ($urls) {
# Button to clear list
print qq~
<form method="post" action="?">
<p style="text-align: right">
<input type="submit" name="clear" value="Clear List" />
</p>
</form>~;
} else { print 'List is empty!'; }
}
}
Using the listgen.exe tool
Tools\listgen.exe requires listgen.cfg to be present, or another config (cfg) file specified as a parameter (listgen.exe [relative_or_full_cfg_file_path]).
See Tools\listgen.cfg for a config file example.
Run listgen.exe and a update list file will be generated for all files in the SwUpdata folder.
To give files in a folder a specific title, author and description, place a file called listgen.txt in the folder with three lines of text in it. The first line should be the title, the second line the author and the third the description. These will overwrite the general FileTitle, FileAuthor and FileDesc config file attribute values.