process_linker.h 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225
  1. /*
  2. * Copyright (c) 2021-2022 Alibaba Group. All rights reserved.
  3. * License-Identifier: Apache-2.0
  4. *
  5. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  6. * not use this file except in compliance with the License.
  7. * You may obtain a copy of the License at
  8. *
  9. * http://www.apache.org/licenses/LICENSE-2.0
  10. *
  11. * Unless required by applicable law or agreed to in writing, software
  12. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  13. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14. * See the License for the specific language governing permissions and
  15. * limitations under the License.
  16. *
  17. */
  18. #ifndef _PROCESS_LINKER_H_
  19. #define _PROCESS_LINKER_H_
  20. #ifdef __cplusplus
  21. extern "C" {
  22. #endif
  23. #define PLINK_VERSION_MAJOR 0
  24. #define PLINK_VERSION_MINOR 1
  25. #define PLINK_VERSION_REVISION 1
  26. /* Maximum data descriptors in one packet */
  27. #define PLINK_MAX_DATA_DESCS 10
  28. /* Close all the connections from client. */
  29. /* Can be used as the second parameter of PLINK_close when the instance is created as SERVER */
  30. #define PLINK_CLOSE_ALL -1
  31. /* invalid file descriptor */
  32. #define PLINK_INVALID_FD -1
  33. #define DATA_HEADER_SIZE (sizeof(PlinkDescHdr))
  34. #define DATA_SIZE(type) (sizeof(type) - DATA_HEADER_SIZE)
  35. typedef void *PlinkHandle;
  36. typedef void PlinkDescriptor;
  37. typedef int PlinkChannelID;
  38. typedef enum _PlinkStatus
  39. {
  40. PLINK_STATUS_OK = 0,
  41. PLINK_STATUS_MORE_DATA = 1, /* have more data to parse in the receive buffer */
  42. PLINK_STATUS_TIMEOUT = 2, /* wait timeout, which means no data received within the time */
  43. PLINK_STATUS_NO_DATA = 3, /* no data recieved */
  44. PLINK_STATUS_ERROR = -1, /* general error */
  45. PLINK_STATUS_WRONG_PARAMS = -2, /* wrong parameters */
  46. PLINK_STATUS_NO_MEMORY = -3, /* not enough memory */
  47. } PlinkStatus;
  48. /* plink mode */
  49. typedef enum _PlinkMode
  50. {
  51. PLINK_MODE_SERVER = 0, /* run plink as server; server should be launched before client */
  52. PLINK_MODE_CLIENT, /* run plink as client which can connect to server */
  53. PLINK_MODE_MAX
  54. } PlinkMode;
  55. typedef union _PlinkVersion
  56. {
  57. struct process_linker
  58. {
  59. unsigned char major;
  60. unsigned char minor;
  61. unsigned char revision;
  62. unsigned char step;
  63. } v;
  64. unsigned int version;
  65. } PlinkVersion;
  66. typedef struct _PlinkDescHdr
  67. {
  68. unsigned int size; /* data size, excluding this header */
  69. int type; /* type of this data descriptor */
  70. int id; /* buffer id if it's buffer descriptor. Only values greater than 0 are valid */
  71. } PlinkDescHdr;
  72. /* data packet can be sent/received in one send/recv call */
  73. typedef struct _PlinkPacket
  74. {
  75. int fd; /* file descriptor. If PLINK_INVALID_FD, it's invalid */
  76. unsigned int timestamp; /* timestamp of this packet, the time for rendering */
  77. int num; /* number of valid data descriptor entries in list[] */
  78. PlinkDescriptor *list[PLINK_MAX_DATA_DESCS]; /* list of pointers which point to data descriptor. */
  79. } PlinkPacket;
  80. /**
  81. * \brief Create a plink instance.
  82. *
  83. * Create a plink object with the specified name as server or client.
  84. * When mode is PLINK_MODE_SERVER, a file of the specified name will be created.
  85. *
  86. * \param plink Point to the pointer of plink instance.
  87. * \param name Socket file name.
  88. * \param mode plink mode, server or client.
  89. * \return PLINK_STATUS_OK successful,
  90. * \return other unsuccessful.
  91. */
  92. PlinkStatus PLINK_getVersion(PlinkVersion *version);
  93. /**
  94. * \brief Create a plink instance.
  95. *
  96. * Create a plink object with the specified name as server or client.
  97. * When mode is PLINK_MODE_SERVER, a file of the specified name will be created.
  98. *
  99. * \param plink Point to the pointer of plink instance.
  100. * \param name Socket file name.
  101. * \param mode plink mode, server or client.
  102. * \return PLINK_STATUS_OK successful,
  103. * \return other unsuccessful.
  104. */
  105. PlinkStatus PLINK_create(PlinkHandle *plink, const char *name, PlinkMode mode);
  106. /**
  107. * \brief Create a connection between server and client
  108. *
  109. * Server calls this function to wait for connection and accept.
  110. * Client calls this function to connect to server.
  111. *
  112. * \param plink Pointer of plink instance.
  113. * \param channel id of the new connection. Valid for server only. Should be 0 for client
  114. * \return PLINK_STATUS_OK successful,
  115. * \return other unsuccessful.
  116. */
  117. PlinkStatus PLINK_connect(PlinkHandle plink, PlinkChannelID *channel);
  118. /**
  119. * \brief Create a connection between server and client with timeout
  120. *
  121. * Server calls this function to wait for connection and accept with timeout.
  122. * Client calls this function to connect to server with timeout.
  123. *
  124. * \param plink Pointer of plink instance.
  125. * \param channel id of the new connection. Valid for server only. Should be 0 for client
  126. * \param timeout_ms timeout in unit of milliseconds.
  127. * \return PLINK_STATUS_OK successful,
  128. * \return PLINK_STATUS_TIMEOUT if no data received within timeout_ms,
  129. * \return other unsuccessful.
  130. */
  131. PlinkStatus PLINK_connect_ex(PlinkHandle plink, PlinkChannelID *channel, int timeout_ms);
  132. /**
  133. * \brief Send a packet
  134. *
  135. * Send a packet through the channel.
  136. *
  137. * \param plink Pointer of plink instance.
  138. * \param channel The channel to send this packet. Valid for server only. Should be 0 for client
  139. * \param pkt Point to the packet to be sent.
  140. * \return PLINK_STATUS_OK successful,
  141. * \return other unsuccessful.
  142. */
  143. PlinkStatus PLINK_send(PlinkHandle plink, PlinkChannelID channel, PlinkPacket *pkt);
  144. /**
  145. * \brief Wait for data from channel
  146. *
  147. * This function returns once there is data received from the channel.
  148. *
  149. * \param plink Pointer of plink instance.
  150. * \param channel The channel to receive data. Valid for server only. Should be 0 for client
  151. * \param timeout_ms timeout in unit of milliseconds.
  152. * \return PLINK_STATUS_OK successful,
  153. * \return PLINK_STATUS_TIMEOUT if no data received within timeout_ms,
  154. * \return other unsuccessful.
  155. */
  156. PlinkStatus PLINK_wait(PlinkHandle plink, PlinkChannelID channel, int timeout_ms);
  157. /**
  158. * \brief Receive data
  159. *
  160. * Receive data from the channel.
  161. * Data descriptors of the packet are stored in the internal buffer,
  162. * and may be overwritten in the next PLINK_recv call.
  163. *
  164. * \param plink Pointer of plink instance.
  165. * \param channel The channel to receive data. Valid for server only. Should be 0 for client
  166. * \param pkt Point to the received packet.
  167. * \return PLINK_STATUS_OK successful,
  168. * \return other unsuccessful.
  169. */
  170. PlinkStatus PLINK_recv(PlinkHandle plink, PlinkChannelID channel, PlinkPacket *pkt);
  171. /**
  172. * \brief Receive data with timeout
  173. *
  174. * Receive data from the channel with timeout.
  175. * Data descriptors of the packet are stored in the internal buffer,
  176. * and may be overwritten in the next PLINK_recv call.
  177. *
  178. * \param plink Pointer of plink instance.
  179. * \param channel The channel to receive data. Valid for server only. Should be 0 for client
  180. * \param pkt Point to the received packet.
  181. * \param timeout_ms timeout in unit of milliseconds.
  182. * \return PLINK_STATUS_OK successful,
  183. * \return PLINK_STATUS_TIMEOUT if no data received within timeout_ms,
  184. * \return other unsuccessful.
  185. */
  186. PlinkStatus PLINK_recv_ex(PlinkHandle plink, PlinkChannelID channel, PlinkPacket *pkt, int timeout_ms);
  187. /**
  188. * \brief Close connections
  189. *
  190. * Close connections. Server can set channel to PLINK_CLOSE_ALL to close all connections.
  191. *
  192. * \param plink Pointer of plink instance.
  193. * \param channel The connection to be closed. Valid for server only. Should be 0 for client
  194. * \return PLINK_STATUS_OK successful,
  195. * \return other unsuccessful.
  196. */
  197. PlinkStatus PLINK_close(PlinkHandle plink, PlinkChannelID channel);
  198. #ifdef __cplusplus
  199. }
  200. #endif
  201. #endif /* !_PROCESS_LINKER_H_ */