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

	Copyright (c) Geoworks 1994 -- All Rights Reserved

PROJECT:	GEOS
MODULE:		socket library
FILE:		socket.def

AUTHOR:		Eric Weber, Mar 15, 1994

MACROS:
	Name			Description
	----			-----------

REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	EW	3/15/94   	Initial revision


DESCRIPTION:
	External definitions for socket library
	contains definitions for applications and for drivers
		
	$Id: socket.def,v 1.1 97/04/04 14:21:54 newdeal Exp $

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

SetDef	__SOCKET

StartLibrary	socket

;#############################################################################
;		       Socket data types
;#############################################################################

Socket	type	word	; 16-bit handle for socket

;
; A port identifies a source or destination for a packet within a machine
;
SocketPort	struct
	SP_port		word		; 16-bit port number
	SP_manuf	ManufacturerID	; 16-bit manufacturer's ID
SocketPort 	ends

;
; Some domains only allow the use of 16 bit port numbers.  For these domains
; the SP_manuf field should be set to the value
; MANUFACTURER_ID_SOCKET_16BIT_PORT
; 

;
; A SocketAddress identifies a particular remote machine
;
; SA_domainSize need be initialized only if the library will write to the
; buffer pointed to by SA_domain (i.e. when a domain name is a return value)
; It is ignored otherwise.
;
SocketAddress	struct
	SA_port	SocketPort
	SA_domainSize	word		; size in bytes of SA_domain buffer
	SA_domain	fptr.TCHAR	; null terminated domain name
	SA_addressSize	word		; size in bytes of address data
	SA_address	label byte	; domain-specific data
SocketAddress	ends

;
; A SocketCondition indicates either the current or desired state of
; a socket, for use with SocketCheckReady
;
SocketCondition		etype	byte
SC_READ			enum	SocketCondition	; data arrived
SC_WRITE		enum	SocketCondition	; data can be written
SC_ACCEPT		enum	SocketCondition	; connect request arrived
SC_EXCEPTION		enum	SocketCondition	; an exception occurred
SC_URGENT		enum	SocketCondition	; urgent data arrived

;
; A SocketCheckRequest indicates a desired condition on some socket
;
SocketCheckRequest	struct
	SCR_socket	word
	SCR_condition	SocketCondition
	align word
SocketCheckRequest	ends

;
; Sockets can use either of two different conventions for delivering data:
;   datagram sockets give high performance, but may be delivered out of
;	order or not delivered at all, without the user's knowledge
;   stream sockets guarantee that all data will be delivered in order
;	and correctly, but doesn't preserve packet boundries
;
SocketDeliveryType	etype	byte
SDT_DATAGRAM		enum	SocketDeliveryType	; unreliable packets
SDT_SEQ_PACKET		enum	SocketDeliveryType	; reliable packets
SDT_STREAM		enum	SocketDeliveryType	; reliable bytes

;
; SocketLoadType controls how geodes are loaded when invoked via
; LoadOnMsg
;
SocketLoadType		etype	word
SLT_USER_LOAD_APPLICATION	enum	SocketLoadType
SLT_GEODE_LOAD			enum	SocketLoadType

;
; The SocketBindFlags influence the behavior of SocketBind
;
SocketBindFlags		record
	SBF_REUSE_PORT:1	; allow bind even if port is already bound
	:15
SocketBindFlags		end

;
; SocketSendFlags control options for sending
;
SocketSendFlags		record	
	SSF_ADDRESS:1		; an address is supplied in es:di
	SSF_URGENT:1		; this is urgent data
	SSF_OPEN_LINK:1		; this datagram should open the link, if closed
	:13
SocketSendFlags		end

;
; SocketRecvFlags control options for receiving
;
SocketRecvFlags		record
	SRF_ADDRESS:1		; return source address of data
	SRF_URGENT:1		; return urgent data, if any
	SRF_PEEK:1		; leave data in socket
	:13
SocketRecvFlags		end


SocketOption		etype	word,0,2
SO_RECV_BUF		enum	SocketOption
SO_SEND_BUF		enum	SocketOption
SO_INLINE		enum	SocketOption
SO_NODELAY		enum	SocketOption
SO_OWNER		enum	SocketOption
SO_LINGER		enum	SocketOption

;
; Functions which expect timeout values can be passed -1, which causes them
; to wait forever.
;
SOCKET_NO_TIMEOUT	equ	-1

