/******************************************************************************/
/*									      */
/*	######    ###   #     #   ###    #####    ###   ####### #     #	      */
/*	#     #    #    #     #    #    #     #    #    #     # ##    #	      */
/*	#     #    #    #     #    #    #          #    #     # # #   #	      */
/*	#     #    #    #     #    #     #####     #    #     # #  #  #	      */
/*	#     #    #     #   #     #          #    #    #     # #   # #	      */
/*	#     #    #      # #      #    #     #    #    #     # #    ##	      */
/*	######    ###      #      ###    #####    ###   ####### #     #	      */
/*									      */
/*			   #     #####   #####  #######			      */
/*			  ##    #     # #     # #			      */
/*			 # #    #     # #     # #			      */
/*			   #     ######  ###### ######			      */
/*			   #          #       #       #			      */
/*			   #    #     # #     # #     #			      */
/*			 #####   #####   #####   #####			      */
/*									      */
/* 		Copyright (c) Division Limited. All rights reserved	      */
/*									      */
/* This Document may not, in whole or in part, be copied, photocopied,	      */
/* reproduced, translated, or reduced to any electronic medium or machine     */
/* readable form without prior written consent from Division Ltd.	      */
/*									      */
/******************************************************************************/

#if !defined _DLINK_H_
#define _DLINK_H_


#if defined __cplusplus
extern "C" {
#endif 

/* This is the interface between dlink and the user. */
/* It keeps track of which device we are talking to (via the */
/* device driver file descriptor. It also keeps track of the protocol mode */

#if defined _UNIX

typedef struct dbi_interface *DBI_INTERFACE_PTR;
typedef struct dbi_interface
{
  int fd;
  int protocol;

} DBI_INTERFACE;

#else /* NOT _UNIX */

typedef void *DBI_INTERFACE_PTR; 	/* Redirect into the linkio structures */

#endif /* _UNIX */












/* Open a dLink Device */
/* On a success, returns a pointer that acts as a handle for all further operations. */
/* When operations on this handle are finished, dlink_closeDevice should be called to */
/* off any resources associated with the handle. In the unix world, dlink_initDevice */
/* should be passed a filename that corresponds to the device being used. eg. /dev/dbi01 */
/* Will return NULL, and print a message on error */

extern DBI_INTERFACE_PTR dlink_initDevice (char *deviceName);






/* Close a dLink Device */
/* Attempts to free off any resources associated with a dLink device handle */
/* which is passed into the routine. Returns 0 on success. On error, will print */
/* a message and return (-1). */
/* After a successful dlink_closeDevice, the dLink device pointer is no longer valid. */

extern int dlink_closeDevice (DBI_INTERFACE_PTR interface);






/* Reset the device associated with the dLink device handle. */
/* This has the effect of resetting the hardware that is associated with the dLink */
/* device handle passed into the routine. */
/* Will return 0 on success, or print a message and return (-1) on error */

extern int dlink_resetDevice (DBI_INTERFACE_PTR interface);







/* Write RAW data */
/* Similar to the UNIX write system call. */
/* Attempts to write nob bytes of data starting from the address in data to */
/* the device associated with the dLink device handle passed in. */
/* Returns the number of bytes written. */
/* If an error occurs, will print a message and return (-1). */

extern int dlink_write (DBI_INTERFACE_PTR interface, char *data, unsigned int nob);









/* Read RAW data */
/* Similar to the UNIX read system call. */
/* Attempts to read nob bytes of data starting to the address in data from */
/* the device associated with the dLink device handle passed in. */
/* Returns the number of bytes read. */
/* If an error occurs, will print a message and return (-1). */

extern int dlink_read (DBI_INTERFACE_PTR interface, char *data, unsigned int nob);









/* See if the link is ready */
/* If there is input from the device waiting will return non-zero, */
/* otherwise will return zero. */
extern int dlink_inputReady (DBI_INTERFACE_PTR interface);


















/* Send out a protocol packet */
/* Attempts to send a protocol packet to the device associated with the dLink */
/* device handle passed to the routine. */
/* Parameters are as follows;

	interface 		dLink device handle.
	data			Address of data.
	nob			Number of bytes to send. Must be a multiple of 4, 
				and no more than 1020 bytes, as defined by the
				protocol used.
	protocolTag		A protocol tag that will be interpreted by the
				user code at the destination process.
	target			The ID of the destination process. Can be 0x0 to 0xFF,
				where 0xFF is a broadcast message.
	toIserver		0 for a non-Iserver message, 1 for a packet destined for
				an Iserver.
	needsFlipping.		Specifies whether the data is affected by machine Endian
				properties. If set to 1, dLink will automatically flip
				the data on despatch. dLink will only do this if the
				host machine is reverse endian to the destination.
				If either needsFlipping is 0, or the host machined is the
				same endian to the destination, no byte flipping is
				performed.

  Returns 0 on success, or -1 and a message on error. */

extern int dlink_sendProtocolPacket (DBI_INTERFACE_PTR interface,
					char *data, unsigned int nob,
					int protocolTag,
					int target, int toIserver,
					int needsFlipping);








/* Receive a protocol packet */
/* Attempts to read a protocol packet from the device associated with the dLink */
/* device handle passed to the routine. */
/* Parameters are as follows;

	interface 		dLink device handle.
	data			Address of where the data is to be read.
	nob			Pointer to the number of bytes actually received.

	protocolTag		Currently not used. Pass in NULL.
	target			Pointer to the ID of the sender of the data.
	toIserver		Pointer saying whether the message was from an Iserver.
				1 will be placed here if the message is from an Iserver,
				0 otherwise.
	needsFlipping.		Specifies whether the data is affected by machine Endian
				properties. If set to 1, dLink will automatically flip
				the data on arrival. dLink will only do this if the
				host machine is reverse endian to the destination.
				If either needsFlipping is 0, or the host machined is the
				same endian to the destination, no byte flipping is
				performed.
*/
/* Returns 0 on success, or -1 and a message on error. */

extern int dlink_recvProtocolPacket (DBI_INTERFACE_PTR interface,
     					char *data, unsigned int *nob,
					int *protocolTag,
					int *target, int *fromIserver,
					int needsFlipping);










/* Switch dLink Error messages to come from the given */
/* file descriptor. If the descriptor is NULL, then */
/* error messages will be switched off */
/* Parameters are as follows;

	fd		Pointer to a file descriptor. If the pointer is NULL
			then dlink error messages will be switched off, otherwise
			dlink error messages will be sent over the given file
			descriptor after the call.
*/

extern void dlink_setErrorFile (FILE *fd);


#if defined __cplusplus
}
#endif

#endif
