File: ext_protocol.html

package info (click to toggle)
slashem 0.0.7E7F2-3
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,456 kB
ctags: 22,409
sloc: ansic: 263,134; cpp: 7,180; yacc: 2,154; sh: 737; lex: 440; makefile: 150; awk: 97; sed: 11
file content (1762 lines) | stat: -rw-r--r-- 56,373 bytes
parent folder | download | duplicates (10)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- $ Id: $ -->
<html>
<head>
   <title>NhExt: A protocol for NetHack plug-in window ports</title>
</head>
<body>
<h1>NhExt: A protocol for NetHack plug-in window ports</h1>

<p>This document describes NhExt 1.0.2, a protocol to be used when NetHack
calls a function located inside a plug-in window port and for when that window
port function in turn calls a function located inside NetHack (a call back).
The protocol specifies no limit to the depth of recursion which may occur.

<p>NhExt requires a two-way, single duplex, connection between the
game and the window-port. How that connection is set up is outside the
scope of the protocol.

<p>NhExt has provision for more than one sub-protocol, to allow for
future backwards compatibility. Initially, both the game and the
window port should be in sub-protocol 0. Sub-protocols 0 and 1 must
be supported by games; sub-protocol 2 is optional (this is to maintain
compatibility with NhExt 1.0).

<h1>Sub-protocol 0</h1>

Sub-protocol 0 is line based. Each line consists of a series of characters
terminated with <em>one</em> end-of-line character. The game will always
use the ASCII NL character (code 0x0A) for this, but it will accept either ASCII
NL or CR (codes 0x0A and 0x0D) - but not both.

<p>The game will always start by writing a line consisting of the five
characters "NhExt" which will be followed by a number of tags and values.

<p>Tags are sequences of up to 64 alpha-numeric characters, plus "_".

<p>Values are sequences of up to 64 printable ASCII characters (space to "~"),
enclosed in double quote marks. Characters may be escaped with backslash.
If every character was escaped, and including the two enclosing quotes, a
64 character sequence could take 130 bytes to transmit.

<p>Tags need not be in any order within the line.

<p>Tags and values are seperated from each other (and from the "NhExt" command)
by one space character.

