% Copyright (c) 1988 Massachusetts Institute of Technology
%	$Source: /mit/zephyr/repository/zephyr/doc/progman/notice-structure.tex,v $
%	$Author: jtkohl $
%	$Header: /mit/zephyr/repository/zephyr/doc/progman/notice-structure.tex,v 2.0 1989/04/05 15:53:49 jtkohl Exp $
%
\subsection{The ZNotice_t Structure}
\label{ZNoticet}

The ZNotice_t structure is the central data object of the \Zephyr\
library.  Outgoing notices are first represented in a ZNotice_t
structure, and incoming notices are returned in one.  A \Zephyr\
notice consists of two primary parts: a header containing information
about the notice and a data area.  The ZNotice_t structure contains
information about both portions of the notice.

\subsubsection{Components of the Header}

All fields in the ZNotice_t structure are filled in with valid data
when a notice is received.  However, only some of the fields need to
be initialized when a notice is sent.  The rest are either filled in
automatically by the library, or are filled in with default values if
they are NULL.  The ZNotice_t structure contains the following fields:

\begin{description}
\item {\bf char *z_packet}: If the notice has been formatted, or the
notice was received, this field points to a buffer containing the
formatted version of the notice.

\item {\bf char *z_version}: The protocol version the notice was formatted
with in the form ZEPH{\em n\/}.{\em m\/} where {\em n\/} is the major
version number and {\em m\/} is the minor version number.  This manual
discusses the functions related to version ZEPH0.2.  If a notice is
received by a client that supports a different major version, the
client will refuse to parse the notice.  (This field is filled in
automatically when the notice is sent.)

\item {\bf ZNotice_Kind_t z_kind}: The type of the notice (see
\myref{notice-kinds}).  (This field must be initialized by the client
before the notice is sent.)

\item {\bf ZUnique_Id_t z_uid}: The unique ID of the notice.  This ID
is actually a per-transaction unique ID instead of a per-notice unique
ID.  This is described in more detail in
\myref{acknowledgment-structure}.  (This
field is filled in automatically when the notice is sent.)

\item {\bf struct timeval z_time}: The time the notice was sent.
(This field is not actually part of the notice that is sent, but is
derived from the unique ID when the notice is received.  Thus it does
not need to be filled in at all when the notice is sent.)

