opennet.h

.net 方面的开发说明资料。

// ========================================================
// OpenNet 1.0
//
// Design by:
// - Floris van den Berg
// - Ben Ashley
//
// Implementation by:
// - Floris van den Berg
// ========================================================

#ifndef OPENNET_H
#define OPENNET_H

#define DLL_CALLCONV __stdcall
#define _STL std // don't use stlport

#ifdef OPENNET_EXPORTS
#define DLL_API __declspec(dllexport)
#else
#define DLL_API __declspec(dllimport)
#endif

// ========================================================
// Include some Windows COM stuff to be able to use GUIDS
// ========================================================

#ifndef _WINDOWS_
#include <windows.h>
#endif

#ifndef _OBJBASE_H_
#include <objbase.h>
#endif

// ========================================================
// GUIDs for protocols
// ========================================================

static const GUID CLSID_NULL_PROTOCOL = 
{ 0x00000000, 0x0000, 0x0000, { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 } };

static const GUID CLSID_SYSTEM_PROTOCOL = 
{ 0xe1223458, 0x8996, 0x4676, { 0xbe, 0xa6, 0xa1, 0x7f, 0xf4, 0xee, 0xa0, 0x4e } };

static const GUID CLSID_MODEM_PROTOCOL = 
{ 0x0e2022a7, 0x2ec1, 0x4627, { 0x8d, 0xac, 0x53, 0x58, 0xb3, 0x58, 0x1e, 0x2f } };

// ========================================================
// Typedefs/Defines for data
// ========================================================

typedef void* TRANSPORT_HANDLE;
typedef void* PROPERTYGROUP_HANDLE;

// ========================================================
// System protocol events and EpEvent structure
// ========================================================

enum SYSTEM_PROTOCOL {
	SYSTEM_DATA_IN = 0,                  // the transport received data
	SYSTEM_DATA_OUT,                     // the transport sent data
	SYSTEM_CONNECTING,                   // the transport started initiating a connection
	SYSTEM_CONNECTED,                    // the transport connected
	SYSTEM_CONNECT_TIMEOUT,              // timeout connection expired
	SYSTEM_DISCONNECTING,                // the transport started initiating a disconnection
	SYSTEM_DISCONNECTED,                 // the transport disconnected
	SYSTEM_LISTENING,                    // the transport is listening for connections
	SYSTEM_SENT_PROGRESS_BYTES,          // a number of bytes were sent
	SYSTEM_SENT_PROGRESS_PERCENTAGE,     // a percentage of the packet was sent
	SYSTEM_SENT_SUCCEEDED,               // complete packet was sent
	SYSTEM_SENT_FAILED,                  // packet failed to sent completely
	SYSTEM_TIMEOUT,                      // timeout event raised
	SYSTEM_IO_ERROR,                     // generic IO error occured. this event will cause all sends to be aborted, and timeouts to be initiated
	SYSTEM_NOT_SUPPORTED,                // this feature is not supported for this link
	SYSTEM_CONNECTION_REQUEST,           // a server transport request a new connection
	SYSTEM_RS232_BREAK,                  // rs232 break flag triggered
	SYSTEM_RS232_ERR_BREAK,              // The hardware detected a break condition
	SYSTEM_RS232_ERR_DNS,                // A parallel device is not selected
	SYSTEM_RS232_ERR_FRAME,              // The hardware detected a framing error
	SYSTEM_RS232_ERR_IOE,                // An I/O error occurred during communications with the device
	SYSTEM_RS232_ERR_MODE,               // The requested mode is not supported
	SYSTEM_RS232_ERR_OOP,                // A parallel device signaled that it is out of paper.
	SYSTEM_RS232_ERR_OVERRUN,            // A character-buffer overrun has occurred. The next character is lost
	SYSTEM_RS232_ERR_PTO,                // A time-out occurred on a parallel device
	SYSTEM_RS232_ERR_RXOVER,             // An input buffer overflow has occurred
	SYSTEM_RS232_ERR_RXPARITY,           // The hardware detected a parity error
	SYSTEM_RS232_ERR_TXFULL,             // The application tried to transmit a character, but the output buffer was full
	SYSTEM_RS232_CTS_ON,                 // carrier detect flag on
	SYSTEM_RS232_CTS_OFF,                // carrier detect flag off
	SYSTEM_RS232_DSR_ON,                 // data-set-ready flag on
	SYSTEM_RS232_DSR_OFF,                // data-set-ready flag off
	SYSTEM_RS232_RING_ON,                // ring indicator on
	SYSTEM_RS232_RING_OFF,               // ring indicator off
	SYSTEM_RS232_RLSD_ON,                // receive-line-signal-detect (e.g. carrier detect) on
	SYSTEM_RS232_RLSD_OFF,               // receive-line-signal-detect (e.g. carrier detect) off
	SYSTEM_TCPIP_NO_SUPPORT      ,       // addresses in the specified family cannot be used with this socket
	SYSTEM_TCPIP_CONNECTION_REFUSED,     // the attempt to connect was forcefully rejected
	SYSTEM_TCPIP_ADDRESS_UNAVAILABLE,    // the host address couldn't be resolved
	SYSTEM_TCPIP_NET_UNREACHABLE,        // the network cannot be reached from this host at this time
	SYSTEM_TCPIP_NO_BUFFERSPACE,         // no buffer space is available. the socket cannot be connected
	SYSTEM_TCPIP_NOT_CONNECTED,          // connection has been reset when SO_KEEPALIVE is set
	SYSTEM_TCPIP_CONNECTION_TIMEOUT,     // attempt to connect timed out without establishing a connection
	SYSTEM_TCPIP_SUBSYSTEM_FAILED,       //	the network subsystem has failed
	SYSTEM_TCPIP_CONNECTION_RESET,       // the connection was reset by the remote side
	SYSTEM_TCPIP_CONNECTION_ABORTED,     // the connection was terminated due to a time-out or other failure
	SYSTEM_TCPIP_NET_RESET,              // the connection has been broken due to keep-alive activity detecting a failure while the operation was in progress
	SYSTEM_TCPIP_OPERATION_ABORTED,      // the overlapped operation has been canceled due to the closure of the socket
	SYSTEM_TCPIP_UNIMPLEMENTED,          // a (not yet) implemented error occurred
	SYSTEM_TCPIP_ACCEPT_FAILED,          // winsock tried to accept a connection but couldn't
	SYSTEM_TCPIP_ACCEPT_TRY_AGAIN,       // the accept was refused by the transport. try again later
	SYSTEM_TCPIP_ACCEPT_WITHDRAWN,       // the connection request that was offered has timed out or been withdrawn.
};

