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// IWYU pragma: private, include <grpc/grpc.h>
23// IWYU pragma: friend "src/.*"
24
25#include <grpc/impl/codegen/port_platform.h>
26
27#include <stddef.h>
28
29#include <grpc/impl/codegen/compression_types.h>
30#include <grpc/impl/codegen/gpr_types.h>
31#include <grpc/impl/codegen/slice.h>
32#include <grpc/impl/codegen/status.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38typedef enum {
39 GRPC_BB_RAW
40 /** Future types may include GRPC_BB_PROTOBUF, etc. */
41} grpc_byte_buffer_type;
42
43typedef struct grpc_byte_buffer {
44 void* reserved;
45 grpc_byte_buffer_type type;
46 union grpc_byte_buffer_data {
47 struct /* internal */ {
48 void* reserved[8];
49 } reserved;
50 struct grpc_compressed_buffer {
51 grpc_compression_algorithm compression;
52 grpc_slice_buffer slice_buffer;
53 } raw;
54 } data;
55} grpc_byte_buffer;
56
57/** Completion Queues enable notification of the completion of
58 * asynchronous actions. */
59typedef struct grpc_completion_queue grpc_completion_queue;
60
61/** The Channel interface allows creation of Call objects. */
62typedef struct grpc_channel grpc_channel;
63
64/** A server listens to some port and responds to request calls */
65typedef 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. */
70typedef struct grpc_call grpc_call;
71
72/** The Socket Mutator interface allows changes on socket options */
73typedef struct grpc_socket_mutator grpc_socket_mutator;
74
75/** The Socket Factory interface creates and binds sockets */
76typedef struct grpc_socket_factory grpc_socket_factory;
77
78/** Type specifier for grpc_arg */
79typedef enum {
80 GRPC_ARG_STRING,
81 GRPC_ARG_INTEGER,
82 GRPC_ARG_POINTER
83} grpc_arg_type;
84
85typedef 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. */
103typedef 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. */
132typedef 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, after which the
161 * server will close the connection. Int valued, milliseconds. INT_MAX means
162 * unlimited. */
163#define GRPC_ARG_MAX_CONNECTION_IDLE_MS "grpc.max_connection_idle_ms"
164/** Maximum time that a channel may exist. Int valued, milliseconds.
165 * INT_MAX means unlimited. */
166#define GRPC_ARG_MAX_CONNECTION_AGE_MS "grpc.max_connection_age_ms"
167/** Grace period after the channel reaches its max age. Int valued,
168 milliseconds. INT_MAX means unlimited. */
169#define GRPC_ARG_MAX_CONNECTION_AGE_GRACE_MS "grpc.max_connection_age_grace_ms"
170/** Timeout after the last RPC finishes on the client channel at which the
171 * channel goes back into IDLE state. Int valued, milliseconds. INT_MAX means
172 * unlimited. The default value is 30 minutes and the min value is 1 second. */
173#define GRPC_ARG_CLIENT_IDLE_TIMEOUT_MS "grpc.client_idle_timeout_ms"
174/** Enable/disable support for per-message compression. Defaults to 1, unless
175 GRPC_ARG_MINIMAL_STACK is enabled, in which case it defaults to 0. */
176#define GRPC_ARG_ENABLE_PER_MESSAGE_COMPRESSION "grpc.per_message_compression"
177/** Experimental Arg. Enable/disable support for per-message decompression.
178 Defaults to 1. If disabled, decompression will not be performed and the
179 application will see the compressed message in the byte buffer. */
180#define GRPC_ARG_ENABLE_PER_MESSAGE_DECOMPRESSION \
181 "grpc.per_message_decompression"
182/** Enable/disable support for deadline checking. Defaults to 1, unless
183 GRPC_ARG_MINIMAL_STACK is enabled, in which case it defaults to 0 */
184#define GRPC_ARG_ENABLE_DEADLINE_CHECKS "grpc.enable_deadline_checking"
185/** Initial stream ID for http2 transports. Int valued. */
186#define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \
187 "grpc.http2.initial_sequence_number"
188/** Amount to read ahead on individual streams. Defaults to 64kb, larger
189 values can help throughput on high-latency connections.
190 NOTE: at some point we'd like to auto-tune this, and this parameter
191 will become a no-op. Int valued, bytes. */
192#define GRPC_ARG_HTTP2_STREAM_LOOKAHEAD_BYTES "grpc.http2.lookahead_bytes"
193/** How much memory to use for hpack decoding. Int valued, bytes. */
194#define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_DECODER \
195 "grpc.http2.hpack_table_size.decoder"
196/** How much memory to use for hpack encoding. Int valued, bytes. */
197#define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_ENCODER \
198 "grpc.http2.hpack_table_size.encoder"
199/** How big a frame are we willing to receive via HTTP2.
200 Min 16384, max 16777215. Larger values give lower CPU usage for large
201 messages, but more head of line blocking for small messages. */
202#define GRPC_ARG_HTTP2_MAX_FRAME_SIZE "grpc.http2.max_frame_size"
203/** Should BDP probing be performed? */
204#define GRPC_ARG_HTTP2_BDP_PROBE "grpc.http2.bdp_probe"
205/** (DEPRECATED) Does not have any effect.
206 Earlier, this arg configured the minimum time between successive ping frames
207 without receiving any data/header frame, Int valued, milliseconds. This put
208 unnecessary constraints on the configuration of keepalive pings,
209 requiring users to set this channel arg along with
210 GRPC_ARG_KEEPALIVE_TIME_MS. This arg also limited the activity of the other
211 source of pings in gRPC Core - BDP pings, but BDP pings are only sent when
212 there is receive-side data activity, making this arg unuseful for BDP pings
213 too. */
214#define GRPC_ARG_HTTP2_MIN_SENT_PING_INTERVAL_WITHOUT_DATA_MS \
215 "grpc.http2.min_time_between_pings_ms"
216/** Minimum allowed time between a server receiving successive ping frames
217 without sending any data/header frame. Int valued, milliseconds
218 */
219#define GRPC_ARG_HTTP2_MIN_RECV_PING_INTERVAL_WITHOUT_DATA_MS \
220 "grpc.http2.min_ping_interval_without_data_ms"
221/** Channel arg to override the http2 :scheme header */
222#define GRPC_ARG_HTTP2_SCHEME "grpc.http2_scheme"
223/** How many pings can the client send before needing to send a
224 data/header frame? (0 indicates that an infinite number of
225 pings can be sent without sending a data frame or header frame) */
226#define GRPC_ARG_HTTP2_MAX_PINGS_WITHOUT_DATA \
227 "grpc.http2.max_pings_without_data"
228/** How many misbehaving pings the server can bear before sending goaway and
229 closing the transport? (0 indicates that the server can bear an infinite
230 number of misbehaving pings) */
231#define GRPC_ARG_HTTP2_MAX_PING_STRIKES "grpc.http2.max_ping_strikes"
232/** How much data are we willing to queue up per stream if
233 GRPC_WRITE_BUFFER_HINT is set? This is an upper bound */
234#define GRPC_ARG_HTTP2_WRITE_BUFFER_SIZE "grpc.http2.write_buffer_size"
235/** Should we allow receipt of true-binary data on http2 connections?
236 Defaults to on (1) */
237#define GRPC_ARG_HTTP2_ENABLE_TRUE_BINARY "grpc.http2.true_binary"
238/** After a duration of this time the client/server pings its peer to see if the
239 transport is still alive. Int valued, milliseconds. */
240#define GRPC_ARG_KEEPALIVE_TIME_MS "grpc.keepalive_time_ms"
241/** After waiting for a duration of this time, if the keepalive ping sender does
242 not receive the ping ack, it will close the transport. Int valued,
243 milliseconds. */
244#define GRPC_ARG_KEEPALIVE_TIMEOUT_MS "grpc.keepalive_timeout_ms"
245/** Is it permissible to send keepalive pings from the client without any
246 outstanding streams. Int valued, 0(false)/1(true). */
247#define GRPC_ARG_KEEPALIVE_PERMIT_WITHOUT_CALLS \
248 "grpc.keepalive_permit_without_calls"
249/** Default authority to pass if none specified on call construction. A string.
250 * */
251#define GRPC_ARG_DEFAULT_AUTHORITY "grpc.default_authority"
252/** Primary user agent: goes at the start of the user-agent metadata
253 sent on each request. A string. */
254#define GRPC_ARG_PRIMARY_USER_AGENT_STRING "grpc.primary_user_agent"
255/** Secondary user agent: goes at the end of the user-agent metadata
256 sent on each request. A string. */
257#define GRPC_ARG_SECONDARY_USER_AGENT_STRING "grpc.secondary_user_agent"
258/** The minimum time between subsequent connection attempts, in ms */
259#define GRPC_ARG_MIN_RECONNECT_BACKOFF_MS "grpc.min_reconnect_backoff_ms"
260/** The maximum time between subsequent connection attempts, in ms */
261#define GRPC_ARG_MAX_RECONNECT_BACKOFF_MS "grpc.max_reconnect_backoff_ms"
262/** The time between the first and second connection attempts, in ms */
263#define GRPC_ARG_INITIAL_RECONNECT_BACKOFF_MS \
264 "grpc.initial_reconnect_backoff_ms"
265/** Minimum amount of time between DNS resolutions, in ms */
266#define GRPC_ARG_DNS_MIN_TIME_BETWEEN_RESOLUTIONS_MS \
267 "grpc.dns_min_time_between_resolutions_ms"
268/** The timeout used on servers for finishing handshaking on an incoming
269 connection. Defaults to 120 seconds. */
270#define GRPC_ARG_SERVER_HANDSHAKE_TIMEOUT_MS "grpc.server_handshake_timeout_ms"
271/** This *should* be used for testing only.
272 The caller of the secure_channel_create functions may override the target
273 name used for SSL host name checking using this channel argument which is of
274 type \a GRPC_ARG_STRING. If this argument is not specified, the name used
275 for SSL host name checking will be the target parameter (assuming that the
276 secure channel is an SSL channel). If this parameter is specified and the
277 underlying is not an SSL channel, it will just be ignored. */
278#define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override"
279/** If non-zero, a pointer to a session cache (a pointer of type
280 grpc_ssl_session_cache*). (use grpc_ssl_session_cache_arg_vtable() to fetch
281 an appropriate pointer arg vtable) */
282#define GRPC_SSL_SESSION_CACHE_ARG "grpc.ssl_session_cache"
283/** If non-zero, it will determine the maximum frame size used by TSI's frame
284 * protector.
285 */
286#define GRPC_ARG_TSI_MAX_FRAME_SIZE "grpc.tsi.max_frame_size"
287/** Maximum metadata size, in bytes. Note this limit applies to the max sum of
288 all metadata key-value entries in a batch of headers. */
289#define GRPC_ARG_MAX_METADATA_SIZE "grpc.max_metadata_size"
290/** If non-zero, allow the use of SO_REUSEPORT if it's available (default 1) */
291#define GRPC_ARG_ALLOW_REUSEPORT "grpc.so_reuseport"
292/** If non-zero, a pointer to a buffer pool (a pointer of type
293 * grpc_resource_quota*). (use grpc_resource_quota_arg_vtable() to fetch an
294 * appropriate pointer arg vtable) */
295#define GRPC_ARG_RESOURCE_QUOTA "grpc.resource_quota"
296/** If non-zero, expand wildcard addresses to a list of local addresses. */
297#define GRPC_ARG_EXPAND_WILDCARD_ADDRS "grpc.expand_wildcard_addrs"
298/** Service config data in JSON form.
299 This value will be ignored if the name resolver returns a service config. */
300#define GRPC_ARG_SERVICE_CONFIG "grpc.service_config"
301/** Disable looking up the service config via the name resolver. */
302#define GRPC_ARG_SERVICE_CONFIG_DISABLE_RESOLUTION \
303 "grpc.service_config_disable_resolution"
304/** LB policy name. */
305#define GRPC_ARG_LB_POLICY_NAME "grpc.lb_policy_name"
306/** The grpc_socket_mutator instance that set the socket options. A pointer. */
307#define GRPC_ARG_SOCKET_MUTATOR "grpc.socket_mutator"
308/** The grpc_socket_factory instance to create and bind sockets. A pointer. */
309#define GRPC_ARG_SOCKET_FACTORY "grpc.socket_factory"
310/** The maximum amount of memory used by trace events per channel trace node.
311 * Once the maximum is reached, subsequent events will evict the oldest events
312 * from the buffer. The unit for this knob is bytes. Setting it to zero causes
313 * channel tracing to be disabled. */
314#define GRPC_ARG_MAX_CHANNEL_TRACE_EVENT_MEMORY_PER_NODE \
315 "grpc.max_channel_trace_event_memory_per_node"
316/** If non-zero, gRPC library will track stats and information at at per channel
317 * level. Disabling channelz naturally disables channel tracing. The default
318 * is for channelz to be enabled. */
319#define GRPC_ARG_ENABLE_CHANNELZ "grpc.enable_channelz"
320/** If non-zero, Cronet transport will coalesce packets to fewer frames
321 * when possible. */
322#define GRPC_ARG_USE_CRONET_PACKET_COALESCING \
323 "grpc.use_cronet_packet_coalescing"
324/** Channel arg (integer) setting how large a slice to try and read from the
325 wire each time recvmsg (or equivalent) is called **/
326#define GRPC_ARG_TCP_READ_CHUNK_SIZE "grpc.experimental.tcp_read_chunk_size"
327/** Note this is not a "channel arg" key. This is the default slice size to use
328 * when trying to read from the wire if the GRPC_ARG_TCP_READ_CHUNK_SIZE
329 * channel arg is unspecified. */
330#define GRPC_TCP_DEFAULT_READ_SLICE_SIZE 8192
331#define GRPC_ARG_TCP_MIN_READ_CHUNK_SIZE \
332 "grpc.experimental.tcp_min_read_chunk_size"
333#define GRPC_ARG_TCP_MAX_READ_CHUNK_SIZE \
334 "grpc.experimental.tcp_max_read_chunk_size"
335/* TCP TX Zerocopy enable state: zero is disabled, non-zero is enabled. By
336 default, it is disabled. */
337#define GRPC_ARG_TCP_TX_ZEROCOPY_ENABLED \
338 "grpc.experimental.tcp_tx_zerocopy_enabled"
339/* TCP TX Zerocopy send threshold: only zerocopy if >= this many bytes sent. By
340 default, this is set to 16KB. */
341#define GRPC_ARG_TCP_TX_ZEROCOPY_SEND_BYTES_THRESHOLD \
342 "grpc.experimental.tcp_tx_zerocopy_send_bytes_threshold"
343/* TCP TX Zerocopy max simultaneous sends: limit for maximum number of pending
344 calls to tcp_write() using zerocopy. A tcp_write() is considered pending
345 until the kernel performs the zerocopy-done callback for all sendmsg() calls
346 issued by the tcp_write(). By default, this is set to 4. */
347#define GRPC_ARG_TCP_TX_ZEROCOPY_MAX_SIMULT_SENDS \
348 "grpc.experimental.tcp_tx_zerocopy_max_simultaneous_sends"
349/* Timeout in milliseconds to use for calls to the grpclb load balancer.
350 If 0 or unset, the balancer calls will have no deadline. */
351#define GRPC_ARG_GRPCLB_CALL_TIMEOUT_MS "grpc.grpclb_call_timeout_ms"
352/* Specifies the xDS bootstrap config as a JSON string.
353 FOR TESTING PURPOSES ONLY -- DO NOT USE IN PRODUCTION.
354 This option allows controlling the bootstrap configuration on a
355 per-channel basis, which is useful in tests. However, this results
356 in having a separate xDS client instance per channel rather than
357 using the global instance, which is not the intended way to use xDS.
358 Currently, this will (a) add unnecessary load on the xDS server and
359 (b) break use of CSDS, and there may be additional side effects in
360 the future. */
361#define GRPC_ARG_TEST_ONLY_DO_NOT_USE_IN_PROD_XDS_BOOTSTRAP_CONFIG \
362 "grpc.TEST_ONLY_DO_NOT_USE_IN_PROD.xds_bootstrap_config"
363/* Timeout in milliseconds to wait for the serverlist from the grpclb load
364 balancer before using fallback backend addresses from the resolver.
365 If 0, enter fallback mode immediately. Default value is 10000. */
366#define GRPC_ARG_GRPCLB_FALLBACK_TIMEOUT_MS "grpc.grpclb_fallback_timeout_ms"
367/* Experimental Arg. Channel args to be used for the control-plane channel
368 * created to the grpclb load balancers. This is a pointer arg whose value is a
369 * grpc_channel_args object. If unset, most channel args from the parent channel
370 * will be propagated to the grpclb channel. */
371#define GRPC_ARG_EXPERIMENTAL_GRPCLB_CHANNEL_ARGS \
372 "grpc.experimental.grpclb_channel_args"
373/* Timeout in milliseconds to wait for the child of a specific priority to
374 complete its initial connection attempt before the priority LB policy fails
375 over to the next priority. Default value is 10 seconds. */
376#define GRPC_ARG_PRIORITY_FAILOVER_TIMEOUT_MS \
377 "grpc.priority_failover_timeout_ms"
378/** If non-zero, grpc server's cronet compression workaround will be enabled */
379#define GRPC_ARG_WORKAROUND_CRONET_COMPRESSION \
380 "grpc.workaround.cronet_compression"
381/** String defining the optimization target for a channel.
382 Can be: "latency" - attempt to minimize latency at the cost of throughput
383 "blend" - try to balance latency and throughput
384 "throughput" - attempt to maximize throughput at the expense of
385 latency
386 Defaults to "blend". In the current implementation "blend" is equivalent to
387 "latency". */
388#define GRPC_ARG_OPTIMIZATION_TARGET "grpc.optimization_target"
389/** Enables retry functionality. Defaults to true. When enabled,
390 transparent retries will be performed as appropriate, and configurable
391 retries are enabled when they are configured via the service config.
392 For details, see:
393 https://github.com/grpc/proposal/blob/master/A6-client-retries.md
394 NOTE: Hedging functionality is not yet implemented, so those
395 fields in the service config will currently be ignored. See
396 also the GRPC_ARG_EXPERIMENTAL_ENABLE_HEDGING arg below.
397 */
398#define GRPC_ARG_ENABLE_RETRIES "grpc.enable_retries"
399/** Enables hedging functionality, as described in:
400 https://github.com/grpc/proposal/blob/master/A6-client-retries.md
401 Default is currently false, since this functionality is not yet
402 fully implemented.
403 NOTE: This channel arg is experimental and will eventually be removed.
404 Once hedging functionality has been implemented and proves stable,
405 this arg will be removed, and the hedging functionality will
406 be enabled via the GRPC_ARG_ENABLE_RETRIES arg above. */
407#define GRPC_ARG_EXPERIMENTAL_ENABLE_HEDGING "grpc.experimental.enable_hedging"
408/** Per-RPC retry buffer size, in bytes. Default is 256 KiB. */
409#define GRPC_ARG_PER_RPC_RETRY_BUFFER_SIZE "grpc.per_rpc_retry_buffer_size"
410/** Channel arg that carries the bridged objective c object for custom metrics
411 * logging filter. */
412#define GRPC_ARG_MOBILE_LOG_CONTEXT "grpc.mobile_log_context"
413/** If non-zero, client authority filter is disabled for the channel */
414#define GRPC_ARG_DISABLE_CLIENT_AUTHORITY_FILTER \
415 "grpc.disable_client_authority_filter"
416/** If set to zero, disables use of http proxies. Enabled by default. */
417#define GRPC_ARG_ENABLE_HTTP_PROXY "grpc.enable_http_proxy"
418/** Channel arg to set http proxy per channel. If set, the channel arg
419 * value will be prefered over the envrionment variable settings. */
420#define GRPC_ARG_HTTP_PROXY "grpc.http_proxy"
421/** If set to non zero, surfaces the user agent string to the server. User
422 agent is surfaced by default. */
423#define GRPC_ARG_SURFACE_USER_AGENT "grpc.surface_user_agent"
424/** If set, inhibits health checking (which may be enabled via the
425 * service config.) */
426#define GRPC_ARG_INHIBIT_HEALTH_CHECKING "grpc.inhibit_health_checking"
427/** If enabled, the channel's DNS resolver queries for SRV records.
428 * This is useful only when using the "grpclb" load balancing policy,
429 * as described in the following documents:
430 * https://github.com/grpc/proposal/blob/master/A5-grpclb-in-dns.md
431 * https://github.com/grpc/proposal/blob/master/A24-lb-policy-config.md
432 * https://github.com/grpc/proposal/blob/master/A26-grpclb-selection.md
433 * Note that this works only with the "ares" DNS resolver; it isn't supported
434 * by the "native" DNS resolver. */
435#define GRPC_ARG_DNS_ENABLE_SRV_QUERIES "grpc.dns_enable_srv_queries"
436/** If set, determines an upper bound on the number of milliseconds that the
437 * c-ares based DNS resolver will wait on queries before cancelling them.
438 * The default value is 120,000. Setting this to "0" will disable the
439 * overall timeout entirely. Note that this doesn't include internal c-ares
440 * timeouts/backoff/retry logic, and so the actual DNS resolution may time out
441 * sooner than the value specified here. */
442#define GRPC_ARG_DNS_ARES_QUERY_TIMEOUT_MS "grpc.dns_ares_query_timeout"
443/** If set, uses a local subchannel pool within the channel. Otherwise, uses the
444 * global subchannel pool. */
445#define GRPC_ARG_USE_LOCAL_SUBCHANNEL_POOL "grpc.use_local_subchannel_pool"
446/** gRPC Objective-C channel pooling domain string. */
447#define GRPC_ARG_CHANNEL_POOL_DOMAIN "grpc.channel_pooling_domain"
448/** gRPC Objective-C channel pooling id. */
449#define GRPC_ARG_CHANNEL_ID "grpc.channel_id"
450/** Channel argument for grpc_authorization_policy_provider. If present, enables
451 gRPC authorization check. */
452#define GRPC_ARG_AUTHORIZATION_POLICY_PROVIDER \
453 "grpc.authorization_policy_provider"
454/** EXPERIMENTAL. Updates to a server's configuration from a config fetcher (for
455 * example, listener updates from xDS) cause all older connections to be
456 * gracefully shut down (i.e., "drained") with a grace period configured by this
457 * channel arg. Int valued, milliseconds. Defaults to 10 minutes.*/
458#define GRPC_ARG_SERVER_CONFIG_CHANGE_DRAIN_GRACE_TIME_MS \
459 "grpc.experimental.server_config_change_drain_grace_time_ms"
460/** \} */
461
462/** Result of a grpc call. If the caller satisfies the prerequisites of a
463 particular operation, the grpc_call_error returned will be GRPC_CALL_OK.
464 Receiving any other value listed here is an indication of a bug in the
465 caller. */
466typedef enum grpc_call_error {
467 /** everything went ok */
468 GRPC_CALL_OK = 0,
469 /** something failed, we don't know what */
470 GRPC_CALL_ERROR,
471 /** this method is not available on the server */
472 GRPC_CALL_ERROR_NOT_ON_SERVER,
473 /** this method is not available on the client */
474 GRPC_CALL_ERROR_NOT_ON_CLIENT,
475 /** this method must be called before server_accept */
476 GRPC_CALL_ERROR_ALREADY_ACCEPTED,
477 /** this method must be called before invoke */
478 GRPC_CALL_ERROR_ALREADY_INVOKED,
479 /** this method must be called after invoke */
480 GRPC_CALL_ERROR_NOT_INVOKED,
481 /** this call is already finished
482 (writes_done or write_status has already been called) */
483 GRPC_CALL_ERROR_ALREADY_FINISHED,
484 /** there is already an outstanding read/write operation on the call */
485 GRPC_CALL_ERROR_TOO_MANY_OPERATIONS,
486 /** the flags value was illegal for this call */
487 GRPC_CALL_ERROR_INVALID_FLAGS,
488 /** invalid metadata was passed to this call */
489 GRPC_CALL_ERROR_INVALID_METADATA,
490 /** invalid message was passed to this call */
491 GRPC_CALL_ERROR_INVALID_MESSAGE,
492 /** completion queue for notification has not been registered
493 * with the server */
494 GRPC_CALL_ERROR_NOT_SERVER_COMPLETION_QUEUE,
495 /** this batch of operations leads to more operations than allowed */
496 GRPC_CALL_ERROR_BATCH_TOO_BIG,
497 /** payload type requested is not the type registered */
498 GRPC_CALL_ERROR_PAYLOAD_TYPE_MISMATCH,
499 /** completion queue has been shutdown */
500 GRPC_CALL_ERROR_COMPLETION_QUEUE_SHUTDOWN
501} grpc_call_error;
502
503/** Default send/receive message size limits in bytes. -1 for unlimited. */
504/** TODO(roth) Make this match the default receive limit after next release */
505#define GRPC_DEFAULT_MAX_SEND_MESSAGE_LENGTH (-1)
506#define GRPC_DEFAULT_MAX_RECV_MESSAGE_LENGTH (4 * 1024 * 1024)
507
508/** Write Flags: */
509/** Hint that the write may be buffered and need not go out on the wire
510 immediately. GRPC is free to buffer the message until the next non-buffered
511 write, or until writes_done, but it need not buffer completely or at all. */
512#define GRPC_WRITE_BUFFER_HINT (0x00000001u)
513/** Force compression to be disabled for a particular write
514 (start_write/add_metadata). Illegal on invoke/accept. */
515#define GRPC_WRITE_NO_COMPRESS (0x00000002u)
516/** Force this message to be written to the socket before completing it */
517#define GRPC_WRITE_THROUGH (0x00000004u)
518/** Mask of all valid flags. */
519#define GRPC_WRITE_USED_MASK \
520 (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS | GRPC_WRITE_THROUGH)
521
522/** Initial metadata flags */
523/** These flags are to be passed to the `grpc_op::flags` field */
524/** Signal that the call should not return UNAVAILABLE before it has started */
525#define GRPC_INITIAL_METADATA_WAIT_FOR_READY (0x00000020u)
526/** Signal that GRPC_INITIAL_METADATA_WAIT_FOR_READY was explicitly set
527 by the calling application. */
528#define GRPC_INITIAL_METADATA_WAIT_FOR_READY_EXPLICITLY_SET (0x00000080u)
529
530/** Mask of all valid flags */
531#define GRPC_INITIAL_METADATA_USED_MASK \
532 (GRPC_INITIAL_METADATA_WAIT_FOR_READY_EXPLICITLY_SET | \
533 GRPC_INITIAL_METADATA_WAIT_FOR_READY | GRPC_WRITE_THROUGH)
534
535/** A single metadata element */
536typedef struct grpc_metadata {
537 /** the key, value values are expected to line up with grpc_mdelem: if
538 changing them, update metadata.h at the same time. */
539 grpc_slice key;
540 grpc_slice value;
541
542 /** The following fields are reserved for grpc internal use.
543 There is no need to initialize them, and they will be set to garbage
544 during calls to grpc. */
545 struct /* internal */ {
546 void* obfuscated[4];
547 } internal_data;
548} grpc_metadata;
549
550/** The type of completion (for grpc_event) */
551typedef enum grpc_completion_type {
552 /** Shutting down */
553 GRPC_QUEUE_SHUTDOWN,
554 /** No event before timeout */
555 GRPC_QUEUE_TIMEOUT,
556 /** Operation completion */
557 GRPC_OP_COMPLETE
558} grpc_completion_type;
559
560/** The result of an operation.
561
562 Returned by a completion queue when the operation started with tag. */
563typedef struct grpc_event {
564 /** The type of the completion. */
565 grpc_completion_type type;
566 /** If the grpc_completion_type is GRPC_OP_COMPLETE, this field indicates
567 whether the operation was successful or not; 0 in case of failure and
568 non-zero in case of success.
569 If grpc_completion_type is GRPC_QUEUE_SHUTDOWN or GRPC_QUEUE_TIMEOUT, this
570 field is guaranteed to be 0 */
571 int success;
572 /** The tag passed to grpc_call_start_batch etc to start this operation.
573 *Only* GRPC_OP_COMPLETE has a tag. For all other grpc_completion_type
574 values, tag is uninitialized. */
575 void* tag;
576} grpc_event;
577
578typedef struct {
579 size_t count;
580 size_t capacity;
581 grpc_metadata* metadata;
582} grpc_metadata_array;
583
584typedef struct {
585 grpc_slice method;
586 grpc_slice host;
587 gpr_timespec deadline;
588} grpc_call_details;
589
590typedef enum {
591 /** Send initial metadata: one and only one instance MUST be sent for each
592 call, unless the call was cancelled - in which case this can be skipped.
593 This op completes after all bytes of metadata have been accepted by
594 outgoing flow control. */
595 GRPC_OP_SEND_INITIAL_METADATA = 0,
596 /** Send a message: 0 or more of these operations can occur for each call.
597 This op completes after all bytes for the message have been accepted by
598 outgoing flow control. */
599 GRPC_OP_SEND_MESSAGE,
600 /** Send a close from the client: one and only one instance MUST be sent from
601 the client, unless the call was cancelled - in which case this can be
602 skipped. This op completes after all bytes for the call
603 (including the close) have passed outgoing flow control. */
604 GRPC_OP_SEND_CLOSE_FROM_CLIENT,
605 /** Send status from the server: one and only one instance MUST be sent from
606 the server unless the call was cancelled - in which case this can be
607 skipped. This op completes after all bytes for the call
608 (including the status) have passed outgoing flow control. */
609 GRPC_OP_SEND_STATUS_FROM_SERVER,
610 /** Receive initial metadata: one and only one MUST be made on the client,
611 must not be made on the server.
612 This op completes after all initial metadata has been read from the
613 peer. */
614 GRPC_OP_RECV_INITIAL_METADATA,
615 /** Receive a message: 0 or more of these operations can occur for each call.
616 This op completes after all bytes of the received message have been
617 read, or after a half-close has been received on this call. */
618 GRPC_OP_RECV_MESSAGE,
619 /** Receive status on the client: one and only one must be made on the client.
620 This operation always succeeds, meaning ops paired with this operation
621 will also appear to succeed, even though they may not have. In that case
622 the status will indicate some failure.
623 This op completes after all activity on the call has completed. */
624 GRPC_OP_RECV_STATUS_ON_CLIENT,
625 /** Receive close on the server: one and only one must be made on the
626 server. This op completes after the close has been received by the
627 server. This operation always succeeds, meaning ops paired with
628 this operation will also appear to succeed, even though they may not
629 have. */
630 GRPC_OP_RECV_CLOSE_ON_SERVER
631} grpc_op_type;
632
633struct grpc_byte_buffer;
634
635/** Operation data: one field for each op type (except SEND_CLOSE_FROM_CLIENT
636 which has no arguments) */
637typedef struct grpc_op {
638 /** Operation type, as defined by grpc_op_type */
639 grpc_op_type op;
640 /** Write flags bitset for grpc_begin_messages */
641 uint32_t flags;
642 /** Reserved for future usage */
643 void* reserved;
644 union grpc_op_data {
645 /** Reserved for future usage */
646 struct /* internal */ {
647 void* reserved[8];
648 } reserved;
649 struct grpc_op_send_initial_metadata {
650 size_t count;
651 grpc_metadata* metadata;
652 /** If \a is_set, \a compression_level will be used for the call.
653 * Otherwise, \a compression_level won't be considered */
654 struct grpc_op_send_initial_metadata_maybe_compression_level {
655 uint8_t is_set;
656 grpc_compression_level level;
657 } maybe_compression_level;
658 } send_initial_metadata;
659 struct grpc_op_send_message {
660 /** This op takes ownership of the slices in send_message. After
661 * a call completes, the contents of send_message are not guaranteed
662 * and likely empty. The original owner should still call
663 * grpc_byte_buffer_destroy() on this object however.
664 */
665 struct grpc_byte_buffer* send_message;
666 } send_message;
667 struct grpc_op_send_status_from_server {
668 size_t trailing_metadata_count;
669 grpc_metadata* trailing_metadata;
670 grpc_status_code status;
671 /** optional: set to NULL if no details need sending, non-NULL if they do
672 * pointer will not be retained past the start_batch call
673 */
674 grpc_slice* status_details;
675 } send_status_from_server;
676 /** ownership of the array is with the caller, but ownership of the elements
677 stays with the call object (ie key, value members are owned by the call
678 object, recv_initial_metadata->array is owned by the caller).
679 After the operation completes, call grpc_metadata_array_destroy on this
680 value, or reuse it in a future op. */
681 struct grpc_op_recv_initial_metadata {
682 grpc_metadata_array* recv_initial_metadata;
683 } recv_initial_metadata;
684 /** ownership of the byte buffer is moved to the caller; the caller must
685 call grpc_byte_buffer_destroy on this value, or reuse it in a future op.
686 The returned byte buffer will be NULL if trailing metadata was
687 received instead of a message.
688 */
689 struct grpc_op_recv_message {
690 struct grpc_byte_buffer** recv_message;
691 } recv_message;
692 struct grpc_op_recv_status_on_client {
693 /** ownership of the array is with the caller, but ownership of the
694 elements stays with the call object (ie key, value members are owned
695 by the call object, trailing_metadata->array is owned by the caller).
696 After the operation completes, call grpc_metadata_array_destroy on
697 this value, or reuse it in a future op. */
698 grpc_metadata_array* trailing_metadata;
699 grpc_status_code* status;
700 grpc_slice* status_details;
701 /** If this is not nullptr, it will be populated with the full fidelity
702 * error string for debugging purposes. The application is responsible
703 * for freeing the data by using gpr_free(). */
704 const char** error_string;
705 } recv_status_on_client;
706 struct grpc_op_recv_close_on_server {
707 /** out argument, set to 1 if the call failed at the server for
708 a reason other than a non-OK status (cancel, deadline
709 exceeded, network failure, etc.), 0 otherwise (RPC processing ran to
710 completion and was able to provide any status from the server) */
711 int* cancelled;
712 } recv_close_on_server;
713 } data;
714} grpc_op;
715
716/** Information requested from the channel. */
717typedef struct {
718 /** If non-NULL, will be set to point to a string indicating the LB
719 * policy name. Caller takes ownership. */
720 char** lb_policy_name;
721 /** If non-NULL, will be set to point to a string containing the
722 * service config used by the channel in JSON form. */
723 char** service_config_json;
724} grpc_channel_info;
725
726typedef struct grpc_resource_quota grpc_resource_quota;
727
728/** Completion queues internally MAY maintain a set of file descriptors in a
729 structure called 'pollset'. This enum specifies if a completion queue has an
730 associated pollset and any restrictions on the type of file descriptors that
731 can be present in the pollset.
732
733 I/O progress can only be made when grpc_completion_queue_next() or
734 grpc_completion_queue_pluck() are called on the completion queue (unless the
735 grpc_cq_polling_type is GRPC_CQ_NON_POLLING) and hence it is very important
736 to actively call these APIs */
737typedef enum {
738 /** The completion queue will have an associated pollset and there is no
739 restriction on the type of file descriptors the pollset may contain */
740 GRPC_CQ_DEFAULT_POLLING,
741
742 /** Similar to GRPC_CQ_DEFAULT_POLLING except that the completion queues will
743 not contain any 'listening file descriptors' (i.e file descriptors used to
744 listen to incoming channels) */
745 GRPC_CQ_NON_LISTENING,
746
747 /** The completion queue will not have an associated pollset. Note that
748 grpc_completion_queue_next() or grpc_completion_queue_pluck() MUST still
749 be called to pop events from the completion queue; it is not required to
750 call them actively to make I/O progress */
751 GRPC_CQ_NON_POLLING
752} grpc_cq_polling_type;
753
754/** Specifies the type of APIs to use to pop events from the completion queue */
755typedef enum {
756 /** Events are popped out by calling grpc_completion_queue_next() API ONLY */
757 GRPC_CQ_NEXT,
758
759 /** Events are popped out by calling grpc_completion_queue_pluck() API ONLY*/
760 GRPC_CQ_PLUCK,
761
762 /** Events trigger a callback specified as the tag */
763 GRPC_CQ_CALLBACK
764} grpc_cq_completion_type;
765
766/** Specifies an interface class to be used as a tag for callback-based
767 * completion queues. This can be used directly, as the first element of a
768 * struct in C, or as a base class in C++. Its "run" value should be assigned to
769 * some non-member function, such as a static method. */
770typedef struct grpc_completion_queue_functor {
771 /** The run member specifies a function that will be called when this
772 tag is extracted from the completion queue. Its arguments will be a
773 pointer to this functor and a boolean that indicates whether the
774 operation succeeded (non-zero) or failed (zero) */
775 void (*functor_run)(struct grpc_completion_queue_functor*, int);
776
777 /** The inlineable member specifies whether this functor can be run inline.
778 This should only be used for trivial internally-defined functors. */
779 int inlineable;
780
781 /** The following fields are not API. They are meant for internal use. */
782 int internal_success;
783 struct grpc_completion_queue_functor* internal_next;
784} grpc_completion_queue_functor;
785
786#define GRPC_CQ_CURRENT_VERSION 2
787#define GRPC_CQ_VERSION_MINIMUM_FOR_CALLBACKABLE 2
788typedef struct grpc_completion_queue_attributes {
789 /** The version number of this structure. More fields might be added to this
790 structure in future. */
791 int version; /** Set to GRPC_CQ_CURRENT_VERSION */
792
793 grpc_cq_completion_type cq_completion_type;
794
795 grpc_cq_polling_type cq_polling_type;
796
797 /* END OF VERSION 1 CQ ATTRIBUTES */
798
799 /* START OF VERSION 2 CQ ATTRIBUTES */
800 /** When creating a callbackable CQ, pass in a functor to get invoked when
801 * shutdown is complete */
802 grpc_completion_queue_functor* cq_shutdown_cb;
803
804 /* END OF VERSION 2 CQ ATTRIBUTES */
805} grpc_completion_queue_attributes;
806
807/** The completion queue factory structure is opaque to the callers of grpc */
808typedef struct grpc_completion_queue_factory grpc_completion_queue_factory;
809
810#ifdef __cplusplus
811}
812#endif
813
814#endif /* GRPC_IMPL_CODEGEN_GRPC_TYPES_H */
815

source code of include/grpc/impl/codegen/grpc_types.h