;#############################################################################
;			     Error Codes
;#############################################################################

SocketError	etype	byte

SocketExtendedError	struct
	SEE_generic	SocketError
	SEE_specific	byte			; domain-specific code
SocketExtendedError	ends

SE_NORMAL			enum	SocketError
; operation completed successfully

SE_OUT_OF_MEMORY		enum	SocketError
; the net library was unable to allocate memory
; either there is no more system memory available, or a net-library
; specific upper bound on memory usage has been exceeded

SE_PORT_IN_USE			enum	SocketError
; Another socket is already bound to this port, and the SBF_REUSE_PORT
; flag was not set.

SE_PORT_ALREADY_LISTENING	enum 	SocketError
; Another socket is already listening on this port.

SE_SOCKET_IN_USE		enum	SocketError
; The socket is already being used in a way inconsistent with the
; requested operation

SE_SOCKET_ALREADY_BOUND		enum	SocketError
; The socket is already bound to a port.

SE_UNUSED_1			enum	SocketError
; This error value is no longer in use

SE_SOCKET_NOT_LISTENING		enum	SocketError
; The socket must be listening on a port for the requested operation.

SE_SOCKET_LISTENING		enum	SocketError
; A listening socket cannot be used for outgoing connections

SE_CONNECTION_REFUSED		enum 	SocketError
; Nobody is listening on the remote port.

SE_CONNECTION_FAILED		enum 	SocketError
; The connection is no longer valid, probably due to a link failure.

SE_CONNECTION_CLOSED		enum 	SocketError
; The connection has been closed from the other end.

SE_NON_UNIQUE_CONNECTION	enum 	SocketError
; Another connection with the same endpoint addresses and ports exists.

SE_TIMED_OUT			enum	SocketError
; The timeout period expired before the operation completed.  In some
; cases the protocol may enforce a shorter timeout then the user-specified
; value, so this is possible even where SOCKET_NO_TIMEOUT is used.

SE_CANT_LOAD_DRIVER		enum	SocketError
; A driver required to establish the connection could not be loaded.

SE_UNKNOWN_DOMAIN		enum	SocketError
; The requested domain is not known to the libarary.

SE_SYSTEM_SHUTDOWN		enum	SocketError
; The operation was aborted because GEOS is exiting

SE_SOCKET_NOT_CONNECTED		enum	SocketError
; The operation requires a connected socket

SE_SOCKET_ALREADY_CLOSED	enum	SocketError
; The send side of the socket is already closed

SE_SOCKET_BUSY			enum	SocketError
; Another thread is operating on the socket

SE_IMPROPER_CONDITION		enum	SocketError
; The requested condition for SocketCheckReady is not valid
; for a socket in the current state

SE_INFO_NOT_AVAILABLE		enum	SocketError
; The driver could not provide the requested information

SE_DOMAIN_REQUIRES_16BIT_PORTS	enum	SocketError
; The requested domain only allows 16 bit port numbers.  The SP_manuf field
; must be set to MANUFACTURER_ID_SOCKET_16BIT_PORT

SE_CONNECTION_ERROR		enum	SocketError
; The connection was not made for some reason which does not have
; it's own specific SocketError.  The actual SocketDrError is in
; SEE_specific.

SE_MEDIUM_BUSY			enum	SocketError
; The medium required for the connection is not available

SE_DESTINATION_UNREACHABLE	enum	SocketError
; The requested destination is not available

SE_LINK_FAILED			enum	SocketError
; The low level link used for this connection failed or could not be
; established

SE_INTERNAL_ERROR		enum	SocketError
; The socket library received an impossible error code from the driver.
; Either the library or the driver has a bug.  The specific error is
; the SocketDrError returned by the driver.

SE_CLOSE_SEND_NOT_SUPPORTED	enum	SocketError
; It is not possible to close only the send side of a socket in this
; domain.  Use SocketClose instead.

SE_BIND_CONFLICT		enum	SocketError
; The same port cannot have both domain restricted and domain unrestricted
; bindings.

SE_ALL_PORTS_BUSY		enum	SocketError
; SocketConnect attempted to implicitly bind a socket, but failed because
; all port numbers in the range used by implicit binds were in use

SE_SOCKET_NOT_INTERRUPTIBLE	enum	SocketError
; An operation which cannot be interrupted is in in progress on the
; socket

SE_INTERRUPT			enum	SocketError
; The operation was interrupted with SocketInterrupt

