bidirectional_stream_c.h 9.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245
  1. // Copyright 2016 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef COMPONENTS_GRPC_SUPPORT_INCLUDE_BIDIRECTIONAL_STREAM_C_H_
  5. #define COMPONENTS_GRPC_SUPPORT_INCLUDE_BIDIRECTIONAL_STREAM_C_H_
  6. #if defined(WIN32)
  7. #define GRPC_SUPPORT_EXPORT __declspec(dllexport)
  8. #else
  9. #define GRPC_SUPPORT_EXPORT __attribute__((visibility("default")))
  10. #endif
  11. #ifdef __cplusplus
  12. extern "C" {
  13. #endif
  14. #include <stddef.h>
  15. /* Engine API. */
  16. /* Opaque object representing a Bidirectional stream creating engine. Created
  17. * and configured outside of this API to facilitate sharing with other
  18. * components */
  19. typedef struct stream_engine {
  20. void* obj;
  21. void* annotation;
  22. } stream_engine;
  23. /* Bidirectional Stream API */
  24. /* Opaque object representing Bidirectional Stream. */
  25. typedef struct bidirectional_stream {
  26. void* obj;
  27. void* annotation;
  28. } bidirectional_stream;
  29. /* A single request or response header element. */
  30. typedef struct bidirectional_stream_header {
  31. const char* key;
  32. const char* value;
  33. } bidirectional_stream_header;
  34. /* Array of request or response headers or trailers. */
  35. typedef struct bidirectional_stream_header_array {
  36. size_t count;
  37. size_t capacity;
  38. bidirectional_stream_header* headers;
  39. } bidirectional_stream_header_array;
  40. /* Set of callbacks used to receive callbacks from bidirectional stream. */
  41. typedef struct bidirectional_stream_callback {
  42. /* Invoked when the stream is ready for reading and writing.
  43. * Consumer may call bidirectional_stream_read() to start reading data.
  44. * Consumer may call bidirectional_stream_write() to start writing
  45. * data.
  46. */
  47. void (*on_stream_ready)(bidirectional_stream* stream);
  48. /* Invoked when initial response headers are received.
  49. * Consumer must call bidirectional_stream_read() to start reading.
  50. * Consumer may call bidirectional_stream_write() to start writing or
  51. * close the stream. Contents of |headers| is valid for duration of the call.
  52. */
  53. void (*on_response_headers_received)(
  54. bidirectional_stream* stream,
  55. const bidirectional_stream_header_array* headers,
  56. const char* negotiated_protocol);
  57. /* Invoked when data is read into the buffer passed to
  58. * bidirectional_stream_read(). Only part of the buffer may be
  59. * populated. To continue reading, call bidirectional_stream_read().
  60. * It may be invoked after on_response_trailers_received()}, if there was
  61. * pending read data before trailers were received.
  62. *
  63. * If |bytes_read| is 0, it means the remote side has signaled that it will
  64. * send no more data; future calls to bidirectional_stream_read()
  65. * will result in the on_data_read() callback or on_succeded() callback if
  66. * bidirectional_stream_write() was invoked with end_of_stream set to
  67. * true.
  68. */
  69. void (*on_read_completed)(bidirectional_stream* stream,
  70. char* data,
  71. int bytes_read);
  72. /**
  73. * Invoked when all data passed to bidirectional_stream_write() is
  74. * sent. To continue writing, call bidirectional_stream_write().
  75. */
  76. void (*on_write_completed)(bidirectional_stream* stream, const char* data);
  77. /* Invoked when trailers are received before closing the stream. Only invoked
  78. * when server sends trailers, which it may not. May be invoked while there is
  79. * read data remaining in local buffer. Contents of |trailers| is valid for
  80. * duration of the call.
  81. */
  82. void (*on_response_trailers_received)(
  83. bidirectional_stream* stream,
  84. const bidirectional_stream_header_array* trailers);
  85. /**
  86. * Invoked when there is no data to be read or written and the stream is
  87. * closed successfully remotely and locally. Once invoked, no further callback
  88. * methods will be invoked.
  89. */
  90. void (*on_succeded)(bidirectional_stream* stream);
  91. /**
  92. * Invoked if the stream failed for any reason after
  93. * bidirectional_stream_start(). HTTP/2 error codes are
  94. * mapped to chrome net error codes. Once invoked, no further callback methods
  95. * will be invoked.
  96. */
  97. void (*on_failed)(bidirectional_stream* stream, int net_error);
  98. /**
  99. * Invoked if the stream was canceled via
  100. * bidirectional_stream_cancel(). Once invoked, no further callback
  101. * methods will be invoked.
  102. */
  103. void (*on_canceled)(bidirectional_stream* stream);
  104. } bidirectional_stream_callback;
  105. /* Creates a new stream object that uses |engine| and |callback|. All stream
  106. * tasks are performed asynchronously on the |engine| network thread. |callback|
  107. * methods are invoked synchronously on the |engine| network thread, but must
  108. * not run tasks on the current thread to prevent blocking networking operations
  109. * and causing exceptions during shutdown. The |annotation| is stored in
  110. * bidirectional stream for arbitrary use by application.
  111. *
  112. * Returned |bidirectional_stream*| is owned by the caller, and must be
  113. * destroyed using |bidirectional_stream_destroy|.
  114. *
  115. * Both |calback| and |engine| must remain valid until stream is destroyed.
  116. */
  117. GRPC_SUPPORT_EXPORT
  118. bidirectional_stream* bidirectional_stream_create(
  119. stream_engine* engine,
  120. void* annotation,
  121. bidirectional_stream_callback* callback);
  122. /* TBD: The following methods return int. Should it be a custom type? */
  123. /* Destroys stream object. Destroy could be called from any thread, including
  124. * network thread, but is posted, so |stream| is valid until calling task is
  125. * complete.
  126. */
  127. GRPC_SUPPORT_EXPORT
  128. int bidirectional_stream_destroy(bidirectional_stream* stream);
  129. /**
  130. * Disables or enables auto flush. By default, data is flushed after
  131. * every bidirectional_stream_write(). If the auto flush is disabled,
  132. * the client should explicitly call bidirectional_stream_flush to flush
  133. * the data.
  134. */
  135. GRPC_SUPPORT_EXPORT void bidirectional_stream_disable_auto_flush(
  136. bidirectional_stream* stream,
  137. bool disable_auto_flush);
  138. /**
  139. * Delays sending request headers until bidirectional_stream_flush()
  140. * is called. This flag is currently only respected when QUIC is negotiated.
  141. * When true, QUIC will send request header frame along with data frame(s)
  142. * as a single packet when possible.
  143. */
  144. GRPC_SUPPORT_EXPORT
  145. void bidirectional_stream_delay_request_headers_until_flush(
  146. bidirectional_stream* stream,
  147. bool delay_headers_until_flush);
  148. /* Starts the stream by sending request to |url| using |method| and |headers|.
  149. * If |end_of_stream| is true, then no data is expected to be written. The
  150. * |method| is HTTP verb.
  151. */
  152. GRPC_SUPPORT_EXPORT
  153. int bidirectional_stream_start(bidirectional_stream* stream,
  154. const char* url,
  155. int priority,
  156. const char* method,
  157. const bidirectional_stream_header_array* headers,
  158. bool end_of_stream);
  159. /* Reads response data into |buffer| of |capacity| length. Must only be called
  160. * at most once in response to each invocation of the
  161. * on_stream_ready()/on_response_headers_received() and on_read_completed()
  162. * methods of the bidirectional_stream_callback.
  163. * Each call will result in an invocation of the callback's
  164. * on_read_completed() method if data is read, or its on_failed() method if
  165. * there's an error. The callback's on_succeeded() method is also invoked if
  166. * there is no more data to read and |end_of_stream| was previously sent.
  167. */
  168. GRPC_SUPPORT_EXPORT
  169. int bidirectional_stream_read(bidirectional_stream* stream,
  170. char* buffer,
  171. int capacity);
  172. /* Writes request data from |buffer| of |buffer_length| length. If auto flush is
  173. * disabled, data will be sent only after bidirectional_stream_flush() is
  174. * called.
  175. * Each call will result in an invocation the callback's on_write_completed()
  176. * method if data is sent, or its on_failed() method if there's an error.
  177. * The callback's on_succeeded() method is also invoked if |end_of_stream| is
  178. * set and all response data has been read.
  179. */
  180. GRPC_SUPPORT_EXPORT
  181. int bidirectional_stream_write(bidirectional_stream* stream,
  182. const char* buffer,
  183. int buffer_length,
  184. bool end_of_stream);
  185. /**
  186. * Flushes pending writes. This method should not be called before invocation of
  187. * on_stream_ready() method of the bidirectional_stream_callback.
  188. * For each previously called bidirectional_stream_write()
  189. * a corresponding on_write_completed() callback will be invoked when the buffer
  190. * is sent.
  191. */
  192. GRPC_SUPPORT_EXPORT
  193. void bidirectional_stream_flush(bidirectional_stream* stream);
  194. /* Cancels the stream. Can be called at any time after
  195. * bidirectional_stream_start(). The on_canceled() method of
  196. * bidirectional_stream_callback will be invoked when cancelation
  197. * is complete and no further callback methods will be invoked. If the
  198. * stream has completed or has not started, calling
  199. * bidirectional_stream_cancel() has no effect and on_canceled() will not
  200. * be invoked. At most one callback method may be invoked after
  201. * bidirectional_stream_cancel() has completed.
  202. */
  203. GRPC_SUPPORT_EXPORT
  204. void bidirectional_stream_cancel(bidirectional_stream* stream);
  205. /* Returns true if the |stream| was successfully started and is now done
  206. * (succeeded, canceled, or failed).
  207. * Returns false if the |stream| stream is not yet started or is in progress.
  208. */
  209. GRPC_SUPPORT_EXPORT
  210. bool bidirectional_stream_is_done(bidirectional_stream* stream);
  211. #ifdef __cplusplus
  212. }
  213. #endif
  214. #endif // COMPONENTS_GRPC_SUPPORT_INCLUDE_BIDIRECTIONAL_STREAM_C_H_