mirror of
https://git.code.sf.net/p/quake/quakeforge
synced 2024-11-26 14:20:59 +00:00
605d60167d
So I don't have to keep duplicating file names all over the place, I've decided to use the "dox" extension on text files that are formatted for doxygen processing. This way, doxygen can search for them using wildcards, and unformated text files won't cause any headaches.
100 lines
3.7 KiB
Text
100 lines
3.7 KiB
Text
//unfortunately, have to wrap the docs in a C comment for doxygen
|
|
/**
|
|
\page qw_download_spec QW Download Specification
|
|
|
|
client has 'h' flag in "*cap" info string
|
|
|
|
format of svc_download message:
|
|
\verbatim
|
|
<size (short)> <percent (byte)> ([url (string)] [newname (string)] | [data])
|
|
\endverbatim
|
|
|
|
size and percent are always present.
|
|
|
|
url is present only for http redirects.
|
|
|
|
data is present only when size is > 0 (ie, normal downloading)
|
|
|
|
newname is present for all http redirects (but may be the empty string) or if
|
|
the file to download has a different name to what what requested. This is so
|
|
the client saves the downloaded file with the correct name (in QF, this is
|
|
currently used for gzipped transfers, but there are plans to enable whole pak
|
|
downloads (similar to RTCW and ET)).
|
|
|
|
size is the number of data bytes in the message (if >= 0) or a special flag:
|
|
\li -1 file not found. download aborted
|
|
\li -2 download filename is not what was requested (in QF, this is because
|
|
the file has been gzipped and has the .gz extension). In this case,
|
|
newname is in the message. Currently, QF checks newname to ensure the
|
|
only modification is the addition of an extension.
|
|
\li -3 http redirect. url is always present and is the full url to download.
|
|
If the download name is the same as the requested name, newname will
|
|
be the empty string (""), otherwise it contains the new name of the
|
|
file. See -2.
|
|
|
|
QF \#defines for the above values:
|
|
\verbatim
|
|
#define DL_NOFILE -1
|
|
#define DL_RENAME -2
|
|
#define DL_HTTP -3
|
|
\endverbatim
|
|
|
|
Pseudo-code representing client side handling of svc_download
|
|
\verbatim
|
|
CL_ParseDownload
|
|
{
|
|
size = MSG_ReadShort (net_message);
|
|
percent = MSG_ReadByte (net_message);
|
|
if (size == DL_NOFILE) {
|
|
abort download
|
|
return
|
|
}
|
|
if (size == DL_RENAME) {
|
|
newname = MSG_ReadString (net_message);
|
|
if (newname is bad) {
|
|
abort download
|
|
return
|
|
}
|
|
rename file
|
|
return
|
|
}
|
|
if (size == DL_HTTP) {
|
|
url = MSG_ReadString (net_message);
|
|
newname = MSG_ReadString (net_message);
|
|
if (newname != "") {
|
|
if (newname is bad) {
|
|
abort download
|
|
return
|
|
}
|
|
rename file
|
|
}
|
|
start http transfer
|
|
return
|
|
}
|
|
normal download processing
|
|
}
|
|
\endverbatim
|
|
|
|
\note While the QF quakeworld server simply appends the requested file's path
|
|
to the given url base, with the addition of a '/' (eg, "maps/foo.map" to
|
|
"http://server/downloads", giving "http://server/downloads/maps/foo.map"), so
|
|
long as it is reasonable for the client to not rename the download file, there
|
|
is no requirement for the full url to match the requested name in any manner,
|
|
and newname can be left as empty (""). However, if the client must rename the
|
|
file, set newname to the new name. The extension checking is done as a
|
|
security measure.
|
|
|
|
\note Currently, the only reason QF renames a download is if it found eg
|
|
"maps/foo.map.gz" instead of "maps/foo.map" (2:1 to 3:1 compression on maps is
|
|
nice). This is the basis of the extension checking the QF clients do.
|
|
|
|
\todo [this has no bearing on the protocol itself]
|
|
One good reason for the name being quite different is when the requested file
|
|
is part of a pak file (and downloading the pak file is permitted), the entire
|
|
pak file can be sent instead. QF does not yet do this, but it should be easy
|
|
enough to implement: if file_from_pak (from FOpenFile) is set, and pak file
|
|
downloading is permitted, do a rename (-2 for non-http, set newname in http)
|
|
and send that instead. The client can check for a ".pak" extension in the
|
|
rename, permit it, and then cause a rescan of the game directory in order to
|
|
pick up the new pak file.
|
|
*/
|