process_linker.h 5.5 KB

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