head	1.11;
access;
symbols
	tonic_4:1.11
	tonic_3:1.11
	tonic_2:1.11
	demo:1.11.0.2
	design_report:1.11
	oral_presentation_freeze:1.2.0.2;
locks; strict;
comment	@% @;


1.11
date	95.12.11.20.33.03;	author hartmans;	state Exp;
branches;
next	1.10;

1.10
date	95.12.11.19.59.45;	author hartmans;	state Exp;
branches;
next	1.9;

1.9
date	95.12.11.14.59.01;	author hartmans;	state Exp;
branches;
next	1.8;

1.8
date	95.12.11.10.25.15;	author hartmans;	state Exp;
branches;
next	1.7;

1.7
date	95.12.09.19.51.09;	author hartmans;	state Exp;
branches;
next	1.6;

1.6
date	95.12.07.23.23.56;	author jered;	state Exp;
branches;
next	1.5;

1.5
date	95.12.07.09.23.49;	author hartmans;	state Exp;
branches;
next	1.4;

1.4
date	95.12.02.09.42.13;	author hartmans;	state Exp;
branches;
next	1.3;

1.3
date	95.12.01.03.38.52;	author hartmans;	state Exp;
branches;
next	1.2;

1.2
date	95.11.30.04.24.16;	author hartmans;	state Exp;
branches
	1.2.2.1;
next	1.1;

1.1
date	95.11.25.10.12.12;	author hartmans;	state Exp;
branches;
next	;

1.2.2.1
date	95.11.30.11.04.44;	author hartmans;	state Exp;
branches;
next	1.2.2.2;

1.2.2.2
date	95.11.30.11.16.04;	author hartmans;	state Exp;
branches;
next	1.2.2.3;

1.2.2.3
date	95.11.30.11.18.17;	author hartmans;	state Exp;
branches;
next	;


desc
@@


1.11
log
@Changes so it goes through latex
@
text
@%Emacs, this is -*- latex -*- 

\chapter {Web protocol}
\label{s:http}

	This section describes the protocol used to communicate
between the web client and the Antichess server.  All protocol
requests shall be encapsulated inside HTTP request.  Currently, all
requests use the HTTP ``get'' method.  The URI transmitted along with
the request shall identify a unique object in the space of the
Antichess server, optionally presenting that object with a request.

\section{Top-level requests}
\label{p:top}


	Several requests can be directed at the root object.  If the root object is queried without a request, the ``welcome'' request as assumed.  Requests to the root object take the form of ``{\tt }http://{\it host\/}:{\it port\/}/{\it request\/}''.
\long\def\rr#1#2{\item[Request: ]|#1|
	\item[Response: ] #2}

\begin{description}

\rr{welcome}{
Presents the Antichess web server home page, which includes  options to get help and to start a game or to view games in progress.}

\rr{new\_game?<{\it arguments\/}>}{ Starts a new game of Antichess.  The arguments are in the standard {\sc WWW URL}-encoded format.  The following list describes available arguments.

\begin{description}

\item[btime:]  The time in seconds for the player who is black

\item[name:]  The name of the human player initiating the request 

	\item[load:] An optional argument.  If specified, it should be
a filename without slashes.  This file will be loaded and should
consist of the board format.

\item[opponent:] A field starting with either ``{\tt h}'' or ``{\tt
c''} that determines whether this will be a human--human or human--computer game

\item[side:] A string starting with ``{\tt b}'' or ``{\tt w}'' or an
uppercase version of the same, indicating whether the game initiator wants to be black of white

\item[wtime: ] How much time (in secods) does white get

\end{description}
}

\rr{incomplete\_games}{Return a web page with buttons that lead to all presently incomplete games}
\rr{{\it nnnn\/}}{Dispatches the rest of the {\sc URI} to the game with {\sc ID} {\it nnnn\/}
}
\end{description}

	In addition, the top level root object also supports requests mandated by the referee protocol.

