518 lines
13 KiB
TeX
518 lines
13 KiB
TeX
\chapter{Communication protocol}
|
|
\label{chapter:communication_protocol}
|
|
|
|
|
|
\section{Server configuration}
|
|
\label{section:communication_protocol:server}
|
|
|
|
On the server there are several configuration files:
|
|
\begin{itemize}
|
|
\item
|
|
The main configuration file, umcd.cfg, this file is stored in the
|
|
data directory, which is a parameter for the programme. This file is
|
|
further discussed in \cref{section:communication_protocol:server:umcd.cfg}.
|
|
|
|
\item
|
|
In this data directory there is a subdirectory per addon. These
|
|
directories have the following files:
|
|
\begin{description}
|
|
\item[umc.cfg]
|
|
The config file for the umc, this file is based on the client's
|
|
pbl file. This file is further discussed in
|
|
\cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[umc.gz]
|
|
The gzipped umc.
|
|
|
|
\item[umc-\emph{lang}.cfg]
|
|
The configuration file for the translation of the umc. The
|
|
\emph{lang} is replace with the locale of the translation.
|
|
This file is further discussed in
|
|
\cref{section:communication_protocol:server:umc-lang.cfg}.
|
|
|
|
\item[umc-\emph{lang}.gz]
|
|
The gzipped mo-file for the translation. Note if the
|
|
compression-ratio for the mo-file is bad, the raw mo-file will be
|
|
stored instead. The final decision in the matter will be specified
|
|
later.
|
|
|
|
\end{description}
|
|
|
|
\end{itemize}
|
|
|
|
|
|
\subsection{umcd.cfg}
|
|
\label{section:communication_protocol:server:umcd.cfg}
|
|
|
|
This file contains the settings of the umcd.
|
|
|
|
\begin{lstlisting}
|
|
[umcd_configuration]
|
|
port = PORT
|
|
threads = THREADS
|
|
|
|
[/umcd_configurattion]
|
|
\end{lstlisting}
|
|
|
|
The keys have the following meaning:
|
|
\begin{description}
|
|
\item[PORT]
|
|
The TCP/IP port to listen to for incoming requests.
|
|
|
|
\item[THREADS]
|
|
The number of listeners threads to start. A value of $0$ means start as
|
|
many threads as there are detected hardware cores\footnote{Whether
|
|
hyper-threading and Co. count as separate cores is unspecified.}.
|
|
|
|
\end{description}
|
|
|
|
|
|
\subsection{umc.cfg}
|
|
\label{section:communication_protocol:server:umc.cfg}
|
|
|
|
This file contains the configuration of the umc on the server. The
|
|
combination of this file together with the various
|
|
\mbox{umc-\emph{lang}.cfg} files form the master information regarding an
|
|
umc. All other files that specify the umc or its wire-protocol get their
|
|
information from these files. Therefore other sections will refer to this
|
|
section.
|
|
|
|
The file is specified like:
|
|
\begin{lstlisting}
|
|
[umc]
|
|
id = ID
|
|
name = NAME
|
|
icon = ICON
|
|
type = TYPE
|
|
description = DESCRIPTION
|
|
version = VERSION
|
|
size = SIZE
|
|
authors = AUTHORS
|
|
email = EMAIL
|
|
uploader_ip_address = UPLOADER_IP_ADDRESS
|
|
timestamp = TIMESTAMP
|
|
downloads = DOWNLOADS
|
|
uploads = UPLOADS
|
|
password = PASSWORD
|
|
language = LANGUAGE
|
|
translatable = TRANSLATABLE
|
|
[dependencies]?
|
|
[dependency]+
|
|
id = ID
|
|
version? = VERSION_MASK
|
|
[/dependency]
|
|
[/dependencies]
|
|
[/umc]
|
|
\end{lstlisting}
|
|
|
|
The keys have the following meaning:
|
|
\begin{description}
|
|
\item[ID]
|
|
The unique id of the content. When uploading this value determines
|
|
whether an umc is the same umc.
|
|
|
|
\item[NAME]
|
|
The name of the content. This string is not unique. This allows two
|
|
versions of the UMC on the server. This can be used to allow a new beta
|
|
next to a stable, as long as the ID differs.
|
|
|
|
\item[ICON]
|
|
The icon of the umc, which is shown in the addon-list on the server.
|
|
TODO it is not yet specified how the icon is transferred to and from the
|
|
client.
|
|
|
|
\item[TYPE]
|
|
The type of the addon. At the moment the following values are allowed:
|
|
\begin{description}
|
|
\item[CAMPAIGN\_SP] A single player campaign.
|
|
\item[CAMPAIGN\_MP] A multi-player player campaign.
|
|
\item[ERA] A multi-player era.
|
|
\item[MAP] A multi-player map.
|
|
\item[MAP\_PACK] A multi-player map pack.
|
|
\item[RPG\_SP]
|
|
A RPG like single player game. (This also includes builder games in
|
|
the style of settlers.)
|
|
|
|
\item[RPG\_MP]
|
|
A RPG like multi-player game. (This also includes builder games in
|
|
the style of settlers.)
|
|
|
|
\item[OTHER] Everything that doesn't fit in one of the above.
|
|
\end{description}
|
|
|
|
\item[DESCRIPTION]
|
|
The description of the umc.
|
|
|
|
\item[VERSION]
|
|
A string determining the version. The string should formatted like:
|
|
`x.y.z' or `x.y.z-q'. When doing so the version can be parsed as version
|
|
number. The `-q' part is sorted alphabetically and is an empty string if
|
|
omitted, thus sorted first.
|
|
|
|
\item[SIZE]
|
|
The size of the umc in bytes packed on the server.
|
|
|
|
\item[AUTHORS]
|
|
A colon separated list of authors of the umc. When there is only one
|
|
author no colon is required.
|
|
|
|
\item[EMAIL]
|
|
The email address of the primary author or a mailinglist. When there are
|
|
problems with the umc the Wesnoth team can use this address to contact
|
|
the authors, so make sure it's valid and doesn't need registration.
|
|
The address is not used in other ways nor shared with third-parties.
|
|
|
|
\item[UPLOADER\_IP\_ADDRESS]
|
|
The ip address of the last uploader of the umc.
|
|
|
|
\item[TIMESTAMP]
|
|
The timestamp of the last upload.
|
|
|
|
\item[DOWNLOADS]
|
|
The number of times the UMC is downloaded.
|
|
|
|
\item[UPLOADS]
|
|
The number of time a new version of the UMC is uploaded.
|
|
|
|
\item[PASSWORD]
|
|
The password required to upload a new version of an umc or remove an umc
|
|
from the server.
|
|
|
|
\item[LANGUAGE]
|
|
The language id of the umc. If omitted American English is assumed.
|
|
This allows umc authors who are not able to create content in English to
|
|
still create content. However it's still recommended to try to write the
|
|
content in American English. (TODO determine whether omitted on the
|
|
server or only during the initial upload, if the latter the server
|
|
should set it if omitted during the upload.)
|
|
|
|
\item[TRANSLATABLE]
|
|
This flag causes the umc to be synchronised with Wescamp. It's advisable
|
|
to only set the flags when the strings are somewhat stable. This flag
|
|
can only be set if the language is American English.
|
|
\end{description}
|
|
|
|
The [dependencies] lists the dependencies of the UMC. This allows the client
|
|
to download all UMC required to use this UMC. The fields mean:
|
|
\begin{description}
|
|
\item[ID]
|
|
The ID of the UMC to depend upon.
|
|
|
|
\item[VERSION\_MASK]
|
|
This mask is used to validate a version used. The format is:
|
|
\begin{description}
|
|
\item[$=$VERSION]
|
|
The version number of the dependency exactly match the VERSION.
|
|
|
|
\item[$>=$VERSION]
|
|
The version number of the dependency must be greater or equal to
|
|
VERSION.
|
|
|
|
\item[$>$VERSION]
|
|
The version number of the dependency must be greater than VERSION.
|
|
|
|
\item[$<$VERSION]
|
|
The version number of the dependency must be less than VERSION
|
|
\item[$<=$VERSION]
|
|
The version number of the dependency must be less than or equal to
|
|
VERSION
|
|
|
|
\end{description}
|
|
Several values can be used in a mask. They are separated by a space. The
|
|
masks are and'ed and the user is responsible for setting a sane value;
|
|
e.g. `$<$1.0.0 $>$1.0.0' can't match a version.
|
|
|
|
If this field is omitted, all versions are allowed.
|
|
|
|
\end{description}
|
|
|
|
|
|
\subsection{umc-\emph{lang}.cfg}
|
|
\label{section:communication_protocol:server:umc-lang.cfg}.
|
|
|
|
The configuration file for the translation of the umc. The
|
|
\emph{lang} is replace with the locale of the translation.
|
|
|
|
\begin{lstlisting}
|
|
[language]
|
|
id = LANGUAGE
|
|
timestamp = TIMESTAMP
|
|
translated = TRANSLATED
|
|
fuzzy = FUZZY
|
|
untranslated = UNTRANSLATED
|
|
[translated_umc_strings]
|
|
name = NAME
|
|
description = DESCRIPTION
|
|
[/translated_umc_strings]
|
|
[/language]
|
|
\end{lstlisting}
|
|
|
|
|
|
|
|
\section{UMC configuration}
|
|
\label{section:communication_protocol:umc}
|
|
|
|
The pbl file contains the information regarding the addon. Its contents are
|
|
stored on the system of the addon developer and on the server. The file
|
|
contains the following data:
|
|
|
|
\begin{lstlisting}
|
|
[umc_configuraton]
|
|
id = ID
|
|
name = NAME
|
|
icon = ICON
|
|
type = TYPE
|
|
description = DESCRIPTION
|
|
version = VERSION
|
|
authors = AUTHORS
|
|
email = EMAIL
|
|
password? = PASSWORD
|
|
language? = LANGUAGE
|
|
translatable = TRANSLATABLE
|
|
[dependencies]?
|
|
[dependency]+
|
|
id = ID
|
|
version? = VERSION_MASK
|
|
[/dependency]
|
|
[/dependencies]
|
|
[/umc_configration]
|
|
\end{lstlisting}
|
|
|
|
The keys have the following meaning:
|
|
\begin{description}
|
|
\item[ID]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[NAME]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[ICON]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[TYPE]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[DESCRIPTION]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[VERSION]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[AUTHORS]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[EMAIL]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[PASSWORD]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
It may be omitted, during the initial upload. In that case the first
|
|
upload results in sending back the password. It's stored in the pbl-file
|
|
and the author doesn't need to remember it.
|
|
|
|
\item[LANGUAGE]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[TRANSLATABLE]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\end{description}
|
|
|
|
\section{Wire}
|
|
\label{section:communication_protocol:wire}
|
|
|
|
\section{Request campaign list}
|
|
\label{wire:request_campaign_list}
|
|
|
|
Request:
|
|
\begin{lstlisting}
|
|
[request_umc_list]
|
|
[/requst_umc_list]
|
|
\end{lstlisting}
|
|
|
|
Replay:
|
|
\begin{lstlisting}
|
|
[umc_list]
|
|
[umc]*
|
|
id = ID
|
|
name = NAME
|
|
type = TYPE
|
|
description = DESCRIPTION
|
|
version = VERSION
|
|
size = SIZE
|
|
authors = AUTHORS
|
|
timestamp = TIMESTAMP
|
|
downloads = DOWNLOADS
|
|
uploads = UPLOADS
|
|
language = LANGUAGE
|
|
[dependencies]?
|
|
[dependency]+
|
|
id = ID
|
|
version? = VERSION_MASK
|
|
[/dependency]
|
|
[/dependencies]
|
|
[languages]?
|
|
[language]+
|
|
id = LANGUAGE
|
|
timestamp = TIMESTAMP
|
|
translated = TRANSLATED
|
|
fuzzy = FUZZY
|
|
untranslated = UNTRANSLATED
|
|
[translated_umc_strings]
|
|
name = NAME
|
|
description = DESCRIPTION
|
|
[/translated_umc_strings]
|
|
[/language]
|
|
[/languages]
|
|
[/umc]
|
|
[/umc_list]
|
|
\end{lstlisting}
|
|
|
|
The fields in [umc] have the following meaning:
|
|
\begin{description}
|
|
\item[ID]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[NAME]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
The version in [language] is the translated name of the UMC.
|
|
|
|
\item[TYPE]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[DESCRIPTION]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[VERSION]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[SIZE]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[TIMESTAMP]
|
|
The timestamp of the last upload. For the [umcs] it is the upload
|
|
of the umc, for the [language] it is the last upload of the
|
|
po-file. (NOTE MERGE WITH MASTER LIST.)
|
|
|
|
\item[DOWNLOADS]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[UPLOADS]
|
|
See \cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
\item[LANGUAGE]
|
|
The id of a language locale. The one in [umc] is the language of
|
|
the UMC. If this language is empty American English is assumed. The UMC
|
|
is only translatable if this is set to American English (this should be
|
|
mentioned in the PBL section).
|
|
\end{description}
|
|
|
|
|
|
The [dependencies] lists the dependencies of the UMC, See
|
|
\cref{section:communication_protocol:server:umc.cfg}.
|
|
|
|
The [languages] contains the list of languages the addon is (partly)
|
|
translated to. The fields mean:
|
|
\begin{description}
|
|
\item[ID]
|
|
The id of the language the translation for.
|
|
|
|
\item[TIMESTAMP]
|
|
The timestamp the po-file was last updated. NOTE UNIX stamp, should be
|
|
at other stamp as well.
|
|
|
|
\item[TRANSLATED]
|
|
The number of translated strings, if this entry is $0$, then the entire
|
|
section is not printed.
|
|
|
|
\item[FUZZY]
|
|
The number of strings that are fuzzy.
|
|
|
|
\item[UNTRANSLATED]
|
|
The number of strings that are not translated.
|
|
|
|
NOTE MAYBE ALSO ADD UP AND DOWNLOAD COUNTER and obviously the SIZE
|
|
\end{description}
|
|
|
|
The section [translated\_umc\_strings] duplicates some strings from the
|
|
general [umc] section. This version contains the translated string from
|
|
the po file. If not translated or fuzzy it contains the original, just like
|
|
normal with gettext. The keys in this section corrospondent with the ones in
|
|
[campaign].
|
|
|
|
\section{Request umc download}
|
|
\label{wire:request_umc_download}
|
|
|
|
This requests to download an umc.
|
|
|
|
Request:
|
|
\begin{lstlisting}
|
|
[request_umc_download]
|
|
id = ID
|
|
[languages]?
|
|
[language]*
|
|
ID = LANGUAGE
|
|
[/language]
|
|
[/languages]
|
|
[/requst_umc_download]
|
|
\end{lstlisting}
|
|
|
|
The fields are:
|
|
\begin{description}
|
|
\item[ID]
|
|
The id of the umc to download.
|
|
|
|
\item[LANGUAGE]
|
|
The id of the requested language to download.
|
|
|
|
\end{description}
|
|
|
|
Replay:
|
|
\begin{lstlisting}
|
|
[umc_download]
|
|
id = ID
|
|
status = STATUS
|
|
[languages]?
|
|
[language]+
|
|
id = LANGUAGE
|
|
status = STATUS
|
|
[/language]
|
|
[/languages]
|
|
[/umc_download]
|
|
\end{lstlisting}
|
|
|
|
This is a mirror of the request, only all items have a status field. The
|
|
status can be OK it the file exists and can be downloaded. Or ERROR if not
|
|
possible.
|
|
|
|
The files send are in the order of appearance in the request and reply. The
|
|
files are named:
|
|
\begin{description}
|
|
\item[ID.gz]
|
|
The gzipped campaign files. The file is packed in a single config file
|
|
to be extracted to the local file-system.
|
|
|
|
\item[ID-LANGUAGE.gz]
|
|
A gzipped mo-file for a language. If gzip's compression ratio for mo
|
|
files is too small the mo-file will be send directly.
|
|
|
|
\end{description}
|
|
|
|
|
|
\section{Request umc change password}
|
|
\label{wire:request_umc_change_password}
|
|
|
|
This request changes the password.
|
|
|
|
|
|
\section{Request umc upload}
|
|
\label{wire:request_umc_upload}
|
|
|
|
|
|
\section{Request umc delete}
|
|
\label{wire:request_umc_delete}
|
|
|
|
\section{Request license}
|
|
\label{wire:request_license}
|