SE_PORT_NOT_LISTENING		enum	SocketError
; No listening socket or LoadOnMsg request exists for this port

SE_LISTEN_QUEUE_EMPTY		enum	SocketError
; No connections are pending for this port

SE_SOCKET_CLOSED		enum	SocketError
; The socket must be open for sending to call either SocketGetSocketName
; or SocketGetPeerName

SE_BUFFER_TOO_SMALL		enum	SocketError
; Returned by SocketResolve to mean that buffer for resolved address is
; too small

SE_TEMPORARY_ERROR		enum	SocketError
; Returned by SocketResolve to indicate that address resolution is temporarily
; unavailable for external reasons( such as network down or server failure )

SE_EXCEPTION			enum	SocketError
SE_URGENT			equ	SE_EXCEPTION
; Returned by SocketRecv if an exception occured on a datagram socket,
; or if urgent data arrived on a connected socket, since the last
; recv.  In the datagram case, the high byte is the exception code.
;

SE_NOT_IMPLEMENTED		enum	SocketError
; You are using a socket function which has not yet been implemented.

SE_CONNECTION_RESET		enum	SocketError
; The connection was reset, either locally or remotely

;#############################################################################
;			       User API
;#############################################################################

global	SocketCreate:far
;
; SYNOPSIS:  Create a socket
;
; PASS:		al = SocketDeliveryType
; RETURN:	carry set on error
;		ax = SocketExtendedError
;		bx = Socket
;
; Note: the socket will be owned by the geode whose thread calls SocketCreate
;  


global	SocketGetSocketOption:far
;
; SYNOPSIS:	get an option from a socket
;
; PASS:		ax	- SocketOption
;		bx	- socket
;
; RETURN:	carry set if information could not be obtained
;		others depending on option:
;			SO_RECV_BUF:
;			SO_SEND_BUF:
;				cx = size of buffer (-1 for no limit)
;			SO_INLINE: 
;			SO_NODELAY:
;				cx = TRUE/FALSE
;			SO_OWNER:
;				cx = geode handle
;

global	SocketSetSocketOption:far
;
; SYNOPSIS:	set an option on a socket
;
; PASS:		ax	- SocketOption
;		bx	- socket
;		others depending on option
;			SO_RECV_BUF:
;			SO_SEND_BUF:
;				cx = size of buffer (-1 for no limit)
;			SO_INLINE: 
;			SO_NODELAY:
;				cx = TRUE/FALSE
;			SO_OWNER:
;				cx = geode handle
;
; RETURN:	nothing
;

global	SocketConnect:far
;
; SYNOPSIS:	connect a sequenced or stream socket
;
; PASS:		bx	= Socket
;		cx:dx	= SocketAddress
;		bp	= timeout
;
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;

global	SocketBind:far
;
; SYNOPSIS: Bind a socket to a port
;
; PASS:		bx	= Socket
;		cxdx	= SocketPort
;			(cx = SP_manuf, dx = SP_port)
;		bp	= SocketBindFlags
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;
;
; NOTES:	see note under SocketBindInDomain
;

global	SocketBindInDomain:far
;
; SYNOPSIS:	Bind a socket to a port, restricted to a specific domain
;
; PASS:		bx	= Socket
;		cx:dx	= SocketAddress
;		bp	= SocketBindFlags
;
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;			  SE_UNKNOWN_DOMAIN
;
;
; NOTES:
;	SocketBind and SocketBindInDomain cannot coexist on the same
;	port number.  There can be domain restricted bindings in several
;	different domains, but if an unrestricted binding exists then
;	restricted bindings are disallowed, and vice versa.
;
;	AddLoadOnMsg and AddLoadOnMsgInDomain are equivelent to Bind and
;	BindInDomain for purposes of the rule mentioned above.
;

global SocketListen:far
;
; SYNOPSIS:	Initialize a socket for incoming connections
;
; PASS:		bx	= Socket
; 		cx 	= number of pending connections permitted
;
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;			SE_OUT_OF_MEMORY
;			SE_PORT_ALREADY_LISTENING
;	
;		
;


global	SocketCheckListen:far
;
; SYNOPSIS:	get domain of first connect request in listen queue
;
; PASS:		axbx	= SocketPort
;			(ax = SP_manuf, bx = SP_port)
;		ds:si	= buffer for domain name
;		cx	= length of buffer
;
; RETURN:	carry set on error:
;			ax	= SocketExtendedError
;		carry clear on success:
;			cx	= length of domain name
;			ds:si	= filled in (without null-terminator)
;			dxax	= MediumType for link over which connection
;				  is coming
;			
;
;