\section{Requests honored by games}
\label{p:game}

	The game object interprets the null request as an error.
Another possible option would have been to interpret a null request as
a ``|show|'' request, but because the ``|show|'' request is depricated
and broken in a two-player game, we chose not to support any
additional use of this request.


\subsection{Primary protocol}

	The primary game protocol is the enhanced (functional)
protocol that includes all information necessary for complex
activities such as move management and human--human games; it is the
protocol produced internally in responses to requests.  The following request table describes it:

\begin{description}

\rr{display?player={\it num\/}}{ The ``|display|'' request will
display the current state of the game, from the point of view of
player {\it num\/}, where {\it num\/} is a zero-based index, strictly
less than |game::players()|. This display includes a display of game
state (such as winner), state for each player, and state of the board.
Many other requests have ``''display-style'' responses; that means
that their output is in the same format as output for this request.
}

\rr{{\it move\/}/board}{The rest of the request is passed off to the board object.}

\rr{{\it move\/}/player/{\it index\/}}{The request is passed off to player {\it
index\/} or an error is generated if the index is out of bounds.}

\end{description}

	Several requests take {\it move\/} as a variable component of the request.  This stands for the current move number (the first move is~0).  This allows |game| to determine if requests are accidentally generated by the user clicking the back button and getting out of sync with the real game.


\subsection{Compatability protocol}
In addition, a compatability protocol is supported as specified in the
problem set handout.  Requests in the protocol are transformed into
requests against the board, players, or display requests as
appropriate.  Since none of the requests in the protocolspecify a
player, the requests are assumed to apply to the player who
initialized the game.  As a special exception, the ``|detach|''
request applies to the second player to attach the game.

\section{Board requests}

The board requests are implemented in the board hierarchy at |chess_display_board|.    The following requests are implemented:

\begin{description}

