335 lines
13 KiB
TeX
335 lines
13 KiB
TeX
% If you somehow got this file without fullpage.sty, delete
|
|
% ``fullpage'' from the list of style options. It just pulls out the
|
|
% margins a bit.
|
|
\documentstyle[11pt,twoside,fullpage]{article}
|
|
% New commands
|
|
%-------------
|
|
% Intro copied from prospero-protocol-v5.txt
|
|
|
|
% for meta-symbols
|
|
\newcommand{\meta}[1]{{\bf \mbox{\(<\)#1\(>\)}}}
|
|
% for literal tokens.
|
|
\newcommand{\lit}[1]{{\tt \mbox{#1}}}
|
|
%for attributes
|
|
\newcommand{\atr}[1]{\mbox{\sc #1}}
|
|
% for identifying text
|
|
\newcommand{\text}[1]{{\em #1}\/}
|
|
|
|
% Start and end of One or More
|
|
\newcommand{\ooms}{\([\,\)}
|
|
\newcommand{\oome}{\(\,]^+\)}
|
|
% start and end of zero or more
|
|
\newcommand{\zoms}{\([\,\)}
|
|
\newcommand{\zome}{\(\,]^*\)}
|
|
% Start and end of zero or one
|
|
\newcommand{\zoos}{\([\,\)}
|
|
\newcommand{\zooe}{\(\,]\)}
|
|
% start an OR
|
|
\newcommand{\ors}{{\bf (\,}}
|
|
\newcommand{\ore}{{\bf \,) }}
|
|
\newcommand{\metaor}{{\em \,or\, }}
|
|
\newcommand{\hexnum}[1]{\(\mbox{#1}_{16}\)}
|
|
\newcommand{\unix}{{\sc unix}}
|
|
\newenvironment{command}{\begin{verse}\sloppy}{\end{verse}}
|
|
\newcommand{\commandsize}{\large}
|
|
|
|
%\newtheorem{example}{Example}
|
|
% Uncomment this for almost-double spacing
|
|
%\renewcommand{\baselinestretch}{1.7}
|
|
%\newcommand{\hozline}{\rule{\textwidth}{0.3mm}}
|
|
%\newcommand{\hozline}{\makebox[\textwidth]{\hrulefill}}
|
|
%\newcommand{\bex}{\begin{example} \begin{rm}}
|
|
%\newcommand{\eex}{$\Box$ \end{rm} \end{example}}
|
|
%\newcommand{\cbs}{\chgbarbegin}
|
|
%\newcommand{\cbe}{\chgbarend}
|
|
%\newcommand{\cbs}{}
|
|
%\newcommand{\cbe}{}
|
|
|
|
%\newcommand{\ptag}{\begin{flushright} {\rm ($P$)} \end{flushright} }
|
|
|
|
|
|
\begin{document}
|
|
|
|
\pagenumbering{arabic}
|
|
\pagestyle{plain}
|
|
|
|
\renewcommand{\thepage}{\arabic{page}}
|
|
|
|
\begin{titlepage}
|
|
|
|
\renewcommand{\thefootnote}{}
|
|
%\footnotetext{\hspace*{-21pt}
|
|
%Digital copies of the latest revision of this document may be obtained
|
|
%through Prospero as
|
|
%\mbox{\verb"/papers/subjects/operating-systems/prospero/doc/menu-api.PS.Z"},
|
|
%in the \mbox{\tt \#/INET/EDU/ISI/swa} virtual system, or through
|
|
%Anonymous FTP from \mbox{\tt PROSPERO.ISI.EDU} as
|
|
%\mbox{\verb"/pub/prospero/doc/prospero-menu-api.PS.Z"}
|
|
%}
|
|
\footnotetext{\hspace*{-21pt}
|
|
This work was supported in part by the National Science
|
|
Foundation (Grant No. CCR-8619663), the Washington Technology Center,
|
|
Digital Equipment Corporation, and the Defense Advance Research
|
|
Projects Agency under NASA Cooperative Agreement NCC-2-539.
|
|
The views and conclusions contained in
|
|
this document are those of the authors and should not be interpreted as
|
|
representing the official policies, either expressed or implied, of
|
|
any of the funding agencies.
|
|
The authors may be reached
|
|
at USC/ISI, 4676 Admiralty Way, Marina del Rey, California\ \ 90292-6695, USA.
|
|
Telephone +1 (310) 822-1511, email \mbox{\verb"info-prospero@isi.edu"}. }
|
|
\renewcommand{\thefootnote}{\arabic{footnote}}
|
|
|
|
|
|
\vspace*{\fill}
|
|
\begin{center}
|
|
\Large Menu-Based Browser API to Prospero\\
|
|
\vskip 1.5em
|
|
{\large Draft of 5 July 1993} \\
|
|
{\large Document Revision No. 0.3} \\
|
|
\end{center}
|
|
\vspace{.5in}
|
|
|
|
%\Large \hspace*{\fill} Steven Augart
|
|
%\footnotetext{\hspace*{-18pt}
|
|
% To Contact the Authors: \\
|
|
% Electronic Mail: \mbox{\verb"info-prospero@isi.edu"} \\
|
|
% Telephone: +1 (310) 822-1511 \\
|
|
% Mail: USC Information Sciences Institute, 4676 Admiralty Way,
|
|
% Marina del Rey, California 90292--6695\ \ U.S.A.
|
|
%}
|
|
%\hfill Kwynn Buess
|
|
%\hspace*{\fill} \\
|
|
\begin{center}
|
|
\Large Steven Seger Augart
|
|
\vspace{.1in}
|
|
\Large B. Clifford Neuman
|
|
\vspace{.1in}
|
|
\Large Kwynn Buess
|
|
\vspace{.2in}
|
|
\Large Information Sciences Institute \\
|
|
University of Southern California
|
|
\end{center}
|
|
\vspace*{1.2in}
|
|
\vspace*{\fill}
|
|
\end{titlepage}
|
|
|
|
\tableofcontents
|
|
|
|
\section{INTRODUCTION}
|
|
|
|
The menu-based browser API is a description of interfaces to the
|
|
PROSPERO library. The functions and variables described here will
|
|
eventually be prototyped in the standard Prospero include file {\tt
|
|
p\_menu.h}; since the menu browser client and this API are still under
|
|
development, that include file is currently located in {\tt user/menu}
|
|
in the Prospero sources, along with the Prospero menu browser client.
|
|
|
|
\section{Data Structures}
|
|
|
|
The data structure {\it VLINK} is described in the include file {\tt
|
|
pfs.h}. The user of this API needs to know only the following facts
|
|
about it:
|
|
|
|
\begin{itemize}
|
|
|
|
\item A {\it VLINK} structure has members {\tt next}
|
|
and {\tt previous}. These members are only meaningful when working with a
|
|
linked list of {\it VLINK structures}; they point to the next and
|
|
previous member of the linked list. The {\tt previous} of the head of the
|
|
list points to the tail of the list. The {\tt next} of the tail of
|
|
the list is a null pointer.
|
|
|
|
\item The {\tt APPEND\_ITEM({\it VLINK new}, {\it VLINK head})} macro,
|
|
defined in {\tt list\_macros.h}, appends {\it new} to a doubly-linked
|
|
list headed by the vlink {\it head}. {\it head} is an initialized
|
|
variable which points to an already existing list of {\it VLINK}s. It
|
|
can be initialized to the empty list by setting its value to the null pointer.
|
|
|
|
\item The {\tt EXTRACT\_ITEM}({\it VLINK item, VLINK head}) macros,
|
|
also defined in {\tt list\_macros.h}, removes the item {\it item} from
|
|
the doubly-linked list headed by {\it head}. If ITEM is not a member
|
|
of the list, the results are not defined. The extracted item will NOT
|
|
be freed. {\tt EXTRACT\_ITEM} will reset {\it head} if necessary.
|
|
This is useful for extracting a single item for future use from a
|
|
linked list of {\it VLINK}s and then running {\tt vllfree()} on the
|
|
list.
|
|
|
|
\end{itemize}
|
|
|
|
The data structure {\it TOKEN} is also used by this API interface.
|
|
It obeys the same doubly linked list convention that {\it VLINK}
|
|
does.
|
|
|
|
\section {Error Reporting}
|
|
|
|
\begin{verbatim}
|
|
extern char *m_error;
|
|
\end{verbatim}
|
|
|
|
All of the functions described in this file set the global variable
|
|
{\tt m\_error} to signal success or failure. Upon failure, they
|
|
will return with {\tt m\_error} set to a pointer to a string which
|
|
is an error message. Upon success, they will return with {\tt
|
|
m\_error} set to a {\it NULL} pointer.
|
|
|
|
\section{Library Calls}
|
|
|
|
\subsection{\tt {\it VLINK }m\_top\_menu({\it void})}
|
|
|
|
{\tt m\_top\_menu()} takes no arguments. It returns a single {\it
|
|
VLINK}, which is a link to the first menu to be displayed to the user.
|
|
You then call m\_get\_menu() to get the contents of that menu.
|
|
|
|
\subsubsection{Implementation}
|
|
|
|
Return a vlink whose host and hsoname are set from the VSWORK\_HOST and
|
|
VSWORK\_FILE environment variables. The NAME of this vlink (the menu
|
|
title that will be displayed) should for now be the last component of
|
|
the VSNAME environment variable. Later we will talk about how to
|
|
start up the browser when somebody is not yet VFSETUP to any virtual
|
|
system.
|
|
|
|
\subsubsection{Additional ways to get top menu --- EXCEPTION TO API}
|
|
|
|
Some menu browsers allow the top menu to be specified on the command
|
|
line, using either native information or a directory name in the
|
|
currently active virtual system. At the moment, no API functions are
|
|
specified to handle this situation, and the PFS library must be called
|
|
directly. If the top menu is specified as a directory name in the
|
|
currently active virtual system, just use rd\_vlink() for now. If it
|
|
was specified with native information, vlalloc() a new link, set its
|
|
HSONAME to the native hsoname, its HOST to the native host, and use
|
|
rd\_vlink(). Eventually, we will design an API function or two to
|
|
handle getting the top menu by Prospero file name or by host and
|
|
hsoname.
|
|
|
|
|
|
\subsection{\tt {\it VLINK }m\_get\_menu({\it VLINK} menu)}
|
|
|
|
{\tt m\_get\_menu()} is given a {\it VLINK} to a menu as its argument.
|
|
It will return an ordered list of {\it VLINK}s, each corresponding to
|
|
an item in the menu.
|
|
|
|
\subsubsection{Implementation}
|
|
|
|
This orders the VLINKs according to the {\sc COLLATION-ORDER} attribute.
|
|
|
|
When asking for attributes to be returned in the underlying Prospero
|
|
call, please specify that you want
|
|
MENU-ITEM-DESCRIPTION+COLLATION-ORDER+ACCESS-METHOD to be returned.
|
|
(Of course, do this only if you are using a PFS library interface that
|
|
allows you to specify which attributes you are requested; at the
|
|
moment, none of the interfaces allow this.)
|
|
This will help us be compatible with possible future changes to the
|
|
way the server works.
|
|
|
|
The 1st two attributes are ones we need to display the menu. Asking
|
|
for the ACCESS-METHOD right away is also a good idea, since if you
|
|
don't support an access-method for a file, you can choose show on the
|
|
menu either that it is unreachable or not display it at all.
|
|
|
|
\subsection{\tt {\it char *} m\_item\_description({\it VLINK vl})}
|
|
|
|
This returns a string to be displayed as a description for the menu item
|
|
associated with VLINK. This is a pointer to data that may be
|
|
overwritten on the next call to {\tt m\_item\_description()}, but not before.
|
|
|
|
If {\it vl} is a link to a sub-menu, then, when that sub-menu is
|
|
displayed, most clients will also use the string returned by {\tt
|
|
m\_item\_description()} as a title for that sub-menu.
|
|
|
|
\subsubsection{Implementation}
|
|
|
|
Look at the {\sc MENU-ITEM-DESCRIPTION} attribute associated with {\it
|
|
vl}. If that fails,look at {\it vl}'s {\tt name} member.
|
|
|
|
\subsection{\tt {\it int} m\_class({\it VLINK vl})}
|
|
|
|
Return a CLASS for the object pointed to by the link. The class says
|
|
what you can do with an object (view it, read it, run a search through
|
|
it, open it up as a submenu, use it to connect to another service, etc.) These classes are constants defined
|
|
in the API.H file. They are: {\sc m\_class\_unknown} (must have a
|
|
value of 0), {\sc m\_class\_menu, m\_class\_document, m\_class\_search,
|
|
m\_class\_portal, m\_class\_sound, m\_class\_image, m\_class\_data,
|
|
and m\_class\_void}.
|
|
|
|
|
|
\subsubsection{Implementation}
|
|
|
|
This is derived from the value of the {\sc object-interpretation}
|
|
attribute. We are working on a new portable interface to this
|
|
function which lets the browser specify whether it knows how to
|
|
display/retrieve/access particular types and particular subtypes. The
|
|
current implementation of the api returns {\sc m\_class\_data} for
|
|
any types that it recognized but cannot perform an appropriate complex
|
|
operation on (e.g., if the OBJECT-INTERPRETATION is a SOUND but you
|
|
have no sound player), then return {\sc m\_class\_data}, and any
|
|
unknown types are returned as {\sc m\_class\_unknown}.
|
|
|
|
\subsection{\tt {\it TOKEN} m\_interpretation({\it vLINK vl})}
|
|
|
|
This will return the sequence that is the value of the
|
|
OBJECT-INTERPRETATION attribute. You will call m\_interpretation() for
|
|
information that will let you actually display the file. This is used
|
|
internally by m\_class(), too.
|
|
|
|
\subsubsection{Implementation}
|
|
|
|
Warning: The current api implementation does not fully meet this specification
|
|
for m\_interpretation().
|
|
|
|
If no {\sc object-interpretation} attribute is present, we look at the
|
|
{\it vl}'s {\tt target} member and see if it is {\tt DIRECTORY}, {\tt
|
|
EXTERNAL}, or {\tt FILE}, and we also perform some simple tests on the
|
|
suffix of a file to check whether it is likely to be a binary or text
|
|
file. If it ends in {\tt .gif,} it's IMAGE GIF. If it ends in {\tt
|
|
.ps} or {\tt .PS,} it's DOCUMENT POSTSCRIPT. If it ends in {\tt .Z,}
|
|
it's EMBEDDED COMPRESS, then strip off the {\tt .Z} and try again for
|
|
the rest of the object interpretation. If it ends in {\tt .z} or {\tt
|
|
.gz,} it's EMBEDDED GZIP. Otherwise, assume it's DOCUMENT TEXT ASCII.
|
|
|
|
The {\sc object-interpretation} attribute is further defined in the
|
|
{\tt working-notes} subdirectory of the menu sources.
|
|
|
|
\subsection{\tt {\it FILE *} m\_fopen\_file({\it VLINK vl})}
|
|
|
|
This opens the file referenced by {\it vl} in read-only mode and
|
|
returns a standard IO library {\it FILE} pointer to it, which is then
|
|
read from and manipulated in accordance with the stdio library
|
|
routines.
|
|
|
|
\subsubsection{Implementation}
|
|
|
|
This is just an interface to {\tt pfs\_fopen()}.
|
|
|
|
\subsection{\tt {\it int} m\_open\_file({\it VLINK vl})}
|
|
|
|
This opens the file referenced by {\it vl} in read-only mode and
|
|
returns a standard UNIX integer file descriptor referring to it. This
|
|
descriptor can then be manipulated in accordance with the standard
|
|
conventions.
|
|
|
|
\subsubsection{Implementation}
|
|
|
|
This is just an interface to {\tt pfs\_open()}.
|
|
|
|
\subsection{\tt {\it void} vlfree({\it vl}), {\it void} vllfree({\it vl}),
|
|
{\it VLINK} vlcopy({\it VLINK vl, int r})}
|
|
|
|
{\tt vlfree()} frees the vlink {\it vl}. It should be called on the
|
|
link returned by {\tt m\_top\_menu()} when the application no
|
|
longer has a use for it. {\tt vllfree} frees a linked list of {\it
|
|
vlink}s headed by {\it vl}. It should be called on the list returned
|
|
by {\tt m\_get\_menu()} when the application no longer has a need for
|
|
it.
|
|
|
|
{\tt vlcopy()} returns a copy of {\it vl}, with the {\tt next} and {\tt
|
|
previous} members set to the null pointer. {\it r} should always be zero.
|
|
|
|
\subsubsection{Implementation}
|
|
|
|
These three functions are already in libpfs; you don't need to implement them.
|
|
|
|
\end{document}
|