global	SocketAccept:far
;
; SYNOPSIS:	accept a connection on a sequenced or stream socket
;
; PASS:		bx	= Socket
;		bp	= timeout (in ticks)
; RETURN:	cx	= new socket for connection
;		ax	= SocketExtendedError
;

global	SocketGetPeerName:far
;
; SYNOPSIS:	get the address of the opposite end of a connection
;
; PASS:		bx	= Socket
;		cx:dx	= SocketAddress
;		   NMA_domain and NMA_address initialized
;		   NMA_domainSize and NMA_addressSize size of respective
;			buffers
; RETURN	cx:dx filled in
;			NMA_domainSize and NMA_addressSize set to size
;			   actually used
;		ax	SocketExtendedError
;

global	SocketGetSocketName:far
;
; SYNOPSIS:	get the address of the local side of a socket
;
; PASS:		bx	= Socket
;		cx:dx	= SocketAddress
;		   NMA_domain and NMA_address initialized
;		   NMA_domainSize and NMA_addressSize size of respective
;			buffers
; RETURN	cx:dx filled in
;			NMA_domainSize and NMA_addressSize set to size
;			   actually used
;		ax	SocketExtendedError
;

global	SocketSend:far
;
; SYNOPSIS:	send a packet on a connected socket
;
; PASS:		es:di	= SocketAddress (only if SSF_ADDRESS is set)
;		bx	= Socket
;		ds:si	= data to send
;		cx	= size of data
;		ax	= SocketSendFlags
;
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;

global	SocketRecv:far
;
; SYNOPSIS:	receive a packet from a socket with its return address
;
; PASS:		bx	= Socket
;		es:di	= buffer for received data
;		cx	= size of buffer
;		bp	= timeout (in ticks)
;		ax	= SocketRecvFlags
;		ON STACK (only if SRF_ADDRESS is set)
;			fptr to SocketAddress structure
;			SA_domain, SA_domainSize, SA_addressSize initialized
; RETURN:	cx	= if SRF_PEEK set
;			    number of bytes available for reading
;			  else
;		            number of bytes actually read
;		es:di	= filled in with data
;		ds:dx	= filled with address information
;			  sizes are before truncation to fit buffers
;		ax	= SocketExtendedError
;		SocketAddress filled in
;

global	SocketPeek:far
;
; SYNOPSIS:	nondestructively examine next packet
;
; PASS:		bx	= Socket
;		es:di	= buffer for received data
;		cx	= size of buffer
;		ds:dx	= SocketAddress
;			domain and address ptrs must be initialized
;			size fields set to size of respective buffers

;		bp	= timeout (in ticks)
;		ON STACK
;			fptr to SocketAddress structure (or 0 for none)
;			SA_domain, SA_domainSize, SA_addressSize initialized
; RETURN:
;		cx	= size of data before truncation to fit buffer
;		es:di	= filled in with data
;			= filled with address information
;			  sizes are before truncation to fit buffers
;		ax	= SocketExtendedError
;		SocketAddress filled in if present
;

global	SocketCloseSend:far
;
; SYNOPSIS:	close a socket for sending
;
; PASS:		bx	= Socket
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;

global	SocketClose:far
;
; SYNOPSIS:	close a socket
;
; PASS:		bx	= Socket
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;

global	SocketReset:far
;
; SYNOPSIS:	reset a socket
;               The socket will be closed immediately without regard for
;               the normal two-way negotiation with the peer.
; PASS:		bx	= Socket
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;

global	SocketCloseDomainMedium:far
;
; SYNOPSIS:	tell a domain to stop using a medium
;
; PASS:		dxbx	= MediumAndUnit
;		ax	= nonzero to force close
;		ds:si	= domain 
; RETURN:	carry set if link not closed
;               ax      = nonzero if carry set
;

global	SocketOpenDomainMedium:far
;
; SYNOPSIS:	Make a low-level connection over the medium, if
;		appropriate.
;
;		The precise action to be taken will depend on the domain.
;		With TCPIP, the PPP connection will be made but no TCP
;		connection established.
;
; PASS:		cx:dx	= SocketAddress
;		bp	= timeout
; RETURN:	carry set on error
;               ax      = SocketExtendedError
;