enum MODEM_PROTOCOL {
	MODEM_OK = 0,                        // modem reported 'OK'
	MODEM_CONNECT,                       // modem reported 'CONNECT'
	MODEM_BUSY,                          // modem reported 'BUSY'
	MODEM_NOCARRIER,                     // modem reported 'NO CARRIER'
	MODEM_NODIALTONE,                    // modem reported 'NO DIAL TONE'
	MODEM_DELAYEDNUMBERWAIT,             // modem reported 'DELAYED NUMBER WAIT'
	MODEM_FORBIDDENNUMBER,               // modem reported 'FORBIDDEN NUMBER'
	MODEM_RING,                          // modem reported 'RING'
	MODEM_ERROR_IN_COMMAND,              // modem reported 'ERROR'
};

// ========================================================
// Transport Options
// ========================================================

#define SERIAL_CTS_STATUS            1  // [GET] DWORD containing CTS status
#define SERIAL_DSR_STATUS            2  // [GET] DWORD containing DSR status
#define SERIAL_RING_STATUS           3  // [GET] DWORD containing RING status
#define SERIAL_RLSD_STATUS           4  // [GET] DWORD containing RLSD status
#define SERIAL_GET_DCB               5  // [GET] device control block
#define SERIAL_SET_DCB               6  // [SET] device control block
#define SERIAL_CLEAR_DTR             7  // [SET] clears the DTR (data-terminal-ready) signal
#define SERIAL_CLEAR_RTS             8  // [SET] clears the RTS (request-to-send) signal
#define SERIAL_SET_DTR               9  // [SET] sends the DTR (data-terminal-ready) signal
#define SERIAL_SET_RTS               10 // [SET] sends the RTS (request-to-send) signal
#define SERIAL_SET_XOFF              11 // [SET] causes transmission to act as if an XOFF character has been received
#define SERIAL_SET_XON               12 // [SET] causes transmission to act as if an XON character has been received
#define SERIAL_SET_BREAK             13 // [SET] suspends character transmission and places the transmission line in a break state
#define SERIAL_CLEAR_BREAK           14 // [SET] Restores character transmission and places the transmission line in a nonbreak state
#define TCP_LOCALHOST                1  // [GET] string containing local hostname
#define TCP_PEERNAME                 2  // [GET] string containing the peername
#define UDP_TARGET                   1  // [GET] target address for sends
#define UDP_MULTICAST_LOOP           2  // [SET]
#define UDP_MULTICAST_TTL            3  // [SET] sets the multicast time-to-live value
#define UDP_MULTICAST_ADDMEMBERSHIP  4  // [SET] adds membership to a certain multicast address
#define UDP_MULTICAST_DROPMEMBERSHIP 5  // [SET] drops membership from a certain multicast address

// ========================================================
// Some system specific types
// ========================================================

