123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245 |
- // Copyright 2016 The Chromium Authors. All rights reserved.
- // Use of this source code is governed by a BSD-style license that can be
- // found in the LICENSE file.
- #ifndef COMPONENTS_GRPC_SUPPORT_INCLUDE_BIDIRECTIONAL_STREAM_C_H_
- #define COMPONENTS_GRPC_SUPPORT_INCLUDE_BIDIRECTIONAL_STREAM_C_H_
- #if defined(WIN32)
- #define GRPC_SUPPORT_EXPORT __declspec(dllexport)
- #else
- #define GRPC_SUPPORT_EXPORT __attribute__((visibility("default")))
- #endif
- #ifdef __cplusplus
- extern "C" {
- #endif
- #include <stddef.h>
- /* Engine API. */
- /* Opaque object representing a Bidirectional stream creating engine. Created
- * and configured outside of this API to facilitate sharing with other
- * components */
- typedef struct stream_engine {
- void* obj;
- void* annotation;
- } stream_engine;
- /* Bidirectional Stream API */
- /* Opaque object representing Bidirectional Stream. */
- typedef struct bidirectional_stream {
- void* obj;
- void* annotation;
- } bidirectional_stream;
- /* A single request or response header element. */
- typedef struct bidirectional_stream_header {
- const char* key;
- const char* value;
- } bidirectional_stream_header;
- /* Array of request or response headers or trailers. */
- typedef struct bidirectional_stream_header_array {
- size_t count;
- size_t capacity;
- bidirectional_stream_header* headers;
- } bidirectional_stream_header_array;
- /* Set of callbacks used to receive callbacks from bidirectional stream. */
- typedef struct bidirectional_stream_callback {
- /* Invoked when the stream is ready for reading and writing.
- * Consumer may call bidirectional_stream_read() to start reading data.
- * Consumer may call bidirectional_stream_write() to start writing
- * data.
- */
- void (*on_stream_ready)(bidirectional_stream* stream);
- /* Invoked when initial response headers are received.
- * Consumer must call bidirectional_stream_read() to start reading.
- * Consumer may call bidirectional_stream_write() to start writing or
- * close the stream. Contents of |headers| is valid for duration of the call.
- */
- void (*on_response_headers_received)(
- bidirectional_stream* stream,
- const bidirectional_stream_header_array* headers,
- const char* negotiated_protocol);
- /* Invoked when data is read into the buffer passed to
- * bidirectional_stream_read(). Only part of the buffer may be
- * populated. To continue reading, call bidirectional_stream_read().
- * It may be invoked after on_response_trailers_received()}, if there was
- * pending read data before trailers were received.
- *
- * If |bytes_read| is 0, it means the remote side has signaled that it will
- * send no more data; future calls to bidirectional_stream_read()
- * will result in the on_data_read() callback or on_succeded() callback if
- * bidirectional_stream_write() was invoked with end_of_stream set to
- * true.
- */
- void (*on_read_completed)(bidirectional_stream* stream,
- char* data,
- int bytes_read);
- /**
- * Invoked when all data passed to bidirectional_stream_write() is
- * sent. To continue writing, call bidirectional_stream_write().
- */
- void (*on_write_completed)(bidirectional_stream* stream, const char* data);
- /* Invoked when trailers are received before closing the stream. Only invoked
- * when server sends trailers, which it may not. May be invoked while there is
- * read data remaining in local buffer. Contents of |trailers| is valid for
- * duration of the call.
- */
- void (*on_response_trailers_received)(
- bidirectional_stream* stream,
- const bidirectional_stream_header_array* trailers);
- /**
- * Invoked when there is no data to be read or written and the stream is
- * closed successfully remotely and locally. Once invoked, no further callback
- * methods will be invoked.
- */
- void (*on_succeded)(bidirectional_stream* stream);
- /**
- * Invoked if the stream failed for any reason after
- * bidirectional_stream_start(). HTTP/2 error codes are
- * mapped to chrome net error codes. Once invoked, no further callback methods
- * will be invoked.
- */
- void (*on_failed)(bidirectional_stream* stream, int net_error);
- /**
- * Invoked if the stream was canceled via
- * bidirectional_stream_cancel(). Once invoked, no further callback
- * methods will be invoked.
- */
- void (*on_canceled)(bidirectional_stream* stream);
- } bidirectional_stream_callback;
- /* Creates a new stream object that uses |engine| and |callback|. All stream
- * tasks are performed asynchronously on the |engine| network thread. |callback|
- * methods are invoked synchronously on the |engine| network thread, but must
- * not run tasks on the current thread to prevent blocking networking operations
- * and causing exceptions during shutdown. The |annotation| is stored in
- * bidirectional stream for arbitrary use by application.
- *
- * Returned |bidirectional_stream*| is owned by the caller, and must be
- * destroyed using |bidirectional_stream_destroy|.
- *
- * Both |calback| and |engine| must remain valid until stream is destroyed.
- */
- GRPC_SUPPORT_EXPORT
- bidirectional_stream* bidirectional_stream_create(
- stream_engine* engine,
- void* annotation,
- bidirectional_stream_callback* callback);
- /* TBD: The following methods return int. Should it be a custom type? */
- /* Destroys stream object. Destroy could be called from any thread, including
- * network thread, but is posted, so |stream| is valid until calling task is
- * complete.
- */
- GRPC_SUPPORT_EXPORT
- int bidirectional_stream_destroy(bidirectional_stream* stream);
- /**
- * Disables or enables auto flush. By default, data is flushed after
- * every bidirectional_stream_write(). If the auto flush is disabled,
- * the client should explicitly call bidirectional_stream_flush to flush
- * the data.
- */
- GRPC_SUPPORT_EXPORT void bidirectional_stream_disable_auto_flush(
- bidirectional_stream* stream,
- bool disable_auto_flush);
- /**
- * Delays sending request headers until bidirectional_stream_flush()
- * is called. This flag is currently only respected when QUIC is negotiated.
- * When true, QUIC will send request header frame along with data frame(s)
- * as a single packet when possible.
- */
- GRPC_SUPPORT_EXPORT
- void bidirectional_stream_delay_request_headers_until_flush(
- bidirectional_stream* stream,
- bool delay_headers_until_flush);
- /* Starts the stream by sending request to |url| using |method| and |headers|.
- * If |end_of_stream| is true, then no data is expected to be written. The
- * |method| is HTTP verb.
- */
- GRPC_SUPPORT_EXPORT
- int bidirectional_stream_start(bidirectional_stream* stream,
- const char* url,
- int priority,
- const char* method,
- const bidirectional_stream_header_array* headers,
- bool end_of_stream);
- /* Reads response data into |buffer| of |capacity| length. Must only be called
- * at most once in response to each invocation of the
- * on_stream_ready()/on_response_headers_received() and on_read_completed()
- * methods of the bidirectional_stream_callback.
- * Each call will result in an invocation of the callback's
- * on_read_completed() method if data is read, or its on_failed() method if
- * there's an error. The callback's on_succeeded() method is also invoked if
- * there is no more data to read and |end_of_stream| was previously sent.
- */
- GRPC_SUPPORT_EXPORT
- int bidirectional_stream_read(bidirectional_stream* stream,
- char* buffer,
- int capacity);
- /* Writes request data from |buffer| of |buffer_length| length. If auto flush is
- * disabled, data will be sent only after bidirectional_stream_flush() is
- * called.
- * Each call will result in an invocation the callback's on_write_completed()
- * method if data is sent, or its on_failed() method if there's an error.
- * The callback's on_succeeded() method is also invoked if |end_of_stream| is
- * set and all response data has been read.
- */
- GRPC_SUPPORT_EXPORT
- int bidirectional_stream_write(bidirectional_stream* stream,
- const char* buffer,
- int buffer_length,
- bool end_of_stream);
- /**
- * Flushes pending writes. This method should not be called before invocation of
- * on_stream_ready() method of the bidirectional_stream_callback.
- * For each previously called bidirectional_stream_write()
- * a corresponding on_write_completed() callback will be invoked when the buffer
- * is sent.
- */
- GRPC_SUPPORT_EXPORT
- void bidirectional_stream_flush(bidirectional_stream* stream);
- /* Cancels the stream. Can be called at any time after
- * bidirectional_stream_start(). The on_canceled() method of
- * bidirectional_stream_callback will be invoked when cancelation
- * is complete and no further callback methods will be invoked. If the
- * stream has completed or has not started, calling
- * bidirectional_stream_cancel() has no effect and on_canceled() will not
- * be invoked. At most one callback method may be invoked after
- * bidirectional_stream_cancel() has completed.
- */
- GRPC_SUPPORT_EXPORT
- void bidirectional_stream_cancel(bidirectional_stream* stream);
- /* Returns true if the |stream| was successfully started and is now done
- * (succeeded, canceled, or failed).
- * Returns false if the |stream| stream is not yet started or is in progress.
- */
- GRPC_SUPPORT_EXPORT
- bool bidirectional_stream_is_done(bidirectional_stream* stream);
- #ifdef __cplusplus
- }
- #endif
- #endif // COMPONENTS_GRPC_SUPPORT_INCLUDE_BIDIRECTIONAL_STREAM_C_H_
|