libcm is a C development framework with an emphasis on audio signal processing applications.
Вы не можете выбрать более 25 тем Темы должны начинаться с буквы или цифры, могут содержать дефисы(-) и должны содержать не более 35 символов.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216
  1. //| Copyright: (C) 2009-2020 Kevin Larke <contact AT larke DOT org>
  2. //| License: GNU GPL version 3.0 or above. See the accompanying LICENSE file.
  3. #ifndef cmRtNet_h
  4. #define cmRtNet_h
  5. #ifdef __cplusplus
  6. extern "C" {
  7. #endif
  8. //( { file_desc:"rtSys networking component." kw:[rtsys network] }
  9. /*
  10. Nodes and Endpoints:
  11. ---------------------
  12. A node corresponds to a process and owns a socket. It also has a label which is
  13. unique among all other nodes on the network. A node also has a set of application
  14. defined 'endpoints'. Each endpoint has a label and id that is unique among all
  15. other endpoints on the same node. Endpoints on different nodes however may share
  16. the same label and id. Endpoints are used by remote senders to identify
  17. a particular receiver which is sharing the node with other receivers. Endpoints
  18. are therefore analogous to port numbers on sockets.
  19. See gt/doc/notes.txt for more discussion of cmRtNet.
  20. */
  21. enum
  22. {
  23. kOkNetRC = cmOkRC,
  24. kUdpPortFailNetRC,
  25. kInvalidLabelNetRC,
  26. kDuplLabelNetRC,
  27. kDuplEndNetRC,
  28. kDuplLocalNetRC,
  29. kThreadFailNetRC,
  30. kBufToSmallNetRC,
  31. kNodeNotFoundNetRC,
  32. kEndNotFoundNetRC,
  33. kLocalNodeNetRC,
  34. kInvalidArgNetRC,
  35. kSyncFailNetRC,
  36. kNodeEndCntErrNetRC
  37. };
  38. typedef cmRC_t cmRtNetRC_t;
  39. typedef cmHandle_t cmRtNetH_t;
  40. typedef cmHandle_t cmRtNetEndptH_t;
  41. extern cmRtNetH_t cmRtNetNullHandle;
  42. extern cmRtNetEndptH_t cmRtNetEndptNullHandle;
  43. // selector id's for cmRtNetSyncMsg_t.selId.
  44. typedef enum
  45. {
  46. kHelloSelNetId, // 0 broadcast msg (label=node label, id=endpt cnt)
  47. kNodeSelNetId, // 1 define remote node (label=remote node label, id=endpt cnt)
  48. kEndpointSelNetId, // 2 define remote endpt (label=remote endpt label, id=endpt id)
  49. kDoneSelNetId, // 3 declare all endpts sent
  50. kInvalidSelNetId // 4
  51. } cmRtNetSelId_t;
  52. // Network synchronization message format.
  53. // cmRtNetRC_t.hdr.selId == kNetSyncSelRtid.
  54. typedef struct
  55. {
  56. cmRtSysMsgHdr_t hdr; // standard cmRtSys msg header
  57. cmRtNetSelId_t selId; // message selector id (See kXXXSelNetId above)
  58. unsigned hdrByteCnt; // size of the header record at transmission (used to locate the serialzed label)
  59. unsigned rtSubIdx; // cmInvalidIdx or rtSubIdx
  60. unsigned id; // endptCnt or endpoint id
  61. const cmChar_t* label; // node or endpoint label
  62. } cmRtNetSyncMsg_t;
  63. const cmChar_t* cmRtNetSyncMsgLabel( const cmRtNetSyncMsg_t* m );
  64. // NOTE: Messages passed between cmRtNet nodes during the synchronization
  65. // process use the cmRtNetSyncMsg_t format (w/ the body of label following
  66. // the record. All other messages use cmRtNetMsg_t (cmRtSysMsg.h) format.
  67. // 'cbFunc' will be called within the context of cmRtNetReceive() to receive
  68. // incoming network messages.
  69. // rtSubIdx is the rtSubIdx of the cmRtSys which owns this cmRtNet.
  70. cmRtNetRC_t cmRtNetAlloc( cmCtx_t* ctx, cmRtNetH_t* hp, unsigned rtSubIdx, cmUdpCallback_t cbFunc, void* cbArg );
  71. cmRtNetRC_t cmRtNetFree( cmRtNetH_t* hp );
  72. bool cmRtNetIsValid( cmRtNetH_t h );
  73. // Get the local host name for this machine. This function
  74. // is synonomous with gethostname().
  75. const cmChar_t* cmRtNetLocalHostName( cmRtNetH_t h );
  76. // Initialize the local network node.
  77. // 'bcastAddr' is the network broadcast address (e.g. 192.168.15.255).
  78. // 'nodeLabel' is the local network node label
  79. // 'ipAddr' may be set to NULL to use any available IP address.
  80. // 'ipPort' refers to the socket port (which may need to be made available
  81. // by the machine firewall cfg.)
  82. cmRtNetRC_t cmRtNetInitialize( cmRtNetH_t h, const cmChar_t* bcastAddr, const cmChar_t* nodeLabel, const cmChar_t* ipAddr, cmUdpPort_t ipPort );
  83. bool cmRtNetIsInitialized( cmRtNetH_t h );
  84. // Register the local endpoints.
  85. // Endpoints may only be registered once the network is initialized via
  86. // cmRtNetInitialize().
  87. // Remote nodes will be able to send messages to these endpoints by
  88. // referring to (nodeLabel/endPtLabel)
  89. cmRtNetRC_t cmRtNetRegisterEndPoint( cmRtNetH_t h, const cmChar_t* endPtLabel, unsigned endPtId );
  90. // Delete all nodes and endpoints.
  91. cmRtNetRC_t cmRtNetFinalize( cmRtNetH_t h );
  92. // Broadcast the 'hello' to all machines listening on the
  93. // broadcast addresss. This starts the synchronization sequence
  94. cmRtNetRC_t cmRtNetDoSync( cmRtNetH_t h );
  95. // This function must be polled to receive incoming network messages
  96. // via the callback funcion 'cbFunc' as passed to cmRtNetAlloc().
  97. // Note that all messages received via 'cbFunc' will be prefixed with
  98. // an cmRtSysMsgHdr_t header (See cmRtSysMsg.h).
  99. cmRtNetRC_t cmRtNetReceive( cmRtNetH_t h );
  100. // Get a remote end point handle for use with cmRtNetSend.
  101. cmRtNetRC_t cmRtNetEndpointHandle( cmRtNetH_t h, const cmChar_t* nodeLabel, const cmChar_t* endptLabel, cmRtNetEndptH_t* hp );
  102. bool cmRtNetEndpointIsValid( cmRtNetEndptH_t endPtH );
  103. // Given an endpoint handle return the id/label of the associated endpoint.
  104. unsigned cmRtNetEndpointId( cmRtNetEndptH_t endPtH );
  105. const cmChar_t* cmRtNetEndpointLabel( cmRtNetEndptH_t endPtH );
  106. // Send a message to a remote endpoint.
  107. // Note that srcEndPtId is used only to inform the receiver of the endpoint
  108. // of the transmitter. It is not used in any part of the transmit or receive
  109. // process.
  110. cmRtNetRC_t cmRtNetSend( cmRtNetH_t h, unsigned srcEndPtId, cmRtNetEndptH_t epH, const void* msg, unsigned msgByteCnt );
  111. // Send a message to a remote endpoint. This function is a composite
  112. // of cmRtNetEndpointHandle() and cmRtNetSend().
  113. cmRtNetRC_t cmRtNetSendByLabels( cmRtNetH_t h, unsigned srcEndPtId, const cmChar_t* nodeLabel, const cmChar_t* endptLabel, const void* msg, unsigned msgByteCnt );
  114. cmRtNetRC_t cmRtNetSendByIndex( cmRtNetH_t h, unsigned srcEndPtId, unsigned dstNodeIdx, unsigned dstEndptIdx, const void* msg, unsigned msgByteCnt );
  115. // Enable/disable synchronization protocol reporting.
  116. // Return the previous state of the report sync. flag.
  117. bool cmRtNetReportSyncEnable( cmRtNetH_t h, bool enableFl );
  118. bool cmRtNetReportSyncIsEnabled( cmRtNetH_t h );
  119. // Query network configuration. Returns true on success or false if
  120. // {nodeIdx, epIdx} does not identify a valid endpoint.
  121. const cmChar_t* cmRtNetLocalNodeLabel( cmRtNetH_t h );
  122. unsigned cmRtNetRemoteNodeCount( cmRtNetH_t h );
  123. unsigned cmRtNetAddrToNodeIndex( cmRtNetH_t h, const struct sockaddr_in* a );
  124. unsigned cmRtNetRemoteNodeIndex( cmRtNetH_t h, const cmChar_t* label );
  125. const cmChar_t* cmRtNetRemoteNodeLabel( cmRtNetH_t h, unsigned idx );
  126. unsigned cmRtNetRemoteNodeEndPointCount( cmRtNetH_t h, unsigned nodeIdx );
  127. cmRtNetRC_t cmRtNetRemoteNodeEndPoint(
  128. cmRtNetH_t h,
  129. unsigned nodeIdx,
  130. unsigned epIdx,
  131. const cmChar_t** labelRef,
  132. unsigned* idRef,
  133. unsigned* rsiRef );
  134. void cmRtNetReport( cmRtNetH_t h );
  135. void cmRtNetTest( cmCtx_t* ctx, bool mstrFl );
  136. /*
  137. Synchronization Protocol:
  138. Machine A Machine B
  139. ================================== ====================================
  140. broadcast 'hello' ------------------=-> create node-A w/ ei=0 -------+
  141. |
  142. +<-- create node-B w/ ei=0 <--------=-- send 'node' <----------------+
  143. |
  144. +--> switch(ei,m_t)
  145. | ei < en : send endpt[ei++] -=--> create endpt[] on node-A -->+
  146. | |
  147. | ei == en : ++ei,send 'done' -=------------------------------->+ |
  148. | |
  149. | m_t!='done': send 'done' -=------------------------------->+ |
  150. | |
  151. | (stop) : |
  152. | |
  153. | v
  154. | switch(ei,m_t)
  155. +<-- create endpt[] on node-B <---=----- send endpt[ei++] : ei < en
  156. |
  157. +<---------------------------------=----- send 'done',++ei : ei == en
  158. |
  159. +<---------------------------------=----- send 'done' : m_t!= 'done'
  160. : (stop)
  161. Notes:
  162. 1) 'ei' is the index of the next local end point to transmit.
  163. 2) 'en' is the count of local endpoints.
  164. 3) 'm_t' is the msg type (i.e.'hello','node','endpoint','done')
  165. of the incoming message.
  166. 4) The symbol -=- in the flow chart implies a network transmission.
  167. */
  168. //)
  169. #ifdef __cplusplus
  170. }
  171. #endif
  172. #endif