third_party/objective_c/Cronet/cronet_c_for_grpc.h

// 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_CRONET_IOS_CRONET_C_FOR_GRPC_H_
#define COMPONENTS_CRONET_IOS_CRONET_C_FOR_GRPC_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <stddef.h>

/* Cronet Engine API. */

/* Opaque object representing Cronet Engine. Created and configured outside
 * of this API to facilitate sharing with other components */
typedef struct cronet_engine { void* obj; } cronet_engine;

void cronet_engine_add_quic_hint(cronet_engine* engine,
                                 const char* host,
                                 int port,
                                 int alternate_port);

/* Cronet Bidirectional Stream API */

/* Opaque object representing Cronet Bidirectional Stream. */
typedef struct cronet_bidirectional_stream {
  void* obj;
  void* annotation;
} cronet_bidirectional_stream;

/* A single request or response header element. */
typedef struct cronet_bidirectional_stream_header {
  const char* key;
  const char* value;
} cronet_bidirectional_stream_header;

/* Array of request or response headers or trailers. */
typedef struct cronet_bidirectional_stream_header_array {
  size_t count;
  size_t capacity;
  cronet_bidirectional_stream_header* headers;
} cronet_bidirectional_stream_header_array;

/* Set of callbacks used to receive callbacks from bidirectional stream. */
typedef struct cronet_bidirectional_stream_callback {
  /* Invoked when request headers are sent. Indicates that stream has initiated
   * the request. Consumer may call cronet_bidirectional_stream_write() to start
   * writing data.
   */
  void (*on_request_headers_sent)(cronet_bidirectional_stream* stream);

  /* Invoked when initial response headers are received.
   * Consumer must call cronet_bidirectional_stream_read() to start reading.
   * Consumer may call cronet_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)(
      cronet_bidirectional_stream* stream,
      const cronet_bidirectional_stream_header_array* headers,
      const char* negotiated_protocol);

  /* Invoked when data is read into the buffer passed to
   * cronet_bidirectional_stream_read(). Only part of the buffer may be
   * populated. To continue reading, call cronet_bidirectional_stream_read().
   * It may be invoked after on_response_trailers_received()}, if there was
   * pending read data before trailers were received.
   *
   * If count is 0, it means the remote side has signaled that it will send no
   * more data; future calls to cronet_bidirectional_stream_read() will result
   * in the on_data_read() callback or on_succeded() callback if
   * cronet_bidirectional_stream_write() was invoked with end_of_stream set to
   * true.
   */
  void (*on_read_completed)(cronet_bidirectional_stream* stream,
                            char* data,
                            int count);

  /**
   * Invoked when all data passed to cronet_bidirectional_stream_write() is
   * sent.
   * To continue writing, call cronet_bidirectional_stream_write().
   */
  void (*on_write_completed)(cronet_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)(
      cronet_bidirectional_stream* stream,
      const cronet_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)(cronet_bidirectional_stream* stream);

  /**
   * Invoked if the stream failed for any reason after
   * cronet_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)(cronet_bidirectional_stream* stream, int net_error);

  /**
   * Invoked if the stream was canceled via
   * cronet_bidirectional_stream_cancel(). Once invoked, no further callback
   * methods will be invoked.
   */
  void (*on_canceled)(cronet_bidirectional_stream* stream);
} cronet_bidirectional_stream_callback;

/* Create 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 |cronet_bidirectional_stream*| is owned by the caller, and must be
 * destroyed using |cronet_bidirectional_stream_destroy|.
 *
 * Both |calback| and |engine| must remain valid until stream is destroyed.
 */
cronet_bidirectional_stream* cronet_bidirectional_stream_create(
    cronet_engine* engine,
    void* annotation,
    cronet_bidirectional_stream_callback* callback);

/* TBD: The following methods return int. Should it be a custom type? */

/* Destroy stream object. Destroy could be called from any thread, including
 * network thread, but is posted, so |stream| is valid until calling task is
 * complete.
 */
int cronet_bidirectional_stream_destroy(cronet_bidirectional_stream* stream);

/* Start 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.
 */
int cronet_bidirectional_stream_start(
    cronet_bidirectional_stream* stream,
    const char* url,
    int priority,
    const char* method,
    const cronet_bidirectional_stream_header_array* headers,
    bool end_of_stream);

/* Read response data into |buffer| of |capacity| length. Must only be called at
 * most once in response to each invocation of the
 * on_response_headers_received() and on_read_completed() methods of the
 * cronet_bidirectional_stream_callback.
 * Each call will result in an invocation of one of the callback's
 * on_read_completed  method if data is read, its on_succeeded() method if
 * the stream is closed, or its on_failed() method if there's an error.
 */
int cronet_bidirectional_stream_read(cronet_bidirectional_stream* stream,
                                     char* buffer,
                                     int capacity);

/* Read response data into |buffer| of |capacity| length. Must only be called at
 * most once in response to each invocation of the
 * on_response_headers_received() and on_read_completed() methods of the
 * cronet_bidirectional_stream_callback.
 * Each call will result in an invocation of one of the callback's
 * on_read_completed  method if data is read, its on_succeeded() method if
 * the stream is closed, or its on_failed() method if there's an error.
 */
int cronet_bidirectional_stream_write(cronet_bidirectional_stream* stream,
                                      const char* buffer,
                                      int count,
                                      bool end_of_stream);

/* Cancels the stream. Can be called at any time after
 * cronet_bidirectional_stream_start(). The on_canceled() method of
 * cronet_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
 * cronet_bidirectional_stream_cancel() has no effect and on_canceled() will not
 * be  invoked. At most one callback method may be invoked after
 * cronet_bidirectional_stream_cancel() has completed.
 */
int cronet_bidirectional_stream_cancel(cronet_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.
 */
bool cronet_bidirectional_stream_is_done(cronet_bidirectional_stream* stream);

#ifdef __cplusplus
}
#endif

#endif  // COMPONENTS_CRONET_IOS_CRONET_C_FOR_GRPC_H_