global	SocketCheckReady:far
;
; SYNOPSIS:	check readiness of one or more sockets
;
; PASS:		ax	= number of sockets
;		ds:si	= array of SocketCheckRequest
;		bp	= timeout (in ticks)
;
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;		cx	= socket meeting condition
;
;

global	SocketAddLoadOnMsg:far
;
; SYNOPSIS:	Load geode when packet arrives on a port
;
; PASS:		axbx	= SocketPort
;			(ax = SP_manuf, bx = SP_port)
;		cx	= SocketLoadType
;		bp	= disk handle
;		ds:si	= path
;
; RETURN:	none
;
; NOTES:	see note under SocketBindInDomain
;

global	SocketAddLoadOnMsgInDomain:far

; SYNOPSIS:	Load geode when packet arrives on a port and domain
;
; PASS:		axbx	= SocketPort
;			(ax = SP_manuf, bx = SP_port)
;		es:di	= domain name
;		cx	= SocketLoadType
;		bp	= disk handle
;		ds:si	= path
;
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;
; NOTES:	see note under SocketBindInDomain
;

global	SocketRemoveLoadOnMsg:far
;
; SYNOPSIS:	Cancel all autoload requests for a port
;
; PASS:		axbx	= SocketPort
;			(ax = SP_manuf, bx = SP_port)
; RETURN:	none
;

global	SocketRemoveLoadOnMsgInDomain:far
;
; SYNOPSIS:	Cancel autoload for a particular port and domain
;
; PASS:		axbx	= SocketPort
;			(ax = SP_manuf, bx = SP_port)
;		dx:di	= domain name
;
; RETURN:	none
;

global	SocketInterrupt:far
;
; SYNOPSIS:	interrupt current operations 
;
; PASS:		bx	= socket handle
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;			SE_SOCKET_NOT_INTERRUPTIBLE
;
; If the socket is not connected, the next connection will be aborted.
;
; If the socket is in the process of connecting via a data driver,
; that process will be aborted.  If the SocketConnect is implicitly
; opening the medium, the medium may or may not be open after
; interrupting the connect.
;
; Currently it is not possible to interrupt a connection on a link
; driver, and SE_SOCKET_NOT_INTERRUPTIBLE will be returned.
;
; If the socket is connected, any pending SocketRecv operations will
; be aborted.  If nobody is receiving, the next receive will be aborted.
; If anybody is sending, they MIGHT be interrupted.  If nobody is
; sending, the next send will be interrupted.