<p>The following tags will <em>always</em> be present:
<ul>
<li><strong>standard</strong>. The NhExt standard to which the game complies.
NhExt standards are always of the form major.minor where major and minor are
non-negative decimal numbers. Micro revisions (eg., 1.0.1) are fully compatible
with each other and are therefore not important. Games complying to a later
standard will be compatible with window ports complying with an earlier
standard in the same series (having the same major number). Window ports should
refuse to connect to a game with a major number greater than the standard to
which they comply; they should connect with full functionality to a game with
the same major number and with a minor number no lower than the standard to
which they comply. Window ports may connect to games complying to earlier
revisions of the standard if they are able to modify their functionality to
comply with the earlier standard.
<li><strong>game</strong>. This value can be used to distinguish vanilla
NetHack (which uses the value "NetHack") from its variants
(eg., Slash'EM uses the value "SlashEM").
<li><strong>version</strong>. This is the value of <code>VERSION_STRING</code>.
<li><strong>protocols</strong>. This is a comma seperated list of protocols
that this game supports. There should be no whitespace in the list.
Sub-protocol zero is not listed.
</ul>

<p>The following tag may also be present:
<ul>
<li><strong>authmethods</strong>. This is a comma seperated list of
authentication methods that this game allows. There should be no whitespace
in the list. If this tag is not present, its value should be taken as
&quot;0&quot;.
</ul>

<p>Window ports should ignore tags they do not recognize.

<p>Example:
<pre>
NhExt standard "1.0" game "NetHack" version "3.3.2" protocols "1" junk "foo \" bar"
</pre>

<p>The window-port should reply with either an error or an acknowledgment
response.

<p>An error response consists of the five characters "Error" followed by a
"mesg" tag and a value. As a special case, this value may be up to 200
characters in length.

<p>Example:
<pre>
Error mesg "X11: Can't open display (Permission denied)"
</pre>

<p>There may also be other tags present, which will be ignored.

<p>The game will respond to an error response by displaying the error
message to the user and then terminating.

<p>An acknowledgment response consists of the three characters "Ack" followed
by a number of tags and values.

<p>The following tags <em>must</em> always be present:
<ul>
<li><strong>windowtype</strong>. The name of the window-port.
<li><strong>protocol</strong>. The sub-protocol to use.
</ul>

<p>The following tags may be present:
<ul>
<li><strong>authmethod</strong>. The authentication method used.
If this tag is not present, its value should be taken as &quot;0&quot;.
<li><strong>username</strong>. The user name for authentication.
<li><strong>password</strong>. The password for authentication.
</ul>

<p>The game will ignore tags it does not recognize.

<p>Example:
<pre>
Ack windowtype "Gtk" protocol "1"
</pre>

On receipt of an acknowledgment response, the game will immediately start
the requested sub-protocol. The window-port should enter listening mode.

<h2>Authentication</h2>

<p>There is currently just one method of authentication defined (in addition
to method 0). This is a simple password authenticaion scheme which transmits
the password in clear text. A future version of this standard may define a
more secure authentication method, perhaps along the same lines as RFC 2195.

<p>Game servers that wish to take advantage of authentication should declare
that they allow authentication by method 1 and optionally also via method 0
if they wish to allow non-authenticated users. On receipt of an acknowledgment
response, the game should check that the authenticaion method employed is
allowed and, in the case of method 1, that the user name and password are
acceptable. The game should then remember whether the remote interface is
authenticated or not. Note that a compliant game may <em>not</em> refuse to
enter the requested sub-protocol even if authentication fails.

<p>If authentication fails then the game should issue an error and exit after
the error is displayed and acknowledged by the user (eg., by using
display_nhwindow with blocking set to TRUE). Games may fail all callbacks
received during this period (while still sending replies where required).

<p>Example:
<pre>
NhExt standard "1.0" game "SlashEM" version "0.0.7E6F2" protocols "1,2" authmethods "1"
Ack windowtype "Gtk" protocol "2" authmethod "1" username "fred" password "secret"
</pre>

<h1>Sub-protocol 1</h1>

<p>This sub-protocol is heavily based on Sun Microsystem's XDR protocol,
documented in <A HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1014.html">
RFC 1014</A>. In addition, I use their XDR language to describe the structure
of request and reply encodings.
It should be possible to use their rpcgen program (supplied with
Solaris) to generate routines to encode and decode data compatible with
sub-protocol 1. There is, however, no need to use rpcgen.

<p>I have also plagiarised window.doc mercilessly.

<p>Sub-protocol 1 is fully synchronous.  That is, at any time either the
game is waiting for input and the window-port is either writing data or
is not yet ready to write data, or the reverse is true.

<h2>  Window Types and Terminology</h2>

<p>There are 5 basic window types, used to call create_nhwindow:

<p><table>
<tr><td>NHW_MESSAGE	</td><td>(top line)</td></tr>
<tr><td>NHW_STATUS	</td><td>(bottom lines)</td></tr>
<tr><td>NHW_MAP		</td><td>(main dungeon)</td></tr>
<tr><td>NHW_MENU	</td><td>(inventory or other "corner" windows)</td></tr>
<tr><td>NHW_TEXT	</td><td>(help/text, full screen paged window)</td></tr>
</table>

<p>The tty window-port also uses NHW_BASE (the base display) internally.

<p>NHW_MENU windows can be used for either menu or text display.  Their
basic feature is that for the tty-port, if the window is small enough,
it appears in the corner of the tty display instead of overwriting
the whole screen.  The first call to add information to the window
will decide if it is going to be used to display a menu or text.
If start_menu() is called, then it will be used as a menu.  If
putstr() is called, it will be used as text.  Once decided, there
is no turning back.  For the tty-port, if the data is too large for
a single screen then the data is paged (with --more--) between pages.
Only NHW_MENU type windows can be used for menus.

<p>NHW_TEXT windows are used to display a large amount of textual data.
This is the type of window one would use for displaying a help file,
for example.  In the tty window-port, windows of type NHW_TEXT can
page using the DEF_PAGER, if DEF_PAGER is defined.  There exists an
assumption that the font for text windows is monospaced.  The help
files are all formatted accordingly.

<p>"window" is always of type int. The proxy module will convert to and
from winids if it ever needs to.  There are
a few fixed window names that are known throughout the code:

<p><table>
<tr><td>WIN_MESSAGE	</td><td>(top line)</td></tr>
<tr><td>WIN_STATUS	</td><td>(bottom lines)</td></tr>
<tr><td>WIN_MAP		</td><td>(main dungeon)</td></tr>
<tr><td>WIN_INVEN	</td><td>(inventory)</td></tr>
</table>

<p>Other windows are created and destroyed as needed.

<p>"Port" in this document refers to a CPU/OS/hardware platform (UNIX, MSDOS
TOS, etc.)  "window-port" refers to the windowing platform.  This is
orthogonal (e.g.  UNIX might use either a tty window-port or an X11
window-port).

<h2>Standard window port procedures</h2>

These procedures must be supported by all plug-in window ports (although for
many procedures they need not actually do anything). Depending on the
setting of the configuration variables, the game may never call some of
these. Such configuration variables have no effect on the values of
the IDs.

<p><table>
<tr><th>Procedure</th><th>ID</th></tr>
<tr><td>init</td><td>0x01</td></tr>
<tr><td>init_nhwindows</td><td>0x02</td></tr>
<tr><td>player_selection</td><td>0x03</td></tr>
<tr><td>askname</td><td>0x04</td></tr>
<tr><td>get_nh_event</td><td>0x05</td></tr>
<tr><td>exit_nhwindows</td><td>0x06</td></tr>
<tr><td>suspend_nhwindows</td><td>0x07</td></tr>
<tr><td>resume_nhwindows</td><td>0x08</td></tr>
<tr><td>create_nhwindow</td><td>0x09</td></tr>
<tr><td>clear_nhwindow</td><td>0x0A</td></tr>
<tr><td>display_nhwindow</td><td>0x0B</td></tr>
<tr><td>destroy_nhwindow</td><td>0x0C</td></tr>
<tr><td>curs</td><td>0x0D</td></tr>
<tr><td>putstr</td><td>0x0E</td></tr>
<tr><td>display_file</td><td>0x0F</td></tr>
<tr><td>start_menu</td><td>0x10</td></tr>
<tr><td>add_menu</td><td>0x11</td></tr>
<tr><td>end_menu</td><td>0x12</td></tr>
<tr><td>select_menu</td><td>0x13</td></tr>
<tr><td>message_menu</td><td>0x14</td></tr>
<tr><td>update_inventory</td><td>0x15</td></tr>
<tr><td>mark_sync</td><td>0x16</td></tr>
<tr><td>wait_sync</td><td>0x17</td></tr>
<tr><td>cliparound</td><td>0x18</td></tr>
<tr><td>update_positionbar</td><td>0x19</td></tr>
<tr><td>print_glyph</td><td>0x1A</td></tr>
<tr><td>raw_print</td><td>0x1B</td></tr>
<tr><td>raw_print_bold</td><td>0x1C</td></tr>
<tr><td>nhgetch</td><td>0x1D</td></tr>
<tr><td>nh_poskey</td><td>0x1E</td></tr>
<tr><td>nhbell</td><td>0x1F</td></tr>
<tr><td>doprev_message</td><td>0x20</td></tr>
<tr><td>yn_function</td><td>0x21</td></tr>
<tr><td>getlin</td><td>0x22</td></tr>
<tr><td>get_ext_cmd</td><td>0x23</td></tr>
<tr><td>number_pad</td><td>0x24</td></tr>
<tr><td>delay_output</td><td>0x25</td></tr>
<tr><td>change_color</td><td>0x26</td></tr>
<tr><td>change_background</td><td>0x27</td></tr>
<tr><td>set_font_name</td><td>0x28</td></tr>
<tr><td>get_color_string</td><td>0x29</td></tr>
<tr><td>start_screen</td><td>0x2A</td></tr>
<tr><td>end_screen</td><td>0x2B</td></tr>
<tr><td>outrip</td><td>0x2C</td></tr>
<tr><td>preference_update</td><td>0x2D</td></tr>
<tr><td>status</td><td>0x2E</td></tr>
<tr><td>print_glyph_layered</td><td>0x2F</td></tr>
<tr><td>send_config_file</td><td>0x30</td></tr>
</table>

<p>Plug-in window ports may define non-standard procedures with IDs of 0x8000 and
above. In response to all other IDs, the window port should return a reply
packet with no results.

<p>The proxy module will initiate a procedure by writing an unsigned integer
(according to RFC1014) whose value is as follows:

<pre>
	value = (ID << 16) | (length >> 2);
</pre>
where <code>length</code> is the length of the following data (<em>not</em>
including <code>value</code>) in bytes. It will then write the relevant
request structure (if a procedure takes no arguments then length will be
zero and no request structure will be written).

<p>The proxy module will then read back an unsigned integer from the plug-in
window-port and decode it as follows:

<pre>
	ID = value >> 16;
	length = (value & 0xffff) << 2;
</pre>

If <code>ID</code> is non-zero, this is a <a href="#callbacks">callback</a>.

<p>If <code>ID</code> is zero, this is a reply to the active procedure. The
proxy module will read that many bytes from the plug-in window-port and
process the reply.

<h3>init</h3>
init takes no arguments and returns no results.

<p>This procedure will be called once before all other procedures.

<h3>init_nhwindows</h3>
<pre>
typedef string argument<>;
typedef string wincap<>;

struct init_nhwindows_req {
	argument argv<>;
};

struct init_nhwindows_res {
	bool inited;
	argument argv<>;
	wincap capabilities<>;
};
</pre>

<p><ul>
<li> Initialize the windows used by NetHack.  This can also
   create the standard windows listed at the top, but does
   not display them.
<li> Any commandline arguments relevant to the windowport
   should be interpreted,
   <var>argv</var> should be changed to remove those arguments and returned.
<li> When the message window is created, 
   <var>inited</var> needs to be returned as <code>TRUE</code>.  Otherwise
   all <code>plines()</code> will be done via raw_print.
<li>ALI: Would a window-port ever want to leave
   <code>iflags.window_inited FALSE</code>?
<li>The capabilities list should be filled in with the relevant values.
The proxy module will ignore capabilities that it does not recognize.
The following capabilities are currently understood:
<ul>
<li>align_message
<li>align_status
<li>ascii_map
<li>color
<li>eight_bit_tty
<li>font_map
<li>font_menu
<li>font_message
<li>font_size_map
<li>font_size_menu
<li>font_size_message
<li>font_size_status
<li>font_size_text
<li>font_status
<li>font_text
<li>hilite_pet
<li>map_mode
<li>mouse_support
<li>perm_invent
<li>player_selection
<li>popup_dialog
<li>preload_tiles
<li>scroll_amount
<li>scroll_margin
<li>splash_screen
<li>tiled_map
<li>tile_file
<li>tile_height
<li>tile_width
<li>use_inverse
<li>var_msgcount
<li>windowcolors
</ul>
</ul>

<h3>player_selection</h3>
<p><pre>
struct player_selection_req {
	int initrole;
	int initrace;
	int initgend;
	int initalign;
};

struct player_selection_res {
	int role;
	int race;
	int gend;
	int align;
	bool quit;
};
</pre>
<p>Do a window-port specific player type selection.  If
player_selection offers a Quit option, it should return
<code>TRUE</code> in <var>quit</var> if this is selected.

<h3>askname</h3>
askname takes no arguments.
<pre>
struct askname_res {
	string plname<>;
};
</pre>

<p>Ask the user for a player name and return it.

<h3>get_nh_event</h3>
get_nh_event takes no arguments and returns no results.

<p>Does window event processing (e.g. exposure events).
		   A noop for the tty and X window-ports.
<h3>exit_nhwindows</h3>
<pre>
struct exit_nhwindows_req {
	string str<>;
};
</pre>
exit_nhwindows returns no results.

		<p>Exits the window system.  This should dismiss all windows,
		   except the "window" used for raw_print().  <var>str</var> is printed
		   if possible.

<h3>suspend_nhwindows</h3>
<pre>
struct suspend_nhwindows_req {
	string str<>;
};
</pre>
suspend_nhwindows returns no results.

		<p> Prepare the windows to be suspended.

<h3>resume_nhwindows</h3>
resume_nhwindows takes no arguments and returns no results.

		<p> Restore the windows after being suspended.
<h3>create_nhwindow</h3>
<pre>
enum nhwindow_type {
    NHW_MESSAGE = 1,		/* (top line) */
    NHW_STATUS = 2,		/* (bottom lines) */
    NHW_MAP = 3,		/* (main dungeon) */
    NHW_MENU = 4,		/* (inventory or other "corner" windows) */
    NHW_TEXT = 5		/* (help/text, full screen paged window) */
};

struct create_nhwindow_req {
    enum nhwindow_type type;
};

struct create_nhwindow_res {
    int window;
};
</pre>
<p> Create a window of type <var>type</var>.

<h3>clear_nhwindow</h3>
<pre>
struct clear_nhwindow_req {
    int window;
    int rows;
    int cols;
    int layers;
};
</pre>
clear_nhwindow returns no results.

<p> Clear the given window, when appropriate.

<p> For windows of type NHW_MAP, the <var>rows</var>, <var>cols</var> and
<var>layers</var> fields specify the number of rows, columns and layers
to be used for this window from now until the next call to clear the window.
Windowing interfaces which choose not to use layered glyphs may ignore this
value.

<h3>display_nhwindow</h3>
<pre>
struct display_nhwindow_req {
    int window;
    bool blocking;
};
</pre>
display_nhwindow returns no results.

<P> Display the window on the screen.  If there is data
   pending for output in that window, it should be sent.
   If <var>blocking</var> is <code>TRUE</code>, display_nhwindow will not
   return until the data has been displayed on the screen,
   and acknowledged by the user where appropriate.
<P> All calls are blocking in the tty window-port.
<P> Calling <code>display_nhwindow(WIN_MESSAGE,???)</code>
will do a
   <samp>--more--</samp>, if necessary, in the tty window-port.

<h3>destroy_nhwindow</h3>
<pre>
struct destroy_nhwindow_req {
    int window;
};
</pre>
destroy_nhwindow returns no results.

<p> Destroy will dismiss the window if the window has not
   already been dismissed.

<h3>curs</h3>
<pre>
struct curs_req {
    int window;
    int x;
    int y;
};
</pre>
curs returns no results.

<p> Next output to window will start at (<var>x</var>,<var>y</var>), also moves
displayable cursor to (<var>x</var>,<var>y</var>). For backward compatibility,
   1&nbsp;<=&nbsp;<var>x</var>&nbsp;<&nbsp;cols,
   0&nbsp;<=&nbsp;<var>y</var>&nbsp;<&nbsp;rows, where cols and rows are
   the size of window.
<p> For variable sized windows, like the status window, the
   behavior when curs is called outside the window's limits
   is unspecified. The mac port wraps to 0, with the status
   window being 2 lines high and 80 columns wide.
<p> Still used by <code>curs_on_u()</code>, status updates, screen locating
   (identify, teleport).
<p> <code>NHW_MESSAGE</code>, <code>NHW_MENU</code> and <code>NHW_TEXT</code>
   windows do not currently support curs in the tty window-port.

<h3>putstr</h3>
<pre>
enum nhwindow_atr {
    ATR_NONE = 0,
    ATR_BOLD = 1,
    ATR_DIM = 2,
    ATR_ULINE = 4,
    ATR_BLINK = 5,
    ATR_INVERSE = 7
};

struct putstr_req {
    int window;
    enum nhwindow_atr attr;
    string str<>;
};
</pre>
putstr returns no results.

<p> Print <var>str</var> on the window with the given attribute.  Only
   printable ASCII characters (040-0126) must be supported.
   Multiple putstrs are output on separate lines.  Attributes
   can be one of
	<code>ATR_NONE</code> (or 0),
	<code>ATR_ULINE</code>,
	<code>ATR_BOLD</code>,
	<code>ATR_BLINK</code>,
	<code>ATR_INVERSE</code>.
   If a window-port does not support all of these, it may map
   unsupported attributes to a supported one (e.g. map them
   all to <code>ATR_INVERSE</code>).  putstr may compress spaces out of
   <var>str</var>, break <var>str</var>, or truncate <var>str</var>, if necessary for the
   display.  Where putstr breaks a line, it has to clear
   to end-of-line.
<p> putstr should be implemented such that if two putstrs
   are done consecutively the user will see the first and
   then the second.  In the tty port, <code>pline()</code> achieves this
   by calling <code>more()</code> or displaying both on the same line.

<h3>display_file</h3>
<pre>
struct display_file_req {
    int fh;
};
</pre>
display_file returns no results.

<p> Display the file whose handle is <var>fh</var>.
<p> The proxy module is responsible for opening the file to be displayed
  as if the dlbh_fopen callback had been called. The window-port should
  read the data from the file using the dlbh_fgets callback (passing it
  <var>fh</var> as the handle). When the display_file procedure returns,
  the proxy module will close the file again.
<p>The proxy module is responsible for complaining (via <code>pline</code>)
  if the file cannot be opened (in which case this procedure will not
  be initiated).

<h3>start_menu</h3>
<pre>
struct start_menu_req {
    int window;
};
</pre>
start_menu returns no results.

<p> Start using window as a menu.  You must call start_menu
   before add_menu.  After calling start_menu you may not
   putstr to the window.  Only windows of type <code>NHW_MENU</code> may
   be used for menus.

<h3>add_menu</h3>
<pre>
struct add_menu_req {
    int window;
    int glyph;
    int identifier;
    int accelerator;
    int groupacc;
    int attr;
    string str<>;
    bool preselected;
};
</pre>
add_menu returns no results.

<p> Add a text line <var>str</var> to the given menu window.
If <var>identifier</var>
   is 0, then the line cannot be selected (e.g. a title).
   Otherwise, <var>identifier</var> is the value returned if the line is
   selected.  <var>accelerator</var> is a keyboard key that can be used
   to select the line.  If the accelerator of a selectable
   item is 0, the window system is free to select its own
   accelerator.  It is up to the window-port to make the
   accelerator visible to the user (e.g. put <samp>a - </samp> in front
   of <var>str</var>).  The value <var>attr</var> is the same as in putstr.
   <var>glyph</var> is an optional glyph to accompany the line.  If
   window port cannot or does not want to display it, this
   is OK.  If there is no glyph applicable, then this
   value will be -1 (converted from NO_GLYPH by the proxy module).
<p> All accelerators should be in the range [A-Za-z].
<p> It is expected that callers do not mix accelerator
   choices.  Either all selectable items have an accelerator
   or let the window system pick them.  Don't do both.
<p> <var>groupacc</var> is a group accelerator.  It may be any character
   outside of the standard accelerator (see above) or a
   number.  If 0, the item is unaffected by any group
   accelerator.  If this accelerator conflicts with
   the menu command (or their user defined alises), it loses.
   The menu commands and aliases take care not to interfere
   with the default object class symbols.
<p> If you want this choice to be preselected when the
   menu is displayed, set <var>preselected</var> to <code>TRUE</code>.
<p>The proxy module is responsible for converting the game's
<code>anything</code> identifiers into integers (and back again in select_menu).

<h3>end_menu</h3>
<pre>
struct end_menu_req {
    int window;
    string prompt<>;
};
</pre>
end_menu returns no results.

<p> Stop adding entries to the menu and flushes the window
   to the screen (brings to front?).  <var>prompt</var> is a prompt
   to give the user.  If <var>prompt</var> is an empty string, no prompt will
   be printed.
<blockquote>
This probably shouldn't flush the window any more (if
it ever did).  That should be select_menu's job.  -dean
</blockquote>

