-- CIFS.mesa  June 2, 1982 6:55 pm
-- Interface to the Cedar Interim File System.
-- Coded August, 1981 by D. Gifford
-- Last edited by
--   MBrown on August 30, 1982 1:06 pm


DIRECTORY
  Ascii: TYPE USING [NUL],
  File: TYPE USING [Capability],
  Rope: TYPE USING [ROPE];

CIFS: CEDAR DEFINITIONS = {

-- Public Procedures
-- Operations that everyone will want to use

  OpenFile: TYPE = REF FileObject;
  FileObject: TYPE;
    -- This type represents an open file.
    -- If an instance is not NIL, it represents an open file.

  Context: TYPE = REF ContextObj;
    -- If NIL is supplied as a context, CIFS will use its default context  
    
  ContextObj: TYPE;
   

  Mode: TYPE = CARDINAL;
  -- any combination of modes can be used, but useful sets
  -- of combinatatons are:
  --  {read}, {write}, {write, create}, {write, replace}, {write, create, replace}
  -- dontCheck can be included in any of these sets 
  read: Mode = 1;
    -- read mode sets a non-exclusive lock on the file
  write: Mode = 2;
    -- write mode sets an exclusive lock on the file
    -- includes read by default
  create: Mode = 4;
    -- create mode will create a file if it doesn't exist
    -- normally write and create modes are used together
  replace: Mode = 8;
    -- Imagine that the file opened is "foo"
    -- and the file that "foo" is stored in is F
    -- replace mode does the following:
    -- (1) it creates a new empty file F' at Open time
    -- (2) this is the file returned to the client by GetFC
    -- (3) at close time it makes "foo" point to F'
    -- (4) F is made temporary so it will be deleted at the
    --   next boot 
  dontCheck: Mode = 16;
    -- If file is on the local disk, assume that the copy is current and don't
    -- check the remote sever
    -- Useful as a performance optimization for files that are "immutable" 
  
  maxPath: CARDINAL = 200;
      -- Maximum path length is 200 characters
  maxComment: CARDINAL = 300;
      -- Maximum comment length is 300 characters
   
  Close: PROC [fh: OpenFile];
      -- Close a file
      -- Errors: None
      
  Connect: PROC [name, password: Rope.ROPE];
      -- Set connect credentials
      -- Errors: None
      
  CreateDir: PROC [name: Rope.ROPE, c: Context _ NIL];
      -- Create a directory
      -- Errors: {illegalFileName, localDiskFull, noSuchDirectory, ConnectionErrors,
      --  CredentialsErrors}
      
  Delete: PROC [name: Rope.ROPE, c: Context _ NIL];
      -- Delete a file
      -- Files are created by Open
      -- Errors: {illegalFileName, noSuchFile, requestRefused, localDiskFull,
      --  fileBusy, noSuchDirectory, ConnectionErrors, CredentialsErrors}
      
  DeleteDir: PROC [name: Rope.ROPE, c: Context _ NIL];
      -- Delete a directory
      -- Errors: {noSuchDirectory, directoryNotEmpty, ConnectionErrors, CredentialsErrors}
      
  GetFC: PROC [fh: OpenFile]
    RETURNS [fc: File.Capability];
      -- Returns the Pilot File Capability of an open file
      -- Errors: None
      
  GetPathname: PROC [fh: OpenFile]
    RETURNS [path: Rope.ROPE];
      -- Returns the pathname of an open file
      -- Errors: None

  Open: PROC [name: Rope.ROPE, mode: Mode, c: Context _ NIL]
    RETURNS [fh: OpenFile];
      -- Open a file
      -- Errors: {ConnectionErrors, CredentialsErrors, FileErrors, localDiskFull, fileBusy,
      -- noSuchDirectory}
       
  Rename: PROC [from: Rope.ROPE, to: Rope.ROPE, c: Context _ NIL];
      -- Rename a file
      -- Errors: {ConnectionErrors, CredentialsErrors, FileErrors, localDiskFull, fileBusy,
      -- noSuchDirectory, fileAlreadyExists}
      
  Swap: PROC [filea: Rope.ROPE, fileb: Rope.ROPE, c: Context _ NIL];
      -- Swap the contents of filea and fileb
      -- Errors: {ConnectionErrors, CredentialsErrors, FileErrors, localDiskFull, fileBusy,
      -- noSuchDirectory}

-- Public Procedures
-- Operations that some people will want to use
        
  AddSearchRule: PROC [path: Rope.ROPE, before: BOOLEAN, c: Context _ NIL];
      -- Add a search rule
      -- If before is T it will add it before the other search rules
      -- Errors: {ConnectionErrors, CredentialsErrors, localDiskFull, noSuchDirectory}
      
  CopyContext: PROC [from: Context _ NIL]
    RETURNS [c: Context];
      -- Copy a context
      -- If from is omitted, CopyContext will return a copy of the default
      -- context.
      -- Errors: None

  CreateContext: PROC
    RETURNS [c: Context];
      -- Create a new context for the interpretation of names
      -- The "Jerry Brown" Operation
      -- Errors: None
      
  CreateLink: PROC [path, targetPath: Rope.ROPE, c: Context _ NIL];
      -- causes path to point to targetPath
      -- whenever path is used as a file name, it will be resolved to
      -- targetPath
      -- Errors: {ConnectionErrors, CredentialsErrors, localDiskFull, noSuchDirectory,
      --  linkAlreadyExists}
      
  DeleteContext: PROC [c: Context _ NIL];
      -- Destroy a context for the interpretation of names.
      -- The "Edward Kennedy" Operation
      -- Errors: None
      
  DeleteSearchRule: PROC [path: Rope.ROPE, c: Context _ NIL];
      -- Delete a search rule
      -- Errors: None
        
  EProc: TYPE = PROC [name, link, comment: REF TEXT]
    RETURNS [stop: BOOLEAN];
      -- Procedure that is called for dir enumeration
      -- name is the entry name
      -- if link.length#0 then link is the path that name will be resolved to
      -- if comment.length#0 then comment is a comment for name
      
  Enumerate: PROC [dir: Rope.ROPE, pattern: Rope.ROPE, p: EProc, c: Context _ NIL];
      -- Enumerate the contents of a directory
      -- pattern can contain "*" and "#"
      -- a pattern of "*" enumerates the entire directory.
      -- If dir = NIL or dir = "" Enumerate assumes the wdir  
      -- Errors: {ConnectionErrors, CredentialsErrors, localDiskFull, noSuchDirectory}
        
  GetSearchRules: PROC [c: Context _ NIL]
    RETURNS [LIST OF Rope.ROPE];
      -- Returns the list of paths in the search rules 
      -- Errors: None

  GetWDir: PROC [c: Context _ NIL]
    RETURNS [path: Rope.ROPE];
      -- Return the path of the working directory
      -- Errors: None
      
  Login: PROC [name, password: Rope.ROPE];
      -- Set credentials
      -- Errors: None
      
  SetDefaultContext: PROC [c: Context];
      -- Set the default context
      -- Errors: None
      
  SetComment: PROC [path, comment: Rope.ROPE, c: Context _ NIL];
      -- Sets the comment on the specified path to be comment
      -- Errors: {ConnectionErrors, CredentialsErrors, FileErrors, localDiskFull, 
      -- noSuchDirectory}
      
  SetWDir: PROC [path: Rope.ROPE, c: Context _ NIL];
      -- Set working directory
      -- Errors: {ConnectionErrors, CredentialsErrors, localDiskFull, 
      -- noSuchDirectory}
      
-- Public Procedures
-- Operations that hardly anyone will want to use

  Expand: PROC [name: Rope.ROPE, c: Context _ NIL]
    RETURNS [path: Rope.ROPE];
      -- Expands a name into a full path name
      -- May raise CIFS.Error if the file is not in the dir
      --   system.
      -- Errors: {ConnectionErrors, CredentialsErrors, FileErrors, localDiskFull, 
      -- noSuchDirectory}
   
  ExplicitBackup: PROC [name: Rope.ROPE, c: Context _ NIL]
    RETURNS [version: INT];
      -- Explicit backup of the named file to its remote server home
      -- The server's version number for the backing file is returned
      -- If name has a version number then ExplicitBackup will use
      --  that number for the backing file
      -- Errors: {ConnectionErrors, CredentialsErrors, FileErrors, fileBusy} 
       
  GetBaseFreeSpace: PROC RETURNS[pages: INT];
      -- Gets the number of free pages that should be maintained
      -- on the local disk
      -- Errors: None
  
  OpenButDontHandleError: PROC [name: Rope.ROPE, mode: Mode, c: Context _ NIL]
    RETURNS [fh: OpenFile];
      -- Open a file
      -- Same as Open, except that it will not automatically handle
      -- a credential error.
      -- Errors: {ConnectionErrors, CredentialsErrors, FileErrors, localDiskFull, fileBusy,
      -- noSuchDirectory}

  Reset: PROC [name: Rope.ROPE, c: Context _ NIL];
      -- Reset a file from its backing store
      -- name must be an absolute path name
      -- Errors: {noSuchFile}
      
  SetBaseFreeSpace: PROC[pages: INT _ 0];
      -- Sets the number of free pages that should be maintained
      -- on the local disk
      -- If pages is omitted, CIFS will just ensure that there are
      -- enough free pages according to the current setting
      -- Errors: None

-- Exceptional conditions
-- Unfortunately, everyone has to know about these
-- In each CIFS call the most likely errors are listed.  However, a client
-- should be prepared for variant of ErrorCode.  The message "error" is 
-- essential, and should be shown to the user.

  HandleError: PROC [code: ErrorCode, error: Rope.ROPE, reply: CHARACTER _ Ascii.NUL]
    RETURNS [resume: BOOLEAN];
    -- Attempts to handle a credential error.  The usage of this procedure is:
    -- CIFS.Operation[ args !
    --    CIFS.Error => {IF CIFS.HandleError[code, error, reply] THEN RESUME}];
    -- NOTE: The above code is included in CIFS, so a client does not have
    --  to write it.  This procedure is exported only for completeness.
    
  Error: SIGNAL [code: ErrorCode, error: Rope.ROPE, reply: CHARACTER _ Ascii.NUL];
    -- error usually contains an interesting message
    -- reply is the code passed from server (see STPReplyCode.mesa)
    
  ErrorCode: TYPE = {
    -- connection errors
    noSuchHost, noRouteToNetwork, noNameLookupResponse, alreadyAConnection,
    noConnection, connectionClosed, connectionRejected,
    connectionTimedOut,
    -- credentials errors
    accessDenied, illegalUserName, illegalUserPassword, illegalUserAccount,
    illegalConnectName, illegalConnectPassword, credentialsMissing,  
    -- protocol errors
    protocolError, 
    -- file errors
    illegalFileName, noSuchFile, requestRefused,
    -- remote stream errors
    accessError, 
    -- catch all
    undefinedError,
    -- local disk full
    localDiskFull,
    -- file is locked
    fileBusy,
    -- file already exists for a rename command
    fileAlreadyExists,
    -- directory does not exist
    noSuchDirectory,
    -- directory contains files and can not be deleted
    directoryNotEmpty,
    -- link alrady exists
    linkAlreadyExists
    };
    
  ConnectionErrors: TYPE = ErrorCode[noSuchHost..connectionTimedOut];
  CredentialsErrors: TYPE = ErrorCode[accessDenied..credentialsMissing];
  FileErrors: TYPE = ErrorCode[illegalFileName..requestRefused];
  
}.. 

CHANGE LOG

Changed by MBrown on August 30, 1982 1:08 pm
-- FileObject is opaque, interface is CEDAR.