-- STPSubr.Mesa, last edit February 4, 1983 2:14 pm
-- definitions file for commonly used STP procedures
-- implemented in STPSubrImpl.Mesa
	
DIRECTORY
  File: TYPE USING [Capability, Permissions, read],
  UnsafeSTP: TYPE USING [ErrorCode, Type, -- FileType, -- Handle],
  Stream: TYPE USING [Handle],
  Subr: TYPE USING[TTYProcs],
  System: TYPE USING [gmtEpoch];
	
STPSubr: DEFINITIONS = {
	
	RetrieveProcType: TYPE = PROC[fileName: LONG STRING, stp: UnsafeSTP.Handle, 
			remoteStream: Stream.Handle] RETURNS[skipRest: BOOL];
	
	-- in all the procedures below that take h as a parameter,
	-- if h = NIL then it uses Exec.w for prompting for input
	
	-- this is an attempt to handle the confusing aspects of remote enumerates
	-- and retrieves
	-- you call EnumerateForRetrieve and I call enumProc with each file that matches
	-- you never need to catch credentialsErrors out of EnumerateForRetrieve;
	--  you might want to catch noSuchFile
	EnumerateForRetrieve: PROC[host, filePattern: LONG STRING,
		enumProc: RetrieveProcType, h: Subr.TTYProcs,
		onlyOne: BOOL ← TRUE];
	
	-- filename can be local or remote
	-- if possible you should call StopSTP at the end of your program
	-- set fileType if this is Subr.Write
	-- set createtime if this is Subr.Write to a remote stream
	GeneralOpen: PROC[filename: LONG STRING, h: Subr.TTYProcs, 
		access: File.Permissions ← File.read, 
		fileType: UnsafeSTP.Type← unknown, 
		createtime: LONG CARDINAL ← LOOPHOLE[System.gmtEpoch]] 
		RETURNS[sh: Stream.Handle, stphandle: UnsafeSTP.Handle];
	-- close the stream, simply call Space.Delete[sh]
	
	-- just like GeneralOpen but filename can be a pattern,
	-- you pass it a proc
	PatternGeneralOpen: PROC[filepattern: STRING, proc: RetrieveProcType, 
		h: Subr.TTYProcs];
	
	
	StpState: TYPE = LONG POINTER TO StpStateRecord;
	StpStateRecord: TYPE = RECORD[
		checkForOverwrite: BOOL ← TRUE
		];
	
	-- raises Subr.FileError if can't find file on local or remote
	-- if host or directory are NIL, then just like Subr.NewStream[];
	-- if wantExplicitVersion is true, wantcreatetime = 0, and version > 0,
	--	then gets that version
	--	otherwise gets !H when wantcreatetime = 0
	CachedOpen: PROC[host, directory, shortname: LONG STRING, 
		version: CARDINAL, wantcreatetime: LONG CARDINAL, 
		h: Subr.TTYProcs,
		stpState: StpState, wantExplicitVersion: BOOL, onlyOne: BOOL ← TRUE,
		tryDollars: BOOL ← FALSE] RETURNS[sh: Stream.Handle, cap: File.Capability];
	
	-- just like CachedOpen but avoids FileStream.Create
	CachedRetrieve: PROC[host, directory, shortname: LONG STRING, 
		version: CARDINAL, wantcreatetime: LONG CARDINAL, h: Subr.TTYProcs,
		stpState: StpState, wantExplicitVersion: BOOL, onlyOne: BOOL ← TRUE, 
		tryDollars: BOOL ← FALSE] RETURNS[cap: File.Capability];
	
	Connect: PROC[host: LONG STRING, h: Subr.TTYProcs, 	
		onlyOne: BOOL ← FALSE] RETURNS[stphandle: UnsafeSTP.Handle];
	
	-- always returns NIL
	ForceClosed: PROC[stphandle: UnsafeSTP.Handle] RETURNS[UnsafeSTP.Handle];
	
	StopSTP: PROC;
	
	
	-- these procedures can be called without using the Connect[] stphandles
	
	-- used by SModelImpl
	Store: PROC[stphandle: UnsafeSTP.Handle, remoteName: LONG STRING, 
		localCap: File.Capability, createDate: LONG CARDINAL, 
		h: Subr.TTYProcs] RETURNS[nbytes: LONG CARDINAL];
	
	-- takes contents of remotesh and writes them onto file localfilename
	-- returns cap, a File.Capability for the file it wrote onto WITH Write permission
	-- may raise UnsafeSTP.Error
	WriteStreamToDisk: PROC[remotesh: Stream.Handle, localfilename: LONG STRING,
		byteLengthHint: LONG CARDINAL, h: Subr.TTYProcs] 
		RETURNS[cap: File.Capability, nbytes: LONG CARDINAL];
	
	HandleSTPError: PROC[stphandle: UnsafeSTP.Handle, stpError: UnsafeSTP.ErrorCode, 
		message: LONG STRING, h: Subr.TTYProcs]
		RETURNS[retryit: BOOL];
	
	AddUserName: PROC[sto: LONG STRING, spat: STRING, h: Subr.TTYProcs];
	
	MakeSTPHandle: PROC[host: LONG STRING, h: Subr.TTYProcs] 
		RETURNS[stphandle: UnsafeSTP.Handle];
	
	-- when called, sets useCIFS to shouldUseCIFS in STPSubrImpl.Mesa
	SetUseOfCIFS: PROC[shouldUseCIFS: BOOL];		
	  
	SetNumberOfConnectTries: PROC[nTries: CARDINAL];
	
	}.