<h3>select_menu</h3>
<pre>
enum menu_pick {
    PICK_NONE = 0,  /* user picks nothing (display only) */
    PICK_ONE = 1,   /* only pick one */
    PICK_ANY = 2    /* can pick any amount */
};

struct select_menu_req {
    int window;
    enum menu_pick how;
};

struct select_menu_res_item {
    int item;       /* identifier */
    long count;     /* count */
};

struct select_menu_res {
    int retval;
    select_menu_res_item selected<>;
};
</pre>

<p> Set <var>retval</var> to the number of items selected;
0 if none were chosen,
   -1 when explicitly cancelled.  If items were selected, then
   <var>selected</var> is filled in with an array of <code>select_menu_res_item</code>
   structures, one for each selected line.  The <var>count</var> field
   of <var>selected</var> is a user supplied count.  If the user did
   not supply a count, then the <var>count</var> field is filled with
   -1 (meaning all).  A count of zero is equivalent to not
   being selected and should not be in the list.  If no items
   were selected, then <var>selected</var> is empty.  <var>how</var> is the
   mode of the menu.  Three valid values are <code>PICK_NONE</code>,
   <code>PICK_ONE</code>, and <code>PICK_ANY</code>, meaning:
nothing is selectable,
   only one thing is selectable, and any number valid items
   may selected.  If <var>how</var> is <code>PICK_NONE</code>,
   <var>retval</var> should never be set to anything but 0 or -1.
