libcm is a C development framework with an emphasis on audio signal processing applications.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

cmRtNet.h 6.5KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162
  1. #ifndef cmNet_h
  2. #define cmNet_h
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. enum
  7. {
  8. kOkNetRC = cmOkRC,
  9. kUdpPortFailNetRC,
  10. kInvalidLabelNetRC,
  11. kDuplLabelNetRC,
  12. kDuplEndNetRC,
  13. kDuplLocalNetRC,
  14. kThreadFailNetRC,
  15. kBufToSmallNetRC,
  16. kNodeNotFoundNetRC,
  17. kEndNotFoundNetRC,
  18. kLocalNodeNetRC,
  19. kInvalidArgNetRC,
  20. kSyncFailNetRC,
  21. kNodeEndCntErrNetRC
  22. };
  23. typedef cmRC_t cmRtNetRC_t;
  24. typedef cmHandle_t cmRtNetH_t;
  25. typedef cmHandle_t cmRtNetEndptH_t;
  26. extern cmRtNetH_t cmRtNetNullHandle;
  27. extern cmRtNetEndptH_t cmRtNetEndptNullHandle;
  28. // selector id's for cmRtNetSyncMsg_t.selId.
  29. typedef enum
  30. {
  31. kHelloSelNetId, // broadcast msg (label=node label, id=endpt cnt)
  32. kNodeSelNetId, // define remote node (label=remote node label, id=endpt cnt)
  33. kEndpointSelNetId, // define remote endpt (label=remote endpt label, id=endpt id)
  34. kDoneSelNetId, // declare all endpts sent
  35. kInvalidSelNetId
  36. } cmRtNetSelId_t;
  37. // Network synchronization message format.
  38. // cmRtNetRC_t.hdr.selId == kNetSyncSelRtid.
  39. typedef struct
  40. {
  41. cmRtSysMsgHdr_t hdr; // standard cmRtSys msg header
  42. cmRtNetSelId_t selId; // message selector id (See kXXXSelNetId above)
  43. const cmChar_t* label; // node or endpoint label
  44. unsigned id; // endptCnt or endpoint id
  45. unsigned rtSubIdx; // cmInvalidIdx or rtSubIdx
  46. } cmRtNetSyncMsg_t;
  47. // NOTE: Messages passed between cmRtNet nodes during the synchronization
  48. // process use the cmRtNetSyncMsg_t format (w/ the body of label following
  49. // the record. All other messages use cmRtNetMsg_t (cmRtSysMsg.h) format.
  50. // 'cbFunc' will be called within the context of cmRtNetReceive() to receive
  51. // incoming network messages.
  52. cmRtNetRC_t cmRtNetAlloc( cmCtx_t* ctx, cmRtNetH_t* hp, cmUdpCallback_t cbFunc, void* cbArg );
  53. cmRtNetRC_t cmRtNetFree( cmRtNetH_t* hp );
  54. bool cmRtNetIsValid( cmRtNetH_t h );
  55. // Get the local host name for this machine. This function
  56. // is synonomous with gethostname().
  57. const cmChar_t* cmRtNetLocalHostName( cmRtNetH_t h );
  58. // Initialize the local network node.
  59. // 'bcastAddr' is the network broadcast address (e.g. 192.168.15.255).
  60. // 'nodeLabel' is the local network node label
  61. // 'ipAddr' may be set to NULL to use any available IP address.
  62. // 'ipPort' refers to the socket port (which may need to be made available
  63. // by the machine firewall cfg.)
  64. cmRtNetRC_t cmRtNetInitialize( cmRtNetH_t h, const cmChar_t* bcastAddr, const cmChar_t* nodeLabel, const cmChar_t* ipAddr, cmUdpPort_t ipPort );
  65. bool cmRtNetIsInitialized( cmRtNetH_t h );
  66. // Register the local endpoints.
  67. // Endpoints may only be registered once the network is initialized via
  68. // cmRtNetInitialize().
  69. // Remote nodes will be able to send messages to these endpoints by
  70. // referring to (nodeLabel/endPtLabel)
  71. cmRtNetRC_t cmRtNetRegisterEndPoint( cmRtNetH_t h, unsigned rtSubIdx, const cmChar_t* endPtLabel, unsigned endPtId );
  72. // Delete all nodes and endpoints.
  73. cmRtNetRC_t cmRtNetFinalize( cmRtNetH_t h );
  74. // Broadcast the 'hello' to all machines listening on the
  75. // broadcast addresss. This starts the synchronization sequence
  76. cmRtNetRC_t cmRtNetDoSync( cmRtNetH_t h );
  77. // This function must be polled to receive incoming network messages
  78. // via the callback funcion 'cbFunc' as passed to cmRtNetAlloc().
  79. // Note that all messages received via 'cbFunc' will be prefixed with
  80. // an cmRtSysMsgHdr_t header (See cmRtSysMsg.h).
  81. cmRtNetRC_t cmRtNetReceive( cmRtNetH_t h );
  82. // Get an end point handle for use with cmRtNetSend.
  83. cmRtNetRC_t cmRtNetEndpointHandle( cmRtNetH_t h, const cmChar_t* nodeLabel, unsigned rtSubIdx, const cmChar_t* endptLabel, cmRtNetEndptH_t* hp );
  84. // Send a message to a remote endpoint.
  85. cmRtNetRC_t cmRtNetSend( cmRtNetH_t h, cmRtNetEndptH_t epH, const void* msg, unsigned msgByteCnt );
  86. // Send a message to a remote endpoint. This function is a composite
  87. // of cmRtNetEndpointHandle() and cmRtNetSend().
  88. cmRtNetRC_t cmRtNetSendByLabels( cmRtNetH_t h, const cmChar_t* nodeLabel, unsigned rtSubIdx, const cmChar_t* endptLabel, const void* msg, unsigned msgByteCnt );
  89. // Enable/disable synchronization protocol reporting.
  90. // Return the previous state of the report sync. flag.
  91. bool cmRtNetReportSyncEnable( cmRtNetH_t h, bool enableFl );
  92. bool cmRtNetReportSyncIsEnabled( cmRtNetH_t h );
  93. void cmRtNetReport( cmRtNetH_t h );
  94. void cmRtNetTest( cmCtx_t* ctx, bool mstrFl );
  95. /*
  96. Synchronization Protocol:
  97. Machine A Machine B
  98. ================================== ====================================
  99. broadcast 'hello' ------------------=-> create node-A w/ ei=0 -------+
  100. |
  101. +<-- create node-B w/ ei=0 <--------=-- send 'node' <----------------+
  102. |
  103. +--> switch(ei,m_t)
  104. | ei < en : send endpt[ei++] -=--> create endpt[] on node-A -->+
  105. | |
  106. | ei == en : ++ei,send 'done' -=------------------------------->+ |
  107. | |
  108. | m_t!='done': send 'done' -=------------------------------->+ |
  109. | |
  110. | (stop) : |
  111. | |
  112. | v
  113. | switch(ei,m_t)
  114. +<-- create endpt[] on node-B <---=----- send endpt[ei++] : ei < en
  115. |
  116. +<---------------------------------=----- send 'done',++ei : ei == en
  117. |
  118. +<---------------------------------=----- send 'done' : m_t!= 'done'
  119. : (stop)
  120. Notes:
  121. 1) 'ei' is the index of the next local end point to transmit.
  122. 2) 'en' is the count of local endpoints.
  123. 3) 'm_t' is the msg type (i.e.'hello','node','endpoint','done')
  124. of the incoming message.
  125. 4) The symbol -=- in the flow chart implies a network transmission.
  126. */
  127. #ifdef __cplusplus
  128. }
  129. #endif
  130. #endif