(* 
	Draft ISL HTTP-NG specification for the actual client/server protocol.
	Derived from Simon Spero's 9/24/95 document.
			Authors:	Jim Gettys
					Dan Connolly
	TODO: Deal with SecuredMessage somehow...

*)

INTERFACE Server BRAND "ng-v1" IMPORTS HTTPTypes, Client END;


(* 2.1.2.2 Initializing The Connection.

 Once the connection has been opened, it must be initialized.  The
 client sends an initialization request, indicating which methods it
 supports, and what degree of synchronicity it desires.  The server
 responds with an initialization response, indicating the methods it
 supports, and what level of synchronicity it will be used.  The client
 need not wait for the initialization response before sending further
 requests.  If a request is sent which is not supported by the server,
 the server may indicate an error.

 The initialization request and response must be the first messages
 sent on each end of the connection.

 If the client supports negotiation, it should send a negotiation
 request immediately after the initialization request.  This should
 setup the basic parameters for the client, but need not contain the
 full array of available options. 
*)

(* 
	Question: in X we have a largest request size; in NG we have a 
	multiplexing transport; presumably there needs to be a way
	to control the transport chunking size.  I define a method to control
	this behavior.  It is a separate method as it may want to be
	(re)set independently of other initialization data if transport
	bandwidth available changes.

	Question: the result from an InitializationResponse is boolean
	named result.  Is this just an indication that the initialization
	succeeded?

	Question: the client and server exchange ClientSupport and
	ServerSupport fields in its initialization response messages.  
	How exactly are these fields used?  Are both fields needed?

	Question: How should Range be defined?  It is not actually
	defined in Simon's specification.  For the moment, I defined
	it to be two Long Integers (2 64 bit numbers).

*)

TYPE BitString = HTTPTypes.BitString;
TYPE SyncBehavior = HTTPTypes.SyncBehavior;
TYPE ServerConnection = OBJECT METHODS
	ASYNCHRONOUS initializeConnection(IN protocolVersion: SHORT CARDINAL,
		IN protocolModel: SyncBehavior,
		IN clientSupport: BitString,
		IN serverSupport: BitString, 	
		IN maxTransportSize: INTEGER),
	ASYNCHRONOUS setConnectionParameters(IN maxTransportSize: INTEGER)
	END;

TYPE ClientConnection = OBJECT METHODS
	ASYNCHRONOUS initializeConnection(IN protocolVersion: SHORT CARDINAL,
		IN protocolModel: SyncBehavior,
		IN clientSupport: BitString,
		IN serverSupport: BitString, IN result: BOOLEAN,
		IN maxTransportSize: INTEGER),
	ASYNCHRONOUS setConnectionParameters(IN maxTransportSize: INTEGER)
	END;




(* 
   Contexts present ISL interesting problems: they will need to be resent
   when transport failures occur, so I need to retain state on the client
   side and retransmit before any pending operations.  How do I do this
   in ILU/ISL?

   I'd like contexts to be full fledged objects, but to make them so would
   force round trips for their creation, a dead loss, as I read the current
   ISL specification.  I'd also like to shadow them on the client, 
   but I don't know how to do so.

   Question: Cloning a context we found useful in X; should we include
   it here?

   Question: Is there anyway to get resource ID's assigned on the client side?
  
   Question: what is the best way to get a bit vector?  There is no fundamental
   type, so I guess I'll use array of BYTE for now.

   Question: How do I generate protocol transport errors for bad Tags?
   This would be a buggy client, but the server needs to indicate the
   bug back to a client in some form.

   Question: PleaseNegotiate seems broken...  Negotiate relative to what?
   Presumably the specified context???  This area seems to have problems.
   And what happens if things have been set in one context, and then
   changed?  Does the request fail?  It might as well, as negotiation
   requires a round trip, but there might be consequences.  The specification
   needs help in this area.  

   HTTPMessage does not have GetRequest as an Operation.
   What does messageId do?
   Question: Simon has a SessionID returned by GetResponse... 
   Is this the stream in which the data is being delivered?

   I would make contextID implicit in each method, along with the optional
   tagged list.

   Question: USMARC metainformation standard?  Pointer to it?

*)