<p> You may call select_menu on a window multiple times --
   the menu is saved until start_menu or destroy_nhwindow
   is called on the window.
<p> Note that <code>NHW_MENU</code> windows need not have select_menu
   called for them. There is no way of knowing whether
   select_menu will be called for the window at
   create_nhwindow time.
<p>The proxy module is responsible for converting the integer identifiers back
   to the original <code>anything</code> value.

<h3>message_menu</h3>
<pre>
struct message_menu_req {
    int let;
    int how;
    string mesg<>;
};

struct message_menu_res {
    int retval;
};
</pre>
<p> tty-specific hack to allow single line context-sensitive
   help to behave compatibly with multi-line help menus.
<p> This should only be called when a prompt is active; it
   sends <var>mesg</var> to the message window.  For tty, it forces
a <samp>--More--</samp> prompt and enables <var>let</var> as a viable keystroke
   for dismissing that prompt, so that the original prompt
   can be answered from the message line "help menu".
<p> <var>retval</var> is either <var>let</var>, 0 (no selection was made),
   or 27 (explicit cancellation was requested).
<p> Interfaces which issue prompts and messages to separate
   windows typically won't need this functionality, and should
   set <var>retval</var> to -1 (in which case the proxy module will
   arrange for the message to be output via <code>pline()</code> instead).
<p>ALI: What does <var>how</var> do?

<h3>update_inventory</h3>
update_inventory takes no arguments and returns no results.

<p> Indicate to the window port that the inventory has been
   changed.
<p> Merely calls the display_inventory callback for window-ports that
   leave the window up, otherwise does nothing.

<h3>mark_sync</h3>
mark_sync takes no arguments and returns no results.

<p> Don't go beyond this point in I/O on any channel until
   all channels are caught up to here.  Can be an empty call
   for the moment

<h3>wait_sync</h3>
wait_sync takes no arguments and returns no results.

<p> Wait until all pending output is complete (<strong>flush</strong>() for
   streams goes here).
<p> May also deal with exposure events etc., so that the
   display is OK when return from wait_synch.

<h3>cliparound</h3>
<pre>
struct cliparounf_req {
    int x;
    int y;
};
</pre>
cliparound returns no values.

<p> Make sure that the user is more-or-less centered on the
   screen if the playing area is larger than the screen.

<h3>update_positionbar</h3>
<pre>
struct update_positionbar_req {
    string features<>;
};
</pre>
update_positionbar returns no values.

<p> Provide some 
   additional information for use in a horizontal
   position bar (most useful on clipped displays).
   <var>features</var> is a series of char pairs.  The first char
   in the pair is a symbol and the second char is the
   column where it is currently located.
   A '<' is used to mark an upstairs, a '>'
   for a downstairs, and an '@' for the current player
   location.

<h3>print_glyph</h3>
<pre>
struct print_glyph_req {
    int window;
    int x;
    int y;
    int glyph;
};
</pre>
print_glyph returns no values.

