home *** CD-ROM | disk | FTP | other *** search
/ C/C++ User's Journal & Wi…eveloper's Journal Tools / C-C__Users_Journal_and_Windows_Developers_Journal_Tools_1997.iso / sysembed / tdi.elh < prev    next >
Encoding:
Text File  |  1995-03-30  |  8.1 KB  |  234 lines
  1. [ 3. Transport Driver Interface]
  2.               EMBEDDED LAN TRANSPORT DRIVER INTERFACE (TDI)
  3. ═════════════════════════════════════════════════════════════════════════
  4. The Embedded LAN Transport Driver Interface (PDI) is an interface your
  5. applications can use to send and receive "logical" messages to coordinate
  6. their activities.  Messages can be from 0-65535 bytes in length, and can
  7. be transported with full reliability or with best-effort delivery.
  8.  
  9. CONNECTIONS AND DATAGRAMS
  10.  
  11. Application programs that need access to TDI communication services can
  12. communicate using DATAGRAMS or CONNECTIONS.  With datagrams, a program
  13. sends a message to a transport address (a name or number, or both), and
  14. any number of other applications running on the network listening on the
  15. same transport address receive the message.
  16.  
  17. An application may establish a connection with another application, so
  18. that data can be transmitted over the connection.  Applications may use
  19. connection-oriented services with any number of other applications
  20. simultaneously.  With connection-oriented services, data are sent to
  21. a connection ID, not a transport address.  The transport address is
  22. specified at the time the connection is opened.  Connections support
  23. simultaneous two-way data transport.
  24.  
  25. QUALITY OF SERVICE CONTROLS:
  26.  
  27. TDI also supports the Embedded LAN quality-of-service options.  Most
  28. applications require absolute data integrity; lost messages due to
  29. network failures require retransmissions.  File service is an example
  30. of this type of activity.  Some applications, like video conferencing,
  31. require that retransmissions MUST NOT occur.  If the picture were to
  32. replay itself because of a missing 1/30th of a second frame, it would
  33. cause more distortion than if the frame were simply lost.  To support
  34. a wide range of embedded communications needs, the Transport Driver
  35. Interface supports service parameters that allow you to control the
  36. data delivery and acknowledgement algorithms.
  37.  
  38. TRANSPORT DRIVER INTERFACE API:
  39.  
  40. TDIAPI TdiOpenEndpoint (
  41.     IN UCHAR *PacketDriverName,
  42.     IN PTRANSPORT_ADDRESS LocalAddress,
  43.     IN TDIBITMASK QualityOfService,
  44.     IN PVOID Context,
  45.     OUT PTDIHANDLE Handle);
  46.  
  47. TDIAPI TdiCloseEndpoint (
  48.     IN TDIHANDLE Handle);
  49.  
  50. TDIAPI TdiConnect (
  51.     IN TDIHANDLE Handle,
  52.     IN PTRANSPORT_ADDRESS RemoteAddress,
  53.     IN PVOID Context,
  54.     OUT USHORT * ConnectionId);
  55.  
  56. TDIAPI TdiDisconnect (
  57.     IN TDIHANDLE Handle,
  58.     IN USHORT ConnectionId,
  59.     IN TDIBITMASK Flags);
  60.  
  61. #define TDI_DISCONNECT_ORDERLY_RELEASE  0x0001 // discon completes sends.
  62. #define TDI_DISCONNECT_ABORT            0x0002 // abort connection.
  63.  
  64. TDIAPI TdiSend (
  65.     IN TDIHANDLE Handle,
  66.     IN USHORT ConnectionId,
  67.     IN TDIBITMASK Flags,
  68.     IN PVOID Buffer,
  69.     IN USHORT BufferLength);
  70.  
  71. #define TDI_SEND_FLAGS_EOR              0x0001  // send end of record mark.
  72. #define TDI_SEND_FLAGS_NOFRAG           0x0002  // don't allow TDU fragmentation.
  73. #define TDI_SEND_FLAGS_EXPEDITED        0x0004  // this is expedited data.
  74.  
  75. TDIAPI TdiSendDatagram (
  76.     IN TDIHANDLE Handle,
  77.     IN PTRANSPORT_ADDRESS RemoteAddress,
  78.     IN TDIBITMASK Flags,
  79.     IN PVOID Buffer,
  80.     IN USHORT BufferLength);
  81.  
  82. TDIAPI TdiQueryInformation (
  83.     IN TDIHANDLE Handle,
  84.     IN USHORT InformationType,
  85.     IN PVOID Buffer,
  86.     IN USHORT BufferLength);
  87.  
  88. #define TDI_INFO_REMOTE_ADDRESS         0x100   // remote transport address.
  89. #define TDI_INFO_LOCAL_ADDRESS          0x101   // local transport address.
  90. #define TDI_INFO_ENDPOINT_STATISTICS    0x102   // statistics about endpoint.
  91. #define TDI_INFO_CONNECTION_STATISTICS  0x103   // statistics about connection.
  92. #define TDI_INFO_PROVIDER_STATISTICS    0x104   // statistics about provider.
  93.  
  94. typedef struct _TRANSPORT_STATISTICS {
  95.  
  96.     //
  97.     // Throughput/interface statistics.
  98.     //
  99.  
  100.     QUADINT UserSends;
  101.     QUADINT UserBytesSent;
  102.     QUADINT UserSendErrors;
  103.     QUADINT UserReceiveIndications;
  104.     QUADINT UserBytesReceived;
  105.  
  106.     //
  107.     // Error statistics.
  108.     //
  109.  
  110.     QUADINT ReceiveErrors;              // packets dropped in MAC/card.
  111.     QUADINT TransmitErrors;             // retransmitted data packets.
  112.     QUADINT OversizeTsdus;              // oversized messages received.
  113.     QUADINT UndersizeTsdus;             // undersized messages received.
  114.  
  115.     //
  116.     // Connection/Indication statistics.
  117.     //
  118.  
  119.     QUADINT ConnectIndications;         // count of connection indications.
  120.     QUADINT DisconnectIndications;      // count of disconnection indications.
  121.     QUADINT StatusIndications;          // count of status indications.
  122.     QUADINT ConnectionsInitiated;       // connections started at endpoint.
  123.     QUADINT ConnectionsAccepted;        // connections started from remote.
  124.  
  125.     //
  126.     // Other control information.
  127.     //
  128.  
  129.     ULONG PriorityLevel;                // priority of this endpoint/connection.
  130.     ULONG SecurityLevel;                // security level/this endpoint/connection.
  131.     ULONG SecurityCompartment;          // compartment for some protocols.
  132.  
  133.     //
  134.     // Statistics about transport provider generated packets.
  135.     //
  136.  
  137.     QUADINT SysSends;
  138.     QUADINT SysBytesSent;
  139.     QUADINT SysSendErrors;
  140.     QUADINT SysReceiveIndications;
  141.     QUADINT SysBytesReceived;
  142. } TRANSPORT_STATISTICS, *PTRANSPORT_STATISTICS;
  143.  
  144. typedef union _TDI_INFORMATION_BUFFER {
  145.     TRANSPORT_ADDRESS LocalAddress;
  146.     TRANSPORT_ADDRESS RemoteAddress;
  147.     TRANSPORT_STATISTICS EndpointStatistics;
  148.     TRANSPORT_STATISTICS ConnectionStatistics;
  149. } TDI_INFORMATION_BUFFER, *PTDI_INFORMATION_BUFFER;
  150.  
  151. TDIAPI TdiSetInformation (
  152.     IN TDIHANDLE Handle,
  153.     IN USHORT InformationType,
  154.     IN PVOID Buffer,
  155.     IN USHORT BufferLength);
  156.  
  157. TDIAPI TdiSetIndicationHandler (
  158.     IN TDIHANDLE Handle,
  159.     IN USHORT TdiIndType,
  160.     IN PTDI_INDICATION IndicationHandler);
  161.  
  162. #define TDI_IND_RECEIVE                 0       // connection-oriented receive.
  163. #define TDI_IND_RECEIVE_DATAGRAM        1       // connectionless receive.
  164. #define TDI_IND_STATUS                  2       // status indication.
  165. #define TDI_IND_CONNECT                 3       // connection request.
  166. #define TDI_IND_DISCONNECT              4       // disconnection request.
  167.  
  168. //
  169. // Transport Driver Interface (TDI) indication routine (user supplied) types.
  170. //
  171.  
  172. //
  173. // Connection-oriented receive indication handler.
  174. //
  175.  
  176. typedef VOID (*PIND_TDIRECEIVE)(
  177.     IN PVOID ConnectionContext,
  178.     IN TDIBITMASK ReceiveFlags,
  179.     IN PVOID Buffer,
  180.     IN USHORT BufferLength);
  181.  
  182. #define TDI_RECEIVE_OVERSIZE    0x0001  // TDU was oversized for media.
  183. #define TDI_RECEIVE_UNDERSIZE   0x0002  // TDU was too short for media.
  184. #define TDI_RECEIVE_DATA_ERROR  0x0004  // TDU had CRC or data error.
  185. #define TDI_RECEIVE_EOR         0x0008  // TDU has end of record set.
  186. #define TDI_RECEIVE_EXPEDITED   0x0010  // TDU contains expedited data.
  187.  
  188. //
  189. // Connectionless receive to endpoint indication handler.
  190. //
  191.  
  192. typedef VOID (*PIND_TDIRECEIVE_DATAGRAM)(
  193.     IN PVOID EndpointContext,
  194.     IN PTRANSPORT_ADDRESS RemoteAddress,
  195.     IN TDIBITMASK ReceiveFlags,
  196.     IN PVOID Buffer,
  197.     IN USHORT BufferLength);
  198.  
  199. #define TDI_RECEIVE_DATAGRAM_OVERSIZE   0x0001 // TDU was oversized for media.
  200. #define TDI_RECEIVE_DATAGRAM_UNDERSIZE  0x0002 // TDU was too short for media.
  201. #define TDI_RECEIVE_DATAGRAM_DATA_ERROR 0x0004 // TDU had CRC or data error.
  202. #define TDI_RECEIVE_DATAGRAM_EOR        0x0008 // TDU has end of record mark.
  203.  
  204. //
  205. // Change in endpoint status indication handler.
  206. //
  207.  
  208. typedef VOID (*PIND_TDISTATUS)(
  209.     IN PVOID EndpointContext,
  210.     IN TDIBITMASK StatusFlags,
  211.     IN PVOID Buffer,
  212.     IN USHORT BufferLength);
  213.  
  214. #define TDI_STATUS_IDLE         0x0000  // endpoint is idle.
  215. #define TDI_STATUS_CONNECTION   0x0001  // a connection is active.
  216.  
  217. //
  218. // Connection request indication handler.
  219. //
  220.  
  221. typedef TDISTATUS (*PIND_TDICONNECT)(
  222.     IN PVOID EndpointContext,
  223.     IN PTRANSPORT_ADDRESS RemoteAddress,
  224.     IN USHORT ConnectionId,
  225.     OUT PVOID * ConnectionContext);
  226.  
  227. //
  228. // Disconnection notification indication handler.
  229. //
  230.  
  231. typedef TDISTATUS (*PIND_TDIDISCONNECT)(
  232.     IN PVOID ConnectionContext,
  233.     IN TDIBITMASK DisconnectFlags);
  234.