/*******************************************************************
 Copyright © 1995 - 1998, 3Com Corporation or its subsidiaries ("3Com").  
 All rights reserved.
   
 This software may be copied and used solely for developing products for 
 the Palm Computing platform and for archival and backup purposes.  Except 
 for the foregoing, no part of this software may be reproduced or transmitted 
 in any form or by any means or used to make any derivative work (such as 
 translation, transformation or adaptation) without express written consent 
 from 3Com.

 3Com reserves the right to revise this software and to make changes in content 
 from time to time without obligation on the part of 3Com to provide notification 
 of such revision or changes.  
 3COM MAKES NO REPRESENTATIONS OR WARRANTIES THAT THE SOFTWARE IS FREE OF ERRORS 
 OR THAT THE SOFTWARE IS SUITABLE FOR YOUR USE.  THE SOFTWARE IS PROVIDED ON AN 
 "AS IS" BASIS.  3COM MAKES NO WARRANTIES, TERMS OR CONDITIONS, EXPRESS OR IMPLIED, 
 EITHER IN FACT OR BY OPERATION OF LAW, STATUTORY OR OTHERWISE, INCLUDING WARRANTIES, 
 TERMS, OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND 
 SATISFACTORY QUALITY.

 TO THE FULL EXTENT ALLOWED BY LAW, 3COM ALSO EXCLUDES FOR ITSELF AND ITS SUPPLIERS 
 ANY LIABILITY, WHETHER BASED IN CONTRACT OR TORT (INCLUDING NEGLIGENCE), FOR 
 DIRECT, INCIDENTAL, CONSEQUENTIAL, INDIRECT, SPECIAL, OR PUNITIVE DAMAGES OF 
 ANY KIND, OR FOR LOSS OF REVENUE OR PROFITS, LOSS OF BUSINESS, LOSS OF INFORMATION 
 OR DATA, OR OTHER FINANCIAL LOSS ARISING OUT OF OR IN CONNECTION WITH THIS SOFTWARE, 
 EVEN IF 3COM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

 3Com, HotSync, Palm Computing, and Graffiti are registered trademarks, and 
 Palm III and Palm OS are trademarks of 3Com Corporation or its subsidiaries.

 IF THIS SOFTWARE IS PROVIDED ON A COMPACT DISK, THE OTHER SOFTWARE AND 
 DOCUMENTATION ON THE COMPACT DISK ARE SUBJECT TO THE LICENSE AGREEMENT 
 ACCOMPANYING THE COMPACT DISK.

 *-------------------------------------------------------------------
 * FileName:
 *		ExgLib.h
 *
 * Description:
 *		Include file the Exchange Library interface. The Exchange Library is a
 *		generic interface to any number of librarys. Any Exchange Library
 *		MUST have entrypoint traps in exactly the order listed here.
 *		The System Exchange manager functions call these functions when 
 *		applications make calls to the Exchange manager. Applications will
 *		usually not make direct calls to this API.
 *
 * History:
 *   	5/23/97 Created by Gavin Peacock
 *
 *******************************************************************/

#ifndef __EXG_LIB_H
#define __EXG_LIB_H

#include <Common.h>
#include <SysTraps.h>
#include <ExgMgr.h>

// special exchange mgr event key
#define exgIntDataChr 0x01ff

//-----------------------------------------------------------------------------
// 	Obx library call ID's. Each library call gets the trap number:
//   exgTrapXXXX which serves as an index into the library's dispatch table.
//   The constant sysLibTrapCustom is the first available trap number after
//   the system predefined library traps Open,Close,Sleep & Wake.
//
// WARNING!!! This order of these traps MUST match the order of the dispatch
//  table in and Exchange library!!!
//-----------------------------------------------------------------------------
#pragma mark Traps
typedef enum {
	exgLibTrapHandleEvent = sysLibTrapCustom,
	exgLibTrapConnect,
	exgLibTrapAccept,
	exgLibTrapDisconnect,
	exgLibTrapPut,
	exgLibTrapGet,
	exgLibTrapSend,
	exgLibTrapReceive,
	exgLibTrapControl,
	exgLibReserved1,
	exgLibTrapLast
	} ExgLibTrapNumberEnum;


/************************************************************
 * Net Library procedures.
 *************************************************************/ 
#pragma mark Functions
#ifdef __cplusplus
extern "C" {
#endif

//--------------------------------------------------
// Library initialization, shutdown, sleep and wake
//--------------------------------------------------
// Open the library - enable server for receiving data.
Err		ExgLibOpen (Word libRefnum)
			SYS_TRAP(sysLibTrapOpen);
					
Err		ExgLibClose (Word libRefnum)
			SYS_TRAP(sysLibTrapClose);
					
Err		ExgLibSleep (Word libRefnum)
			SYS_TRAP(sysLibTrapSleep);
					
Err		ExgLibWake (Word libRefnum)
			SYS_TRAP(sysLibTrapWake);
					
//	Handle events that this library needs. This will be called by
//	sysHandle event when certain low level events are triggered.					
Err		ExgLibHandleEvent(Word libRefnum,VoidPtr eventP)
			SYS_TRAP(exgLibTrapHandleEvent);
						
//  Establish a new connection 						
Err	 	ExgLibConnect(UInt libRefNum,ExgSocketPtr exgSocketP)
			SYS_TRAP(exgLibTrapConnect);

// Accept a connection request from remote end
Err		ExgLibAccept(Word libRefnum,ExgSocketPtr exgSocketP)
			SYS_TRAP(exgLibTrapAccept);

// Disconnect
Err		ExgLibDisconnect(Word libRefnum,ExgSocketPtr exgSocketP,Err error)
			SYS_TRAP(exgLibTrapDisconnect);

// Initiate a Put command. This passes the name and other information about
// an object to be sent
Err		ExgLibPut(Word libRefnum,ExgSocketPtr exgSocketP)
			SYS_TRAP(exgLibTrapPut);

// Initiate a Get command. This requests an object from the remote end.
Err		ExgLibGet(UInt libRefNum,ExgSocketPtr exgSocketP)
			SYS_TRAP(exgLibTrapGet);

// Send data to remote end - called after a Put command
ULong 	ExgLibSend(UInt libRefNum, ExgSocketPtr exgSocketP, const void * const bufP, const ULong bufLen, Err *errP)
			SYS_TRAP(exgLibTrapSend);

// Receive data from remote end -- called after Accept
ULong 	ExgLibReceive(UInt libRefNum, ExgSocketPtr exgSocketP, VoidPtr bufP, const ULong bufSize, Err *errP)
			SYS_TRAP(exgLibTrapReceive);

// Send various option commands to the Exg library
Err 	ExgLibControl(UInt libRefNum, Word op, VoidPtr valueP, WordPtr valueLenP)
			SYS_TRAP(exgLibTrapControl);

						
#ifdef __cplusplus
}
#endif

#endif  // EXG_LIB_H