TYPE ServerContextID = HTTPTypes.ServerContextID;
TYPE URIOpt = HTTPTypes.URIOpt;
TYPE Tag = HTTPTypes.Tag;
TYPE TagList = HTTPTypes.TagList;
TYPE TaggedListOpt = HTTPTypes.TaggedListOpt;
TYPE Value = HTTPTypes.Value;
TYPE Option = HTTPTypes.Option;
TYPE Set = HTTPTypes.Set;
TYPE VariableName = HTTPTypes.VariableName;
TYPE OptionName = HTTPTypes.OptionName;
TYPE OptionLevel = HTTPTypes.OptionLevel;
TYPE DateOpt = HTTPTypes.DateOpt;
TYPE CancelOrSuspend = HTTPTypes.CancelOrSuspend;
TYPE BasicMetaInformation = HTTPTypes.BasicMetaInformation;
TYPE MetaInfoFields = HTTPTypes.MetaInfoFields;
TYPE MetaInfoFieldsOpt = HTTPTypes.MetaInfoFieldsOpt;
TYPE Range = HTTPTypes.Range;
TYPE HTTP1XMessage = HTTPTypes.HTTP1XMessage;
TYPE ClientDocument = Client.ClientDocument;
TYPE URI = HTTPTypes.URI;
TYPE TagVal = HTTPTypes.TagVal;
TYPE TagSet = HTTPTypes.TagSet;
TYPE TagVariable = HTTPTypes.TagVariable;
TYPE Negotiate = HTTPTypes.Negotiate;

(* Question: how to extend enumerations to allow extensions??? *)
(* Type definitions to perform Negotiation related requests *)


TYPE NegDes = ENUMERATION 
	DeleteContext, LoadProfile, SaveProfile, DefineValue,
	DefineSet, DefineList, DeleteValue, SetVariable, SetOption 
	END;
TYPE NegotiationOperation = NegDes UNION
	uri: URI = LoadProfile, SaveProfile END,
	tagval: TagVal = DefineValue END,
	tagset: TagSet = DefineSet END,
	taglist: TagList = DefineList END,
	tag: Tag = DeleteValue END,
	tagvariable: TagVariable = SetVariable END,
	option: Option = SetOption END
	END;
TYPE NegotiationOperationSeq = SEQUENCE of NegotiationOperation;


(* 
   Document objects perform callbacks on Document objects to deliver the 
   data 
*)
TYPE MessageID = HTTPTypes.MessageID;

TYPE Document = OBJECT METHODS
	(* For simple Get, the server must respond by calling the
	   basicMetaInfo method on the client, followed by the sendData
	   method to deliver the data.
	*)
	ASYNCHRONOUS simpleGet(
		IN messageID: MessageID,
		IN context: ServerContextID,
		IN opt: TaggedListOpt,
		IN metaInformationOnly: BOOLEAN,
		IN ifModifiedSince: DateOpt,
		IN referer: URIOpt,
		IN callback: ClientDocument),
	ASYNCHRONOUS get(
		IN messageID: MessageID,
		IN context: ServerContextID,
		IN opt: TaggedListOpt,
		IN metaInformationOnly: BOOLEAN,
		IN ifModifiedSince: DateOpt,
		IN referer: URIOpt,
		IN range: Range,
		IN metainfoFields: MetaInfoFields,
		IN variantspec: TaggedListOpt,
		IN callback: ClientDocument),
	ASYNCHRONOUS cancelOrSuspend(
		IN messageID: MessageID,
		IN context: ServerContextID,
		IN opt: TaggedListOpt,
		IN cancelOrSuspend: CancelOrSuspend,
		IN callback: ClientDocument),
	ASYNCHRONOUS resume(
		IN messageID: MessageID,
		IN context: ServerContextID,
		IN opt: TaggedListOpt,
		IN callback: ClientDocument),
	ASYNCHRONOUS httpTOS(
		IN messageID: MessageID,
		IN context: ServerContextID,
		IN opt: TaggedListOpt,
		IN cacheHeaders: BOOLEAN,
		IN requestStream: HTTP1XMessage),
	ASYNCHRONOUS negotiate(
		IN messageID: MessageID,
		IN context: ServerContextID,
		IN opt: TaggedListOpt,
		IN operations: NegotiationOperationSeq),
	ASYNCHRONOUS pleaseNegotiate(
		IN messageID: MessageID,
		IN context: ServerContextID,
		IN opt: TaggedListOpt,
		IN negotiation: Negotiate)
	END;