COMMENT @%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

	Copyright (c) GeoWorks 1992 -- All Rights Reserved

PROJECT:	Include Files
MODULE:		IACP Specification
FILE:		iacp.def

AUTHOR:		Adam de Boor, Oct 12, 1992

REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	ardeb	10/12/92	Initial revision


DESCRIPTION:
	Definition of IACP structures, constants and routines
		
	$Id: iacp.def,v 1.1 97/04/04 14:24:49 newdeal Exp $

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%@

SetDef	__IACP

StartLibrary	ui

;------------------------------------------------------------------------------
;
;		       Data Types and Constants
;
;------------------------------------------------------------------------------

;
; The data type used to identify an active IACP connection.
; 
IACPConnection	type	word

IACP_NO_CONNECTION	equ	0	; Returned by IACPConnect if it is
					;  unable to establish a connection
;
; The mode in which an IACP server is operating. A user-interactible server
; is expected to cope with messages addressed to a non-user-interactible server,
; but the reverse is not true.
; 
IACPServerMode	etype	byte
    IACPSM_NOT_USER_INTERACTIBLE	enum IACPServerMode
    IACPSM_IN_FLUX			enum IACPServerMode
    IACPSM_USER_INTERACTIBLE		enum IACPServerMode

IACPServerFlags		record
    IACPSF_MULTIPLE_INSTANCES:1
    ; Set if application may have multiple instances of itself launched
    
    IACPSF_MAILBOX_DONT_ASK_USER:1
    ; Asks the Mailbox library to not notify the user of new messages for this
    ; application when it's the foreground application; the app will itself
    ; handle notification.

    :6
IACPServerFlags		end

IACPConnectFlags	record		; Flags to pass to IACPConnect
    :10

    IACPCF_OBEY_LAUNCH_MODEL:1
    ; Set if IACP should obey any launch model for the field that would cause it
    ; to ask the user whether an existing server should be used, or a new one
    ; started. AppLaunchBlock must be passed w/ALB_appMode set to
    ; OPEN_APPLICATION and IACPCF_SERVER_MODE set to IACPSM_USER_INTERACTIBLE.

    IACPCF_CLIENT_OD_SPECIFIED:1
    ; Set to indicate ^lcx:dx contains client OD for the IACP connection. If
    ; not set, the client OD is set to the application object of the process on
    ; whose thread the IACPConnect call is made.

    IACPCF_FIRST_ONLY:1
    ; Set to connect only to the first server on the list, else connects to
    ; all of them.

    IACPCF_SERVER_MODE IACPServerMode : 3
    ; Mode in which server is expected to be operating (IACPSM_IN_FLUX not
    ; allowed). Higher-numbered modes are expected to support requests for
    ; lower-numbered modes.

IACPConnectFlags	end

IACPSide	etype	word		; Specify which side of an IACP
					;  connection is sending a message
					;  via IACPSendMessage
    IACPS_CLIENT	enum	IACPSide
    IACPS_SERVER	enum	IACPSide

;
; Reason an IACPConnect failed. Note that if no server exists, and the
; caller passed an AppLaunchBlock, and IACP was unable to load the server,
; it will return a GeodeLoadError (defined in geode.def). IACPConnectError codes
; purposely start after the highest GeodeLoadError
; 
IACPConnectError	etype	word, GeodeLoadError
    IACPCE_CANNOT_FIND_SERVER	enum IACPConnectError
    ; asked to start server w/o specifying location of app, and IACP was
    ; unable to find an application with the same token as the list.
    ; 

    IACPCE_NO_SERVER		enum IACPConnectError
    ; didn't ask IACP to start server, and no server is registered for the list.
    ; 


;------------------------------------------------------------------------------
; 
;			Imported MetaMessages
;
;------------------------------------------------------------------------------

