• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  *
3  * Copyright 2015 gRPC authors.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  */
18 
19 #ifndef GRPC_IMPL_CODEGEN_GRPC_TYPES_H
20 #define GRPC_IMPL_CODEGEN_GRPC_TYPES_H
21 
22 #include <grpc/impl/codegen/port_platform.h>
23 
24 #include <grpc/impl/codegen/compression_types.h>
25 #include <grpc/impl/codegen/gpr_types.h>
26 #include <grpc/impl/codegen/slice.h>
27 #include <grpc/impl/codegen/status.h>
28 
29 #include <stddef.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 typedef enum {
36   GRPC_BB_RAW
37   /** Future types may include GRPC_BB_PROTOBUF, etc. */
38 } grpc_byte_buffer_type;
39 
40 typedef struct grpc_byte_buffer {
41   void* reserved;
42   grpc_byte_buffer_type type;
43   union grpc_byte_buffer_data {
44     struct /* internal */ {
45       void* reserved[8];
46     } reserved;
47     struct grpc_compressed_buffer {
48       grpc_compression_algorithm compression;
49       grpc_slice_buffer slice_buffer;
50     } raw;
51   } data;
52 } grpc_byte_buffer;
53 
54 /** Completion Queues enable notification of the completion of
55  * asynchronous actions. */
56 typedef struct grpc_completion_queue grpc_completion_queue;
57 
58 /** An alarm associated with a completion queue. */
59 typedef struct grpc_alarm grpc_alarm;
60 
61 /** The Channel interface allows creation of Call objects. */
62 typedef struct grpc_channel grpc_channel;
63 
64 /** A server listens to some port and responds to request calls */
65 typedef struct grpc_server grpc_server;
66 
67 /** A Call represents an RPC. When created, it is in a configuration state
68     allowing properties to be set until it is invoked. After invoke, the Call
69     can have messages written to it and read from it. */
70 typedef struct grpc_call grpc_call;
71 
72 /** The Socket Mutator interface allows changes on socket options */
73 typedef struct grpc_socket_mutator grpc_socket_mutator;
74 
75 /** The Socket Factory interface creates and binds sockets */
76 typedef struct grpc_socket_factory grpc_socket_factory;
77 
78 /** Type specifier for grpc_arg */
79 typedef enum {
80   GRPC_ARG_STRING,
81   GRPC_ARG_INTEGER,
82   GRPC_ARG_POINTER
83 } grpc_arg_type;
84 
85 typedef struct grpc_arg_pointer_vtable {
86   void* (*copy)(void* p);
87   void (*destroy)(void* p);
88   int (*cmp)(void* p, void* q);
89 } grpc_arg_pointer_vtable;
90 
91 /** A single argument... each argument has a key and a value
92 
93     A note on naming keys:
94       Keys are namespaced into groups, usually grouped by library, and are
95       keys for module XYZ are named XYZ.key1, XYZ.key2, etc. Module names must
96       be restricted to the regex [A-Za-z][_A-Za-z0-9]{,15}.
97       Key names must be restricted to the regex [A-Za-z][_A-Za-z0-9]{,47}.
98 
99     GRPC core library keys are prefixed by grpc.
100 
101     Library authors are strongly encouraged to \#define symbolic constants for
102     their keys so that it's possible to change them in the future. */
103 typedef struct {
104   grpc_arg_type type;
105   char* key;
106   union grpc_arg_value {
107     char* string;
108     int integer;
109     struct grpc_arg_pointer {
110       void* p;
111       const grpc_arg_pointer_vtable* vtable;
112     } pointer;
113   } value;
114 } grpc_arg;
115 
116 /** An array of arguments that can be passed around.
117 
118     Used to set optional channel-level configuration.
119     These configuration options are modelled as key-value pairs as defined
120     by grpc_arg; keys are strings to allow easy backwards-compatible extension
121     by arbitrary parties. All evaluation is performed at channel creation
122     time (i.e. the keys and values in this structure need only live through the
123     creation invocation).
124 
125     However, if one of the args has grpc_arg_type==GRPC_ARG_POINTER, then the
126     grpc_arg_pointer_vtable must live until the channel args are done being
127     used by core (i.e. when the object for use with which they were passed
128     is destroyed).
129 
130     See the description of the \ref grpc_arg_keys "available args" for more
131     details. */
132 typedef struct {
133   size_t num_args;
134   grpc_arg* args;
135 } grpc_channel_args;
136 
137 /** \defgroup grpc_arg_keys
138  * Channel argument keys.
139  * \{
140  */
141 /** If non-zero, enable census for tracing and stats collection. */
142 #define GRPC_ARG_ENABLE_CENSUS "grpc.census"
143 /** If non-zero, enable load reporting. */
144 #define GRPC_ARG_ENABLE_LOAD_REPORTING "grpc.loadreporting"
145 /** Request that optional features default to off (regardless of what they
146     usually default to) - to enable tight control over what gets enabled */
147 #define GRPC_ARG_MINIMAL_STACK "grpc.minimal_stack"
148 /** Maximum number of concurrent incoming streams to allow on a http2
149     connection. Int valued. */
150 #define GRPC_ARG_MAX_CONCURRENT_STREAMS "grpc.max_concurrent_streams"
151 /** Maximum message length that the channel can receive. Int valued, bytes.
152     -1 means unlimited. */
153 #define GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH "grpc.max_receive_message_length"
154 /** \deprecated For backward compatibility.
155  * Use GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH instead. */
156 #define GRPC_ARG_MAX_MESSAGE_LENGTH GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH
157 /** Maximum message length that the channel can send. Int valued, bytes.
158     -1 means unlimited. */
159 #define GRPC_ARG_MAX_SEND_MESSAGE_LENGTH "grpc.max_send_message_length"
160 /** Maximum time that a channel may have no outstanding rpcs. Int valued,
161     milliseconds. INT_MAX means unlimited. */
162 #define GRPC_ARG_MAX_CONNECTION_IDLE_MS "grpc.max_connection_idle_ms"
163 /** Maximum time that a channel may exist. Int valued, milliseconds.
164  * INT_MAX means unlimited. */
165 #define GRPC_ARG_MAX_CONNECTION_AGE_MS "grpc.max_connection_age_ms"
166 /** Grace period after the chennel reaches its max age. Int valued,
167    milliseconds. INT_MAX means unlimited. */
168 #define GRPC_ARG_MAX_CONNECTION_AGE_GRACE_MS "grpc.max_connection_age_grace_ms"
169 /** Enable/disable support for per-message compression. Defaults to 1, unless
170     GRPC_ARG_MINIMAL_STACK is enabled, in which case it defaults to 0. */
171 #define GRPC_ARG_ENABLE_PER_MESSAGE_COMPRESSION "grpc.per_message_compression"
172 /** Enable/disable support for deadline checking. Defaults to 1, unless
173     GRPC_ARG_MINIMAL_STACK is enabled, in which case it defaults to 0 */
174 #define GRPC_ARG_ENABLE_DEADLINE_CHECKS "grpc.enable_deadline_checking"
175 /** Initial stream ID for http2 transports. Int valued. */
176 #define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \
177   "grpc.http2.initial_sequence_number"
178 /** Amount to read ahead on individual streams. Defaults to 64kb, larger
179     values can help throughput on high-latency connections.
180     NOTE: at some point we'd like to auto-tune this, and this parameter
181     will become a no-op. Int valued, bytes. */
182 #define GRPC_ARG_HTTP2_STREAM_LOOKAHEAD_BYTES "grpc.http2.lookahead_bytes"
183 /** How much memory to use for hpack decoding. Int valued, bytes. */
184 #define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_DECODER \
185   "grpc.http2.hpack_table_size.decoder"
186 /** How much memory to use for hpack encoding. Int valued, bytes. */
187 #define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_ENCODER \
188   "grpc.http2.hpack_table_size.encoder"
189 /** How big a frame are we willing to receive via HTTP2.
190     Min 16384, max 16777215. Larger values give lower CPU usage for large
191     messages, but more head of line blocking for small messages. */
192 #define GRPC_ARG_HTTP2_MAX_FRAME_SIZE "grpc.http2.max_frame_size"
193 /** Should BDP probing be performed? */
194 #define GRPC_ARG_HTTP2_BDP_PROBE "grpc.http2.bdp_probe"
195 /** Minimum time between sending successive ping frames without receiving any
196     data frame, Int valued, milliseconds. */
197 #define GRPC_ARG_HTTP2_MIN_SENT_PING_INTERVAL_WITHOUT_DATA_MS \
198   "grpc.http2.min_time_between_pings_ms"
199 /** Minimum allowed time between a server receiving successive ping frames
200    without sending any data frame. Int valued, milliseconds */
201 #define GRPC_ARG_HTTP2_MIN_RECV_PING_INTERVAL_WITHOUT_DATA_MS \
202   "grpc.http2.min_ping_interval_without_data_ms"
203 /** Channel arg to override the http2 :scheme header */
204 #define GRPC_ARG_HTTP2_SCHEME "grpc.http2_scheme"
205 /** How many pings can we send before needing to send a data frame or header
206     frame? (0 indicates that an infinite number of pings can be sent without
207     sending a data frame or header frame) */
208 #define GRPC_ARG_HTTP2_MAX_PINGS_WITHOUT_DATA \
209   "grpc.http2.max_pings_without_data"
210 /** How many misbehaving pings the server can bear before sending goaway and
211     closing the transport? (0 indicates that the server can bear an infinite
212     number of misbehaving pings) */
213 #define GRPC_ARG_HTTP2_MAX_PING_STRIKES "grpc.http2.max_ping_strikes"
214 /** How much data are we willing to queue up per stream if
215     GRPC_WRITE_BUFFER_HINT is set? This is an upper bound */
216 #define GRPC_ARG_HTTP2_WRITE_BUFFER_SIZE "grpc.http2.write_buffer_size"
217 /** Should we allow receipt of true-binary data on http2 connections?
218     Defaults to on (1) */
219 #define GRPC_ARG_HTTP2_ENABLE_TRUE_BINARY "grpc.http2.true_binary"
220 /** After a duration of this time the client/server pings its peer to see if the
221     transport is still alive. Int valued, milliseconds. */
222 #define GRPC_ARG_KEEPALIVE_TIME_MS "grpc.keepalive_time_ms"
223 /** After waiting for a duration of this time, if the keepalive ping sender does
224     not receive the ping ack, it will close the transport. Int valued,
225     milliseconds. */
226 #define GRPC_ARG_KEEPALIVE_TIMEOUT_MS "grpc.keepalive_timeout_ms"
227 /** Is it permissible to send keepalive pings without any outstanding streams.
228     Int valued, 0(false)/1(true). */
229 #define GRPC_ARG_KEEPALIVE_PERMIT_WITHOUT_CALLS \
230   "grpc.keepalive_permit_without_calls"
231 /** Default authority to pass if none specified on call construction. A string.
232  * */
233 #define GRPC_ARG_DEFAULT_AUTHORITY "grpc.default_authority"
234 /** Primary user agent: goes at the start of the user-agent metadata
235     sent on each request. A string. */
236 #define GRPC_ARG_PRIMARY_USER_AGENT_STRING "grpc.primary_user_agent"
237 /** Secondary user agent: goes at the end of the user-agent metadata
238     sent on each request. A string. */
239 #define GRPC_ARG_SECONDARY_USER_AGENT_STRING "grpc.secondary_user_agent"
240 /** The minimum time between subsequent connection attempts, in ms */
241 #define GRPC_ARG_MIN_RECONNECT_BACKOFF_MS "grpc.min_reconnect_backoff_ms"
242 /** The maximum time between subsequent connection attempts, in ms */
243 #define GRPC_ARG_MAX_RECONNECT_BACKOFF_MS "grpc.max_reconnect_backoff_ms"
244 /** The time between the first and second connection attempts, in ms */
245 #define GRPC_ARG_INITIAL_RECONNECT_BACKOFF_MS \
246   "grpc.initial_reconnect_backoff_ms"
247 /** Minimum amount of time between DNS resolutions, in ms */
248 #define GRPC_ARG_DNS_MIN_TIME_BETWEEN_RESOLUTIONS_MS \
249   "grpc.dns_min_time_between_resolutions_ms"
250 /** The timeout used on servers for finishing handshaking on an incoming
251     connection.  Defaults to 120 seconds. */
252 #define GRPC_ARG_SERVER_HANDSHAKE_TIMEOUT_MS "grpc.server_handshake_timeout_ms"
253 /** This *should* be used for testing only.
254     The caller of the secure_channel_create functions may override the target
255     name used for SSL host name checking using this channel argument which is of
256     type \a GRPC_ARG_STRING. If this argument is not specified, the name used
257     for SSL host name checking will be the target parameter (assuming that the
258     secure channel is an SSL channel). If this parameter is specified and the
259     underlying is not an SSL channel, it will just be ignored. */
260 #define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override"
261 /** If non-zero, a pointer to a session cache (a pointer of type
262     grpc_ssl_session_cache*). (use grpc_ssl_session_cache_arg_vtable() to fetch
263     an appropriate pointer arg vtable) */
264 #define GRPC_SSL_SESSION_CACHE_ARG "grpc.ssl_session_cache"
265 /** Maximum metadata size, in bytes. Note this limit applies to the max sum of
266     all metadata key-value entries in a batch of headers. */
267 #define GRPC_ARG_MAX_METADATA_SIZE "grpc.max_metadata_size"
268 /** If non-zero, allow the use of SO_REUSEPORT if it's available (default 1) */
269 #define GRPC_ARG_ALLOW_REUSEPORT "grpc.so_reuseport"
270 /** If non-zero, a pointer to a buffer pool (a pointer of type
271  * grpc_resource_quota*). (use grpc_resource_quota_arg_vtable() to fetch an
272  * appropriate pointer arg vtable) */
273 #define GRPC_ARG_RESOURCE_QUOTA "grpc.resource_quota"
274 /** If non-zero, expand wildcard addresses to a list of local addresses. */
275 #define GRPC_ARG_EXPAND_WILDCARD_ADDRS "grpc.expand_wildcard_addrs"
276 /** Service config data in JSON form.
277     This value will be ignored if the name resolver returns a service config. */
278 #define GRPC_ARG_SERVICE_CONFIG "grpc.service_config"
279 /** Disable looking up the service config via the name resolver. */
280 #define GRPC_ARG_SERVICE_CONFIG_DISABLE_RESOLUTION \
281   "grpc.service_config_disable_resolution"
282 /** LB policy name. */
283 #define GRPC_ARG_LB_POLICY_NAME "grpc.lb_policy_name"
284 /** The grpc_socket_mutator instance that set the socket options. A pointer. */
285 #define GRPC_ARG_SOCKET_MUTATOR "grpc.socket_mutator"
286 /** The grpc_socket_factory instance to create and bind sockets. A pointer. */
287 #define GRPC_ARG_SOCKET_FACTORY "grpc.socket_factory"
288 /** The maximum number of trace events to keep in the tracer for each channel or
289  * subchannel. The default is 10. If set to 0, channel tracing is disabled. */
290 #define GRPC_ARG_MAX_CHANNEL_TRACE_EVENTS_PER_NODE \
291   "grpc.max_channel_trace_events_per_node"
292 /** If non-zero, gRPC library will track stats and information at at per channel
293  * level. Disabling channelz naturally disables channel tracing. The default
294  * is for channelz to be disabled. */
295 #define GRPC_ARG_ENABLE_CHANNELZ "grpc.enable_channelz"
296 /** If non-zero, Cronet transport will coalesce packets to fewer frames
297  * when possible. */
298 #define GRPC_ARG_USE_CRONET_PACKET_COALESCING \
299   "grpc.use_cronet_packet_coalescing"
300 /** Channel arg (integer) setting how large a slice to try and read from the
301    wire each time recvmsg (or equivalent) is called **/
302 #define GRPC_ARG_TCP_READ_CHUNK_SIZE "grpc.experimental.tcp_read_chunk_size"
303 /** Note this is not a "channel arg" key. This is the default slice size to use
304  * when trying to read from the wire if the GRPC_ARG_TCP_READ_CHUNK_SIZE
305  * channel arg is unspecified. */
306 #define GRPC_TCP_DEFAULT_READ_SLICE_SIZE 8192
307 #define GRPC_ARG_TCP_MIN_READ_CHUNK_SIZE \
308   "grpc.experimental.tcp_min_read_chunk_size"
309 #define GRPC_ARG_TCP_MAX_READ_CHUNK_SIZE \
310   "grpc.experimental.tcp_max_read_chunk_size"
311 /* Timeout in milliseconds to use for calls to the grpclb load balancer.
312    If 0 or unset, the balancer calls will have no deadline. */
313 #define GRPC_ARG_GRPCLB_CALL_TIMEOUT_MS "grpc.grpclb_call_timeout_ms"
314 /* Timeout in milliseconds to wait for the serverlist from the grpclb load
315    balancer before using fallback backend addresses from the resolver.
316    If 0, fallback will never be used. Default value is 10000. */
317 #define GRPC_ARG_GRPCLB_FALLBACK_TIMEOUT_MS "grpc.grpclb_fallback_timeout_ms"
318 /** If non-zero, grpc server's cronet compression workaround will be enabled */
319 #define GRPC_ARG_WORKAROUND_CRONET_COMPRESSION \
320   "grpc.workaround.cronet_compression"
321 /** String defining the optimization target for a channel.
322     Can be: "latency"    - attempt to minimize latency at the cost of throughput
323             "blend"      - try to balance latency and throughput
324             "throughput" - attempt to maximize throughput at the expense of
325                            latency
326     Defaults to "blend". In the current implementation "blend" is equivalent to
327     "latency". */
328 #define GRPC_ARG_OPTIMIZATION_TARGET "grpc.optimization_target"
329 /** If set to zero, disables retry behavior. Otherwise, transparent retries
330     are enabled for all RPCs, and configurable retries are enabled when they
331     are configured via the service config. For details, see:
332       https://github.com/grpc/proposal/blob/master/A6-client-retries.md
333  */
334 #define GRPC_ARG_ENABLE_RETRIES "grpc.enable_retries"
335 /** Per-RPC retry buffer size, in bytes. Default is 256 KiB. */
336 #define GRPC_ARG_PER_RPC_RETRY_BUFFER_SIZE "grpc.per_rpc_retry_buffer_size"
337 /** Channel arg that carries the bridged objective c object for custom metrics
338  * logging filter. */
339 #define GRPC_ARG_MOBILE_LOG_CONTEXT "grpc.mobile_log_context"
340 /** If non-zero, client authority filter is disabled for the channel */
341 #define GRPC_ARG_DISABLE_CLIENT_AUTHORITY_FILTER \
342   "grpc.disable_client_authority_filter"
343 /** If set to zero, disables use of http proxies. Enabled by default. */
344 #define GRPC_ARG_ENABLE_HTTP_PROXY "grpc.enable_http_proxy"
345 /** If set to non zero, surfaces the user agent string to the server. User
346     agent is surfaced by default. */
347 #define GRPC_ARG_SURFACE_USER_AGENT "grpc.surface_user_agent"
348 /** \} */
349 
350 /** Result of a grpc call. If the caller satisfies the prerequisites of a
351     particular operation, the grpc_call_error returned will be GRPC_CALL_OK.
352     Receiving any other value listed here is an indication of a bug in the
353     caller. */
354 typedef enum grpc_call_error {
355   /** everything went ok */
356   GRPC_CALL_OK = 0,
357   /** something failed, we don't know what */
358   GRPC_CALL_ERROR,
359   /** this method is not available on the server */
360   GRPC_CALL_ERROR_NOT_ON_SERVER,
361   /** this method is not available on the client */
362   GRPC_CALL_ERROR_NOT_ON_CLIENT,
363   /** this method must be called before server_accept */
364   GRPC_CALL_ERROR_ALREADY_ACCEPTED,
365   /** this method must be called before invoke */
366   GRPC_CALL_ERROR_ALREADY_INVOKED,
367   /** this method must be called after invoke */
368   GRPC_CALL_ERROR_NOT_INVOKED,
369   /** this call is already finished
370       (writes_done or write_status has already been called) */
371   GRPC_CALL_ERROR_ALREADY_FINISHED,
372   /** there is already an outstanding read/write operation on the call */
373   GRPC_CALL_ERROR_TOO_MANY_OPERATIONS,
374   /** the flags value was illegal for this call */
375   GRPC_CALL_ERROR_INVALID_FLAGS,
376   /** invalid metadata was passed to this call */
377   GRPC_CALL_ERROR_INVALID_METADATA,
378   /** invalid message was passed to this call */
379   GRPC_CALL_ERROR_INVALID_MESSAGE,
380   /** completion queue for notification has not been registered
381    * with the server */
382   GRPC_CALL_ERROR_NOT_SERVER_COMPLETION_QUEUE,
383   /** this batch of operations leads to more operations than allowed */
384   GRPC_CALL_ERROR_BATCH_TOO_BIG,
385   /** payload type requested is not the type registered */
386   GRPC_CALL_ERROR_PAYLOAD_TYPE_MISMATCH,
387   /** completion queue has been shutdown */
388   GRPC_CALL_ERROR_COMPLETION_QUEUE_SHUTDOWN
389 } grpc_call_error;
390 
391 /** Default send/receive message size limits in bytes. -1 for unlimited. */
392 /** TODO(roth) Make this match the default receive limit after next release */
393 #define GRPC_DEFAULT_MAX_SEND_MESSAGE_LENGTH -1
394 #define GRPC_DEFAULT_MAX_RECV_MESSAGE_LENGTH (4 * 1024 * 1024)
395 
396 /** Write Flags: */
397 /** Hint that the write may be buffered and need not go out on the wire
398     immediately. GRPC is free to buffer the message until the next non-buffered
399     write, or until writes_done, but it need not buffer completely or at all. */
400 #define GRPC_WRITE_BUFFER_HINT (0x00000001u)
401 /** Force compression to be disabled for a particular write
402     (start_write/add_metadata). Illegal on invoke/accept. */
403 #define GRPC_WRITE_NO_COMPRESS (0x00000002u)
404 /** Force this message to be written to the socket before completing it */
405 #define GRPC_WRITE_THROUGH (0x00000004u)
406 /** Mask of all valid flags. */
407 #define GRPC_WRITE_USED_MASK \
408   (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS | GRPC_WRITE_THROUGH)
409 
410 /** Initial metadata flags */
411 /** Signal that the call is idempotent */
412 #define GRPC_INITIAL_METADATA_IDEMPOTENT_REQUEST (0x00000010u)
413 /** Signal that the call should not return UNAVAILABLE before it has started */
414 #define GRPC_INITIAL_METADATA_WAIT_FOR_READY (0x00000020u)
415 /** Signal that the call is cacheable. GRPC is free to use GET verb */
416 #define GRPC_INITIAL_METADATA_CACHEABLE_REQUEST (0x00000040u)
417 /** Signal that GRPC_INITIAL_METADATA_WAIT_FOR_READY was explicitly set
418     by the calling application. */
419 #define GRPC_INITIAL_METADATA_WAIT_FOR_READY_EXPLICITLY_SET (0x00000080u)
420 /** Signal that the initial metadata should be corked */
421 #define GRPC_INITIAL_METADATA_CORKED (0x00000100u)
422 
423 /** Mask of all valid flags */
424 #define GRPC_INITIAL_METADATA_USED_MASK                  \
425   (GRPC_INITIAL_METADATA_IDEMPOTENT_REQUEST |            \
426    GRPC_INITIAL_METADATA_WAIT_FOR_READY |                \
427    GRPC_INITIAL_METADATA_CACHEABLE_REQUEST |             \
428    GRPC_INITIAL_METADATA_WAIT_FOR_READY_EXPLICITLY_SET | \
429    GRPC_INITIAL_METADATA_CORKED | GRPC_WRITE_THROUGH)
430 
431 /** A single metadata element */
432 typedef struct grpc_metadata {
433   /** the key, value values are expected to line up with grpc_mdelem: if
434      changing them, update metadata.h at the same time. */
435   grpc_slice key;
436   grpc_slice value;
437 
438   uint32_t flags;
439 
440   /** The following fields are reserved for grpc internal use.
441       There is no need to initialize them, and they will be set to garbage
442       during calls to grpc. */
443   struct /* internal */ {
444     void* obfuscated[4];
445   } internal_data;
446 } grpc_metadata;
447 
448 /** The type of completion (for grpc_event) */
449 typedef enum grpc_completion_type {
450   /** Shutting down */
451   GRPC_QUEUE_SHUTDOWN,
452   /** No event before timeout */
453   GRPC_QUEUE_TIMEOUT,
454   /** Operation completion */
455   GRPC_OP_COMPLETE
456 } grpc_completion_type;
457 
458 /** The result of an operation.
459 
460     Returned by a completion queue when the operation started with tag. */
461 typedef struct grpc_event {
462   /** The type of the completion. */
463   grpc_completion_type type;
464   /** If the grpc_completion_type is GRPC_OP_COMPLETE, this field indicates
465       whether the operation was successful or not; 0 in case of failure and
466       non-zero in case of success.
467       If grpc_completion_type is GRPC_QUEUE_SHUTDOWN or GRPC_QUEUE_TIMEOUT, this
468       field is guaranteed to be 0 */
469   int success;
470   /** The tag passed to grpc_call_start_batch etc to start this operation.
471       Only GRPC_OP_COMPLETE has a tag. */
472   void* tag;
473 } grpc_event;
474 
475 typedef struct {
476   size_t count;
477   size_t capacity;
478   grpc_metadata* metadata;
479 } grpc_metadata_array;
480 
481 typedef struct {
482   grpc_slice method;
483   grpc_slice host;
484   gpr_timespec deadline;
485   uint32_t flags;
486   void* reserved;
487 } grpc_call_details;
488 
489 typedef enum {
490   /** Send initial metadata: one and only one instance MUST be sent for each
491       call, unless the call was cancelled - in which case this can be skipped.
492       This op completes after all bytes of metadata have been accepted by
493       outgoing flow control. */
494   GRPC_OP_SEND_INITIAL_METADATA = 0,
495   /** Send a message: 0 or more of these operations can occur for each call.
496       This op completes after all bytes for the message have been accepted by
497       outgoing flow control. */
498   GRPC_OP_SEND_MESSAGE,
499   /** Send a close from the client: one and only one instance MUST be sent from
500       the client, unless the call was cancelled - in which case this can be
501       skipped. This op completes after all bytes for the call
502       (including the close) have passed outgoing flow control. */
503   GRPC_OP_SEND_CLOSE_FROM_CLIENT,
504   /** Send status from the server: one and only one instance MUST be sent from
505       the server unless the call was cancelled - in which case this can be
506       skipped. This op completes after all bytes for the call
507       (including the status) have passed outgoing flow control. */
508   GRPC_OP_SEND_STATUS_FROM_SERVER,
509   /** Receive initial metadata: one and only one MUST be made on the client,
510       must not be made on the server.
511       This op completes after all initial metadata has been read from the
512       peer. */
513   GRPC_OP_RECV_INITIAL_METADATA,
514   /** Receive a message: 0 or more of these operations can occur for each call.
515       This op completes after all bytes of the received message have been
516       read, or after a half-close has been received on this call. */
517   GRPC_OP_RECV_MESSAGE,
518   /** Receive status on the client: one and only one must be made on the client.
519       This operation always succeeds, meaning ops paired with this operation
520       will also appear to succeed, even though they may not have. In that case
521       the status will indicate some failure.
522       This op completes after all activity on the call has completed. */
523   GRPC_OP_RECV_STATUS_ON_CLIENT,
524   /** Receive close on the server: one and only one must be made on the
525       server. This op completes after the close has been received by the
526       server. This operation always succeeds, meaning ops paired with
527       this operation will also appear to succeed, even though they may not
528       have. */
529   GRPC_OP_RECV_CLOSE_ON_SERVER
530 } grpc_op_type;
531 
532 struct grpc_byte_buffer;
533 
534 /** Operation data: one field for each op type (except SEND_CLOSE_FROM_CLIENT
535    which has no arguments) */
536 typedef struct grpc_op {
537   /** Operation type, as defined by grpc_op_type */
538   grpc_op_type op;
539   /** Write flags bitset for grpc_begin_messages */
540   uint32_t flags;
541   /** Reserved for future usage */
542   void* reserved;
543   union grpc_op_data {
544     /** Reserved for future usage */
545     struct /* internal */ {
546       void* reserved[8];
547     } reserved;
548     struct grpc_op_send_initial_metadata {
549       size_t count;
550       grpc_metadata* metadata;
551       /** If \a is_set, \a compression_level will be used for the call.
552        * Otherwise, \a compression_level won't be considered */
553       struct grpc_op_send_initial_metadata_maybe_compression_level {
554         uint8_t is_set;
555         grpc_compression_level level;
556       } maybe_compression_level;
557     } send_initial_metadata;
558     struct grpc_op_send_message {
559       /** This op takes ownership of the slices in send_message.  After
560        * a call completes, the contents of send_message are not guaranteed
561        * and likely empty.  The original owner should still call
562        * grpc_byte_buffer_destroy() on this object however.
563        */
564       struct grpc_byte_buffer* send_message;
565     } send_message;
566     struct grpc_op_send_status_from_server {
567       size_t trailing_metadata_count;
568       grpc_metadata* trailing_metadata;
569       grpc_status_code status;
570       /** optional: set to NULL if no details need sending, non-NULL if they do
571        * pointer will not be retained past the start_batch call
572        */
573       grpc_slice* status_details;
574     } send_status_from_server;
575     /** ownership of the array is with the caller, but ownership of the elements
576         stays with the call object (ie key, value members are owned by the call
577         object, recv_initial_metadata->array is owned by the caller).
578         After the operation completes, call grpc_metadata_array_destroy on this
579         value, or reuse it in a future op. */
580     struct grpc_op_recv_initial_metadata {
581       grpc_metadata_array* recv_initial_metadata;
582     } recv_initial_metadata;
583     /** ownership of the byte buffer is moved to the caller; the caller must
584         call grpc_byte_buffer_destroy on this value, or reuse it in a future op.
585         The returned byte buffer will be NULL if trailing metadata was
586         received instead of a message.
587        */
588     struct grpc_op_recv_message {
589       struct grpc_byte_buffer** recv_message;
590     } recv_message;
591     struct grpc_op_recv_status_on_client {
592       /** ownership of the array is with the caller, but ownership of the
593           elements stays with the call object (ie key, value members are owned
594           by the call object, trailing_metadata->array is owned by the caller).
595           After the operation completes, call grpc_metadata_array_destroy on
596           this value, or reuse it in a future op. */
597       grpc_metadata_array* trailing_metadata;
598       grpc_status_code* status;
599       grpc_slice* status_details;
600       /** If this is not nullptr, it will be populated with the full fidelity
601        * error string for debugging purposes. The application is responsible
602        * for freeing the data by using gpr_free(). */
603       const char** error_string;
604     } recv_status_on_client;
605     struct grpc_op_recv_close_on_server {
606       /** out argument, set to 1 if the call failed in any way (seen as a
607           cancellation on the server), or 0 if the call succeeded */
608       int* cancelled;
609     } recv_close_on_server;
610   } data;
611 } grpc_op;
612 
613 /** Information requested from the channel. */
614 typedef struct {
615   /** If non-NULL, will be set to point to a string indicating the LB
616    * policy name.  Caller takes ownership. */
617   char** lb_policy_name;
618   /** If non-NULL, will be set to point to a string containing the
619    * service config used by the channel in JSON form. */
620   char** service_config_json;
621 } grpc_channel_info;
622 
623 typedef struct grpc_resource_quota grpc_resource_quota;
624 
625 /** Completion queues internally MAY maintain a set of file descriptors in a
626     structure called 'pollset'. This enum specifies if a completion queue has an
627     associated pollset and any restrictions on the type of file descriptors that
628     can be present in the pollset.
629 
630     I/O progress can only be made when grpc_completion_queue_next() or
631     grpc_completion_queue_pluck() are called on the completion queue (unless the
632     grpc_cq_polling_type is GRPC_CQ_NON_POLLING) and hence it is very important
633     to actively call these APIs */
634 typedef enum {
635   /** The completion queue will have an associated pollset and there is no
636       restriction on the type of file descriptors the pollset may contain */
637   GRPC_CQ_DEFAULT_POLLING,
638 
639   /** Similar to GRPC_CQ_DEFAULT_POLLING except that the completion queues will
640       not contain any 'listening file descriptors' (i.e file descriptors used to
641       listen to incoming channels) */
642   GRPC_CQ_NON_LISTENING,
643 
644   /** The completion queue will not have an associated pollset. Note that
645       grpc_completion_queue_next() or grpc_completion_queue_pluck() MUST still
646       be called to pop events from the completion queue; it is not required to
647       call them actively to make I/O progress */
648   GRPC_CQ_NON_POLLING
649 } grpc_cq_polling_type;
650 
651 /** Specifies the type of APIs to use to pop events from the completion queue */
652 typedef enum {
653   /** Events are popped out by calling grpc_completion_queue_next() API ONLY */
654   GRPC_CQ_NEXT,
655 
656   /** Events are popped out by calling grpc_completion_queue_pluck() API ONLY*/
657   GRPC_CQ_PLUCK,
658 
659   /** EXPERIMENTAL: Events trigger a callback specified as the tag */
660   GRPC_CQ_CALLBACK
661 } grpc_cq_completion_type;
662 
663 /** EXPERIMENTAL: Specifies an interface class to be used as a tag
664     for callback-based completion queues. This can be used directly,
665     as the first element of a struct in C, or as a base class in C++.
666     Its "run" value should be assigned to some non-member function, such as
667     a static method. */
668 typedef struct grpc_experimental_completion_queue_functor {
669   /** The run member specifies a function that will be called when this
670       tag is extracted from the completion queue. Its arguments will be a
671       pointer to this functor and a boolean that indicates whether the
672       operation succeeded (non-zero) or failed (zero) */
673   void (*functor_run)(struct grpc_experimental_completion_queue_functor*, int);
674 } grpc_experimental_completion_queue_functor;
675 
676 /* The upgrade to version 2 is currently experimental. */
677 
678 #define GRPC_CQ_CURRENT_VERSION 2
679 #define GRPC_CQ_VERSION_MINIMUM_FOR_CALLBACKABLE 2
680 typedef struct grpc_completion_queue_attributes {
681   /** The version number of this structure. More fields might be added to this
682      structure in future. */
683   int version; /** Set to GRPC_CQ_CURRENT_VERSION */
684 
685   grpc_cq_completion_type cq_completion_type;
686 
687   grpc_cq_polling_type cq_polling_type;
688 
689   /* END OF VERSION 1 CQ ATTRIBUTES */
690 
691   /* EXPERIMENTAL: START OF VERSION 2 CQ ATTRIBUTES */
692   /** When creating a callbackable CQ, pass in a functor to get invoked when
693    * shutdown is complete */
694   grpc_experimental_completion_queue_functor* cq_shutdown_cb;
695 
696   /* END OF VERSION 2 CQ ATTRIBUTES */
697 } grpc_completion_queue_attributes;
698 
699 /** The completion queue factory structure is opaque to the callers of grpc */
700 typedef struct grpc_completion_queue_factory grpc_completion_queue_factory;
701 
702 #ifdef __cplusplus
703 }
704 #endif
705 
706 #endif /* GRPC_IMPL_CODEGEN_GRPC_TYPES_H */
707