\rr{select?player={\it num\/}\&square={\it sq\/}}{ Selects square {\it
sq} on player {\it num\/}'s board.  The display is returned, and if
the player making the selection is active (it is this player's turn),
the square is highlighted.  If a previous selection existed, it is lost.
}
\rr{move?player={\it num\/}\&from={\it square\/}\&to={\it square\/}}{Submit a move on behalf of a player.
}


\rr{dest?player={\it num\/}\&square={\it sq\/}}{
If a source square is selected,  enter a move from source to dest.  Else, return an error.  The move generates a display response.
}

\end{description}


A square is represented as something like ``|a4|''.

\section{Requests on player}
The following requests are supported on players:
\begin{description}
\rr{set\_name?name={\it new name\/}}{ Requests a name change of the
current player.  This requests either returns a display response, a success message, or a failure message.  Any page that is returned will provide a facility to get to a display response of the current state.}

\rr{forfeit}{Requests a human player give up on the game.}


\rr{set\_time?time={\it seconds\/}\&msecs={\it miliseconds\/}}{
Sets the time left on the player; either |time| or |msecs| should be used, but not both.  
It is expected that the form presented to the user will allow setting time only to the granularity of a second.}

\rr{make\_move}{Ask a machine player to make a move.  If this is
impossible (possibly because it is not the machine player's turn), or the machine player is not actually a machine player, this request will fail.  Otherwise, a display response is returned.}

\rr{set?can\_go={\it y/n}} {This request changes whether or not the
|machine\_player| can move without being explicitly told to by a human
player.}

\end{description}
% Other requests needed for things like setting time, etc, etc, etc, etc.





@


1.10
log
@Update design
@
text
@d136 1
a136 1
\rr{set\_time?time={\it seconds\/}&msecs={\it miliseconds\/}}{
d143 3
a145 1
\rr{set?can\_go={\it y/n}} {This request changes whether or not the machine_player can move without being explicitly told to by a human player.} 
@


1.9
log
@Document forfeit
@
text
@d2 1
a2 1
n
d4 1
@


1.8
log
@Define more specs
@
text
@d132 1
d134 1
d147 1
@


1.7
log
@Document set_time
l
@
text
@d33 4
d145 2
@


1.6
log
@More display updates
@
text
@d129 4
@


1.5
log
@random changes I made and forgot about
@
text
@d132 1
a132 1

@


1.4
log
@Move move from player to board.
@
text
@d107 1
a107 1
the square is highlighted.
@


1.3
log
@Integrate oral presentation changes into main line.
@
text
@d109 3
a127 5
\rr{move?from={\it square\/}\&to={\it square\/}}{ Consider making the
move implied by the arguments.  Human players will always take the
suggestion given, even if it is an invalid move (although |game| will
catch this and report it as an error), but machine players probably
will not take hints on where to move.}
@


1.2
log
@Made some changes of some sort
@
text
@d2 1
a2 1

d17 1
a17 1
\def\rr#1#2{\item[Request: ]|#1|
d25 1
a25 1
\rr{new_game?<{\it arguments\/}>}{ Starts a new game of Antichess.  The arguments are in the standard {\sc WWW URL}-encoded format.  The following list describes available arguments.
d68 1
a68 1
\begin{descriptionn}
d104 1
a104 1
\rr{select?player={\it num\/}&square={\it sq\/}}{ Selects square {\it
d110 1
a110 1
\rr{dest?player={\it num\/}&square={\it sq\/}}{
d122 1
a122 1
\rr{set_name?name={\it new name\/}}{ Requests a name change of the
d125 5
a129 1
\rr{move?from={\it square\/}&to={\it square\/}}{ Consider making the move implied by the arguments.  Human players will always take the suggestion  given, even if it is an invalid move (although |game| will catch this and report it as an error), but machine players probably will not take hints on where to move.  
d131 1
a131 1
\rr{make_move}{Ask a machine player to make a move.  If this is
@


1.2.2.1
log
@more fixes
@
text
@d2 1
a2 1
n
d17 1
a17 1
\long\def\rr#1#2{\item[Request: ]|#1|
d68 1
a68 1
\begin{description}
@


1.2.2.2
log
@Additional design fixes
@
text
@d25 1
a25 1
\rr{new\_game?<{\it arguments\/}>}{ Starts a new game of Antichess.  The arguments are in the standard {\sc WWW URL}-encoded format.  The following list describes available arguments.
d104 1
a104 1
\rr{select?player={\it num\/}\&square={\it sq\/}}{ Selects square {\it
d110 1
a110 1
\rr{dest?player={\it num\/}\&square={\it sq\/}}{
d122 1
a122 1
\rr{set\_name?name={\it new name\/}}{ Requests a name change of the
d125 1
a125 1
\rr{move?from={\it square\/}\&to={\it square\/}}{ Consider making the move implied by the arguments.  Human players will always take the suggestion  given, even if it is an invalid move (although |game| will catch this and report it as an error), but machine players probably will not take hints on where to move.  
d127 1
a127 1
\rr{make\_move}{Ask a machine player to make a move.  If this is
@


1.2.2.3
log
@and yet again
@
text
@d125 1
a125 5
\rr{move?from={\it square\/}\&to={\it square\/}}{ Consider making the
move implied by the arguments.  Human players will always take the
suggestion given, even if it is an invalid move (although |game| will
catch this and report it as an error), but machine players probably
will not take hints on where to move.}
@


1.1
log
@Check in first version of HTTP protocol for our ps; this is rough
and not complete, but a good start.
Also, split design.tex into chapters.

to
make any this evening, really.  all of my stuff has been new code.
     UNAUTHENTIC Personal message at 05:11:34 on Sat Nov 25 1995
          From: Gymnast <daveg> on BART-SAVAGEWOOD.MIT.EDU
                     To: hartmans@@ATHENA.MIT.EDU-------------------------------
make any this evening, really.  all of my stuff has been new code.
od start.
@
text
@d13 1
d52 1
@