MSG_META_IACP_PROCESS_MESSAGE			method	MetaIACPMessages
; Dispatch an IACP message to its rightful destination, sending the
; passed completion message back when that has finished.
;
; Context:	This is sent by the IACP system to get the processing
;		of the two recorded messages to happen on someone else's
;		time.
; Source:	IACPSendMessage
; Destination:  Any object registered as an IACP server, or the GenApplication
;		object of a geode who is a client of such.
; Interception: If you have an object other than GenApplication that is an
;		IACP server, you will need to intercept this message. You
;		do not need to pass it to the superclass. Usually you will
;		just want to call IACPProcessMessage.
;
; Pass:
;		cx - handle of recorded message the other side of the
;		     connection is actually sending.
;		dx - TravelOption or -1. If -1, cx should be dispatched
;		     via MessageDispatch, else it should be delivered by
;		     sending MSG_META_SEND_CLASSED_EVENT to yourself.
;		bp - handle of recorded message to send when the message in cx
;		     has been handled. If 0, then there's no completion
;		     message to send.
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_IACP_NEW_CONNECTION			method	MetaIACPMessages
; Take note that another client has connected to you.
;
; Context:	Sent by the IACP system to every server to which a client
;		connects when it calls IACPConnect
; Source:	IACPConnect
; Destination:  Any object registered as an IACP server.
; Interception: Must be intercepted if you want to do anything about receiving
;		a new client, as there is no default handler for this message.
;		If you don't intercept it, no harm done.
;
; Pass:
;		cx	= handle of AppLaunchBlock passed to IACPConnect. DO
;			  NOT FREE THIS BLOCK.
;		dx	= non-zero if recipient was just launched (i.e. it
;			  received the AppLaunchBlock in its MSG_META_ATTACH
;			  call)
;		bp	= IACPConnection that is now open.
;
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_IACP_LOST_CONNECTION			method	MetaIACPMessages
; Take note that one of your clients has shutdown.
;
; Context:	Sent by the IACP system to the other side of a connection
;		when one side shuts down.
; Source:	IACPShutdown
; Destination:  Any object registered as an IACP server, or the GenApplication
;		object of a geode who is a client of such.
; Interception: Must be intercepted if you want to do anything about losing
;		a client or server, as there is no default handler for this
;		message. IACPLostConnection is a good routine for servers
;		to call (and is called by GenApplication, for example) to ensure
;		that connections don't hang around too long after the client
;		has shut down its side.
;
; Pass:
;		cx	= server number that shut down, or 0 if it was the
;			  client that shut down, and thus it's a server that's
;			  receiving this message.
;		bp	= IACPConnection being closed
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_IACP_SHUTDOWN_CONNECTION		method	MetaIACPMessages
; Shutdown the appropriate side of the indicated connection.
;
; Context:	Sent to server object after all relevant queues have been
;		flushed following a call to IACPLostConnection.
; Source:	IACPLostConnection, after a delay
; Destination:  Any IACP server object
; Interception: Must be intercepted to finish the work of the call to
;		IACPLostConnection. Call IACPShutdownConnection to
;		get default handling of this message.
;
; Pass:
;		bp	= IACPConnection to shutdown
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_IACP_DOC_OPEN_ACK			method MetaIACPMessages
; The document passed in the AppLaunchBlock when the IACP connection was
; made has been opened. The optr of the GenDocument object managing the
; document is passed so messages can be sent to it explicitly, though
; these messages must always be sent via IACP (with a TravelOption of -1),
; not using ObjMessage, to deal with the application being able to exit at
; any time.
;
; Context:	Sent to the client of a new IACP connection if a document
; 		was passed in the AppLaunchBlock.
; Source:	GenDocumentGroup
; Destination:	IACP client (i.e. GenApplication object of client app)
; Interception:	No default handler defined.
;
; Pass:
; 		ss:bp	= IACPDocOpenAckParams
; Return:
; 		nothing
; 		ax, cx, dx, bp - destroyed
; 
IACPDocOpenAckParams	struct
    IDOAP_docObj	optr		; optr of the document object managing
					;  the document
    IDOAP_connection	IACPConnection	; connection over which open request
					;  was received
    IDOAP_serverNum	word		; server number the document object's
					;  GenApplication object is for that
					;  connection (0 if connection goes
					;  through some other object)
IACPDocOpenAckParams	ends


MSG_META_IACP_DOC_CLOSE_ACK			method	MetaIACPMessages
; This is the acknowledgement sent by GenDocument after processing
; MSG_GEN_DOCUMENT_CLOSE telling if the close was successful. Documents opened
; via IACP always operate in transparent mode, meaning if you close a dirty
; document, it will be saved. If you don't want the changes saved, you
; will have to send a message to revert the document.
;
; Context:	Sent by GenDocument after processing MSG_GEN_DOCUMENT_CLOSE
; Source:	GenDocumentClass
; Destination:  IACP client
; Interception: No default handler defined.
;
; Pass:
;		ss:bp	= IACPDocCloseAckParams
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;
IACPDocCloseAckParams	struct
    IDCAP_docObj	optr
    IDCAP_connection	IACPConnection
    IDCAP_serverNum	word
    IDCAP_status	word		; DocQuitStatus (gDocGrpC.def)
