process_linker.h 7.6 KB

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