\item {\bf unsigned short z_port}: The port number on the client from
which the notice was sent.  (This field must be filled in before the
notice is sent.  If it is 0, it is automatically filled in with the
client's port number.)

\item {\bf int z_auth}: An indication of how authentic the notice claims
to be.  0 means not authenticated, 1 means authenticated by Kerberos.
Note this is an indication of the claim to authenticity, not an
indication of the actual authenticity.  The function
ZCheckAuthentication (\myref{ZCheckAuthentication}) verifies or rejects
this claim.
(This field is filled in automatically when the notice is sent.)

\item {\bf int z_authent_len}: The length of the authenticator in
{\bf z_ascii_authent}.  (This field is filled in automatically when
the notice is sent.)

\item {\bf char *z_ascii_authent}: The authenticator.  This data is
used to determine the authenticity of the notice as it is passed from
the client program to the server.  (It is filled in automatically when
the notice is sent.)

\item {\bf char *z_class}: The class of the notice.  (This field must be
filled in before the notice is sent.)

\item {\bf char *z_class_inst}: The class instance of the notice.  (This
field must be filled in before the notice is sent.)

\item {\bf char *z_opcode}: The opcode of the notice.  This is an extra
field with no specified purpose.  It may be used to provide extra
information between a client and recipient about a notice's contents.
The name ``opcode'' is derived from its initial creation as a place to
put an ``operation code'' about what to do with the notice once it was
received.  Some internal \Zephyr\ functions use this field.
Very few applications actually use it for this purpose,
however.  (It must be filled in before the notice is sent.)

\item {\bf char *z_sender}: The sender of the notice.  (If this field is
NULL, it will be filled in with the current user's username.  It must
be set to either a string or NULL before the notice is sent.)

\item {\bf char *z_recipient}: The recipient of the notice.  (This field
must be filled in before the notice is sent.)

\item {\bf char *z_default_format}: The default display format for the
notice.  See the \Zephyr\ design document's chapter on the WindowGram
client for more information about the default format string.  (This
field must be filled in before the notice is sent.)

\item {\bf char *z_multinotice}: An indication of what part of a
fragmented notice this notice constitutes.  (This field will be
filled in automatically.)

\item {\bf ZUnique_Id_t z_multiuid}: An identification of which
fragmented notice this notice is a part of.  (This field will be
filled in automatically.)

\item {\bf ZChecksum_t z_checksum}: The cryptographic checksum of
various header fields, used to check the authenticity of the notice as
it is passed from the server to the recipient.  (This field will be
filled in automatically.)

\item {\bf int z_num_other_fields}: The number of extra user-defined or
unknown fields present in this notice.

\item {\bf char *z_other_fields[Z_MAXOTHERFIELDS]}: An array of the
extra fields (if any) for this notice.

\item {\bf int z_message_len}: The length, in bytes, of the message in
{\bf z_message}.  (This field must be filled in before the notice is
sent.  It may be 0 if no message is being included in the notice body.)

\item {\bf char *z_message}: The body of the message.  (This field must be
filled in before the notice is sent.  It may be NULL if no message is
being included in the message body.)

\end{description}

\subsubsection{Notice Kinds}
\label{notice-kinds}

A ZNotice_Kind_t is an enumerated type of one of the following kinds.
These kinds may be used in the {\bf z_kind} field of a ZNotice_t
structure.  Only the first three kinds, UNSAFE, UNACKED, and ACKED,
will normally be used by an application program.  They are used to
deliver a notice to a recipient.  The other kinds are included for
internal communication between the various portions of a \Zephyr\
system, and the notice is not delivered to a recipient.

\begin{description}
\item {\bf UNSAFE}: The notice should be delivered.
No user acknowledgments will be performed.  No
acknowledgment is sent from the HostManager to the source client, and
the HostManager will not forward the server acknowledgment to the
client.  Note that the server still sends the HostManager an
acknowledgment, and the destination clients still send acknowledgments
to the server.  UNSAFE is used when a notice needs to be sent, but the
client can't afford to wait around for acknowledgments (for example, a
system shutdown message).

\item {\bf UNACKED}: The notice should be
delivered.  The HostManager will send an acknowledgment to the
client, but will not forward the server's acknowledgment.  This is
used by clients which wish to make sure that the notice has actually
reached the HostManager safely, but don't care if the
server ever received it.

\item {\bf ACKED}: The notice should be delivered.  The HostManager
will send an acknowledgment to the client, and will forward the
server's acknowledgment.  This is used by clients which want to make
sure the notice got to the server safely, and perhaps want to know if
the server redistributed the notice to any recipients.

\item {\bf HMACK}: The notice is an acknowledgment from the HostManager to
a client.

\item {\bf HMCTL}: The notice is a HostManager control packet, which
may be sent to a HostManager to change its state.  See 
\myref{comm-hostmanager} for more
information.

\item {\bf SERVACK}: The notice is an acknowledgment from a server to
a HostManager, and possibly to a client if the HostManager forwards
it.

\item {\bf SERVNAK}: The notice is a negative acknowledgment from a
server to a HostManager, and possibly to a client if the HostManager
forwards it.  This notice means that something failed and the server
was unable to distribute the original notice.

\item {\bf CLIENTACK}: The notice is an acknowledgment from a
receiving client to a server.  These notices are sent automatically
when a notice is received by the \Zephyr\ library.

\item {\bf STAT}: The notice contains a request for statistics
information from a HostManager.  See the section on
HostManager communication (\myref{comm-hostmanager}) for more information.
\end{description}

\subsubsection{Field Structure of the Notice Body}

The {\bf z_message} field of a notice can contain information in any
format.  The data may be ASCII text, or it may be raw binary data.
However, if a notice is to be displayed (by the WindowGram client or a
similar application), it should conform to the following standard:

\begin{itemize}
\item All data in the message body should be in printable ASCII form.
Newline and tab characters are allowed.
\item If the information can be conveniently broken into fields, the
fields should be concatenated with a NULL between each field and after
the last field.
\item The {\bf z_message_len} should include all NULLs, including
the one after the last field.
\end{itemize}

The WindowGram client is capable of accepting a notice in this format
and displaying it in a user-friendly manner.  See the Zephyr design
document \cite{zephyr-design} for more information on the WindowGram
client.
