// Copyright 2016 The Chromium Authors // 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 … #else #define GRPC_SUPPORT_EXPORT … #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 */ stream_engine; /* Bidirectional Stream API */ /* Opaque object representing Bidirectional Stream. */ bidirectional_stream; /* A single request or response header element. */ bidirectional_stream_header; /* Array of request or response headers or trailers. */ bidirectional_stream_header_array; /* Set of callbacks used to receive callbacks from bidirectional 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, const 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_
Codebase Browser
chromium