IACPDocCloseAckParams	ends

protominor IACPNewForJedi

MSG_META_IACP_ALLOW_FILE_ACCESS			method	MetaIACPMessages
; This message is sent to the server of a file (as registered via
; IACPRegisterDocument) when a client to a connection established via
; IACPConnectToDocumentServer needs access to access the file being served
; (e.g., do a FileOpen on it, denying read/write privilege to others).
; The recipient of this message should do its best to release its grip on
; the file in question (the 48-bit unique file identifier can be obtained
; by passing the IACPConnection to IACPGetDocumentConnectionFileID) until
; it receives notification that the client is finished with the file via
; MSG_META_IACP_NOTIFY_FILE_ACCESS_FINISHED.
;
; Context:	Sent to server object by client requesting exclusive
;		access to a file.
; Source:	IACPSendMessage
; Destination:  IACP server
; Interception: The default GenApplicationClass behavior for this message is
; 		to check for HINT_APPLICATION_QUIT_ON_IACP_ALLOW_FILE_ACCESS,
;		and send itself a MSG_META_DETACH, if found. If not found,
;		GenApplicationClass will send a MSG_GEN_DOCUMENT_CLOSE_FILE
;		to its model exclusive. Applications which register as servers
;		of files which are not governed by a GenDocument, and which
;		don't wish to detach when they receive this message, should
;		intercept this message to close the file in question.
;
; Pass:
;		bp - IACPConnection
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;



MSG_META_IACP_NOTIFY_FILE_ACCESS_FINISHED	method	MetaIACPMessages
; This message is sent to the server of a file (as registered via
; IACPRegisterDocument) when a client to a connection established via
; IACPConnectToDocumentServer has released its hold on the file in question,
; to inform the server that it may reopen the file. The 48-bit unique file
; identifier can be obtained by passing the IACPConnection to
; IACPGetDocumentConnectionFileID, but note that there is no direct way
; to map the unique identifier to a path and filename, as such that you
; might pass to FileOpen, VMOpen, et. al., so the server object may need
; to maintain a record of which file identifiers are associated with which
; filenames if there's to be any question about which is which.
;
; Context:	Sent to server object by client to inform the server that
;		it may reopen the file in question, if desired.
; Source:	IACPSendMessage
; Destination:  IACP server
; Interception: The default GenApplicationClass behavior for this message is
; 		to check for HINT_APPLICATION_QUIT_ON_IACP_ALLOW_FILE_ACCESS,
;		and do nothing, if found. If not found,	GenApplicationClass
;		will send a MSG_GEN_DOCUMENT_REOPEN_FILE to its model
;		exclusive. Applications which register as servers
;		of files which are not governed by a GenDocument, and which
;		don't wish to detach when they receive this message, should
;		intercept this message to reopen the file in question.
;
; Pass:
;		bp - IACPConnection
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

protominor	IACPForDataExchange

MSG_META_IACP_DATA_EXCHANGE			method	MetaIACPMessages
;
;	cxdx = DataXInfo buffer
;	bp = IACPConnection
;
; This message is sent to an application when they are being requested
; for a data pipe.  See the Data Exchange Library or the Hilton tech
; spec for details.
;

protoreset

;------------------------------------------------------------------------------
;
;			  Exported Routines
;
;------------------------------------------------------------------------------

global	IACPRegisterServer:far
;
;	Desc:	Register an object as a server for a particular list. Can
;		also be used to change the mode in which the server is
;		registered.
;	Pass:	es:di	= GeodeToken for the list
;		^lcx:dx	= server object
;		al	= IACPServerMode
;		ah	= IACPServerFlags
;		
;	Return:	nothing
;	Destroyed:	nothing
;

global	IACPUnregisterServer:far
;
;	Desc:	Unregister an object as a server for a particular list.
;	Pass:	es:di	= GeodeToken for the list
;		^lcx:dx	= server object
;	Return:	nothing
;	Destroyed:	nothing
;

global	IACPRegisterDocument:far
;
;	Desc:	Register a document as being open, specifying the server to
;		which to connect to communicate about the document.
;	Pass:	^lbx:si	= server object
;		ax	= disk handle
;		cxdx	= FileID
;	Return:	nothing
;	Destroyed:	nothing
;

global	IACPUnregisterDocument:far
;
;	Desc:	Indicate a document is closed. New-connection messages may
;		still be queued based on the document having been registered,
;		so the caller will need to handle those gracefully.
;	Pass:	^lbx:si	= server object
;		ax	= disk handle
;		cxdx	= FileID
;	Return:	nothing
;	Destroyed:	nothing
;

