1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
// 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_
|