global  SocketGetDomains:far
;
; SYNOPSIS:     get a list of known domains
;
; PASS:         ^hbx    = lmem heap
;                 si    = chunk handle (0 to allocate one)
;
; RETURN:	carry set on error
;		ax = SocketExtendedError
;			SE_OUT_OF_MEMORY (if unable to expand user's heap)
;		^lbx:si = chunk array of domain names
;		

global  SocketGetDomainMedia:far
;
; SYNOPSIS:     get available media in a domain
;
; PASS:         ^hbx    = lmem heap
;                 si    = chunk handle (0 to allocate one)
;               ds:di   = domain name
;
; RETURN:       carry set on error
;               ax = SocketExtendedError
;                       SE_UNKNOWN_DOMAIN
;			SE_OUT_OF_MEMORY (if unable to expand user's heap)
;               ^lbx:si = chunk array of MediumType
;


global  SocketGetAddressMedium:far
;
; SYNOPSIS:     get medium for an address
;
; PASS:         ds:di   = SocketAddress
;
; RETURN:       carry set on error
;               ax = SocketExtendedError
;                       SE_UNKNOWN_DOMAIN
;                       SE_INVALID_ADDRESS
;               cxdx    = MediumType
;               bl      = MediumUnitType
;               bp      = MediumUnit
;

global	SocketCheckMediumConnection:far
;
; SYNOPSIS:     Check if there is an active connection through the 
;		specified unit of the medium.  If a point-to-point connection
;		exists (e.g., an IRLAP connection), then return the address
;		to which the connection exists.  If the connection is not
;		to a specific address (e.g., TCP/IP), then return a null 
; 		address (zero-sized.)
;
; PASS:		ds:si	= domain name (null-terminated string)
;		es:di	= buffer for address, large enough to accomodate
;			  the expected address.  
;		cx	= size of address buffer, in bytes.
;		dx:ax	= MediumAndUnit
;
; RETURN:       carry set on error (no connection exists over the unit 
;		of the medium):
;			ax	= SocketExtendedError
;				SE_CONNECTION_ERROR
;		carry clear if connection exists:
;			es:di	= filled in with the address.  If the address
;				  is larger than the size of the buffer,
;				  then only the beginning of the address, up
;				  to the buffer size, will be copied in.
;			cx	= number of bytes in address returned.  Caller
;				  should check if value returned in cx is 
;				  greater than the value passed in.  If so,
;				  it may be necessary to call this function
;				  again, with a larger address buffer.
;			

global	SocketGetMediumAddress:far
;
; SYNOPSIS:     If there is a connection through the specified medium,
;		return it's local address.  This is the address another
;		machine would use to connect to us over the medium.
;
; PASS:		ds:si	= domain name (null-terminated string)
;		es:di	= buffer for address, large enough to accomodate
;			  the expected address.  
;		cx	= size of address buffer, in bytes.
;		dx:ax	= MediumAndUnit
;
; RETURN:       carry set on error (no connection exists over the unit 
;		of the medium):
;			ax	= SocketExtendedError
;				SE_CONNECTION_ERROR
;		carry clear if connection exists:
;			es:di	= filled in with the address.  If the address
;				  is larger than the size of the buffer,
;				  then only the beginning of the address, up
;				  to the buffer size, will be copied in.
;			cx	= number of bytes in address returned.  Caller
;				  should check if value returned in cx is 
;				  greater than the value passed in.  If so,
;				  it may be necessary to call this function
;				  again, with a larger address buffer.
;			

global	SocketGetAddressController:far
;
; SYNOPSIS:	get address controller class for a domain
;
; PASS:		ds:si	= domain name
;
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;			SE_UNKNOWN_DOMAIN
;			SE_INVALID_MEDIUM
;		cx:dx	= pointer to class
;		

global	SocketGetAddressSize:far
;
; SYNOPSIS:	get the maximum (resolved) address size for a domain
;
; PASS:		ds:si	= domain name
; RETURN:	carry set on error
;		ax 	= SocketExtendedError
;			SE_UNKNOWN_DOMAIN
;			SE_CANT_LOAD_DRIVER
;			SE_INFO_NOT_AVAILABLE
;		cx	= address size

global	SocketResolve:far
;
; SYNOPSIS:	Convert an address into a form that can be used with SocketSend
;
; PASS:		dx:bp	= domain name
;		ds:si	= buffer for address to be resolved
;		cx	= size of the address
;		es:di	= buffer for resolved address
;		ax	= size of resolved address
;
; RETURN:	carry clr if address returned
;		  dx:bp = buffer filled w/non-null terminated addr if buffer
;			  is big enough
;		  cx	= size of resolved address
;
;		carry set if couldn't resolve it or buffer too small
;		  ax	= SocketExtendedError
;		  SE_BUFFER_TOO_SMALL: answer buffer is too small
;					cx = resolved address size
;		  SE_DESTINATION_UNREACHABLE: address doesn't exist in network
;		  SE_TEMPORARY_ERROR: address unreachable temporarily
;		  SE_CANT_LOAD_DRIVER: driver for the domain is not found
;					cx = SocketExtendedError
; DESTROYED:	contents of es:di if error occurs

global	SocketCreateResolvedAddress:far
;
; SYNOPSIS:	Convert an unresolved address into a SocketAddress block that
;		can be used with SocketConnect, et al.
;
; PASS:		dx:bp	= domain name
;		ds:si	= unresolved address buffer
;		cx	= size of unresolved address
;
; RETURN:	carry set on error
; 			ax	= SocketExtendedError
;				  SE_UNKNOWN_DOMAIN
;				  SE_CANT_LOAD_DRIVER
;				  SE_INFO_NOT_AVAILABLE
;				  SE_OUT_OF_MEMORY
;		carry clear if ok:
;			^hax	= SocketAddress, SA_domain set to dx:bp on
;				  entry; SA_domainSize, SA_port uninitialized
;
; DESTROYED:	nothing


global	SocketInterruptResolve:far
;
; SYNOPSIS:	interrupt a resolve
;
; PASS:		dx:bp	= domain name
;		ds:si   = address being resolved
;		cx	= size of address
;
; RETURN:	carry set on error
;		ax	= SocketExtendedError
;
; WARNING:	This function is unreliable.  It may not interrupt
;		the desired resolve call,if it executes before the
;		resolve call has begun to be processed.  If may also
;		cause other, parallel resolve in the same domain
;		to also be interrupted.
;

global	SocketSetMediumBusy:far
;
; SYNOPSIS:	Set whether the given medium looks busy even when
;		there are no active connections.  Medium should
;		be restored to normal as soon as medium may be
;		allowed to close.  
;		
; PASS:		dxbx	= MediumAndUnit
;		cx	= TRUE to mark medium always busy
;			  FALSE to return medium to normal 
;
; RETURN:	carry set if error
;
; DESTROYED:	nothing
;
; NOTES:
;		Should only be used by applications wishing to prevent
;		non-forcing SocketCloseDomainMedium from closing the
;		medium when there are no active connections.  An
;		example would be an application which makes a series
;		of connections with pauses between each connection
;		and doesn't want the medium closed during a pause.
;

global  SocketResolveLinkLevelAddress:far
; SYNOPSIS:	Converts a socket level address (i.e. ip address) into the
; 		address the hardware address the link driver delivers it to
;		(i.e. ethernet mac addresss). Most link drivers won't support
;		this. When supported, will most likely only work if the
;		requested SocketAddress exists on the same local network.
;
; PASS:		ds:si   = SocketAddress
;		cx:dx   = buffer
;		bx	= size of buffer (0 if just checking for existance)
; RETURN:	ax	= SocketError
;		bx	= Address size
; DESTROYED:	nothing

;#############################################################################
;			  Domain conversion
;
; These routines are primarily exported for use by preferences, but
; applications can use them as well
;
;#############################################################################

;
; SYNOPSIS:	Convert a (DBCS) domain name to an (SBCS) init file category
;
; PASS:		ds:si - domain name
; RETURN:	ds:si - init file category
;
ConvDomainNameToIniCat	macro
if DBCS_PCGEOS
	call	DomainNameToIniCat
endif
endm

;
; SYNOPSIS:	free storage associated with a category name
;
; PASS:		ds:si - init file category returned from DomainNameToIniCat
; RETURN:	ds:si - values passed to DomainNameToIniCat
;
ConvDomainNameDone macro
if DBCS_PCGEOS
	call	DomainNameDone
endif
endm

global	DomainNameToIniCat:far
global	DomainNameDone:far

;#############################################################################
;			  Error Checking
;#############################################################################

global	ECCheckSocket:far
;
; SYNOPSIS:	validate a socket
; PASS:		bx	- Socket
; RETURN:	nothing
; DESTROYED:	nothing
;

;#############################################################################
;			  C Stubs
;#############################################################################

global  SOCKETCREATE:far
global  SOCKETBIND:far
global  SOCKETBINDINDOMAIN:far
global  SOCKETLISTEN:far
global  SOCKETADDLOADONMSG:far
global  SOCKETADDLOADONMSGINDOMAIN:far
global  SOCKETREMOVELOADONMSG:far
global  SOCKETREMOVELOADONMSGINDOMAIN:far
global	SOCKETINTERRUPT:far
global  SOCKETCONNECT:far
global  SOCKETCHECKLISTEN:far
global  SOCKETACCEPT:far
global  SOCKETGETPEERNAME:far
global  SOCKETGETSOCKETNAME:far
global  SOCKETSEND:far
global  SOCKETRECV:far
global  SOCKETCLOSESEND:far
global  SOCKETCLOSE:far
global	SOCKETCLOSEDOMAINMEDIUM:far
global  SOCKETCHECKREADY:far
global	SOCKETGETDOMAINS:far
global	SOCKETGETDOMAINMEDIA:far
global	SOCKETGETADDRESSMEDIUM:far
global	SOCKETCHECKMEDIUMCONNECTION:far
global	SOCKETGETADDRESSCONTROLLER:far
global	SOCKETGETADDRESSSIZE:far
global	SOCKETRESOLVE:far
global	SOCKETCREATERESOLVEDADDRESS:far
global	SOCKETGETINTSOCKETOPTION:far
global	SOCKETSETINTSOCKETOPTION:far
global	SOCKETOPENDOMAINMEDIUM:far
global	SOCKETINTERRUPTRESOLVE:far
global	SOCKETGETMEDIUMADDRESS:far
global	SOCKETRESET:far
global	SOCKETSETMEDIUMBUSY:far
global  SOCKETRESOLVELINKLEVELADDRESS:far

EndLibrary	socket