global	IACPGetDocumentID:far
;
;	Desc:	Figure the 48-bit ID for a document (this can be gotten most
;		efficiently using FileGetHandleExtAttributes once you've got
;		the thing open, but sometimes you need the ID when all you
;		have is the path, so...)
;	Pass:	ds:dx	= directory in which document resides
;		bx	= disk on which document resides
;		ds:si	= name of document
;	Return:	carry set on error:
;			ax	= FileError
;			cx, dx	= destroyed
;		carry clear if ok:
;			ax	= disk handle (may be different from passed bx
;				  if document is actually a link)
;			cxdx	= FileID
;	Destroyed:	nothing
;

global	IACPConnect:far
global	IACPConnectToDocumentServer:far
;
;	Desc:	Establish a connection with one or all of the servers
;		on a particular list.
;	Pass:	(IACPConnect)
;		es:di	= GeodeToken for the list
;		ax	= IACPConnectFlags
;		^hbx	= AppLaunchBlock if server is to be launched,
;			  should none be registered
;		^lcx:dx	= client object, if IACPCF_CLIENT_OD_SPECIFIED
;			  set in ax.
;		(IACPConnectToDocumentServer)
;		ax	= IACPConnectFlags
;		^lcx:bp	= client optr if IACPCF_CLIENT_OD_SPECIFIED
;		bx	= disk handle
;		ds:dx	= directory name
;		ds:si	= file name
;	Return:	carry set on error:
;			ax	= IACPConnectError or GeodeLoadError
;				  (the two sets of errors are disjoint)
;		carry clear if successful connection made:
;			bp	= IACPConnection token
;			cx	= number of servers connected to
;			ax	= destroyed
;	Destroyed:	dx, bx
;
;	Notes:	In some cases, messages sent through the returned connection
;		will be held up until the server can field them. This happens,
;		for example, if an application needs to change from engine
;		mode to application mode in order to handle the connection. Once
;		it's safely in application mode, the server will call
;		IACPFinishConnect and release and process any queued messages.
;		All of this is transparent to the client.
;

global	IACPFinishConnect:far
;
;	Desc:	Complete the process of connecting. Called by the server
;		when it's ready to accept messages from the client.
;	Pass:	^lcx:dx	= server that's ready to accept client messages
;		bp	= IACPConnection over which it's willing to accept
;			  them.
;	Return:	nothing
;	Destroyed:	nothing
;

global	IACPSendMessage:far
global	IACPSendMessageAndWait:far
;
;	Desc:	Send a message through an IACP connection to all
;		connected servers, or to the client, depending on
;		which side is doing the sending.
;	Pass:	bp	= IACPConnection
;		bx	= recorded message to send
;		dx	= TravelOption, -1 if recorded message
;			  contains the proper destination already
;		cx	= completion message, 0 if none
;		ax	= IACPSide doing the sending.
;	Return:	ax	= number of servers to which message was
;			  sent.
;	Destroyed:	bx, cx, dx, both recorded messages
;

global	IACPSendMessageToServer:far
;
;	Desc:	Send a message through an IACP connection to a specific
;		connected server.
;	Pass:	bp	= IACPConnection
;		bx	= recorded message to send
;		dx	= TravelOption, -1 if recorded message
;			  contains the proper destination already
;		cx	= completion message, 0 if none
;		ax	= server number (1 -> numServers)
;	Return:	ax	= number of servers to which message was
;			  sent (1 or 0).
;	Destroyed:	bx, cx, dx, both recorded messages
;

global	IACPGetServerNumber:far
;
;	Desc:	Returns the number a server object is for a particular
;		IACP connection, so the client can use the number to direct
;		a message to a particular server.
;	Pass:	bp	= IACPConnection
;		^lcx:dx	= server object
;	Return:	ax	= server number (0 if object isn't a server for the
;			  connection)
;	Destroyed:	nothing
;

global	IACPShutdown:far
;
;	Desc:	Sever an IACP connection. MSG_META_IACP_LOST_CONNECTION
;		is sent to the other side of the connection.
;	Pass:	bp	= IACPConnection to shut down
;		^lcx:dx	= server object, or cx == 0 if client is
;			  shutting down.
;	Return:	nothing
;	Destroyed:	ax
;

global	IACPShutdownAll:far
;
;	Desc:	Shutdown all connections open to or from an object
;	Pass:	^lcx:dx	= client or server object for which all
;			  connections are to be shutdown.
;	Return:	nothing
;	Destroyed:	ax
;