struct TDCB { 
  DWORD DCBlength; 
  DWORD BaudRate; 
  DWORD Options;
  WORD wReserved; 
  WORD XonLim; 
  WORD XoffLim; 
  BYTE ByteSize; 
  BYTE Parity; 
  BYTE StopBits; 
  char XonChar; 
  char XoffChar; 
  char ErrorChar; 
  char EofChar; 
  char EvtChar; 
  WORD wReserved1; 
};

// ========================================================
// OpenNet Event
// ========================================================

#pragma pack(push, 1)
struct EpAction {
	GUID protocol;                      // protocol id for action
	int msg;                            // message id for action
	int size;                           // size of data
	unsigned char *data;                // action data
	int timeout;                        // timeout in ms
};

struct EpEvent {
	GUID protocol;                      // protocol id for event
	int msg;                            // message id for event
	int size;                           // size of data
	unsigned char *data;                // event data
	int reference_id;                   // reference identification for this event
};

struct EpTimeOut {
	GUID protocol;                      // protocol id that timed out
	int msg;                            // message id that timed out
};

struct UDPTarget {
	int port;
	char address[64];
};
#pragma pack(pop)

// ========================================================
// Protocol Handling
// ========================================================

typedef void* (DLL_CALLCONV *protocol_create)(TRANSPORT_HANDLE transport);
typedef void (DLL_CALLCONV *protocol_receive)(void *self, unsigned char *data, int size);
typedef void (DLL_CALLCONV *protocol_send)(void *self, EpAction *action);
typedef void (DLL_CALLCONV *protocol_reset)(void *self);
typedef void (DLL_CALLCONV *protocol_destroy)(void *self);
typedef int (DLL_CALLCONV *protocol_getname)(void *self, char *name, int size);
typedef int (DLL_CALLCONV *protocol_getmessagename)(void *self, int msg, char *name, int size);

#pragma pack(push, 1)
struct Protocol {
	protocol_create create;                 // protocol constructor
	protocol_receive receive;               // called when data is received
	protocol_send send;                     // called when data is sent
	protocol_reset reset;                   // reset the protocol
	protocol_destroy destroy;               // protocol destructor
	protocol_getname getname;               // retrieve the protocol name
	protocol_getmessagename getmessagename; // retrieve the name of a protocol msg
};
#pragma pack(pop)

// ========================================================
// System callback
// ========================================================

typedef void (DLL_CALLCONV *CallbackProc)(TRANSPORT_HANDLE transport, EpEvent *event, void *data);

// ========================================================
// OpenNet Functions
// ========================================================

extern "C" {
	// ##########################################################
	// INITIALIZE FUNCTIONS
	// ##########################################################
	// ----------------------------------------------------------
	// Purpose: Initialises the OpenNet communication system
	// Usage  : Call this function exactly ONE time at the start
	//          of the program
	// Notes  : None
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpInit();

	// ----------------------------------------------------------
	// Purpose: Drives OpenNet's event pushing mechanism
	// Usage  : Call this function repeatedly so that OpenNet
	//          can deliver its events.
	// Notes  : This function is needed because events have
	//          to be delivered in the thread space of the
	//          calling thread. EpHeartBeat will return true,
	//          if a message was processed, and false otherwise.
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpHeartBeat();

	// ----------------------------------------------------------
	// Purpose: deinitialises the OpenNet communication system
	// Usage  : call this function exactly ONE time at the end
	//          of the program
	// Notes  : Make sure there are no open transports anymore
	//          when you deinitialise the library.
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpFinalize();

	// ----------------------------------------------------------
	// Purpose: Retrieves the number of cpus in the system
	// Usage  : This function is used internally in the library
	//          for thread creation and data load balancing
	// Notes  : This function calls the Win32 API function
	//          GetSystemInfo
	// ----------------------------------------------------------

	DLL_API int DLL_CALLCONV EpGetCpuCount();

	// ----------------------------------------------------------
	// Purpose: Receives the version string of the library
	// Usage  : Use this function to show the OpenNet
	//          version string in an application
	// Notes  : None
	// ----------------------------------------------------------

	DLL_API const char *DLL_CALLCONV EpGetVersion();

	// ##########################################################
	// PROPERTY GROUPS
	// ##########################################################
	// ----------------------------------------------------------
	// Purpose: Creates a new, empty property group object.
	//          A property group stores the type of a transport
	//          and key/value pairs. Every transport contains
	//          exactly one property group.
	// Usage  : None
	// ----------------------------------------------------------

	DLL_API PROPERTYGROUP_HANDLE DLL_CALLCONV EpCreatePropertyGroup();

	// ----------------------------------------------------------
	// Purpose: Converts properties in a string to a property
	//          group and loads it into a group. A property
	//          string should have the format
	//
	//               "type property=value property=value"
	//
	// Usage  : None
	// ----------------------------------------------------------