<p> Print <var>glyph</var> at (<var>x</var>,<var>y</var>) on the given window.
Glyphs are
   integers at the interface, mapped to whatever the window-port
   wants (symbol, font, color, attributes, ...there's
   a 1-1 map between glyphs and distinct things on the map).

<h3>raw_print</h3>
<pre>
struct raw_print_req {
    string str<>;
};
</pre>
raw_print returns no values.

<p> Print directly to a screen, or otherwise guarantee that
   the user sees <var>str</var>.  raw_print appends a newline to <var>str</var>.
   It need not recognize ASCII control characters.  This is
   used during startup (before windowing system initialization
   -- maybe this means only error startup messages are raw),
   for error messages, and maybe other "msg" uses.  E.g.
   updating status for micros (i.e, "saving").

<h3>raw_print_bold</h3>
<pre>
struct raw_print_bold_req {
    string str<>;
};
</pre>
raw_print_bold returns no values.

<p> Like raw_print, but prints in bold/standout (if possible).

<h3>nhgetch</h3>
nhgetch takes no arguments.

<p><pre>
struct nhgetch_res {
    int ch;
};
</pre>

<p> Sets <var>ch</var> to a single character input from the user.
<p> In the tty window-port, nhgetch assumes that <code>tgetch()</code>
   will be the routine the OS provides to read a character.
   The character returned <em>must</em> be non-zero.

<h3>nh_poskey</h3>
nh_poskey takes no arguments.

<p><pre>
enum mouse_click {
    CLICK_1 = 1,	/* mouse click type 1 */
    CLICK_2 = 2		/* mouse click type 2 */
};

struct nh_poskey_res {
    int retval;
    int x;
    int y;
    enum mouse_click mod;
};
</pre>

<p> Returns a single character input from the user or
   a positioning event (perhaps from a mouse).  If 
   <var>retval</var> is non-zero, a character was typed, else,
   a position in the MAP window is returned in
   <var>x</var>, <var>y</var> and <var>mod</var>.

<p>The different click types can map to whatever the
   hardware supports.  If no mouse is supported, this
   routine always sets <var>retval</var> to a non-zero character.

<h3>nhbell</h3>
nhbell takes no arguments and returns no values.

