opennet.pas

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

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

unit OpenNet;

interface

uses
  Windows, SysUtils, OpenObjects;

const
  DLL_NAME = 'OpenNet.dll';

  // ========================================================
  // Plug Options
  // ========================================================

  UDP_MULTICAST_LOOP = 0;
  UDP_MULTICAST_TTL = 1;
  UDP_MULTICAST_ADDMEMBERSHIP = 2;
  UDP_MULTICAST_DROPMEMBERSHIP = 3;

  // ========================================================
  // Defined CLSIDs
  // ========================================================

  CLSID_NULL_PROTOCOL : TGUID = '{00000000-0000-0000-C000-000000000000}';
  CLSID_SYSTEM_PROTOCOL : TGUID = '{e1223458-8996-4676-bea6-a17ff4eea04e}';
  CLSID_MODEM_PROTOCOL : TGUID =  '{0e2022a7-2ec1-4627-8dac-5358b3581e2f}';
  CLSID_TRANSPORT_SERIAL : TGUID = '{df9292c9-3aa6-4deb-9e40-f206f27d3373}';
  CLSID_TRANSPORT_TCPIP : TGUID = '{323df3ba-349a-48ad-a3c4-8ebcfffbf6b2}';
  CLSID_TRANSPORT_TCPIPSERVER : TGUID = '{7bd8ef99-03bb-4446-b3d0-73bfe2941565}';
  CLSID_TRANSPORT_UDP : TGUID = '{529542b3-42f5-4eea-a0cd-da05924ba75b}';
  CLSID_TRANSPORT_INDIRECT : TGUID = '{068903dd-ba1b-42d5-9878-df3ba43135f4}';

type
  TRANSPORT_HANDLE = Pointer;

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

  SYSTEM_PROTOCOL = (
    SYSTEM_DATA_IN = 0,                  // the transport received data
    SYSTEM_DATA_OUT,                     // the transport sent data
    SYSTEM_CONNECTION_INITIAL,           // first time connection event
    SYSTEM_CONNECTION_CHANGED,           // a connection status changed
    SYSTEM_CONNECT_TIMEOUT,              // event passed when a transport connection times out
    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
    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.
  );

  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'
  );

  // ========================================================
  // Plug Types and property structures
  // ========================================================

  PTransportProperties = ^TransportProperties;
  TransportProperties = packed record
    size : Integer;
  end;

  PTransportIndirect = ^TransportIndirect;
  TransportIndirect = packed record
    _type : TGUID;
    long : Integer;
  end;

  PTransportPropertiesSerial = ^TransportPropertiesSerial;
  TransportPropertiesSerial = packed record
    size : Integer;
    port : PChar;
    dcb  : DCB;
  end;

  PTransportPropertiesTCPIPServer = ^TransportPropertiesTCPIPServer;
  TransportPropertiesTCPIPServer = packed record
    size : Integer;
    port : Integer;
  end;

  PTransportPropertiesUDP = ^TransportPropertiesUDP;
  TransportPropertiesUDP = packed record
    size : Integer;
    port : Integer;
  end;

  // ========================================================
  // Connection Handling
  // ========================================================

  PPConnection = ^PConnection;
  PConnection = ^Connection;
  Connection = (
    ECS_CONNECTING = 0,
    ECS_CONNECTED,
    ECS_DISCONNECTING,
    ECS_DISCONNECTED,
    ECS_LISTENING
  );

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

  PEpAction = ^EpAction;
  EpAction = packed record
    protocol : TGuid;
    msg : Integer;
    size : Integer;
    data : PByte;
    timeout : Integer;
  end;

  PEpEvent = ^EpEvent;
  EpEvent = packed record
    protocol : TGuid;
    msg : Integer;
    size : Integer;
    data : PByte;
    reference_id : Integer;
  end;

  PEpTimeOut = ^EpTimeOut;
  EpTimeOut = packed record
    protocol : TGUID;
    msg : Integer;
  end;

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

  PPProtocol = ^PProtocol;
  PProtocol = ^IProtocol;
  IProtocol = interface(IUnknown)
    procedure Initialize(transport : TRANSPORT_HANDLE); stdcall;
    procedure Receive(data : PByteArray; size : Integer); stdcall;
    procedure Send(action : PEpAction); stdcall;
    procedure Reset(); stdcall;
    function GetName(name : PChar; size : Integer) : Integer; stdcall;
    function GetMessageName(msg : Integer; name : PChar; size : Integer) : Integer; stdcall;
  end;

  // ========================================================
  // Session Handling
  // ========================================================

  PPSession = ^PSession;
  PSession = ^ISession;
  ISession = interface(IUnknown)
    procedure Initialize(transport : TRANSPORT_HANDLE; connection : PConnection); stdcall;
    function GetProtocolCount() : Integer; stdcall;
    procedure GetProtocols(guid : PGUID); stdcall;
    function Receive(event : PEpEvent) : Boolean; stdcall;
  end;

  // ========================================================
  // Callback functions
  // ========================================================

  CallbackProc = procedure(transport : TRANSPORT_HANDLE; event : PEpEvent; data : Pointer); stdcall;

  // ========================================================
  // OpenNet Functions
  // ========================================================
  // ----------------------------------------------------------
  // Purpose: initialises the OpenNet communication system
  // Usage  : call this function exactly ONE time at the start
  //          of the program
  // Notes  : None
  // ----------------------------------------------------------

  procedure EpInit(); stdcall; external DLL_NAME name '_EpInit@0';

  // ----------------------------------------------------------
  // 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 it's possible
  //          to retrieve events (e.g. EpInit is called) and
  //          false otherwise (e.g. EpFinalize is called).
  // ----------------------------------------------------------

  function EpHeartBeat() : Boolean; stdcall; external DLL_NAME name '_EpHeartBeat@0';

  // ----------------------------------------------------------
  // 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.
  // ----------------------------------------------------------

  procedure EpFinalize(); stdcall; external DLL_NAME name '_EpFinalize@0';

  // ----------------------------------------------------------
  // 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
  // ----------------------------------------------------------

  function EpGetCpuCount() : Integer; stdcall; external DLL_NAME name '_EpGetCpuCount@0';

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