% 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}