global	IACPProcessMessage:far
;
;	Desc:	Utility routine to handle a MSG_META_IACP_PROCESS_MESSAGE.
;		Can be bound as the method for this message for any class
;		that might receive it.
;	Pass:	cx	= handle of message to send
;		dx	= TravelOption or -1
;		bp	= handle of message to send after cx is
;			  processed, or 0 if no completion
;			  notification is needed.
;		*ds:si	= server object
;	Return:	nothing
;	Destroyed:	ax, bx, cx, dx, bp, si, di
;

global	IACPLostConnection:far
;
;	Desc:	Utility routine to handle a MSG_META_IACP_LOST_CONNECTION
;		received by a server object (the handling is likely
;		inappropriate for one received by a client object). The
;		routine queues a MSG_META_IACP_SHUTDOWN_CONNECTION
;		message for the server object to make sure all requests
;		by the client have been processed before calling IACPShutdown.
;	Pass:	*ds:si	= server object
;		bp	= IACPConnection
;	Return:	nothing
;	Destroyed:	ax, bx, cx, dx, bp, di
;

global 	IACPShutdownConnection:far
;
;	Desc:	Utility routine to handle a MSG_META_IACP_SHUTDOWN_CONNECTION
;		by calling IACPShutdown, passing the optr of the server object.
;	Pass:	*ds:si	= server object
;		bp	= IACPConnection to shut down.
;	Return:	nothing
;	Destroyed:	ax, cx, dx, bp
;

global	IACPCreateDefaultLaunchBlock:far
;
;	Desc:	Utility routine to create an AppLaunchBlock to be given to
;		IACPConnect. The block is initialized with the following
;		defaults:
;			- IACP will locate the app, given its token
;			- initial directory should be SP_DOCUMENT
;			- no initial data file
;			- application will determine generic parent for
;			  itself
;			- no one to notify in event of an error
;			- no extra data
;	Pass:	dx	= mode in which server should be launched:
;			  MSG_GEN_PROCESS_OPEN_APPLICATION or
;			  MSG_GEN_PROCESS_OPEN_ENGINE
;	Return:	carry clear if block created:
;			^hdx	= AppLaunchBlock
;		carry set if couldn't allocate memory
;	Destroyed:	nothing
;

global	IACPLocateServer:far
;	Desc:	Locate the server application for a token.
;
;	Pass:	es:di	= GeodeToken
;	Return:	carry set if couldn't be found
;			bx	= destroyed
;		carry clear if server found:
;			^hbx	= AppInstanceReference with AIR_diskHandle and
;				  AIR_fileName filled in.

global	IACPBindToken:far
;	Desc:	Bind a path under SP_APPLICATION or SP_SYS_APPLICATION to a
;		GeodeToken, for the purposes of IACP server location. This is
;		used most often, when installing a new application, to make
;		the application the server for one of the generic application-
;		class tokens used in system inbox/outbox transactions.
;
;	Pass:	es:di	= GeodeToken
;		ds:dx	= null-terminated path below SP_APPLICATION or
;			  SP_SYS_APPLICATION of the server for the token.
;	Return:	nothing
;		.ini file *not* committed
;

global	IACPUnbindToken:far
;	Desc:	Remove the binding between a GeodeToken and an application.
;		Note that this will not prevent the application from being
;		found under its own token, but those aren't the sort of bindings
;		usually established in this way, so that shouldn't worry
;		anyone.
;
;	Pass:	es:di	= GeodeToken
;	Return:	nothing
;		.ini file *not* committed
;

global      IACPREGISTERSERVER:far
global      IACPUNREGISTERSERVER:far
global      IACPCONNECT:far
global      IACPCONNECTTODOCUMENTSERVER:far
global      IACPSENDMESSAGE:far
global	    IACPSENDMESSAGETOSERVER:far
global      IACPSENDMESSAGEANDWAIT:far
global      IACPGETDOCUMENTID:far
global      IACPSHUTDOWN:far
global      IACPSHUTDOWNALL:far
global      IACPPROCESSMESSAGE:far
global      IACPLOSTCONNECTION:far
global      IACPCREATEDEFAULTLAUNCHBLOCK:far
global	    IACPGETSERVERNUMBER:far
global	    IACPREGISTERDOCUMENT:far
global	    IACPUNREGISTERDOCUMENT:far
global	    IACPFINISHCONNECT:far
global	    IACPBINDTOKEN:far
global	    IACPUNBINDTOKEN:far
global	    IACPLOCATESERVER:far

EndLibrary	ui