<p> Beep at user.  [This will exist at least until sounds are
		   redone, since sounds aren't attributable to windows anyway.]

<h3>doprev_message</h3>
doprev_message takes no arguments.

<p><pre>
struct doprev_message_res {
    int retval;
};
</pre>

<p> Display previous messages.  Used by the ^P command.
<p> On the tty-port this scrolls WIN_MESSAGE back one line.
<p> ALI: What purpose does retval serve?

<h3>yn_function</h3>
<pre>
struct yn_function_req {
    string ques<>;
    string choices<>;
    int default_response;
};

struct yn_function_res {
    int retval;
    int count;
};
</pre>

<p> Print a prompt made up of <var>ques</var>, <var>choices</var> and
<var>default</var>.
   Read a single character response that is contained in
   <var>choices</var> or <var>default</var>.  If choices is empty, all possible
   inputs are accepted and returned.  This overrides
   everything else.  The choices are expected to be in
   lower case.  Entering ESC always maps to 'q', or 'n',
   in that order, if present in <var>choices</var>, otherwise it maps
   to <var>default</var>.  Entering any other quit character (SPACE,
   RETURN, NEWLINE) maps to <var>default</var>.
<p> If the choices string contains ESC, then anything after
   it is an acceptable response, but the ESC and whatever
   follows is not included in the prompt.
<p> If the choices string contains a '#' then accept a count.
   Place this value in <var>count</var> and set <var>retval</var> to '#'.
<p> This uses the top line in the tty window-port, other
   ports might use a popup.

<h3>getlin</h3>
<pre>
struct getlin_req {
    string ques<>;
};

struct getlin_res {
    string input<>;
};
</pre>

<p> Prints <var>ques</var> as a prompt and reads a single line of text,
   up to a newline.  The string entered is returned in <var>input</var>
   without the
   newline.  ESC is used to cancel, in which case the string
   "\033" is returned.
<p> getlin must call the flush_screen callback with <var>cursor_on_u</var> set
to <code>TRUE</code> before doing anything.
<p> This uses the top line in the tty window-port, other
   ports might use a popup.

<h3>get_ext_cmd</h3>
get_ext_cmd takes no arguments.

<p><pre>
struct get_ext_cmd_res {
    int extcmd;
};
</pre>

<p> Get an extended command in a window-port specific way.  An index into
the extended command list (readable with the get_extended_commands callback)
is returned on a successful selection, -1 otherwise.

<h3>number_pad</h3>
<pre>
enum number_pad_mode {
    NP_KEYPAD = -1,		/* activate keypad mode (escape sequences) */
    NP_NUMERIC = 1		/* activate numeric mode for keypad (digits) */
};

struct number_pad_req {
    enum number_pad_mode state;
};
</pre>
number_pad returns no values.

<p>Initialize the number pad to the given state.

<h3>delay_output</h3>
delay_output takes no arguments and returns no values.

<p> Causes a visible delay of 50ms in the output.
   Conceptually, this is similar to wait_synch() followed
   by a nap(50ms), but allows asynchronous operation.

<h3>change_color</h3>
<pre>
struct change_color_req {
    int color;
    int rgb;
    bool reverse;
};
</pre>
change_color returns no values.

<h3>change_background</h3>
<pre>
struct change_background_req {
    bool white_or_black;
};
</pre>
change_background returns no values.

<h3>set_font_name</h3>
<pre>
struct set_font_name_req {
    int window;
    string font<>;
};

struct set_font_name_res {
    int retval;
};
</pre>

<h3>get_color_string</h3>
get_color_string takes no arguments.

<p><pre>
struct get_color_string_res {
    string retval<>;
};
</pre>

<h3>start_screen</h3>
start_screen takes no arguments and returns no values.

<p> Only used on Unix tty ports.  Sets up the tty to work in full-screen
   graphics mode.  Look at win/tty/termcap.c for an
   example.

<h3>end_screen</h3>
end_screen takes no arguments and returns no values.

<p> Only used on Unix tty ports.  The complement of start_screen().

<h3>outrip</h3>
<pre>
struct outrip_req {
    int window;
    string killed_by_prefix<>;
};

struct outrip_res {
    bool handled;
};
</pre>

<p> The tombstone code.  If you want the traditional code set <var>handled</var>
   to <code>FALSE</code>
   (the proxy module will then call <code>genl_outrip</code>).

<p>ALI: I suspect we should pass rather more information to this procedure;
<code>genl_outrip()</code> uses a <em>lot</em> of global variables.

<h3>preference_update</h3>
<pre>
struct preference_update_req {
    string pref<>;
    string value<>;
};
</pre>

<p> Notify the window client that the value of option <var>pref</var> has
changed to <var>value</var>. The set of options of which the window client
will be notified is determined by the window capabilities, set in the
init_nhwindows procedure.

<h3>status</h3>
<pre>
typedef string value<>;

struct proxy_status_req {
    int reconfig;
    value values<>;
};
</pre>

<h3>print_glyph_layered</h3>
<pre>
struct glyph_row {
    int start;
    int glyphs<>;
};

struct glyph_layer {
    int start;
    struct glyph_row rows<>;
};

struct print_glyph_layered_req {
    int window;
    struct glyph_layer layers<>;
};
</pre>
print_glyph_layered returns no values.

<p> Place <var>glyphs</var> at the relevant places on the given window.
All layers are included in the call, even if there have been no changes to
the glyphs in that layer. In contrast, only a subset of the rows and the
glyphs within those rows are included. The <var>start</var> fields specify
the first row or column in the window which should be written to. Note that
the start column may vary across different rows and that some rows may contain
no glyphs.

Window interfaces may display layered glyphs using either opacity (lowest
present glyph is displayed), transparancy (each glyph is represented by an
irregular shaped image. Glyphs from layers further away may be seen behind the
image), translucency (glpyhs are represented by images that only partially
obscure the underlying image) or some other suitable method.

<p>
Layers are numbered counting away from the viewer. Layers which have no glyph
present have a value of NO_GLYPH.

<p>
Glyphs are
   integers at the interface, mapped to whatever the window-port
   wants (symbol, font, color, attributes, ...there's
   a 1-1 map between glyphs and distinct things on the map).

<p>
Note: This procedure will only be called if the interface flag
EXT_IM_DISPLAY_LAYERS is set.

<h3>send_config_file</h3>
<pre>
struct send_config_file_req {
    int handle;
};
</pre>
send_config_file returns no values.

<p>Request that if the window interface has a local config file then it
should be sent to the game by writing it to the specified handle using
the dlbh_fwrite callback. The handle will be closed when send_config_file
returns.

<h2><a name="callbacks">Standard window port call backs</a></h2>

Plug-in window ports may assume that the following call backs are supported.

<p><table>
<tr><th>Call back</th><th>ID</th></tr>
<tr><td>display_inventory</td><td>0x01</td></tr>
<tr><td>dlbh_fopen</td><td>0x02</td></tr>
<tr><td>dlbh_fgets</td><td>0x03</td></tr>
<tr><td>dlbh_fread</td><td>0x04</td></tr>
<tr><td>dlbh_fwrite</td><td>0x05</td></tr>
<tr><td>dlbh_fclose</td><td>0x06</td></tr>
<tr><td>dlbh_fmd5sum</td><td>0x07</td></tr>
<tr><td>flush_screen</td><td>0x08</td></tr>
<tr><td>doredraw</td><td>0x09</td></tr>
<tr><td>interface_mode</td><td>0x0A</td></tr>
<tr><td>parse_options</td><td>0x0B</td></tr>
<tr><td>get_option</td><td>0x0C</td></tr>
<tr><td>get_player_choices</td><td>0x0D</td></tr>
<tr><td>get_valid_selections</td><td>0x0E</td></tr>
<tr><td>quit_game</td><td>0x0F</td></tr>
<tr><td>display_score</td><td>0x10</td></tr>
<tr><td>doset</td><td>0x11</td></tr>
<tr><td>get_extended_commands</td><td>0x12</td></tr>
<tr><td>map_menu_cmd</td><td>0x13</td></tr>
<tr><td>get_standard_winid</td><td>0x14</td></tr>
<tr><td>get_tilesets</td><td>0x15</td></tr>
<tr><td>get_glyph_mapping</td><td>0x16</td></tr>
<tr><td>get_extensions</td><td>0x17</td></tr>
<tr><td>set_option_mod_status</td><td>0x18</td></tr>
</table>

<h3>display_inventory</h3>
display_inventory takes no arguments and returns no values.

<p>Display the hero's inventory.

<h3>dlbh_fopen</h3>
<pre>
struct dlbh_fopen_req {
    string name<>;
    string mode<>;
};

struct dlbh_fopen_res {
    int fh;
};
</pre>

<p>Open a file and return a handle or -1 on error. The following names have
special meanings as follows:
<table>
<tr><th>Name</th><th>File</th></tr>
<tr><td>$(RECORD)</td><td>NetHack record</td></tr>
<tr><td>$(HELP)</td><td>NetHack help</td></tr>
<tr><td>$(SHELP)</td><td>NetHack short help</td></tr>
<tr><td>$(DEBUGHELP)</td><td>NetHack wizard mode help</td></tr>
<tr><td>$(DATAFILE)</td><td>NetHack data</td></tr>
<tr><td>$(CMDHELPFILE)</td><td>NetHack command help</td></tr>
<tr><td>$(HISTORY)</td><td>NetHack history</td></tr>
<tr><td>$(LICENSE)</td><td>NetHack license</td></tr>
<tr><td>$(OPTIONFILE)</td><td>NetHack option</td></tr>
<tr><td>$(OPTIONS_USED)</td><td>NetHack options used</td></tr>
<tr><td>$(GUIDEBOOK)</td><td>NetHack guidebook</td></tr>
</table>

<p>The following modes are supported: <b>r</b> and <b>rb</b>.

<h3>dlbh_fgets</h3>
<pre>
struct dlbh_fgets_req {
    int len;
    int fh;
};

struct dlbh_fgets_res {
    string line<>;
};
</pre>

<p>Read one line of a file previously opened with dlbh_fopen. At most len
characters will be returned including the newline at the end of the line.
If len is too short to return a whole line the first len characters will
be returned (with no terminating newline) and the rest of the line will
be available for reading with the next call the dlbh_fgets. An empty
string will be returned on end of file or other error.

<h3>dlbh_fread</h3>
<pre>
struct dlbh_fread_req {
    int len;
    int fh;
};

struct dlbh_fread_res {
    int retval;
    opaque buffer<>;
};
</pre>

<p>Read up to len bytes of a file previously opened with dlbh_fopen.
If an error occurs, retval will be non-zero. Any bytes read before the
error occured will be returned in the buffer. An empty buffer will be
returned on end of file.

<h3>dlbh_fwrite</h3>
<pre>
struct dlbh_fwrite_req {
    int fh;
    opaque buffer<>;
};

struct dlbh_fwrite_res {
    int retval;
};
</pre>

<p>Write buffer to a file previously opened for writing. At present,
the only means of aquiring a writable handle is via the send_config_file
procedure. If an error occurs, retval will be non-zero.

<h3>dlbh_fclose</h3>
<pre>
struct dlbh_fclose_req {
    int fh;
};

struct dlbh_fclose_res {
    int retval;
};
</pre>

<p>Close a file previously opened with dlbh_fclose. Return non-zero on error.

<h3>dlbh_fmd5sum</h3>
<pre>
struct dlbh_fmd5sum_req {
    string name<>;
};

struct dlbh_fmd5sum_res {
    int retval;
    string digest<>;
};
</pre>

<p>Compute a message digest for a file according to RFC 1321 (MD5).  See
dlbh_fopen for information on file names. Retval will be zero if the
file was opened successfully and -1 if an error was encountered.

<h3>flush_screen</h3>
flush_screen takes no arguments and returns no values.

<p>Flush the screen.

<h3>doredraw</h3>
doredraw takes no arguments and returns no values.

<p>Redraw the screen.

<h3>interface_mode</h3>
<pre>
struct interface_mode_fclose_req {
    unsigned long mode;
};
</pre>

<p>Set or reset flags to change the behaviour of the interface as follows:
<table>
<tr><th>Flag</th><th>Status</th><th>Behaviour</th></tr>
<tr><td>EXT_IM_STATUS</td><td>0</td><td>Report status via calls to putstr(WIN_STATUS,...)</td></tr>
<tr><td></td><td>1</td><td>Report status via calls to status(...)</td></tr>
<tr><td>EXT_IM_DISPLAY_LAYERS</td><td>0</td><td>Use print_glyph procedure</td></tr>
<tr><td></td><td>1</td><td>Use print_glyph_layered procedure<td></tr>
</table>

<h3>parse_options</h3>
<pre>
struct parse_options_req {
    string opts<>;
};

struct parse_options_res {
    int retval;
};
</pre>

<p>Parse the options passed. Multiple options may be given, seperated with
commas. The format for options is the save as when included with the OPTIONS
keyword in NetHack defaults files. See the guidebook for details.

<p>parse_options returns non-zero on error.

<h3>get_option</h3>
<pre>
struct get_option_req {
    string opt<>;
};

struct get_option_res {
    string value<>;
};
</pre>

<p>Get the value of an option, or the empty string if the option is not
recognized. Boolean options are returned as values of &quot;yes&quot;
or &quot;no&quot;.

<h3>get_player_choices</h3>
<pre>
typedef string choices<>;

struct get_player_choices_res_role {
    string male<>;
    string female<>;
};

struct get_player_choices_res {
    choices aligns<>;
    choices genders<>;
    choices races<>;
    struct get_player_choices_res_role roles<>;
};
</pre>

<p>Returns an array of the possible values for each of player alignment,
gender, race and role. Note that this includes all possible values, not
just the ones that are compatible with the currently set options.

<p>The (integer) values of align, gend, race and role used by the
player_selection procedure can be used as indices into these arrays.

<h3>get_valid_selctions</h3>
<pre>
struct get_valid_selections_res {
    int no_roles;
    int no_races;
    int no_aligns;
    int no_genders;
    unsigned long masks<>;
};
</pre>

<p>Get a packed array of masks of combinations of role, race, gender
and alignment which form a valid player selection.

<p>When unpacked, the array contains no_roles * no_races * no_aligns
elements each of which is a mask of the valid genders for this
combination of role, race, alignment. If there are no valid genders
then this mask will be zero, otherwise it will be the bitwise-OR of
<code>(1&lt;&lt;gender)</code> for each gender that is valid.

<p>The array is packed by copying no_gender bits from the next mask
in the unpacked array into the least significant unused bits of the
current element in the packed array (the order of bits within each
mask is unchanged during this process). A new element in the packed
array is started when there is not enough room for a complete mask
to be stored (masks are not split across array elements). The final
element in the packed array may only be partially filled.

<h3>quit_game</h3>
quit_game takes no arguments and returns no values.

<p>User request to quit the game.

<h3>display_score</h3>
display_score takes no arguments and returns no values.

<p>Display the current score list.

<h3>doset</h3>
doset takes no arguments and returns no values.

<p>Display the current options and allow the user to modify them.

<h3>get_extended_commands</h3>
<pre>
typedef string commands<>;

struct get_extended_commands_res {
    commands ext_cmd_list<>;
};
</pre>

<p>Get a list of extended commands. Note that this command list may change
(for example when starting in wizard mode).

<h3>map_menu_cmd</h3>
<pre>
struct map_menu_cmd_req {
    int ch;
};

struct map_menu_cmd_res {
    int retval;
};
</pre>

<p>Map the given character to its corresponding menu command. If it
doesn't match anything, just return the original.

<h3>get_standard_winid</h3>
<pre>
struct get_standard_winid_req {
    string window<>;
};

struct get_standard_winid_res {
    int retval;
};
</pre>

<p>Return the window ID of standard windows (this will be -1 if the window is not open).
The following window names are currently recognized:
<table>
<tr><th>Name</th><th>Window</th></tr>
<tr><td>MESSAGE</td><td>The message window</td></tr>
<tr><td>STATUS</td><td>The status window</td></tr>
<tr><td>MAP</td><td>The map window</td></tr>
<tr><td>INVEN</td><td>The permanent inventory window or, if none, the current transitory inventory window</td></tr>
</table>

<p>Unrecognized windows will return -1.

<h3>get_tilesets</h3>
<pre>
struct get_tilesets_res_tileset {
    string name<>;
    string file<>;
    string mapfile<>;
    long flags;
};

struct get_tilesets_res {
    struct get_tilesets_res_tileset tilesets<>;
};
</pre>

<p>Return a list of the currently configured tile sets.

<h3>get_glyph_mapping</h3>
<pre>
struct get_glyph_mapping_res_symdef {
    long rgbsym;
    string description<>;
};

struct get_glyph_mapping_res_submapping {
    struct get_glyph_mapping_res_symdef symdef;
    struct get_glyph_mapping_res_symdef glyphs<>;
};

struct get_glyph_mapping_res_mapping {
    string flags<>;
    int base_mapping;
    int alt_glyph;
    struct get_glyph_mapping_res_symdef symdef;
    struct get_glyph_mapping_res_submapping submappings<>;
};

struct get_glyph_mapping_res {
    int no_glyph;
    long transparent;
    struct get_glyph_mapping_res_mapping mappings<>;
};
</pre>

<p>Return a set of descriptions for each glyph so that the window port can
generate a map between glyphs and tiles and/or characters for display.

<p>The descriptions are returned in a tiered structure for efficiency. The
top level contains the value of no_glyph, which is both the number of glyphs
in the map and the value used by the game to indicate that no glyph is present.

<p>The transparent field contains an arbitary RGB colour which is used within
the glyph map to indicate a transparent colour. When combining glyph maps
(see below) a non-transparent colour should always superceed the transparent
colour. Similarly, the symbol part of the transparent field contains a value
which is used to indicate a transparent symbol which is used in an
equivalent way. The field (and the rgbsym field described later) is
encoded with an 8-bit red value in the top 8 bits, an 8-bit green value
in bits 16 to 23, an 8-bit blue value in bits 9 to 15 and an 8-bit symbol
in the bottom 8 bits.

<p>There then follows a series of mappings which form the second level. Here
a comma seperated set of flags may be specified which is used to distinguish
similar glyphs. Window ports should ignore flags that they do not recognize.

<p>Where a set of glyphs is substantially the same as another set, then they
will be specified as being based on another mapping with the base_mapping field.
This will be -1 where no base mapping is in use. Where a base mapping is
specified and the number of sub-mappings is zero then the current mapping
should be taken as a duplicate of the base mapping, with different flags and
alternate glyph (see below) possibly with different colour and symbol (if
these are different to the transparent colour and symbol). Where a base mapping
is specified with sub-mappings, then each sub-mapping specifes a number of
glyphs for each of the glyphs in the base mapping. This is used, for example,
with swallows which are based on the monster mapping.

<p>Also provided for some mappings is an alternate glyph which should be used
where the windowing port does not support the glyph set. If there is no
alternate glyph then the alt_glyph field will contain the value of no_glyph.

<p>Finally, each mapping has a symdef field which contains an RGB colour and
symbol which may be set if all glyphs in the set share the same colour and/or
symbol.

<p>Each sub-map contains a symdef field which is used in the same way as the
same field in the containing mapping structure and a set of symdefs, one for
each glyph in the sub-mapping.

<h3>get_extensions</h3>
<pre>
struct get_extensions_res_extension {
    string name<>;
    string vers<>;
    int no_procedures;
};

struct get_extensions_res {
    struct get_extensions_res_extension extensions<>;
};
</pre>

<p>Return a list of the supported extensions. The first extension listed will
use no_procedures IDs starting at 0x8000. Subsequent extensions will use IDs
starting just after the previous extension.

<h3>set_option_mod_status</h3>
<pre>
/*
 * Option flags
 * Each higher number includes the characteristics of the numbers
 * below it.
 */
enum option_mod_flag {
    SET_IN_FILE = 0,	/* config file option only */
    SET_VIA_PROG = 1,	/* may be set via extern program, not seen in game */
    DISP_IN_GAME = 2,	/* may be set via extern program, displayed in game */
    SET_IN_GAME = 3	/* may be set via extern program or set in the game */
};

struct set_option_mod_status_req {
    string optnam<>;
    enum option_mod_flag status;
};
</pre>

<h1>Sub-protocol 2</h1>

<p>Sub-protocol 2 has exactly the same procedures and callbacks that are
documented above for sub-protocol 1 (except <a href="#init2">init</a>),
but is no longer fully synchronous. This means that some procedures and
callbacks which have no need to send a reply can be defined as asynchronous.
This lets the remote end know that no reply will be generated, allowing
serveral requests to be sent at the same time.

<p>In order to cope with the asychronous nature of the protocol, the header
is modified slightly from that used in sub-protocol 0 so that the serial
number to which a reply relates can be sent. This means that there is one
less bit available and the maximum packet size (including the header) is
consequently reduced to 128Kb (sub-protocol 1 allows 256Kb).

<p>In sub-protocol 2, the proxy module will initiate a procedure by writing
an unsigned integer (according to RFC1014) whose value is as follows:

<pre>
	value = (ID << 16) | (length >> 2);
</pre>
where <code>length</code> is the length of the following data (<em>not</em>
including <code>value</code>) in bytes. It will then write the relevant
request structure (if a procedure takes no arguments then length will be
zero and no request structure will be written). Bit 15 will always be zero.
An <code>ID</code> of 0xffff indicates a <a href="#special">special packet</a>.

<p>The proxy module will then read back an unsigned integer from the plug-in
window-port and decode it as follows:

<pre>
	ID = value >> 16;
	is_reply = value & 0x8000;
	length = (value & 0x7fff) << 2;
</pre>

<p>If <code>ID</code> is 0xffff and <code>is_reply</code> is zero, this is a
<a href="#special">special packet</a>. Otherwise, if <code>is_reply</code> is
zero, this is a <a href="#callbacks">callback</a>.

<p>If <code>is_reply</code> is non-zero, this is a reply. The ID field contains
the serial number of the request to which it relates. The first request to
be sent has a serial number of 1. Each subsequent request has the next serial
number in sequence, wrapping to 0 after 0xffff. There is no requirement that
replies must be sent in any particular order.

<h2><a name="special">Special packets</a></h2>

<p>Special packets provide a kind of out-of-band communication stream which
have no effect on the processing of request and reply packets. They are
distingushed by a header with the top 17 bits set to 0x1fffe (which corresponds
to an <code>ID</code> of 0xffff and bit 15 reset). Special packets are
further decoded as follows:

<pre>
	type = (value & 0x7f00) >> 8;
	length = (value & 0xff) << 2;
</pre>

<h3>Special packet type 0 (error packets)</h3>

<p>Error packets are at least two words long which are decoded as follows:

<pre>
	serial = word1 >> 16;
	id = word1 & 0xffff;
	code = word2 & 0xff;
</pre>

<p>Other bits are reserved and should be written as zero and ignored on
read. <code>serial</code> is the serial number of the request to which this
error relates. <code>id</code> is the ID of that request. <code>code</code>
is an error code, which is one of the following:

<table>
<tr><th>Code</th><th>Meaning</th></tr>
<tr><td>1</td><td>The function is unsupported</td></tr>
<tr><td>2</td><td>The function is unsupported in this state
	(eg., directory_update() before game started)</td></tr>
<tr><td>3</td><td>Invalid paramameter encoding
	(eg., passing params to a function which takes none)</td></tr>
<tr><td>4</td><td>Invalid parameters
	(eg., set_option_mod_status() for an undefined status)</td></tr>
<tr><td>5</td><td>Resource failure
	(eg., add_menu() runs out of memory)</td></tr>
</table>

<p>Other error codes should be treated as a generic error.

<p>On receit of a code 1 error (unsupported function), implementations
may take it that all further requests with this ID will be ignored
(other than to generate errors) and drop them at source. Window interfaces
that would otherwise ignore certain requests from the game should instead
signal an error to reduce bandwidth. Games are not expected to cope with
every combination of procedures being signalled as unsupported, but will
cope with the following procedures being unsupported:

<ul>
<li>get_nh_event
<li>suspend_nhwindows and resume_nhwindows (must be both or none)
<li>update_inventory
<li>mark_sync
<li>wait_sync
<li>cliparound
<li>update_positionbar
<li>nhbell
<li>doprev_message
<li>number_pad
<li>delay_output
<li>change_color
<li>change_background
<li>set_font_name
<li>get_color_string
<li>start_screen
<li>end_screen
</ul>

<p>Window interfaces are not required to be able to cope with any of
the standard callbacks being signalled as unsupported.

</ul>

<h3>Unrecognized special packets</h3>

<p>Special packets of a type other than those listed here should be ignored.

<h2>Window port procedures specific to sub-protocol 2</h2>

<h3><a name="init2">init</a></h3>
<pre>
struct init_req {
    unsigned long async_callbacks<>;
};

struct init_res {
    unsigned long async_procedures<>;
};
</pre>

<p>In sub-protocol 2, the init procedure is passed a list of callbacks that
will not generate a reply and returns a similar list for procedures supported
by the window interface.

<p>Lists of async callbacks and procedures are encoded as an array of bitmasks
with one mask per 32 callbacks or procedures starting with IDs 1-32 and going
up by 32 for each subsequent mask. Within each mask, the least significant bit
represents the lowest ID within the 32 IDs encoded. Bits are set to denote an
asychronous callback or procedure and reset to denote a synchronous one.
Synchronous callbacks and procedures always expect a reply; asynchronous ones
expect no reply. IDs beyond the end of the array are treated as synchronous.

<p>This procedure will be called once before all other procedures. No callbacks
may be invoked before the init procedure returns.

<h1>Change history</h1>

<h2>NhExt 1.0.1</h2>

<ul>
<li>Added sub-protocol 2.
</ul>

<h2>NhExt 1.0.2</h2>

<ul>
<li>Added authentication.
</ul>

</body>
</html>